fractal-engine.agentcli — net.clojars.deadmeme5441/fractal-engine 0.1.1

The agent USE surface for the engine — not an inspector, the whole interface an agent works through, the way bd is for tasks. One grammar fractal <verb> <subject> [args] [--flags] covers both halves of the loop:

DRIVE (do work): READ (see what happened): fractal run <task> fractal show <run> [node] detail; the hub fractal resume <run> <task> fractal tree <run> addressable tree fractal fork <run> <task> fractal prime <run> orientation fractal ls list runs fractal verify <run> [node] claim-vs-evidence fractal trace <run> [node] provenance fractal cost <run> spend fractal leaves <run> [node] leaf I/O fractal step <run> [node] N one step fractal stream <run> events as JSONL

Every verb takes --json; exit codes mean something (0 final · 1 error · 2 no-final · 3 timeout · 5 confabulation-suspected). A drive verb prints the run's name so it chains straight into a read verb — fractal run "…" → fractal verify <run>. A node address is root, child-0001, or child-0001/child-0004 (the leading root/ is implied). <run> is a path (.fractal/foo) or a bare name resolved under the runs dir (foo → .fractal/foo). Runs live in .fractal/ in the directory you invoke from (discovered up the tree like git/bd); override with --runs-dir DIR. Provider/model flags match the engine: --provider, --model, --leaf-model, --child-model, --fake-script, --max-turns, --max-fanout, --max-leaf-concurrency, --call-timeout-ms.

-main clj

(-main & args)

cmd-chat clj

(cmd-chat pos flags)

cmd-cost clj

(cmd-cost pos flags)

cmd-fork clj

(cmd-fork pos flags)

cmd-help clj

(cmd-help _ _)

cmd-leaves clj

(cmd-leaves pos flags)

cmd-ls clj

(cmd-ls _pos flags)

cmd-prime clj

(cmd-prime pos flags)

cmd-resume clj

(cmd-resume pos flags)

cmd-run clj

(cmd-run pos flags)

cmd-show clj

(cmd-show pos flags)

cmd-step clj

(cmd-step pos flags)

cmd-stream clj

(cmd-stream pos flags)

cmd-trace clj

(cmd-trace pos flags)

cmd-tree clj

(cmd-tree pos flags)

cmd-verify clj

(cmd-verify pos flags)

dispatch clj

(dispatch cmd args)

Run a verb, returning {:out str :exit int}. Pure except for filesystem reads and (for drive verbs) running the engine — no printing, no System/exit (that's -main), so the surface is unit-testable.

handles? clj

(handles? cmd)

True for verbs this surface owns. Interactive chat and the legacy inspect stay in cli.

json-str clj

(json-str x)

node-address clj

(node-address token)

Normalize a node token to a projection address. nil/"root" → "root"; "child-0001" → "root/child-0001"; a stray leading "root/" is tolerated.

node-exit clj

(node-exit node)

parse-args clj

(parse-args args)

Split args into {:pos [..] :flags {..}}. --k v is a value flag; --k (followed by another flag or nothing) is boolean.

resolve-run clj

(resolve-run token {:keys [runs-dir]})

Resolve a run token to a dir: an existing path wins; otherwise <runs-dir>/<token>. Returns the dir string or nil.

verbs clj