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
(cat dir) ; a DIRECTORY path -> shallow listing {:path :entries [{name path type size}] :depth}
(cat dir opts) ; opts keys: depth (recurse) / is_hidden / is_respect_gitignore
(grep query) ; -> content hits (anchored) + ranked file-NAME matches;
; query = a term or list of terms (OR), smart-case
; substring. Opts: paths/include/limit/is_hidden
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
(cat dir) ; a DIRECTORY path -> shallow listing {:path :entries [{name path type size}] :depth}
(cat dir opts) ; opts keys: depth (recurse) / is_hidden / is_respect_gitignore
(grep query) ; -> content hits (anchored) + ranked file-NAME matches;
; query = a term or list of terms (OR), smart-case
; substring. Opts: paths/include/limit/is_hidden
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)No separate editing prompt: active native descriptions own routing and their JSON Schemas own inputs. Structural tools are already omitted by their activation gate when unsupported, so repeating that matrix would waste tokens.
No separate editing prompt: active native descriptions own routing and their JSON Schemas own inputs. Structural tools are already omitted by their activation gate when unsupported, so repeating that matrix would waste tokens.
Compatibility view of the now-empty editing prompt. Native tool contracts replaced this duplicated prompt fragment.
Compatibility view of the now-empty editing prompt. Native tool contracts replaced this duplicated prompt fragment.
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 anchored patch edits to the filesystem.
Returns a structured map; never throws on normal failure paths (stale anchor, file not found, path escape). Reserves exceptions for genuinely unexpected errors (thread interrupt, disk full, etc.).
Success shape: {:success? true :plans [{:path :before :after} ...] :checks [<per-edit-check> ...]}
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 anchored patch edits to the filesystem.
Returns a structured map; **never throws on normal failure paths**
(stale anchor, file not found, path escape). Reserves exceptions for genuinely
unexpected errors (thread interrupt, disk full, etc.).
Success shape:
{:success? true
:plans [{:path :before :after} ...]
:checks [<per-edit-check> ...]}
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 |