The audited agent compartment

cruft agent run executes a script, canonically code an LLM wrote, inside a fail-closed, budgeted compartment where every authority is explicit and every action is a JSONL audit record. Covers the programming model, the full run flag reference, budgets, approvals, secrets, audit records, and doctor.

cruft agent runs a piece of code, canonically code an LLM wrote, inside a fail-closed, budgeted, fully audited compartment. It is the isolation story (compartments) productized for the agent use case: every authority is explicit, every action is a JSONL audit record, every resource has a budget, and the whole run is replayable from that log.

cruft agent run agent.js --timeout-ms=500 --audit-log=audit.jsonl \
  --tool=echo --context-json='{"goal":"summarize"}'
cruft agent doctor              # machine-readable control inventory
cruft agent replay audit.jsonl  # summarize a recorded run

Beyond a single run, cruft agent schedule turns the one-shot sandbox into a durable, resumable, multi-turn job: an agent can suspend at a tool call, a timer, or a human approval, persist its whole state to disk, and resume, even after a full process restart, still inside the same fail-closed compartment. That durability makes cruft agent a harness for long-running agents whose jobs outlive the process that started them.

This page is the overview: the programming model, the full cruft agent run flag reference, budgets, async behavior, the approval and secret mechanics, the audit-log record types, and doctor. Three companion pages go deeper:

• The durable multi-turn scheduler.
• Every tool, what it can touch, and its schema.
• Projects, policy files, and the commands that build and pin them.

Subcommand map

cruft agent is one verb with many subcommands. Running an agent and inspecting a run live here; authoring and pinning a project live on the companion pages.

The agent programming model

An agent file is a script evaluated in strict mode inside the compartment, with a small endowed surface:

Round trip:

// agent.js
emit({ kind: "start", goal: context.goal });
const r = callTool("echo", { value: context.goal });
emit({ kind: "tool-result", r });

{"type":"run_start","tools":["echo"],"event_budget":{...},...}
{"type":"event","event":{"kind":"start","goal":"docs-probe"},...}
{"type":"tool_call","tool":"echo","policy":"allowed","args":{...},"arg_bytes":22,...}
{"type":"tool_result","tool":"echo","result":{...},"result_bytes":22,...}
{"type":"availability_check",...}
{"type":"authority_check","object_prototype_polluted":false,"global_polluted":false,...}
{"type":"state_snapshot","state":{},...}

Note the authority_check record: the runtime verifies after the turn that the agent did not pollute Object.prototype or the global. This is tamper evidence recorded after the turn, on top of the prevention the boundary already enforces.

Fail-closed authority

Nothing is ambient.

• Tools are an explicit registry. With no --tool=echo flag, callTool("echo", …) throws agent tool denied: echo, the run fails, and the audit log records a tool_denial. The built-in tool set exists for harness use; process requires a supervisor that is not yet available and says so. The full manifest is on Agent tools.
• Modules are an explicit policy. Imports resolve only through --module specifier=path (inline admission), --package specifier=path with --package-integrity specifier=fnv1a64:hash (hash-capped package graphs), or --import-hook with its own source-hash cap. Ambient node_modules fallback is denied. --entry-module selects a static module entrypoint instead of script mode. See Projects & policy.
• The tool membrane clones and classifies. Arguments and results are JSON-cloned across the boundary (no shared mutable objects), byte-budgeted, and failures are classified (invalid shape vs. denial vs. tool error) in the audit record.

cruft agent run flag reference

Every flag below appears in the shipping run usage. The agent file is the one positional argument (or --entry-module in module mode). Alternatively, pass --project=<dir> or --policy=<agent-policy.json> to take identity, authority, budgets, and inputs from a project (see Projects & policy); flags on the command line still apply.

Identity and output

Tools and approval

Tool inputs

Modules

Context, state, and session

Budgets

Budgets: everything is bounded

Pending promises at turn end are detached, not awaited, an agent cannot extend its life by leaving work dangling. Project policy files carry their own budget block (for example the package-review template pins timeout_ms: 500, tool_timeout_ms: 250, max_events: 16); those values override the defaults above when you run from a project.

Async, timers, and the availability check

Asynchrony is bounded and audited the same way authority is. At turn end the runtime writes an availability_check record, a self-attestation of exactly how each async effect was handled, and the behavior behind each field is enforced, not advisory:

• No ambient timers. An agent compartment has no setTimeout or clearTimeout (typeof setTimeout === "undefined"), attested as timer_handles: "not_endowed_use_scheduler_sleep_protocol". Microtasks still run (Promise.resolve().then(…) fires within the microtask budget), but any real wall-clock delay must go through the durable scheduler's scheduler.sleep. There is no way for an agent to arm a background timer.
• Pending promises are detached. A promise that never settles does not hang the turn; at turn end it is detached (pending_promise_disposition: "detached_at_turn_end") and the run still ends ok. An agent cannot extend its life by leaving async work dangling.
• Async tool calls are independently timed. callTool(...).then(...) is gated by --tool-timeout-ms, separate from the wall timeout. An overrun writes a tool_timeout record (with the budget), the success continuation never fires, and the tenant's rejection handler runs, the run can still end ok because the rejection was handled.
• Revocation crosses the async boundary. A synchronous close() writes a revocation record; a queued microtask continuation that touches a surface (emit, callTool, state.set) after the close is refused and logged as a revocation_denial. A continuation cannot escape a revocation that already happened this turn.
• Unavailable capabilities fail closed, visibly. An async effect that needs an ambient capability the build does not endow (for example the process tool's supervisor, or the full worker membrane) does not run best-effort: it aborts before any tenant event and writes a single unsupported_control record naming the control and a …required_not_available reason. The effect is refused and named, never partially performed.

Approval workflow

Any tool can be put behind a pre-effect gate. Under --require-approval=<tool>, each call to that tool is held before it can touch anything; the gate consults --approve-tool=<tool> (a pre-approval for this run) and the durable --approval-log=<approval.jsonl>. Decisions in the log older than --approval-max-age-ms=<n> are treated as stale and do not satisfy the gate.

Decisions are recorded out of band with:

cruft agent approval allow audit/approval.jsonl <approval-id> --reason="reviewed diff"
cruft agent approval deny  audit/approval.jsonl <approval-id> --reason="unexpected host"

The gate runs the same way on the same thread and under --worker (the worker path routes the decision through its host-call RPC). Approvals and denials are replay-visible: they appear in the audit log so a reviewer sees exactly which calls were held and how they were resolved.

Secrets and named-network cache

Secrets are env-only. --secret=<tool=ENV> binds a named environment variable as a secret scope for one tool; --model-api-key-env and --github-token-env name the env vars for the model and GitHub credentials. In every case the audit record stores the env-var name and the credential mode, never the value. There is no way to hand a tool a literal secret on the command line, so the value cannot leak into a log or a shell history.

The named-network tools (osv.query, npm.metadata, the github.* readers, and model.call) can be backed by a persistent cache. --named-network-cache-dir sets the directory; --named-network-cache-mode=read-through fetches and caches, while offline serves only from the cache and never touches the network. --named-network-cache-max-age-ms and --named-network-cache-max-entries bound freshness and size, and cache hits and misses are replay-visible so there is no hidden freshness claim. --named-network-retry-attempts=<0..3> adds bounded live retries whose backoff and outcome are also audited.

Audit log record types

The JSONL audit log is the run's complete record. The type field takes these values:

Replay also surfaces module imports and denials, session loads and saves, budget breaches, timeouts, and RSS breaches. Replay is a pure function of the log: cruft agent replay audit.jsonl reduces it to a one-glance summary of runs, events, tool calls, results, denials, and errors, and cruft agent replay --diff [--events] before.jsonl after.jsonl compares two recorded runs (add --events to diff the event streams too).

State, sessions, and turns

State is deliberately a single-turn store: the state object is snapshotted to the audit log at turn end and reset between turns (a counter agent run twice through the same --session-file reports count: 1 both times). --session-file provides turn lineage, the session records the advancing turn_id, not ambient memory. An agent that should remember something must emit it, and its operator must feed it back through --context-json or --state-json: memory crosses the boundary explicitly, where it is visible and auditable, or not at all.

cruft agent doctor

Doctor emits one JSON object inventorying every control and its exact status. Two controls are reported as currently not available: the process-tool supervisor (so the shell, exec, and spawn tools are listed unavailable with reason=process_tool_supervisor_required_not_available), and the full worker membrane (--worker today forwards emits, tools, state, and the rest, but the complete membrane is required_not_available). Its closing field is the discipline in one line:

"public_claim_predicate": "sandbox claims must be scoped to listed controls"

A sandbox claim about cruft agent may only cite what doctor lists as enforced, the anti-overclaim rule, machine-checkable. Pass cruft agent doctor --project <dir> to scope the inventory to a project's resolved authority.

Reading the design

Three ideas organize the design:

1. Audit is the product. The JSONL log is complete enough that replay is a pure function of it; the run's story is data.
2. Budgets compose with authority. Capability control says what an agent may touch; budgets say how much, count, bytes, steps, microtasks, memory, time. The boundary enforces both; the agent is never asked to limit itself.
3. doctor scopes the claims. Unfinished controls are listed as not available rather than omitted, and the public claim predicate scopes what may be said to what is listed.