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.
Extra filesystem roots the current tool call may ALSO operate under, beyond the
primary *workspace-root*, as [{:trunk :clone}] canonical pairs: :trunk
is the REAL directory the user added (what the model addresses), :clone is
the backend working copy edits land in (== :trunk when live). Bound
per-turn by the channel layer from the session's persisted filesystem roots.
Empty in the common single-root case. The editing layer confines to the
clones and transparently remaps trunk↔clone (see filesystem-root-mappings).
Extra filesystem roots the current tool call may ALSO operate under, beyond the
primary `*workspace-root*`, as `[{:trunk :clone}]` canonical pairs: `:trunk`
is the REAL directory the user added (what the model addresses), `:clone` is
the backend working copy edits land in (== `:trunk` when live). Bound
per-turn by the channel layer from the session's persisted filesystem roots.
Empty in the common single-root case. The editing layer confines to the
clones and transparently remaps trunk↔clone (see `filesystem-root-mappings`).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]})Release backend-owned roots and transition the row to :discarded. A :live
backend (trunk) owns no clone, so its shared root is never deleted.
Release backend-owned roots and transition the row to :discarded. A `:live` backend (trunk) owns no clone, so its shared root is never deleted.
(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.
(add-filesystem-root! db-info workspace-id path)Add path to the workspace's extra filesystem roots. Drafts require the same
isolation capabilities for every added root; live workspaces add it live.
Add `path` to the workspace's extra filesystem roots. Drafts require the same isolation capabilities for every added root; live workspaces add it live.
(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 the draft's since-fork edits into the user's real dirs (trunk),
leaving them uncommitted for the user to review/commit. A draft is about
the WHOLE workspace: this lands the primary clone AND every auto-cloned
filesystem root (each into its own trunk). Vis owns no git lifecycle.
Adds/modifications come from the mtime diff; deletions are files that
existed at the fork but the agent removed in the draft. Returns
{:status :ok :changed [{:status :path :root}] :landed n :workspace ws}.
Land the draft's since-fork edits into the user's real dirs (trunk),
leaving them uncommitted for the user to review/commit. A draft is about
the WHOLE workspace: this lands the primary clone AND every auto-cloned
filesystem root (each into its own trunk). Vis owns no git lifecycle.
Adds/modifications come from the mtime diff; deletions are files that
existed at the fork but the agent removed in the draft. Returns
`{:status :ok :changed [{:status :path :root}] :landed n :workspace ws}`.(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 filesystem root to path — the
session now works in a different project directory: shell cwd, relative
path resolution, file tools (cat/patch/write), and search (rg/find_files)
all follow from the next turn, because they resolve through the session's
pinned workspace. Additional filesystem roots CARRY OVER (they are
session-scoped permissions, not root-relative); an entry equal to the new
root is dropped as redundant. Refuses while the session is in a draft —
a draft is a fork of the OLD root, so apply/abandon it first. Returns the
newly pinned trunk workspace (or the current one when path already IS
the root).
Repoint `session-state-id`'s PRIMARY filesystem root to `path` — the session now works in a different project directory: shell cwd, relative path resolution, file tools (cat/patch/write), and search (rg/find_files) all follow from the next turn, because they resolve through the session's pinned workspace. Additional filesystem roots CARRY OVER (they are session-scoped permissions, not root-relative); an entry equal to the new root is dropped as redundant. Refuses while the session is in a draft — a draft is a fork of the OLD root, so apply/abandon it first. Returns the newly pinned trunk workspace (or the current one when `path` already IS the root).
(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]})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).
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).
(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.
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.
(discard-session-clones! db-info session-soul-id)On session DELETE, walk the complete revision lineage and release every backend-owned root. Live roots are never deleted.
On session DELETE, walk the complete revision lineage and release every backend-owned root. Live roots are never deleted.
(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.
(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 for the current tool call's extra
filesystem roots, beyond the primary. Reads :workspace/filesystem-roots from an
env map (or a raw coll). :trunk is the real dir the model addresses;
:clone is the backend working copy edits land in (== trunk when live).
The channel layer binds *filesystem-roots* from this per turn; the editing
layer confines to the clones and transparently remaps trunk↔clone.
Canonical `[{:trunk :clone}]` pairs for the current tool call's extra
filesystem roots, beyond the primary. Reads `:workspace/filesystem-roots` from an
env map (or a raw coll). `:trunk` is the real dir the model addresses;
`:clone` is the backend working copy edits land in (== trunk when live).
The channel layer binds `*filesystem-roots*` from this per turn; the editing
layer confines to the clones and transparently remaps trunk↔clone.(exit-to-trunk! db-info session-state-id)Repoint session-state-id back to a TRUNK workspace (the real cwd),
leaving any draft. Returns the trunk workspace now pinned.
Repoint `session-state-id` back to a TRUNK workspace (the real cwd), leaving any draft. Returns the trunk workspace now pinned.
(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).(filesystem-roots ws)Extra filesystem roots configured for ws, normalized to
[{:trunk :clone :fork-ms :backend}].
Extra filesystem roots configured for `ws`, normalized to
`[{:trunk :clone :fork-ms :backend}]`.(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-finished db-info repo-id)Discarded workspaces for repo-id, newest first.
Discarded workspaces for `repo-id`, newest first.
(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.
(remove-filesystem-root! db-info workspace-id path)Remove path from the workspace's extra filesystem roots and release any
backend-owned isolated root.
Remove `path` from the workspace's extra filesystem roots and release any backend-owned isolated root.
(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.
(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 |