Filesystem tools exposed as bare symbols in the Python sandbox.
Two layers:
Structured helpers for read / tree / search:
(cat path) ; -> {:path :anchors {<N:hash> text…} :next-offset N? :truncated? B}
(cat path n) ; first n lines from line 1
(cat path offset n) ; n lines starting at line offset (1-based)
(cat path :tail) ; last 400 lines (tail)
(cat path :tail n) ; last n lines
(ls path) ; -> nested dict tree (name/path/type/size/children)
(ls path opts) ; opts keys: depth / is_hidden / is_respect_gitignore
(rg query) ; -> content hits; query = a term or list of terms (OR),
; smart-case substring. Opts: paths/include/context/is_files_only
Cwd-safe wrappers over the babashka.fs file API. patch is
the canonical text edit surface:
(cat path) (patch [edit-map]) ; keys: path / from_anchor / replace (create-dirs path) (copy src dest) (move src dest) (delete path) (delete-if-exists path) (exists? path)
Hard guard: every path must stay inside the session's working
directory (fs/cwd); .. traversal is rejected before any I/O.
Filesystem tools exposed as bare symbols in the Python sandbox.
Two layers:
1. Structured helpers for read / tree / search:
(cat path) ; -> {:path :anchors {<N:hash> text…} :next-offset N? :truncated? B}
(cat path n) ; first n lines from line 1
(cat path offset n) ; n lines starting at line `offset` (1-based)
(cat path :tail) ; last 400 lines (tail)
(cat path :tail n) ; last n lines
(ls path) ; -> nested dict tree (name/path/type/size/children)
(ls path opts) ; opts keys: depth / is_hidden / is_respect_gitignore
(rg query) ; -> content hits; query = a term or list of terms (OR),
; smart-case substring. Opts: paths/include/context/is_files_only
2. Cwd-safe wrappers over the babashka.fs file API. `patch` is
the canonical text edit surface:
(cat path)
(patch [edit-map]) ; keys: path / from_anchor / replace
(create-dirs path)
(copy src dest)
(move src dest)
(delete path)
(delete-if-exists path)
(exists? path)
Hard guard: every path must stay inside the session's working
directory (`fs/cwd`); `..` traversal is rejected before any I/O.(available-editing-prompt)The editing extension's model-facing prompt. When the project contains NO
structurally-supported code (structural-supported? false — e.g. a docs/config
repo), the tree-sitter STRUCTURAL editors are neither advertised nor bound, so
their tool names + strategy are OMITTED here too — the prompt stays consistent
with what's actually callable, and the model is steered to anchor-based patch.
The editing extension's model-facing prompt. When the project contains NO structurally-supported code (`structural-supported?` false — e.g. a docs/config repo), the tree-sitter STRUCTURAL editors are neither advertised nor bound, so their tool names + strategy are OMITTED here too — the prompt stays consistent with what's actually callable, and the model is steered to anchor-based `patch`.
Default editing prompt for docs/tests. A delay for the same reason as
editing-symbols above — deref with @editing-prompt.
Default editing prompt for docs/tests. A `delay` for the same reason as `editing-symbols` above — deref with `@editing-prompt`.
Default editing symbol set for docs/tests. A delay so the language/env
scan it triggers runs on first deref (tests, docs) and NEVER at namespace
load — a load-time call reaches git/run-git's future, which starts the
agent thread-pool and native-image refuses that started thread in the image
heap. Deref with @editing-symbols.
Default editing symbol set for docs/tests. A `delay` so the language/env scan it triggers runs on first deref (tests, docs) and NEVER at namespace load — a load-time call reaches `git/run-git`'s `future`, which starts the agent thread-pool and native-image refuses that started thread in the image heap. Deref with `@editing-symbols`.
(patch-safe edits)Apply exact-replace patch edits to the filesystem.
Returns a structured map; never throws on normal failure paths (no-match, anchor-not-found, stale mtime, file not found, path escape, ambiguous selection). Reserves exceptions for genuinely unexpected errors (thread interrupt, disk full, etc.).
Success shape: {:success? true :plans [{:path :before :after :passes? :indent-delta?} ...] :checks [<per-edit-check> ...]}
:passes lists only meaningful non-anchor alarms that fired against this
plan's path, in edit order. The ordinary :hashline anchor path is
expected and therefore omitted from user/model-facing summaries. Same for
:indent-delta: present only when a :relative-indent pass auto-shifted
:replace.
Failure shape: {:success? false :failures [failure-check-with-:consecutive-failures] :checks [<every-edit-check>] :loop-hint <string-or-nil> :message <human-readable summary>}
patch-tool projects the result into the standard tool-success /
tool-failure envelope so the model sees :reason, :loop-hint,
and per-edit diagnostics in :error without try/catch.
Apply exact-replace patch edits to the filesystem.
Returns a structured map; **never throws on normal failure paths**
(no-match, anchor-not-found, stale mtime, file not found, path
escape, ambiguous selection). Reserves exceptions for genuinely
unexpected errors (thread interrupt, disk full, etc.).
Success shape:
{:success? true
:plans [{:path :before :after :passes? :indent-delta?} ...]
:checks [<per-edit-check> ...]}
`:passes` lists only meaningful non-anchor alarms that fired against this
plan's path, in edit order. The ordinary `:hashline` anchor path is
expected and therefore omitted from user/model-facing summaries. Same for
`:indent-delta`: present only when a `:relative-indent` pass auto-shifted
`:replace`.
Failure shape:
{:success? false
:failures [<failure-check-with-:consecutive-failures>]
:checks [<every-edit-check>]
:loop-hint <string-or-nil>
:message <human-readable summary>}
`patch-tool` projects the result into the standard tool-success /
tool-failure envelope so the model sees `:reason`, `:loop-hint`,
and per-edit diagnostics in `:error` without `try/catch`.(refresh-file-summary summary before after)Recompute a per-file summary's "diff"/"changed" from the ORIGINAL before
and the FINAL on-disk after. A language pack that rewrites a just-edited
file in an :after op-hook (parinfer paren-repair + cljfmt) calls this so the
MODEL-FACING diff shows the bytes actually written, not the pre-hook
intermediate the raw edit produced. All other summary keys are preserved.
Recompute a per-file summary's "diff"/"changed" from the ORIGINAL `before` and the FINAL on-disk `after`. A language pack that rewrites a just-edited file in an :after op-hook (parinfer paren-repair + cljfmt) calls this so the MODEL-FACING diff shows the bytes actually written, not the pre-hook intermediate the raw edit produced. All other summary keys are preserved.
(structural-supported? _env)Whether the STRUCTURAL editors should be advertised for the current project:
true when its language scan finds at least one file in a structurally-supported
language. FAILS OPEN — a scan error, an empty/new repo, or an all-unrecognized
tree all return true, so a useful editor is NEVER hidden on uncertainty. Only a
project that scanned cleanly AND contains code, NONE of it structurally supported
(a pure docs/config repo, or an unsupported-language project), returns false.
env is ignored — the answer comes from the cached env snapshot, not per-call
runtime state.
Whether the STRUCTURAL editors should be advertised for the current project: true when its language scan finds at least one file in a structurally-supported language. FAILS OPEN — a scan error, an empty/new repo, or an all-unrecognized tree all return true, so a useful editor is NEVER hidden on uncertainty. Only a project that scanned cleanly AND contains code, NONE of it structurally supported (a pure docs/config repo, or an unsupported-language project), returns false. `env` is ignored — the answer comes from the cached env snapshot, not per-call runtime state.
(write-safe args)Whole-file write primitive: create a new file OR overwrite an
existing one with :content. Returns a structured result; never
throws on normal failure paths (file exists with is_overwrite false,
stale mtime/size, path escape).
Required keys: :path, :content (string).
Optional keys:
:is_overwrite default true; when false and target exists
→ :reason :exists
:expected_mtime staleness guard; mismatch → :reason :stale
:expected_size staleness guard; mismatch → :reason :stale
Success shape: {:success? true :plan {:path :before :after :op} :checks [<check>]}
Failure shape: {:success? false :failures [failure-with-:reason] :checks [<check>] :loop-hint <string-or-nil> :message <human-readable>}
Whole-file write primitive: create a new file OR overwrite an
existing one with `:content`. Returns a structured result; **never
throws on normal failure paths** (file exists with is_overwrite false,
stale mtime/size, path escape).
Required keys: `:path`, `:content` (string).
Optional keys:
:is_overwrite default true; when false and target exists
→ :reason :exists
:expected_mtime staleness guard; mismatch → :reason :stale
:expected_size staleness guard; mismatch → :reason :stale
Success shape:
{:success? true
:plan {:path :before :after :op}
:checks [<check>]}
Failure shape:
{:success? false
:failures [<failure-with-:reason>]
:checks [<check>]
:loop-hint <string-or-nil>
:message <human-readable>}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 |