Backend-neutral workspaces, DB-pinned to session_state 1:1.
The user's real cwd is trunk — Vis never mutates it, and Vis no
longer requires it to be a git repo. A session works in trunk by
default; /draft new opts into an isolated workspace supplied by a
registered backend. Backends declare concrete capabilities such as
isolated fork, rollback, merge-back, retained revisions, and parallel
safety. Core never assumes which implementation provides them.
'What changed since the fork' is computed git-free: clonefile
preserves source mtimes, so files the agent touches in the clone get
a fresh mtime greater than the fork timestamp we capture at clone
time. apply! lands exactly those files back into cwd, uncommitted,
and leaves the user to commit with their own tools — Vis owns no
git/branch/commit/merge lifecycle whatsoever.
Vis never mutates JVM user.dir. Channels rebind workspace-root per
turn from the active workspace; tools resolve paths via
(workspace/cwd). There is NO process-cwd fallback in production -
the env carries :workspace/root from create-environment onward.
Backend-neutral workspaces, DB-pinned to session_state 1:1. The user's real cwd is *trunk* — Vis never mutates it, and Vis no longer requires it to be a git repo. A session works in trunk by default; `/draft new` opts into an isolated workspace supplied by a registered backend. Backends declare concrete capabilities such as isolated fork, rollback, merge-back, retained revisions, and parallel safety. Core never assumes which implementation provides them. 'What changed since the fork' is computed git-free: `clonefile` preserves source mtimes, so files the agent touches in the clone get a fresh mtime greater than the fork timestamp we capture at clone time. `apply!` lands exactly those files back into cwd, uncommitted, and leaves the user to commit with their own tools — Vis owns no git/branch/commit/merge lifecycle whatsoever. Vis never mutates JVM user.dir. Channels rebind *workspace-root* per turn from the active workspace; tools resolve paths via (workspace/cwd). There is NO process-cwd fallback in production - the env carries `:workspace/root` from `create-environment` onward.
Parent dir for every trunk's draft store. nil (production default)
resolves to the vis.drafts.dir system property, else
~/.vis/drafts. Tests point it at a throwaway dir (the :test alias
sets -Dvis.drafts.dir=target/vis-drafts-test) so the suite never
litters the real ~/.vis.
Parent dir for every trunk's draft store. `nil` (production default) resolves to the `vis.drafts.dir` system property, else `~/.vis/drafts`. Tests point it at a throwaway dir (the `:test` alias sets `-Dvis.drafts.dir=target/vis-drafts-test`) so the suite never litters the real ~/.vis.
Configured filesystem catalog entries available to the current tool call, as
canonical [{:trunk :clone}] pairs. These are rebuilt from vis.yml on
/reload; they are never session-persisted or mutable through a command.
Configured filesystem catalog entries available to the current tool call, as
canonical `[{:trunk :clone}]` pairs. These are rebuilt from `vis.yml` on
`/reload`; they are never session-persisted or mutable through a command.Canonical workspace root for the current tool call. Bound per-turn
by the channel layer; never nil in normal operation.
Canonical workspace root for the current tool call. Bound per-turn by the channel layer; never `nil` in normal operation.
(abandon! db-info {:keys [workspace-id reason]})Transition a workspace to :discarded and release its primary backend-owned clone.
Transition a workspace to :discarded and release its primary backend-owned clone.
(abandon-lineage! db-info {:keys [workspace-id reason]})Discard workspace-id and each draft ancestor up to (but never including)
trunk. Used when an operator applies or abandons the session draft. A plain
draft's parent is its trunk, so this normally abandons the single draft.
Discard `workspace-id` and each draft ancestor up to (but never including) trunk. Used when an operator applies or abandons the session draft. A plain draft's parent is its trunk, so this normally abandons the single draft.
(allowed-roots)Canonical absolute CLONE/working-copy paths the current tool call may
operate under: the primary cwd FIRST, then each bound filesystem root's
:clone. Deduped; the primary is always present. The confinement set the
editing layer's safe-path checks the (possibly remapped) target against.
Canonical absolute CLONE/working-copy paths the current tool call may operate under: the primary cwd FIRST, then each bound filesystem root's `:clone`. Deduped; the primary is always present. The confinement set the editing layer's `safe-path` checks the (possibly remapped) target against.
(apply! db-info {:keys [workspace-id]})Land a draft's primary clone changes into its real workspace root.
Land a draft's primary clone changes into its real workspace root.
(capability-matrix source-root)(capability-matrix source-root store-root)Describe every registered backend for source-root, including availability
and declared capabilities. This is the public feature-discovery surface.
It never loads extensions: extension discovery owns backend registration.
Describe every registered backend for `source-root`, including availability and declared capabilities. This is the public feature-discovery surface. It never loads extensions: extension discovery owns backend registration.
(change-root! db-info session-state-id path)Repoint session-state-id's primary workspace root to path. Refuses while
the session is in a draft, which must be applied or abandoned first.
Repoint `session-state-id`'s primary workspace root to `path`. Refuses while the session is in a draft, which must be applied or abandoned first.
(changed-paths clone fork-ms)Repo-relative paths of files under clone whose mtime is newer than
fork-ms — i.e. exactly what the agent touched since the fork
(clonefile preserves source mtimes, so untouched files stay older).
Prunes VCS/build/cache dirs (prune-dir?) — landing .git/ would corrupt
trunk's repo, and tool caches would flood the result. Returns a vec
of strings.
Repo-relative paths of files under `clone` whose mtime is newer than `fork-ms` — i.e. exactly what the agent touched since the fork (`clonefile` preserves source mtimes, so untouched files stay older). Prunes VCS/build/cache dirs (`prune-dir?`) — landing `.git/` would corrupt trunk's repo, and tool caches would flood the result. Returns a vec of strings.
(create! db-info
{:keys [session-state-id label from required-capabilities blank?]})Create an isolated DRAFT using the strongest available backend and pin it
to :session-state-id. The backend must provide the full draft capability
set; core never silently falls back to a shared root.
The fork PARENT is chosen so apply! lands back where it forked from:
pass :from <parent-workspace> to clone that workspace's :root and
inherit its :repo-root (apply target); otherwise the parent is the
user's real cwd (trunk).
:fresh? true forks from an EMPTY seed instead: the draft starts with
NONE of the files currently in trunk (HEAD). Its baseline :fork-ms is 0,
so every file created inside the draft counts as a since-fork edit and
lands on apply!, while deleted-paths (trunk files OLDER than the
baseline yet absent from the clone) can never match — a fresh draft only
ever ADDS/OVERWRITES into trunk, it cannot infer deletions of files it
never saw. The ZERO baseline is HEREDITARY: a draft forked :from a
fresh-lineage workspace (a sub-loop child, a revision) keeps baseline 0
too — its clone still lacks the trunk files the lineage never saw, so
applying it with a real fork timestamp would mass-report trunk's files
as deletions and wipe the repo.
Create an isolated DRAFT using the strongest available backend and pin it to `:session-state-id`. The backend must provide the full draft capability set; core never silently falls back to a shared root. The fork PARENT is chosen so `apply!` lands back where it forked from: pass `:from <parent-workspace>` to clone that workspace's `:root` and inherit its `:repo-root` (apply target); otherwise the parent is the user's real cwd (trunk). `:fresh? true` forks from an EMPTY seed instead: the draft starts with NONE of the files currently in trunk (HEAD). Its baseline `:fork-ms` is 0, so every file created inside the draft counts as a since-fork edit and lands on `apply!`, while `deleted-paths` (trunk files OLDER than the baseline yet absent from the clone) can never match — a fresh draft only ever ADDS/OVERWRITES into trunk, it cannot infer deletions of files it never saw. The ZERO baseline is HEREDITARY: a draft forked `:from` a fresh-lineage workspace (a sub-loop child, a revision) keeps baseline 0 too — its clone still lacks the trunk files the lineage never saw, so applying it with a real fork timestamp would mass-report trunk's files as deletions and wipe the repo.
(create-dir! parent name)Create a single child directory name under existing directory parent.
Returns the canonical path of the (possibly already-existing) child. Throws
when parent is not a directory or name is not a single safe path segment.
name may not contain a separator, be blank, or be ./...
Create a single child directory `name` under existing directory `parent`. Returns the canonical path of the (possibly already-existing) child. Throws when `parent` is not a directory or `name` is not a single safe path segment. `name` may not contain a separator, be blank, or be `.`/`..`.
(create-trunk-at! db-info root)Mint a TRUNK workspace rooted at root (an arbitrary directory), not
pinned to any session. Lets a channel open a session under a directory
OTHER than the one vis was launched from — a tab in another project.
Returns the workspace row (with :id) to pass as :workspace-id when
creating the session.
Mint a TRUNK workspace rooted at `root` (an arbitrary directory), not pinned to any session. Lets a channel open a session under a directory OTHER than the one vis was launched from — a tab in another project. Returns the workspace row (with `:id`) to pass as `:workspace-id` when creating the session.
(cwd)Resolve the current workspace cwd. In production the channel
wrapper binds *workspace-root* per turn, so the process-cwd
fallback only fires from REPL / test / one-off CLI paths that have
no session context.
Resolve the current workspace cwd. In production the channel wrapper binds `*workspace-root*` per turn, so the process-cwd fallback only fires from REPL / test / one-off CLI paths that have no session context.
(deleted-paths clone trunk fork-ms)Repo-relative paths the agent DELETED in the draft: present under
trunk (pruning VCS/build/cache dirs via prune-dir?) with an mtime
older than fork-ms — so they existed at the fork and are not user
post-fork additions — yet absent from clone. The mtime guard means
apply! never reverts a file the user added to cwd after forking, and
the prune keeps cache churn (e.g. .clj-kondo/.cache rewritten in the
clone) from being reported as spurious deletions.
A non-positive fork-ms is the FRESH-lineage baseline: the clone never
saw trunk's files, so a deletion is semantically impossible — return []
unconditionally, whatever the trees contain. The hard exit (rather than
relying on the < comparison alone) also keeps pathological trunk
mtimes (epoch/pre-epoch, e.g. unpacked from a tarball) from ever
comparing below the baseline into a real .delete of the user's files.
Repo-relative paths the agent DELETED in the draft: present under `trunk` (pruning VCS/build/cache dirs via `prune-dir?`) with an mtime older than `fork-ms` — so they existed at the fork and are not user post-fork additions — yet absent from `clone`. The mtime guard means `apply!` never reverts a file the user added to cwd after forking, and the prune keeps cache churn (e.g. `.clj-kondo/.cache` rewritten in the clone) from being reported as spurious deletions. A non-positive `fork-ms` is the FRESH-lineage baseline: the clone never saw trunk's files, so a deletion is semantically impossible — return [] unconditionally, whatever the trees contain. The hard exit (rather than relying on the `<` comparison alone) also keeps pathological trunk mtimes (epoch/pre-epoch, e.g. unpacked from a tarball) from ever comparing below the baseline into a real `.delete` of the user's files.
(discard-session-clones! db-info session-soul-id)On session DELETE, release primary backend-owned clones in its lineage.
On session DELETE, release primary backend-owned clones in its lineage.
(display-label workspace)(display-label db-info workspace session)Human-facing label for workspace. Order: explicit :label →
pinned session title → clone name (:branch) → id prefix.
Human-facing label for `workspace`. Order: explicit `:label` → pinned session title → clone name (`:branch`) → id prefix.
(draft? ws)True when a workspace carries an apply baseline and therefore represents isolated filesystem state rather than a logical-only graph revision.
True when a workspace carries an apply baseline and therefore represents isolated filesystem state rather than a logical-only graph revision.
(drafts-store-path)Canonical path of the drafts-store parent (~/.vis/drafts by default, or the
vis.drafts.dir override / *drafts-home* test binding). The DEFAULT search
sweep prunes the raw ~/.vis grant tree but KEEPS real draft clones, which
live under this dir and remain searchable. nil when unresolvable.
Canonical path of the drafts-store parent (`~/.vis/drafts` by default, or the `vis.drafts.dir` override / `*drafts-home*` test binding). The DEFAULT search sweep prunes the raw `~/.vis` grant tree but KEEPS real draft clones, which live under this dir and remain searchable. nil when unresolvable.
(ensure-workspace! db-info {:keys [session-state-id]})Find-or-create the session's workspace. The DEFAULT is TRUNK — the
user's real cwd (no clone); the agent works directly in the repo
until /draft new. Resume returns whatever the session was pinned to
(trunk, or an open draft). Idempotent per session-state.
Find-or-create the session's workspace. The DEFAULT is TRUNK — the user's real cwd (no clone); the agent works directly in the repo until `/draft new`. Resume returns whatever the session was pinned to (trunk, or an open draft). Idempotent per session-state.
(env-filesystem-roots env-or-roots)Canonical [{:trunk :clone}] pairs available to the current tool call.
Includes configured workspace catalog entries and immutable read/write roots from
the environment security snapshot. Configured roots map to themselves (no draft
clone). With the jail disabled, host filesystem roots are granted and marked
no-search so explicit paths are unrestricted without making default searches
crawl the machine.
Canonical `[{:trunk :clone}]` pairs available to the current tool call.
Includes configured workspace catalog entries and immutable read/write roots from
the environment security snapshot. Configured roots map to themselves (no draft
clone). With the jail disabled, host filesystem roots are granted and marked
no-search so explicit paths are unrestricted without making default searches
crawl the machine.(exit-to-trunk! db-info session-state-id)(exit-to-trunk! db-info session-state-id root)Repoint session-state-id back to a TRUNK workspace (the real cwd),
leaving any draft. Returns the trunk workspace now pinned. The three-argument
arity preserves an explicit repo root when the session was opened away from
the process launch directory.
Repoint `session-state-id` back to a TRUNK workspace (the real cwd), leaving any draft. Returns the trunk workspace now pinned. The three-argument arity preserves an explicit repo root when the session was opened away from the process launch directory.
(filesystem-root-mappings)The bound filesystem roots as canonical [{:trunk :clone}] pairs — the
trunk↔clone remap table the editing layer uses so the model can address a
context file by its REAL (trunk) path while edits land in the :clone.
Empty in the single-root case. Does NOT include the primary (relative paths
resolve under cwd directly).
The bound filesystem roots as canonical `[{:trunk :clone}]` pairs — the
trunk↔clone remap table the editing layer uses so the model can address a
context file by its REAL (trunk) path while edits land in the `:clone`.
Empty in the single-root case. Does NOT include the primary (relative paths
resolve under cwd directly).(focus! db-info workspace-id)Stamp last_focused_at_ms and upsert the per-repo repo_focus
pointer. Returns the updated workspace record.
Stamp `last_focused_at_ms` and upsert the per-repo `repo_focus` pointer. Returns the updated workspace record.
(for-session db-info session-state-id)Workspace pinned to session-state-id, or nil.
Workspace pinned to `session-state-id`, or nil.
(get db-info workspace-id)Return the workspace with workspace-id, or nil.
Return the workspace with `workspace-id`, or nil.
(isolated-workspaces-supported?)(isolated-workspaces-supported? root)True when the current root can create full draft workspaces.
True when the current root can create full draft workspaces.
(last-focused db-info repo-id)Workspace id from repo_focus for repo-id, or nil.
Workspace id from `repo_focus` for `repo-id`, or nil.
(list-active db-info repo-id)Active workspaces for repo-id, newest first.
Active workspaces for `repo-id`, newest first.
(list-active-with-sessions db-info repo-id)Like list-active but each entry is the {:workspace :session-state}
pair, sorted by last_focused_at_ms DESC NULLS LAST, then
created_at DESC.
Like `list-active` but each entry is the `{:workspace :session-state}`
pair, sorted by `last_focused_at_ms` DESC NULLS LAST, then
`created_at` DESC.(list-drafts db-info repo-id)Active DRAFTS for repo-id, newest first — the parked/stashable drafts a
session can resume!. Trunk workspaces are filtered out. A draft that a
session leaves via stash! stays :active and keeps appearing here until it
is applied or abandoned.
Active DRAFTS for `repo-id`, newest first — the parked/stashable drafts a session can `resume!`. Trunk workspaces are filtered out. A draft that a session leaves via `stash!` stays `:active` and keeps appearing here until it is applied or abandoned.
(list-finished db-info repo-id)Discarded workspaces for repo-id, newest first.
Discarded workspaces for `repo-id`, newest first.
(no-search-roots)Canonical CLONE paths of bound filesystem roots flagged search: false in
the workspace catalog. resolve-search-roots prunes these from the DEFAULT
grep sweep; explicit paths still reach them.
Canonical CLONE paths of bound filesystem roots flagged `search: false` in the workspace catalog. `resolve-search-roots` prunes these from the DEFAULT grep sweep; explicit paths still reach them.
(normalize-root root)Canonicalize a workspace root string/File. Blank/nil → nil.
Canonicalize a workspace root string/File. Blank/nil → nil.
(register-backend! backend)Register a workspace backend. Idempotent by backend id.
Register a workspace backend. Idempotent by backend id.
(register-hook! hook-id hook-fn)Register hook-fn for hook-id ∈ {:on-spawn :on-apply :on-discard}.
Synchronous; exceptions swallowed.
Register `hook-fn` for `hook-id` ∈ {:on-spawn :on-apply :on-discard}.
Synchronous; exceptions swallowed.(registered-backends)Registered workspace backends ordered by descending priority.
Registered workspace backends ordered by descending priority.
(resume! db-info {:keys [session-state-id workspace-id]})Re-enter a previously stashed DRAFT: pin session-state-id to workspace-id,
which MUST be an :active draft from the session's current repo and not
currently pinned to another session. The session must already have left any
draft (be on trunk) — a stash/apply/abandon precedes a resume. Returns the
draft workspace now pinned. Throws ex-info with a :type on any precondition
failure.
Re-enter a previously stashed DRAFT: pin `session-state-id` to `workspace-id`, which MUST be an `:active` draft from the session's current repo and not currently pinned to another session. The session must already have left any draft (be on trunk) — a stash/apply/abandon precedes a resume. Returns the draft workspace now pinned. Throws `ex-info` with a `:type` on any precondition failure.
(select-backend source-root store-root required)Select the highest-priority available backend covering required.
Returns nil when no backend can provide the requested semantics.
Select the highest-priority available backend covering `required`. Returns nil when no backend can provide the requested semantics.
(set-label! db-info {:keys [workspace-id label]})Set the workspace's human-friendly :label. Empty/nil clears it.
Set the workspace's human-friendly `:label`. Empty/nil clears it.
(stash! db-info session-state-id)Park the session's current draft: repoint session-state-id back to trunk
while LEAVING the draft row :active and its clone on disk intact, so it can
be resumed later. This is the non-destructive twin of abandon! — nothing is
discarded. Returns {:draft <stashed-draft-or-nil> :trunk <trunk-ws>}; on
trunk :draft is nil and this just ensures a trunk pin. The draft's own
:repo-root is preserved for sessions opened away from the launch directory.
Park the session's current draft: repoint `session-state-id` back to trunk
while LEAVING the draft row `:active` and its clone on disk intact, so it can
be resumed later. This is the non-destructive twin of `abandon!` — nothing is
discarded. Returns `{:draft <stashed-draft-or-nil> :trunk <trunk-ws>}`; on
trunk `:draft` is nil and this just ensures a trunk pin. The draft's own
`:repo-root` is preserved for sessions opened away from the launch directory.(status db-info workspace-id)Enrich a workspace record with live status. Stamps
:workspace/root, :workspace/sandbox?, :workspace/exists?, :workspace/changed
(count of since-fork edits) and :workspace/dirty?. No git.
Enrich a workspace record with live status. Stamps `:workspace/root`, `:workspace/sandbox?`, `:workspace/exists?`, `:workspace/changed` (count of since-fork edits) and `:workspace/dirty?`. No git.
(subdirs path)Child directory names (non-hidden) of path, case-insensitively sorted.
Empty vec when path is blank, not a directory, or unreadable.
Child directory names (non-hidden) of `path`, case-insensitively sorted. Empty vec when `path` is blank, not a directory, or unreadable.
(supports? source-root required)(supports? source-root store-root required)True when some backend can provide required for the given roots.
True when some backend can provide `required` for the given roots.
(trunk-info)(trunk-info root)The user's real cwd (trunk). No git read; just the launch dir.
The user's real cwd (trunk). No git read; just the launch dir.
(trunk-root)The user's real working directory — where they launched vis.
Canonical absolute path. This is trunk: never mutated, never
required to be a git repo. (bin/vis preserves the invocation cwd
as JVM user.dir even though it cd's to the repo for deps.)
The user's real working directory — where they launched `vis`. Canonical absolute path. This is *trunk*: never mutated, never required to be a git repo. (`bin/vis` preserves the invocation cwd as JVM user.dir even though it cd's to the repo for deps.)
(workspace-backend backend)Validate and return a workspace backend descriptor.
Required keys: :workspace.backend/id keyword :workspace.backend/capabilities capability set :workspace.backend/available-fn ({:source-root :store-root} -> bool or {:available? bool :reason keyword :details map}) :workspace.backend/fork-fn ({:source-root :store-root :name} -> path) :workspace.backend/discard-fn ({:root} -> nil)
Validate and return a workspace backend descriptor.
Required keys:
:workspace.backend/id keyword
:workspace.backend/capabilities capability set
:workspace.backend/available-fn ({:source-root :store-root} -> bool or
{:available? bool :reason keyword :details map})
:workspace.backend/fork-fn ({:source-root :store-root :name} -> path)
:workspace.backend/discard-fn ({:root} -> nil)Closed capability vocabulary for workspace backends.
Closed capability vocabulary for workspace backends.
(workspace-capability-matrix workspace-or-root)Capability matrix for a workspace (or root path), using the real derived workspace storage location rather than assuming source and destination are on the same filesystem.
Capability matrix for a workspace (or root path), using the real derived workspace storage location rather than assuming source and destination are on the same filesystem.
(workspace-root env-or-root)Extract a canonical :workspace/root from an env map or raw root value.
Extract a canonical :workspace/root from an env map or raw root value.
(workspace-with-session db-info workspace-id)Hydrate workspace-id with its pinned session_state. Returns
{:workspace <ws> :session-state <ss>}.
Hydrate `workspace-id` with its pinned `session_state`. Returns
`{:workspace <ws> :session-state <ss>}`.cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |