CLAUDE.md

1# packages/agent
2 
3`@caveman-ai/agent`: opinionated TypeScript efficiency framework over exact-pinned
4Pi. `src/runtime.ts` owns agent execution, cache safety, tool isolation, runtime
5supervision, and content-blind evidence. Loopback runtime readiness requires
6health identity plus proxy-validated run-state/PID/executable ownership.
7`src/build.ts` owns finite candidate search, eval-complete selection, immutable
8lock, and drift checks.
9Build lock Context IR contains static definition segments only. Eval/user input,
10history, and tool results are runtime segments and never enter lock digest.
11Conversation handles are opaque, process-local, transactional, single-owner,
12and bind cache epoch to agent/model/full-plan/prefix fingerprint. Stream close
13aborts and settles provider/tool/subagent execution before releasing ownership.
14Dev reuses one immutable staged project-relative source graph until watched
15project inputs change. Definition, sandboxed tools, nested file sources, and
16lock identity use same snapshot. Reload preserves parent-owned conversation.
17Programmatic required-sandbox runs create per-run immutable copy of complete
18source graph before provider traffic and import tool workers only from copy.
19Keep module top level side-effect-free: Node ESM cannot tear down old graph
20timers/listeners after hot reload; restart when editing resource-owning modules.
21Nested normal tools use private root-relative agent paths, root/leaf definition
22digests, recursive graph validation, ancestor-shared pre-spend ledgers, and
23process-group sandbox teardown. Required sandbox policy propagates down graph;
24each reserved turn needs complete usage and exact provider/model identity.
25Third sandbox mode `host` is explicit opt-in for interactive/coding agents whose
26tools need real host access: closures run in-process with no worker and no
27`entryPath`, and `effect: "write"` executes instead of being blocked, while
28effect declaration stays mandatory. Host mode under a required ancestor fails
29closed (`cave_host_sandbox_nested_under_required`) so a subagent cannot escape
30root containment. Live host runs are lock-ineligible (EAB-101): `compile` throws
31`cave_host_sandbox_lock_ineligible` before any search run for host mode ANYWHERE
32in the definition graph — root or subagent, since a host subagent runs closures
33in this process just as a host root does — and locked builds for coding agents
34compile against fixture corpora (EAB-112) under a contained mode.
35Optional `RunOptions.maxCostUsd` seeds one root ledger into that same ancestor
36chain, so root turns reserve against it too. It is a best-effort public-catalog
37cap (EAB-102), not financial enforcement; exhaustion ends the run with
38`cave_run_cost_budget_exceeded` before the next model call, and a model the
39catalog cannot price fails closed instead of consuming $0 of budget.
40Cold machines degrade instead of failing: when the loopback gateway cannot be
41reached (or `RunOptions.cave: "off"` is set), the run keeps the provider's own
42base URL, applies no transform, sends no Caveman account key, and reports
43`RunResult.mode: "observe-only"`. `ensureRuntime: false` skips loopback startup
44and probing because the caller manages that runtime; it never bypasses HTTPS and
45gateway-identity verification for a non-loopback URL.
46Concurrent cold runs coalesce by gateway URL onto one readiness/start attempt;
47the completed positive or negative result is then cached for five seconds.
48Caller-supplied fetch transports bypass both shared states.
49Route resolution is not routing: the gateway proxies only `anthropic`, `openai`,
50and `google`, so every other Pi provider (xai, groq, bedrock, openrouter…) keeps
51its own base URL even on a reachable gateway. Actual routing is the source of
52truth for both honesty questions — a request that does not go through the
53gateway carries NO `x-cave-*` header at all (the account key is a credential;
54agent/workflow/session/cache-epoch/prefix-digest/context-bill/build+plan digests
55are account-linked identifiers), and `mode` is `observe-only`. Mixed graphs
56under-claim: one subagent call off the gateway makes the whole run
57`observe-only`.
58Gateway-routed Pi runs carry one framework-owned 32-hex trace id. Every root or
59child agent invocation gets a distinct 16-hex span id; provider requests name
60the current invocation through `x-cave-parent-span-id`, and child invocation
61spans share their parent invocation. With a route-time `CAVE_API_KEY`, children
62append only identity, timing, depth, and status metadata to one bounded
63root-owned batch; after descendants settle, the root defers exactly one
64best-effort OTLP/JSON request. Prompt, message, tool, result, and error content
65never enter that payload. Each child `invoke_agent` span also carries a bounded
66`cave.guard.*` manifest describing the controls effective at admission: only
67fixed categorical states for child call/spend/context, depth, root budget,
68per-turn fan-out, and total model/tool calls. It contains no thresholds, tool
69names, prompt/content, or spend. Its basis is `client_runtime_declared`: useful
70for advisory coverage and avoiding redundant proposals, never platform
71attestation, verified enforcement, or a reason to suppress a finding. Missing
72or ambiguous state is `unknown`, never inferred as unprotected. The immutable
73route-time key and root agent/workflow/session labels propagate through children;
74account-less local routing keeps request correlation headers but sends no
75unauthenticated OTLP request. The batch labels its delivery basis
76`attempted_unconfirmed`: HTTP
77acceptance is deliberately not awaited or surfaced, and export failure never
78changes paid execution, so Cloud detector coverage is measured and may
79honestly be zero.
80After every descendant settles, the root `invoke_agent` span emits four closed
81integer outcome attributes outside the guard manifest:
82`cave.agent.tree.admitted_descendants`,
83`cave.agent.tree.peak_active_descendants`,
84`cave.agent.tree.invocation_limit_rejections`, and
85`cave.agent.tree.concurrency_limit_rejections`. They are exact root-ledger
86outcomes, including admitted children whose individual span was dropped by the
871,024-span batch ceiling. They appear only on the root span and are zero when
88no child was admitted. They never contain configured cap magnitudes, content,
89task text, tool names, or error text, and do not change guard-manifest v2.
90Per-tool child-call counters, per-run model/tool counters, and breaker state
91still restart in every child; `maxCalls`, `maxSubagentDepth`, and the per-turn
92breaker are not tree-width contracts. Callers that need a root-tree bound may
93opt into `RunOptions.maxSubagentInvocations` (monotonic admissions across all
94tools and depths) and/or `maxConcurrentSubagents` (simultaneously active
95descendants). Descendants inherit one mutable root ledger; reservation is
96synchronous, and active capacity is released after success, error, or abort.
97Depth and wallet rejections happen before admission and consume no tree slot.
98Leaving both options unset preserves the prior behavior. New child spans emit
99strict guard-manifest v2: `tree_invocations` and `tree_concurrency` are each
100only `active` or `absent`, derived from whether the root option was supplied.
101The manifest never exports either numeric value and remains client-declared,
102not enforcement attestation. Historical v1 stays valid only when both v2-only
103keys are absent and cannot describe either tree control; malformed, missing, or
104unknown v2 states are invalid rather than inferred.
105A run carrying a locked build or candidate plan never degrades silently and
106throws `cave_gateway_required_for_locked_plan`. Nested runs inherit the parent's
107resolved route instead of re-probing. `doctor` treats a missing engine, missing
108runtime CLI, or unreachable gateway as WARN with exit 0 and reports
109`execution_mode`; locked-execution readiness stays false in that state.
110Child-process permission fails closed without portable descendant containment.
111`cave_` tool names are framework-reserved.
112Public `RunOptions` excludes nested routing/recursion and compiled plan/build
113identity. Only package-internal compiler/CLI path may execute validated plans.
114 
115Public entry points:
116 
117- `src/index.ts` and `src/primitives.ts` — builder API;
118- `src/build.ts` — compiler API;
119- `src/execution-kernel.ts` — locked harness/plan/Context-IR preparation,
120  shared agent-to-Context-IR lowering, selected model/reasoning enforcement,
121  provider usage validation, and public catalog cost finalization shared by Pi
122  runtime, compiler, checker, and adapter boundary. Reasoning-breakdown
123  availability stays separate from aggregate usage; locked/nested evidence
124  rejects a missing split from reasoning-capable models;
125- `src/runtime-identity.ts` — single source for framework, Pi adapter, and
126  exact-pinned upstream versions used by compiler, checker, and runtime;
127- `src/catalog.ts` — GENERATED from
128  `public/shared/provider-catalog/catalog/current.yaml` by
129  `scripts/generate-agent-catalog.mjs`; never hand-edit it and never hand-type a
130  price. It carries every USD row the catalog prices region-agnostically
131  (`region: global`) and omits regional-only rows rather than borrowing one
132  region's rate. `CATALOG_SHA256` is the sha256 of those exact catalog bytes and
133  is stamped into lock evidence; `tests/catalog.drift.runtime.mjs` fails until
134  the generator is re-run after a catalog edit. `RunResult.priceBasis` labels
135  whether `costUsd` came from that catalog or is an honest zero;
136- `src/source-graph.ts` — strict project/workspace dependency graph plus opaque
137  installed-package artifact closure. It uses `es-module-lexer` for ESM and
138  narrow comment-aware scanners for TypeScript type edges, `require`, and
139  `new URL(..., import.meta.url)`. It resolves ESM import-only exports,
140  follows dependency edges from physical package roots so pnpm symlink layouts
141  lock the same reachable artifacts as npm installs,
142  rejects computed project loaders, hashes every file in reachable installed
143  packages and their declared dependency closure, and never regex-parses vendor
144  comments as project source;
145- `src/code.ts` — the new caveman-code: `createCodingAgent` (host-sandbox
146  read_file/grep/bash/edit_file over one workspace, output capped BEFORE any
147  transform and under the 32 KiB inline tool-result ceiling so observe-only
148  works with no engine) plus the session surface `startCodingSession`,
149  `runCodingTurn`, `runCodingSession`. Optimized is the default:
150  `defaultCodingPlan` routes exactly one CCR-recoverable transform per live-zone
151  kind (`tool_result`→terminal, `history`→text; two routes on one kind collapse
152  into `dynamic_route_ambiguous`), never `toon`, with `cave_retrieve` on.
153  Degrading to observe-only is loud and recorded on `session.notices`; only
154  `cave_gateway_required_for_locked_plan` earns the one retry without the plan.
155  The route is resolved ONCE at `startCodingSession` and pinned on
156  `session.route`; every turn is handed it via the internal `caveRoute` option,
157  so a session makes exactly one runtime-ensure attempt however many turns it
158  runs, and session mode governs (degradation is sticky, and a turn override can
159  never re-open routing). Caller `overrides`/`runOverrides` face
160  `rejectInternalRunOptions` before any session-internal field is merged.
161  Tool containment is realpath-based (a symlink out of the workspace is out),
162  and `bash` runs its command in its own process group so a timeout kills the
163  tree instead of waiting on a backgrounded child's inherited stdout. `bash` is
164  **uncontained by design** — it runs arbitrary host commands with the user's
165  privileges — but its subprocess env is a fixed shell/locale allow-list, not a
166  spread of `process.env`, so a model-driven command cannot read the framework's
167  own account/provider credentials (`CAVE_API_KEY`, `ANTHROPIC_API_KEY`, …) and
168  exfiltrate them (issue #143).
169  Bills print token counts labelled `inferred (local estimate)` and spend in USD
170  with its `priceBasis` — no dollar figure is ever attached to a saving; a
171  zero-turn session prints an honest absence instead of basis-labelled zeros.
172  `proveRecovery` runs the real engine compress/retrieve pair and reports the
173  sha256 comparison. Live sessions are lock-ineligible by construction (host
174  mode anywhere in the graph, root or subagent, is refused by `compile`).
175  Example wrapper: `examples/coding-agent/`;
176- `src/claude.ts` — public unlocked Claude Agent SDK facade;
177- `src/claude-runtime.ts` — exact-pinned public Claude executor. Public calls
178  cannot inject build identity. Every locked/candidate call rejects before SDK
179  or MCP launch pending current source/runtime provenance, per-turn semantic
180  bills, byte-exact CCR proof, cached-substitution evidence, and parity replay.
181  Memory and framework subagents also remain fail-closed. Public tools are
182  read+inline only, inherited `x-cave-*` headers are stripped, model-specific
183  thinking capability is resolved before spend, and provider output usage is a
184  hard terminal ceiling. SDK aggregate output stays provider-reported, while its
185  unavailable authoritative thinking split is explicitly marked unavailable;
186- `src/adapters.ts` — public advanced adapter surface with explicit bundle/
187  dependency manifest digests and executable exact-pinned Vercel AI SDK 7.0.43,
188  Eve 0.29.2, and Mastra 1.55.0 bridges. Every call binds matching harness lock,
189  plan, Context IR, upstream identity, response model, complete usage, transforms,
190  recovery, and catalog cost. Eve supports reasoning-off locks because its durable
191  event contract omits reasoning usage. Pre-execution limit support is deliberately
192  framework-specific: Mastra alone accepts the adapter's opt-in `maxSteps`, passed
193  unchanged to `Agent.generate` and recorded in the adapter contract. Omitting it
194  preserves the existing call shape. Vercel's `stopWhen` belongs to construction of
195  the already-built `ToolLoopAgent`, not its generic `generate` call; Eve's client
196  `send` API exposes no server execution limit. Those integrations therefore require
197  an agent-construction/server-definition boundary before Caveman can enforce a
198  native limit. The Claude facade already forwards operator-supplied `maxTurns` and
199  `maxBudgetUsd`; its task-budget field does not qualify because upstream documents
200  task budgets as advisory and unsupported on Claude Code/Cowork, while its
201  provider-output check is post-execution. Neither is described as an adapter hard
202  cap. None of these
203  adapter controls proves dollar savings, a reserve-guaranteed cost cap, or fanout;
204- `src/cli.ts` — `dev`, `build`, `check`, zero-spend `doctor`, `register`;
205- `src/budget.ts` — the run budget contract. `RunOptions.budget` declares
206  exactly one denomination (`maxUsd` at public catalog list prices, or
207  `maxTokens`), runtime-gated on two independent grounds: the catalog must
208  price the model, AND the run must be billed in dollars — a Claude Pro/Max
209  subscription reached through Pi's credential store fails closed as
210  `cave_budget_denomination_unavailable`, read from `checkAuth` and never
211  inferred from the model. The regime is judged on the credential that
212  actually pays, so the check runs AFTER routing and does not apply to a
213  caller-supplied `streamFn` (that transport never asks Pi to authenticate
214  anything) or to a gateway-routed run (the account key pays, not the local
215  login). That last exemption holds only where the gateway supplies the
216  provider credential. Gateway readiness makes that boundary explicit:
217  managed returns `billing: "managed"`, standalone returns `billing: "byok"`,
218  and missing/unknown billing provenance falls through to the local credential
219  gate rather than authorizing dollars. The Claude lane reads the selected
220  `apiKeySource` from the SDK's first init message: OAuth/unknown auth reports
221  token counts but `costUsd: 0`, `priceBasis: "unpriced"`, and unpriced receipt
222  calls; `maxBudgetUsd` requires a positively identified API-key source.
223  Subscription dollars are fiction. Enforcement is reserve-and-clamp, one mode, no soft
224  option: each call reserves its worst case (byte-derived input ceiling capped
225  at the context window, times the catalog's worst rate, plus the configured
226  output allowance), and a remainder that cannot cover the full allowance
227  clamps the call's output down to what it affords, to
228  `OUTPUT_CLAMP_FLOOR_TOKENS`. The input ceiling includes whatever the request
229  could still GROW by if `onPayload` restores uncompressed originals on cache
230  drift, so the hold bounds the payload that actually leaves. Below the floor
231  the run stops **between** calls and returns a normal result carrying
232  `RunResult.stopReason` — never a throw, never mid-tool, and an in-flight call
233  always finishes and is counted. The runtime never *chooses* to spend past
234  max; when a provider nonetheless reports more than could be bounded, the
235  ledger records the REAL amount (never clamped — a rewritten ledger is fake
236  accounting), sets `capBreached` with a signed `overspent` on both
237  `RunResult` and its receipt, and funds nothing further — reserve, carve and
238  tranche release all refuse. `spent > max` never appears without that flag.
239  The FLAG rolls up from any subagent wallet that breached beneath the run
240  (the ordinary shape, since wallets are small carves); the AMOUNT does not —
241  `overspent` is always this level's own `max(0, spent − max)`, because
242  settling a carve books the child's real spend against the parent too, and
243  summing would count the same money twice and could print a figure larger
244  than the whole tree spent. Each subagent's amount is on its own receipt.
245  `capBreached` sits beside `stopReason` because both a clean stop at the cap
246  and a breached one report `budget_exhausted`.
247  `RunOptions.deadlineMs` stops at the same points. `maxCostUsd` is the older
248  error-terminating cap and cannot be combined with `budget`. `budget.ts` also
249  owns `RunResult.receipt`: every run — budgeted or not — returns the per-call,
250  per-tool, per-subagent breakdown plus tranche history. Its money figures are
251  **estimated list-price subtotals** from the public catalog, never invoices;
252  an unpriced call is flagged, never counted as free. Serialized receipts carry
253  `schema: caveman.agent.run-receipt.v1` and must validate against
254  `public/shared/contracts/schemas/agent-run-receipt.schema.json`. That shared
255  shape is not sent through the anonymous CLI telemetry lane; future hub upload
256  requires separate authenticated, tenant-scoped consent. Under a budget,
257  `subagent()` caps become **wallets**: the child's `maxCostUsd` (USD runs) or
258  `maxTokens` (token runs) is carved out of the parent's *remaining* budget
259  synchronously at spawn, so parallel spawns cannot double-spend, and the
260  unspent remainder returns to the parent when the child finishes. A revoked
261  parent revokes every wallet under it. `RunOptions.maxSubagentDepth` defaults
262  to 2 and is capped at `ABSOLUTE_SUBAGENT_DEPTH_LIMIT`. Budget can be **staged**:
263  `budget.initialUsd`/`initialTokens` meters the run against a first tranche and
264  `createBudgetController()` + `RunOptions.budgetController` lets the developer's
265  own deterministic checkpoints release more, up to `max` — releasing past `max`
266  throws at the release site. No model can reach the controller (detection law 1:
267  never a model in the money path), and a controller is inert outside its run.
268  `RunOptions.onBudgetExhausted` is `"stop"` by default; a handler instead gets
269  the read-only exhaustion context between calls (never mid-tool) and answers
270  `"stop"` or `{ release, reason }`, which tops up a tranche through the same
271  `max`-bounded mechanism. Exactly one escalation per exhaustion. Pausing and
272  resuming a run from a serializable handle is deliberately not built;
273- `src/breakers.ts` — opt-in deterministic circuit breakers
274  (`RunOptions.breakers`): repeated-tool-call loop detection (exact
275  tool+normalized-args hash within a configurable assistant-turn window,
276  default 8, with `tool({ allowRepeat: true })` for legitimately repetitive
277  tools), a no-progress window over turn outcome signatures, a
278  per-turn fan-out cap, and retry budgeted in the run's denomination rather than
279  by attempt count. Each retry takes a real BudgetMeter hold; pre-stream
280  failures cancel at measured zero, successful attempts settle provider usage,
281  and receipt events expose reserved + measured spend with basis. Old exact
282  repeats decay out of the turn window instead of poisoning a long run. Local
283  enforcement shares worker F16's H6 edge rule — including exclusion of a
284  repeat following a failed attempt — but does not claim parity with worker-side
285  session SCC + population Isolation-Forest finding arithmetic. No model runs
286  anywhere in this path.
287  No-progress signatures include tool identity/result; successful declared
288  writes reset that window because identical text cannot prove host state stayed
289  unchanged. Breaking stops between calls with
290  `stopReason: "loop_detected"` / `"no_progress"`; the fan-out cap only blocks
291  the extra calls. Every decision lands on `receipt.breakers`;
292- `src/compaction.ts` — budget-triggered compaction, and **the only place in this package
293  that rewrites model-visible context**. That is why it lives here: compaction
294  is a model-visible rewrite, so it can exist only where the builder owns the
295  context — no wrap or gateway path ever performs it. The exhaustion ladder is
296  **evict → summarize → clamp → stop**. Default-on compaction triggers when
297  remaining budget falls below four full cold next-call ceilings; `"stop"`
298  skips that pre-emptive rung and only clamps/stops once a call stops fitting.
299  Eviction is free and deterministic: stale tool output becomes a
300  citation carrying its digest, selected by role and freshness — the class is
301  safe to elide because every runtime tool result the IR lowers carries
302  `recovery: "exact_ccr"`, but the choice is not driven off each segment's own
303  `recovery` field.
304  Summarization is a real provider call metered from the same budget and from
305  every ancestor subagent wallet, built by the same request shape as a working
306  call — same system prompt, same tool definitions, same history, same gateway
307  headers, instruction appended last. Its usage joins `RunResult`'s own totals,
308  not just the receipt. The rung is closed once the run has decided to stop: a
309  turn that asked for no tools, a tripped breaker, or an expired deadline all
310  skip it, because no working call would follow. Its reserve is priced **cold,
311  always** — the rewrite diverges from the working call's prefix at its first
312  changed message, so a warm read there is not evidence for a warm read here.
313  Earlier timing makes the own-model default reachable without discounting its
314  cold reserve; a cheap-class summarizer remains an opt-in gated on its context
315  window covering the history. Cold pricing is not the whole story: the input ceiling is a UTF-8 BYTE
316  count (~3-4x the real token count), so both the working call and the
317  summarizer are priced ~4x high, which pushes the affordability trigger earlier
318  than a true-token ceiling would. Tightening it needs a provider count-tokens
319  endpoint (issue #165); until then the byte bound is kept because it never
320  under-reserves. A subagent with a carved wallet uses that child meter as its
321  sole economic boundary, so its compaction can run and rolls usage into the
322  parent receipt; an unfunded child cannot borrow around the parent. Other
323  preconditions: a yield floor and headroom for several working
324  calls. `maxCompactions` counts attempts that actually reserved — a free
325  decline does not burn it. Safeguards after: schema-validated
326  sectioned summary (invalid ⇒ discard and clamp), a constraint-integrity
327  assertion comparing the accepted rewrite's CONTENT against every pinned
328  segment (identity comparison cannot fail), an inflation guard, and a
329  self-contained tail so no tool result outlives its call. `receipt.compactions`
330  keeps the REAL metered cost and the MODELED effect in separate fields with
331  separate bases; the word "saved" appears nowhere.
332 
333`doctor` is framework readiness truth surface: Node, sandbox, engine registry,
334runtime CLI, project/Context IR, lock drift, provider selection, and per-harness
335locked-execution state. Caveman public CLI version probe is `caveman version`
336(not `--version`). Optional project/provider warnings do not hide foundation
337failures; Claude detail distinguishes public execution from fail-closed Cave
338Build execution; third-party adapter readiness remains separate per harness.
339 
340Claude Agent SDK dependency is governed by Anthropic Commercial Terms linked
341from its README, not package MIT license. Keep disclosure in public README.
342 
343Run `pnpm --dir public/agent test`. Unknown state fails closed. Transform failure
344passes original bytes. Missing usage/pricing/eval/recovery writes no optimized
345lock. Local evidence is always `inferred`; this package never mints verified
346savings.
347 
348Authority: `docs/strategy/EFFICIENT_AGENT_BUILDER_SPEC.md`.
349