car-runtime 0.52.1 → 0.53.0

package/README.md

@@ -74,6 +74,36 @@ const result = await executeProposal(rt, proposal, async (callJson) => {
 });
 ```
 
+## Packaged agent loop
+
+Do not copy a harness into each agent. Import the versioned loop and keep the
+project entry file declarative:
+
+```javascript
+import { main } from 'car-runtime/agent-loop';
+
+main({
+  agentName: 'Lookup Agent',
+  identity: 'Use lookup before answering; never guess.',
+  toolSchemas: [{
+    name: 'lookup', description: 'Look up one key',
+    parameters: { type: 'object', properties: { key: { type: 'string' } }, required: ['key'] },
+  }],
+  tools: { lookup: async ({ key }) => ({ key, value: await lookup(key) }) },
+  policies: [],
+  maxTurns: 8,
+});
+```
+
+`runAgent(config, goal)` is also exported for embedding and tests. `main(config)`
+provides `--task`, `--json`, and `--serve`. The loop adds `finish`, statically
+verifies every proposal before execution, preserves tool-call/result IDs,
+honors per-schema `timeoutMs`, traces task and chat runs, and uses request-shaped
+inference with prompt-cache breakpoints. It loads the native binding only when a
+loop runs, so `require('car-runtime/agent-loop')` is safe for package discovery.
+Type declarations ship as `agent-loop.d.ts` and shared config/outcome types in
+`index.d.ts`.
+
 Full API reference lives in [`index.d.ts`](./index.d.ts). The package also
 ships a `docs/` directory (`node_modules/car-runtime/docs/`) with prose
 reference docs — `SPEC.md`, `GUIDE.md`, `CLI.md`, `ASSISTANT.md`, `MCP.md`,

package/agent-loop.d.ts

@@ -0,0 +1,30 @@
+import type {
+  AgentLoopConfig,
+  AgentLoopOptions,
+  AgentOutcome,
+  AgentToolSchema,
+  AgentTool,
+  CarRuntime,
+} from './index';
+
+export function runAgent(
+  config: AgentLoopConfig,
+  goal: string,
+  options?: AgentLoopOptions,
+): Promise<AgentOutcome>;
+
+export function runChatTurn(
+  runtime: CarRuntime,
+  config: AgentLoopConfig,
+  toolSchemas: AgentToolSchema[],
+  tools: Record<string, AgentTool>,
+  toolTimeouts: Record<string, number>,
+  sessionId: string,
+  messages: Record<string, unknown>[],
+  requestedModel?: string | null,
+): Promise<string>;
+
+export function main(config: AgentLoopConfig): Promise<void>;
+
+declare const agentLoop: { main: typeof main; runAgent: typeof runAgent; runChatTurn: typeof runChatTurn };
+export default agentLoop;

package/agent-loop.js

@@ -0,0 +1,578 @@
+'use strict';
+
+// Versioned generic CAR agent loop. Agent projects import this package export;
+// they do not copy or fork the propose -> verify -> execute -> observe cycle.
+// The native binding is loaded lazily so tooling can inspect/require this
+// subpath without first installing a platform binary.
+let nativeApi = null;
+let cancelHandlerInstalled = false;
+function runtimeApi() {
+  if (nativeApi === null) nativeApi = require('./index.js');
+  if (!cancelHandlerInstalled && typeof nativeApi.registerToolCancelHandler === 'function') {
+    nativeApi.registerToolCancelHandler((requestId) => {
+      const ctl = ABORTS.get(requestId);
+      if (ctl) {
+        ABORTS.delete(requestId);
+        try { ctl.abort(new Error('tool callback reaped by daemon (budget exceeded)')); } catch { /* already aborted */ }
+      }
+    });
+    cancelHandlerInstalled = true;
+  }
+  return nativeApi;
+}
+
+// Process-wide abort registry keyed on the daemon's per-call `request_id`
+// (Parslee-ai/car#264). When the daemon reaps a tool callback (the call
+// exceeded its budget) it emits `tools.cancel` with the `request_id`; the
+// handler below aborts the matching controller so a long child (e.g. a
+// `claude -p` / `codex exec` driven by drive_cli) is killed instead of
+// orphaned. Each tool callback registers its controller under its request_id
+// and removes it on completion. Registered once at module load; a daemon
+// without the cancel surface simply never fires it.
+const ABORTS = new Map();
+
+// A built-in sentinel tool every agent gets for free, so the loop always has a
+// clean way to terminate with a final answer. Your agent calls finish(answer).
+const FINISH_SCHEMA = {
+  name: 'finish',
+  description: 'Return the final answer to the user and stop. Call this exactly once, when the task is complete or cannot proceed.',
+  parameters: {
+    type: 'object',
+    properties: { answer: { type: 'string', description: 'The final answer or status for the user.' } },
+    required: ['answer'],
+  },
+};
+
+function buildProposal(modelUsed, toolCalls, toolTimeouts = {}) {
+  // Glue between the inference IR (ToolCall {id,name,arguments}) and the
+  // action IR (Action {id,type,tool,parameters,timeout_ms}). The only IR
+  // plumbing you owe.
+  //
+  // `timeout_ms` (Parslee-ai/car#259): a tool that shells out to a build,
+  // drives another CLI, or calls a slow API needs more than the daemon's
+  // default callback budget. Declare `timeoutMs` on the tool's schema and
+  // it flows here as the action's per-call budget — without it the call is
+  // reaped at the default. Omitted (undefined) when the schema sets none,
+  // so the action falls back to the daemon default.
+  return JSON.stringify({
+    source: modelUsed || 'model',
+    actions: toolCalls.map((tc, i) => ({
+      id: tc.id || `a${i}`,
+      type: 'tool_call',
+      tool: tc.name,
+      parameters: tc.arguments || {},
+      dependencies: [],
+      timeout_ms: toolTimeouts[tc.name],
+    })),
+  });
+}
+
+/**
+ * Build the `executeProposal` tool callback. ONE implementation, used by BOTH
+ * the one-shot `--task` loop (`runAgent`) and the `--serve` chat path
+ * (`runChatTurn`). They used to carry two copies, and the chat copy silently
+ * missed `timeout_ms` and the `request_id`/AbortController wiring — the path a
+ * registered CarHost agent actually runs. Do not re-fork it.
+ *
+ * The callback receives { tool, params, action_id, request_id, timeout_ms }.
+ * The `request_id` keys this call's abort controller (Parslee-ai/car#264) so
+ * the daemon's `tools.cancel` can kill a reaped child. The tool fn receives the
+ * budget (timeoutMs) and an AbortSignal as a second arg; tools that shell out
+ * should honor the signal (e.g. pass it to child_process / fetch) so a reap
+ * actually terminates their child. The callback's `timeout_ms` is authoritative
+ * — it is the budget of the action actually executing (Parslee-ai/car#259) — so
+ * it wins over the locally derived `toolTimeouts` map, which is the fallback.
+ * `onFinish` (optional) is called with the `finish` tool's answer.
+ */
+function makeToolCallback(tools, toolTimeouts = {}, onFinish = null) {
+  return async (callJson) => {
+    const { tool, params, request_id: requestId, timeout_ms: timeoutMs } = JSON.parse(callJson);
+    const fn = tools[tool];
+    if (!fn) throw new Error(`unknown tool: ${tool}`);
+    const ctl = new AbortController();
+    if (requestId) ABORTS.set(requestId, ctl);
+    try {
+      const out = await fn(params || {}, { signal: ctl.signal, timeoutMs: timeoutMs ?? toolTimeouts[tool] });
+      if (tool === 'finish' && onFinish) onFinish((out && out.answer) ?? '');
+      return JSON.stringify(out ?? {});
+    } finally {
+      // In a `finally` so a throwing tool can never leak its entry.
+      if (requestId) ABORTS.delete(requestId);
+    }
+  };
+}
+
+// ---- Prompt caching (Anthropic) --------------------------------------------
+//
+// The loop resends the WHOLE growing thread every turn, so an N-turn run bills
+// the stable prefix N times at the full input rate — cost that grows with the
+// square of the turn count. CAR's protocol layer already knows how to mark
+// Anthropic cache breakpoints; it only needs `cache_control: true`, and the
+// 9-positional-argument `inferTracked` has no slot to carry it. That is the
+// whole reason every caller has been paying full price: the flag exists, the
+// call shape could not reach it. `inferTrackedWithRequest` takes the options
+// object (a JSON `GenerateRequest`) and can.
+//
+// BREAKPOINT PLACEMENT — we do not pick it; CAR does, and its choice is already
+// the max-reuse one (car-inference/src/protocol.rs, AnthropicHandler::
+// build_request_body). With `cache_control: true` it emits three of Anthropic's
+// four allowed breakpoints:
+//   1. the system block — identity plus the finish instruction, byte-identical
+//      for the entire run;
+//   2. the LAST tool definition — so identity + every tool schema forms ONE
+//      cached prefix, the largest genuinely stable block this loop has;
+//   3. the LAST message — the moving breakpoint. Anthropic serves the longest
+//      cached prefix it can find, so each turn writes only its own delta and
+//      READS everything the previous turn wrote. That is what turns quadratic
+//      re-billing into one write plus N cheap reads.
+// The 4th breakpoint is deliberately left unused. It would buy a
+// `context_stable_prefix` split of the system prompt, which helps only when the
+// system prompt has a volatile tail; ours has none, so splitting it would
+// shrink the cached block rather than grow it.
+//
+// TTL — `one_hour`, not the 5-minute default. Turns in an agentic loop are
+// separated by real tool execution (browser drives, FMS reads, verification),
+// which routinely exceeds five minutes; a 5-minute entry would expire mid-run
+// and re-bill the entire prefix as a fresh write. A 1h write costs ~2x base
+// input against ~1.25x for 5m, but that one-time 0.75x is far cheaper than a
+// single full re-write of the prefix, and every surviving turn then reads at
+// ~0.1x.
+//
+/** One request-shaped, cache-aware inference path for task and chat loops. */
+async function inferTurn(rt, { model, maxTokens, toolSchemas, messages, toolChoice = 'auto' }) {
+  return JSON.parse(await rt.inferTrackedWithRequest(JSON.stringify({
+    prompt: '',
+    model: model ?? null,
+    params: {
+      max_tokens: maxTokens,
+      tool_choice: toolChoice,
+      strict_model: model != null,
+      cache_ttl: 'one_hour',
+    },
+    tools: toolSchemas,
+    messages,
+    cache_control: true,
+  })));
+}
+
+/**
+ * Run the agent once toward `goal`. Returns an AgentOutcome-shaped object:
+ *   { status, summary, evidence[], metrics{}, tools_called[] }
+ * `status` is one of the six OutcomeStatus values (success|partial_success|
+ * done|give_up|timeout|failure). AgentOutcome is caller-built — CAR does not
+ * return it; we assemble it from what the loop observed.
+ *
+ * Run-trace lifecycle: each `runAgent` invocation is one run. Before the first
+ * proposal we bracket the run open with `rt.runsStart` (daemon mints a durable
+ * `run_id`); after the terminal AgentOutcome is assembled we close it with
+ * `rt.runsComplete`. Both are best-effort and never print, so the daemon traces
+ * the run for CarHost while older daemons (no runs.*) behave exactly as before.
+ */
+async function runAgent(config, goal, { maxTurns } = {}) {
+  const { CarRuntime, executeProposal } = runtimeApi();
+  const turnsCap = maxTurns ?? config.maxTurns ?? 8;
+  const toolSchemas = [...(config.toolSchemas || []), FINISH_SCHEMA];
+  const tools = { finish: ({ answer }) => ({ answer }), ...(config.tools || {}) };
+  // Per-tool execution budget (Parslee-ai/car#259): a tool schema may set
+  // `timeoutMs` (e.g. a CLI driver that runs for 180s); it flows onto each
+  // action so the daemon honors it instead of reaping at the default.
+  const toolTimeouts = Object.fromEntries(
+    toolSchemas.filter((s) => s && s.timeoutMs != null).map((s) => [s.name, s.timeoutMs]),
+  );
+
+  const rt = new CarRuntime();
+  // Best-effort: some daemon versions don't expose agents.register_basics. It
+  // only adds CAR's built-in utility tools, which a tool-declaring agent doesn't
+  // depend on, so a missing method must not abort the run.
+  try { await rt.registerAgentBasics(); } catch { /* unsupported on this daemon — fine */ }
+  for (const s of toolSchemas) await rt.registerTool(s.name);
+  // Guardrails are declarative policies, enforced in Rust BEFORE the tool fires
+  // — not prompt rules. Each entry is the argument list for registerPolicy.
+  for (const p of (config.policies || [])) await rt.registerPolicy(...p);
+
+  // Run-trace bracket (open). Tell the daemon a run is starting so CarHost can
+  // trace it: prompt -> CLI outcome -> verifier verdict -> AgentOutcome. The
+  // daemon mints a durable run_id and tags it as this session's current run
+  // BEFORE replying, so the per-turn recorder reads the right id; we await that
+  // ack before submitting any proposal. The owning agent_id resolves from
+  // CAR_AGENT_ID (the supervisor injects it) when supervised, else falls back to
+  // config.agentName for the unsupervised one-shot / run_scenarios path.
+  // Best-effort, exactly like registerAgentBasics: a daemon without runs.* (an
+  // older build) makes this throw, and the run must continue unchanged. NEVER
+  // print here — the last stdout line in --json mode must stay the AgentOutcome
+  // (run_scenarios.py parses it).
+  let runId = null;
+  try {
+    const started = JSON.parse(await rt.runsStart(JSON.stringify({
+      intent: goal,
+      agent_id: process.env.CAR_AGENT_ID || config.agentName,
+      agent_name: config.agentName,
+      outcome_description: config.targetOutcome ?? '',
+    })));
+    runId = started.run_id ?? null;
+  } catch { /* daemon lacks runs.* — degrade to untraced behavior */ }
+
+  // Local Qwen3 models default to "thinking" (they emit a long <think> block
+  // before acting), which on a multi-tool agent prompt can exceed the daemon's
+  // per-call read timeout — the agent loop then fails with a timeout instead of
+  // calling a tool. When pinned to a local model, append Qwen3's `/no_think`
+  // soft switch so it acts via tools directly. Only applied for clearly-local
+  // model ids (a null/router model may resolve to a cloud model, where thinking
+  // is fine and fast); cloud models simply ignore the token.
+  const isLocalModel = typeof config.defaultModel === 'string'
+    && /^(mlx|qwen)\//.test(config.defaultModel);
+  const noThink = isLocalModel ? '\n\n/no_think' : '';
+  const messages = [
+    { role: 'system', content: `${config.identity}\n\nWhen the task is complete or you cannot proceed, call the \`finish\` tool with a concise answer. Do not narrate; act via tools.${noThink}` },
+    { role: 'user', content: goal },
+  ];
+
+  const metrics = { turns: 0, tool_calls: 0, actions_succeeded: 0, actions_failed: 0 };
+  const toolsCalled = new Set();
+  let outcome = null;        // null === no terminal AgentOutcome yet
+  let turns = 0;
+
+  while (outcome === null) {
+    if (++turns > turnsCap) {
+      outcome = mkOutcome('timeout', `hit ${turnsCap}-turn cap without finishing`,
+        [{ kind: 'stop_reason', description: 'max turns', data: { turnsCap } }], metrics, toolsCalled);
+      break;
+    }
+    metrics.turns = turns;
+
+    // 1. PROPOSE — multi-turn, tool-aware inference (NOT plain `infer`).
+    let tracked;
+    try {
+      tracked = await inferTurn(rt, {
+        model: config.defaultModel ?? null,
+        maxTokens: config.maxTokens ?? 1024,
+        toolSchemas,
+        messages,
+      });
+    } catch (e) {
+      outcome = mkOutcome('failure', `inference failed: ${e.message || e}`,
+        [{ kind: 'stop_reason', description: 'infer_tracked error', data: null }], metrics, toolsCalled);
+      break;
+    }
+
+    const calls = tracked.tool_calls || [];
+    if (calls.length === 0) {
+      // Model answered in prose with no tool call — treat as a neutral Done.
+      outcome = mkOutcome('done', tracked.text || 'no further actions',
+        [{ kind: 'self_assessment', description: tracked.text || '', data: null }], metrics, toolsCalled);
+      break;
+    }
+
+    // Normalize ids so assistant tool_calls and tool_results correlate across
+    // turns (local models often omit ids).
+    calls.forEach((c, i) => { c.id = c.id || `a${i}`; });
+    messages.push({ role: 'assistant', content: tracked.text || '', tool_calls: calls });
+    const idToTool = Object.fromEntries(calls.map((c) => [c.id, c.name]));
+
+    const proposal = buildProposal(tracked.model_used, calls, toolTimeouts);
+
+    // 2. VERIFY — static gate. Never execute an unverified proposal.
+    let check;
+    try {
+      check = JSON.parse(await rt.verifyProposal(proposal));
+    } catch (e) {
+      outcome = mkOutcome('failure', `verification failed: ${e.message || e}`,
+        [{ kind: 'stop_reason', description: 'verifyProposal error', data: null }], metrics, toolsCalled);
+      break;
+    }
+    if (!check.valid) {
+      // Feed the rejection back as tool_results so tool_use/tool_result stay
+      // paired, then let the model repair on the next turn.
+      for (const c of calls) {
+        messages.push({ role: 'tool_result', tool_use_id: c.id,
+          content: JSON.stringify({ error: `runtime rejected proposal: ${JSON.stringify(check.issues)}` }) });
+      }
+      continue;
+    }
+
+    // 3. EXECUTE — CAR owns the DAG, retries, timeouts, rollback. The callback
+    // receives { tool, params } (note: `params`).
+    let finishAnswer = null;
+    let result;
+    try {
+      result = JSON.parse(await executeProposal(rt, proposal,
+        makeToolCallback(tools, toolTimeouts, (a) => { finishAnswer = a; })));
+    } catch (e) {
+      outcome = mkOutcome('failure', `execution failed: ${e.message || e}`,
+        [{ kind: 'stop_reason', description: 'executeProposal error', data: null }], metrics, toolsCalled);
+      break;
+    }
+
+    // 4. OBSERVE — feed each ActionResult back as a tool_result turn.
+    // tools_called records tools that SUCCESSFULLY executed, so a policy-denied
+    // /failed tool is correctly absent (guardrail scenarios can assert
+    // tool_not_called against it).
+    for (const r of (result.results || [])) {
+      const ok = r.status === 'succeeded';
+      if (ok && idToTool[r.action_id]) toolsCalled.add(idToTool[r.action_id]);
+      messages.push({ role: 'tool_result', tool_use_id: r.action_id,
+        content: JSON.stringify(ok ? (r.output ?? {}) : { error: r.error }) });
+      metrics.tool_calls += 1;
+      if (ok) metrics.actions_succeeded += 1; else metrics.actions_failed += 1;
+    }
+
+    // 5. Terminal? finish() succeeded -> success.
+    if (finishAnswer !== null) {
+      outcome = mkOutcome('success', finishAnswer,
+        [{ kind: 'tool_result', description: 'finish called', data: { answer: finishAnswer } }], metrics, toolsCalled);
+    }
+    // else: loop for the next proposal.
+  }
+
+  // Run-trace bracket (close). Report the terminal AgentOutcome to the daemon so
+  // CarHost shows the run's final status and stops streaming it. Await the ack
+  // before returning (the connection may close right after) so a healthy run is
+  // never raced into `Incomplete`. Best-effort + never prints, mirroring the
+  // open bracket: an older daemon without runs.* (or one that never acked the
+  // start, leaving runId null) just skips this and behaves as before.
+  if (runId !== null) {
+    try {
+      await rt.runsComplete(JSON.stringify({ run_id: runId, outcome }));
+    } catch { /* daemon lacks runs.* — nothing to report to */ }
+  }
+
+  return outcome;
+}
+
+function mkOutcome(status, summary, evidence, metrics, toolsCalled) {
+  return { status, summary, evidence, metrics, tools_called: [...toolsCalled].sort(), timestamp: new Date().toISOString() };
+}
+
+// ---- CLI entrypoint -------------------------------------------------------
+//
+//   node agent.mjs --task "<goal>" [--json]      one-shot; prints outcome
+//   node agent.mjs --serve                       supervised/standing mode
+//
+// run_scenarios.py invokes the --task --json form.
+
+function parseArgs(argv) {
+  const a = { task: null, json: false, serve: false };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--task') a.task = argv[++i];
+    else if (argv[i] === '--json') a.json = true;
+    else if (argv[i] === '--serve') a.serve = true;
+  }
+  return a;
+}
+
+// ---- Chat serving (agent.chat surface) --------------------------------------
+//
+// In `--serve` mode the agent attaches to the daemon (the binding sends
+// CAR_AGENT_ID + CAR_AGENT_TOKEN on session.auth) and registers an `agent.chat`
+// handler. The daemon reverse-calls `agent.chat { session_id, prompt }` for
+// every host `agents.chat`; we keep a per-session message THREAD and run the
+// same propose→verify→execute loop per turn, streaming the reply back via
+// `agent.chat.event`. Threads are ephemeral (process lifetime). The agent's
+// declared policies still gate tool execution, so guardrails (draft-only, etc.)
+// carry into the conversation.
+
+/** Run one chat turn against a persistent `messages` thread; stream via chatEvent. */
+async function runChatTurn(
+  rt, config, toolSchemas, tools, toolTimeouts, sessionId, messages, requestedModel = null,
+) {
+  const { executeProposal } = runtimeApi();
+  const turnsCap = config.maxTurns ?? 8;
+  const selectedModel = typeof requestedModel === 'string' && requestedModel.trim()
+    ? requestedModel
+    : null;
+
+  // Run-trace bracket (open) — the SAME bracket `runAgent` opens, on the chat
+  // path. Without it a chat-driven turn does real tool work that never appears
+  // in `runs.list` / `runs.get_trace`, so a host that dispatches through
+  // `agents.chat` has no daemon-side record of what it ran: CarHost shows the
+  // agent as merely "running", and an outer loop cannot read back the tool
+  // returns or the terminal outcome. Same best-effort contract as `runAgent`'s
+  // — never throws, never prints (the last stdout line in --json mode must stay
+  // the AgentOutcome), and an older daemon without runs.* behaves exactly as it
+  // did before.
+  const intent = [...messages].reverse().find((m) => m.role === 'user')?.content ?? 'chat turn';
+  let runId = null;
+  try {
+    const started = JSON.parse(await rt.runsStart(JSON.stringify({
+      intent,
+      agent_id: process.env.CAR_AGENT_ID || config.agentName,
+      agent_name: config.agentName,
+      outcome_description: config.targetOutcome ?? '',
+    })));
+    runId = started.run_id ?? null;
+  } catch { /* daemon lacks runs.* — degrade to untraced behavior */ }
+
+  const metrics = { turns: 0, tool_calls: 0, actions_succeeded: 0, actions_failed: 0 };
+  const toolsCalled = new Set();
+  let terminal = null;
+  let finalText = '';
+  for (let turns = 0; turns < turnsCap; turns++) {
+    metrics.turns = turns + 1;
+    // Same cached request form as the one-shot loop. A chat thread grows for
+    // the whole session, so it is the path that benefits most from the moving
+    // conversation breakpoint.
+    const tracked = await inferTurn(rt, {
+      model: selectedModel ?? config.defaultModel ?? null,
+      maxTokens: config.maxTokens ?? 1024,
+      toolSchemas,
+      messages,
+    });
+    const calls = tracked.tool_calls || [];
+    if (calls.length === 0) {
+      finalText = tracked.text || '';
+      messages.push({ role: 'assistant', content: finalText });
+      terminal = 'done';
+      break;
+    }
+    calls.forEach((c, i) => { c.id = c.id || `a${i}`; });
+    messages.push({ role: 'assistant', content: tracked.text || '', tool_calls: calls });
+    const idToTool = Object.fromEntries(calls.map((c) => [c.id, c.name]));
+    // Surface non-finish tool calls as progress so the host UI can show them.
+    for (const c of calls) {
+      if (c.name !== 'finish') await rt.chatEvent(sessionId, 'tool_call', c.name).catch(() => {});
+    }
+    const proposal = buildProposal(tracked.model_used, calls, toolTimeouts);
+    const check = JSON.parse(await rt.verifyProposal(proposal));
+    if (!check.valid) {
+      for (const c of calls) {
+        messages.push({ role: 'tool_result', tool_use_id: c.id,
+          content: JSON.stringify({ error: `runtime rejected proposal: ${JSON.stringify(check.issues)}` }) });
+      }
+      continue;
+    }
+    // Same callback the one-shot loop uses, so the declared per-action budget
+    // and the request_id/AbortController cancel wiring reach tools on the
+    // --serve path too.
+    let finishAnswer = null;
+    const result = JSON.parse(await executeProposal(rt, proposal,
+      makeToolCallback(tools, toolTimeouts, (a) => { finishAnswer = a; })));
+    for (const r of (result.results || [])) {
+      const ok = r.status === 'succeeded';
+      if (ok && idToTool[r.action_id]) toolsCalled.add(idToTool[r.action_id]);
+      messages.push({ role: 'tool_result', tool_use_id: r.action_id,
+        content: JSON.stringify(ok ? (r.output ?? {}) : { error: r.error }) });
+      metrics.tool_calls += 1;
+      if (ok) metrics.actions_succeeded += 1; else metrics.actions_failed += 1;
+    }
+    if (finishAnswer !== null) { finalText = finishAnswer; terminal = 'success'; break; }
+  }
+  if (finalText) await rt.chatEvent(sessionId, 'token', finalText).catch(() => {});
+  await rt.chatEvent(sessionId, 'done', finalText).catch(() => {});
+
+  // Run-trace bracket (close). The outcome is assembled exactly as `runAgent`
+  // assembles it, so a chat-driven run and a --task run are the same shape in
+  // the trace and a host reads one code path, not two.
+  if (runId !== null) {
+    const outcome = terminal === 'success'
+      ? mkOutcome('success', finalText,
+        [{ kind: 'tool_result', description: 'finish called', data: { answer: finalText } }], metrics, toolsCalled)
+      : (terminal === 'done'
+        ? mkOutcome('done', finalText || 'no further actions',
+          [{ kind: 'self_assessment', description: finalText || '', data: null }], metrics, toolsCalled)
+        : mkOutcome('timeout', `hit ${turnsCap}-turn cap without finishing`,
+          [{ kind: 'stop_reason', description: 'max turns', data: { turnsCap } }], metrics, toolsCalled));
+    try {
+      await rt.runsComplete(JSON.stringify({ run_id: runId, outcome }));
+    } catch { /* daemon lacks runs.* — nothing to report to */ }
+  }
+  return finalText;
+}
+
+/** Set up the long-lived chat runtime: register tools/policies + the agent.chat handler. */
+async function serveChat(config) {
+  const { CarRuntime, registerChatHandler } = runtimeApi();
+  const rt = new CarRuntime();
+  const toolSchemas = [...(config.toolSchemas || []), FINISH_SCHEMA];
+  const tools = { finish: ({ answer }) => ({ answer }), ...(config.tools || {}) };
+  const toolTimeouts = Object.fromEntries(
+    toolSchemas.filter((s) => s && s.timeoutMs != null).map((s) => [s.name, s.timeoutMs]),
+  );
+  try { await rt.registerAgentBasics(); } catch { /* unsupported — fine */ }
+  for (const s of toolSchemas) await rt.registerTool(s.name);
+  for (const p of (config.policies || [])) await rt.registerPolicy(...p);
+
+  if (typeof registerChatHandler !== 'function') {
+    console.error(`[${config.agentName}] car-runtime has no agent.chat support — chat disabled (update car-runtime).`);
+    return rt;
+  }
+
+  const threads = new Map(); // session_id -> messages[]
+  const isLocalModel = typeof config.defaultModel === 'string' && /^(mlx|qwen)\//.test(config.defaultModel);
+  const noThink = isLocalModel ? '\n\n/no_think' : '';
+
+  registerChatHandler((paramsJson) => {
+    // Fire-and-forget — the daemon already got its {accepted:true} ack. Run the
+    // turn on its own microtask and stream results back via chatEvent.
+    let params;
+    try { params = JSON.parse(paramsJson); } catch { return; }
+    const sessionId = params.session_id;
+    if (!sessionId) return;
+    let messages = threads.get(sessionId);
+    if (!messages) {
+      messages = [{ role: 'system', content: `${config.identity}\n\nWhen the task is complete or you cannot proceed, call the \`finish\` tool with a concise answer. Do not narrate; act via tools.${noThink}` }];
+      threads.set(sessionId, messages);
+    }
+    messages.push({ role: 'user', content: params.prompt ?? '' });
+    runChatTurn(
+      rt, config, toolSchemas, tools, toolTimeouts, sessionId, messages, params.model,
+    )
+      .catch((e) => rt.chatEvent(sessionId, 'error', String(e && e.message || e)).catch(() => {}));
+  });
+  console.error(`[${config.agentName}] chat ready (agent.chat) — drive via CarHost or an agents.chat host client`);
+  return rt;
+}
+
+async function main(config) {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.serve) {
+    // Standing mode keeps the supervised process alive so CarHost shows it
+    // "running". Always serve chat (agent.chat); if the agent has a standing
+    // goal + interval, ALSO run it on a loop.
+    // car_register.py can set these via CAR_STANDING_GOAL / CAR_INTERVAL_SECS.
+    try { await serveChat(config); } catch (e) { console.error(`[${config.agentName}] chat setup failed:`, e); }
+    const goal = config.standingGoal ?? process.env.CAR_STANDING_GOAL ?? null;
+    const everyMs = (config.intervalSecs ?? Number(process.env.CAR_INTERVAL_SECS || 0)) * 1000;
+    console.error(`[${config.agentName}] serving${goal ? ` — "${goal}" every ${everyMs / 1000}s` : ' (idle; start via dashboard or --task)'}`);
+    if (goal && everyMs > 0) {
+      for (;;) {
+        try {
+          // Each iteration is its own run: runAgent opens and closes one
+          // runs.start/runs.complete bracket on its own fresh CarRuntime.
+          const o = await runAgent(config, goal);
+          console.error(`[${config.agentName}] ${o.status} — ${o.summary}`);
+        } catch (e) { console.error(`[${config.agentName}] error:`, e); }
+        await new Promise((r) => setTimeout(r, everyMs));
+      }
+    } else {
+      // Keep the event loop alive. A pending promise alone does NOT keep Node
+      // running — it exits when the loop is empty — so use a no-op heartbeat.
+      setInterval(() => {}, 1 << 30);
+    }
+    return;
+  }
+
+  if (!args.task) {
+    console.error('usage: node agent.mjs --task "<goal>" [--json]   |   --serve');
+    process.exit(2);
+  }
+
+  let outcome;
+  try {
+    outcome = await runAgent(config, args.task);
+  } catch (e) {
+    outcome = { status: 'failure', summary: String(e && e.message || e),
+      evidence: [{ kind: 'stop_reason', description: 'uncaught', data: null }],
+      metrics: { turns: 0, tool_calls: 0, actions_succeeded: 0, actions_failed: 0 }, tools_called: [] };
+  }
+
+  if (args.json) {
+    // The LAST stdout line is the machine-readable outcome (run_scenarios reads it).
+    console.log(JSON.stringify(outcome));
+  } else {
+    console.log(`${outcome.status} — ${outcome.summary}`);
+  }
+  process.exit(outcome.status === 'failure' ? 1 : 0);
+}
+
+module.exports = { main, runAgent, runChatTurn };

package/agent-loop.mjs

@@ -0,0 +1,4 @@
+import loop from './agent-loop.js';
+
+export const { main, runAgent, runChatTurn } = loop;
+export default loop;

package/docs/ASSISTANT.md

@@ -422,6 +422,7 @@ emitter that builds it:
     "network": "none",
     "tier": "sandbox_edit",
     "root": "/work",
+    "mount": null,
     "fallback_notice": null
   },
   "elapsed_seconds": 12.4

package/docs/CLI.md

@@ -2,17 +2,17 @@
 
 > **Generated file — do not hand-edit below the task map.** Produced by
 > `scripts/gen-cli-docs.sh` from `car --help` / `car help <command>` on car
-> 0.52.1 (2026-09-04). Every subcommand the installed binary reports is
+> 0.52.1 (2026-09-06). Every subcommand the installed binary reports is
 > below; a new subcommand cannot ship without appearing here the next time
 > this script runs. To regenerate: `bash scripts/gen-cli-docs.sh`.
 >
-> 68 top-level commands, 101 nested subcommands
+> 69 top-level commands, 106 nested subcommands
 > (one level deep) — counted from the live binary at generation time, not
 > typed by hand.
 
 ## Finding your way around
 
-`car` is one binary with 68 subcommands spanning several different jobs:
+`car` is one binary with 69 subcommands spanning several different jobs:
 running the built-in agent, coding, local model management, OS integrations,
 and installing other people's agents on your machine. This map groups the
 commands people actually reach for; the full alphabetical reference with every
@@ -174,6 +174,7 @@ commands on a cadence via launchd / cron / schtasks).
 | [`car code-task`](#car-code-task) | Run a coder session headlessly and IN THIS PROCESS: derive or accept an outcome contract, work in a git worktree until the runtime's own re-run of that contract is green, then deliver the result as a pull request |
 | [`car coder-ab`](#car-coder-ab) | A/B-test CAR's coder against an external agent (Codex / Claude Code) over a corpus, and grow that corpus from git history — the productionized dogfooding loop (docs/proposals/coder-ab-dogfood.md) |
 | [`car keys`](#car-keys) | Store cloud-provider API keys in the OS keychain, so a native-app user never sets an environment variable (docs/proposals/native-secrets-no-env.md). The key is read env-first, keychain-fallback by the runtime |
+| [`car selfheal`](#car-selfheal) | Inspect and operate the daemon's deterministic self-healing detector |
 | [`car daemon`](#car-daemon) | Start the daemon server (delegates to car-server binary) |
 | [`car models`](#car-models) | Manage local inference models |
 | [`car setup`](#car-setup) | Set up the right model for this machine — detect hardware, recommend, and install. Run with no flags for an interactive walkthrough |
@@ -647,6 +648,90 @@ Options:
   -h, --help  Print help
 ```
 
+### car selfheal
+
+```text
+Inspect and operate the daemon's deterministic self-healing detector
+
+Usage: car selfheal <COMMAND>
+
+Commands:
+  status   Show cadence, active counts, and the route resolved by the last tick
+  list     List active detections, optionally filtered by kind, severity, or time
+  show     Print the trusted local issue document for one detection
+  dismiss  Dismiss one active detection by dedup key
+  run      Run one deterministic detection tick now
+  help     Print this message or the help of the given subcommand(s)
+
+Options:
+  -h, --help  Print help
+```
+
+#### car selfheal status
+
+```text
+Show cadence, active counts, and the route resolved by the last tick
+
+Usage: car selfheal status
+
+Options:
+  -h, --help  Print help
+```
+
+#### car selfheal list
+
+```text
+List active detections, optionally filtered by kind, severity, or time
+
+Usage: car selfheal list [OPTIONS]
+
+Options:
+      --kind <KIND>          Detection kind (metrics_alert, agent_gave_up, agent_log_error,
+      agent_silently_idle, recurring_tool_failure, capability_miss)
+      --severity <SEVERITY>  Severity (warning or critical)
+      --since <SINCE>        Only detections observed at or after this RFC3339 timestamp
+  -h, --help                 Print help
+```
+
+#### car selfheal show
+
+```text
+Print the trusted local issue document for one detection
+
+Usage: car selfheal show <DEDUP_KEY>
+
+Arguments:
+  <DEDUP_KEY>  Detection SHA-256 dedup key
+
+Options:
+  -h, --help  Print help
+```
+
+#### car selfheal dismiss
+
+```text
+Dismiss one active detection by dedup key
+
+Usage: car selfheal dismiss <DEDUP_KEY>
+
+Arguments:
+  <DEDUP_KEY>  Detection SHA-256 dedup key
+
+Options:
+  -h, --help  Print help
+```
+
+#### car selfheal run
+
+```text
+Run one deterministic detection tick now
+
+Usage: car selfheal run
+
+Options:
+  -h, --help  Print help
+```
+
 ### car daemon
 
 ```text

package/docs/agent-ir-spec.md

@@ -181,6 +181,35 @@ Proposed → Validated → Executing → Succeeded
 
 `ActionStatus` is observable through the event log, not part of the input contract.
 
+#### Execution outcome event data
+
+Every per-action `ActionFailed` event carries:
+
+- `params_digest`: lowercase SHA-256 of the RFC 8785/JCS-canonicalized action
+  `parameters` object. The event never copies raw parameters; consumers join
+  through `proposal_id` + `action_id` to the authoritative `ProposalReceived`
+  record and can use the digest to detect a mismatch.
+- `expected_effects`: the action's declared expected-effects object, unchanged.
+- `error_class`: one of `timeout`, `rejected_by_policy`, `tool_error`,
+  `validation`, or `unknown`.
+
+`ActionSucceeded` carries `params_digest` and `expected_effects` too, making the
+success/failure join symmetric without adding an error classification to a
+successful call.
+
+The normalized error mapping is intentionally low-cardinality:
+
+| `error_class` | Mapping |
+|---|---|
+| `timeout` | the engine's action deadline expired, or the daemon-to-host tool callback reported its own timeout |
+| `rejected_by_policy` | a dispatch-time tool guard returned the stable `denied by policy:` or `rejected by policy:` prefix |
+| `validation` | post-dispatch output or callback-state JCS/I-JSON, state-key-set, or serialization validation failed |
+| `tool_error` | any other error returned while dispatching a tool action |
+| `unknown` | a post-dispatch failure on an action with no tool |
+
+Normal action/schema/policy admission failures happen before execution and are
+`ActionRejected`, not `ActionFailed`, so this mapping does not reclassify them.
+
 ---
 
 ## Precondition
@@ -220,6 +249,7 @@ Registered when a tool is added to the runtime. Carries everything the runtime n
 ```jsonc
 {
   "name": "deploy",
+  "source": "user_defined",
   "description": "Deploys an artifact to a target environment.",
   "parameters": {
     "type": "object",
@@ -238,6 +268,7 @@ Registered when a tool is added to the runtime. Carries everything the runtime n
 | Field | Type | Required | Default | Notes |
 |-------|------|----------|---------|-------|
 | `name` | string | **yes** | — | unique within a runtime |
+| `source` | `builtin \| user_defined \| subprocess \| mcp` | no | `user_defined` | stable origin category assigned by the runtime; MCP server detail remains registry-private |
 | `description` | string | no | `""` | human-readable; included in tool catalog |
 | `parameters` | JSON Schema | no | `{}` | validated by the runtime before dispatch |
 | `returns` | JSON Schema | no | none | validated against tool return value when set |
@@ -562,15 +593,21 @@ allow = ["staging", "preview"]   # any other target — or none at all — is de
 | `allow` | no | permitted values; defaults to empty, which denies every call |
 
 #### `deny_tool_param_matching`
-The content counterpart to `deny_tool_param`, for prohibitions no fixed substring expresses — credential shapes, account numbers, an address family. `matches` is a regex over the string-coerced parameter value. The match is **unanchored**, so the pattern fires anywhere in the value; anchor it with `^`/`$` when that matters. Like `deny_tool_param`, an absent parameter is not a violation — use `allow_tool_param` when absence itself must be refused.
+The content counterpart to `deny_tool_param`, for conditions no fixed substring expresses — credential shapes, account numbers, an address family, or an open-ended trusted prefix. `matches` is a regex over the string-coerced parameter value. The match is **unanchored**, so the pattern fires anywhere in the value; anchor it with `^`/`$` when that matters.
 
-The pattern is compiled once when the rule set is applied, not per action. A pattern that fails to compile **denies every call to that tool** rather than disappearing, matching the loader's loud-error posture.
+By default a regex match denies and an absent parameter does not. Set `negate = true` for the "unless" form: a mismatch denies, and an absent parameter also denies because nothing proves the required pattern. The pattern is compiled once when the rule set is applied, not per action. A pattern that fails to compile **denies every call to that tool** rather than disappearing, matching the loader's loud-error posture.
 
 ```toml
 [[deny_tool_param_matching]]
 tool    = "http_request"
 param   = "body"
 matches = "sk-[A-Za-z0-9]{20,}"   # never let an API-key-shaped string leave in a body
+
+[[deny_tool_param_matching]]
+tool    = "docker.rm"
+param   = "name"
+matches = "^parslee-"
+negate  = true                     # deny unless the name has the trusted prefix
 ```
 
 | Param | Required | Notes |
@@ -578,6 +615,7 @@ matches = "sk-[A-Za-z0-9]{20,}"   # never let an API-key-shaped string leave in
 | `tool` | yes | tool name the rule applies to |
 | `param` | yes | parameter key inspected on the action |
 | `matches` | yes | regex source; unanchored; an uncompilable pattern denies the tool outright |
+| `negate` | no | defaults to `false`; when `true`, deny mismatch or absence instead of match |
 
 #### `rate_limit_tool`
 A sliding-window cap on how often `tool` may be called. The call is denied when admitting it would make it the `max_calls + 1`-th call to `tool` within the trailing `interval_secs`. `max_calls = 0` denies every call. This bounds how much of a side effect an agent can produce in a stretch of wall-clock time, independently of whether any single call is legitimate.

package/index.d.ts

@@ -32,6 +32,61 @@
  * `ws://127.0.0.1:9100`).
  */
 
+/** Agent-loop tool declaration. `timeoutMs` becomes the action budget. */
+export interface AgentToolSchema {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+  timeoutMs?: number;
+}
+
+export interface AgentToolContext {
+  signal: AbortSignal;
+  timeoutMs?: number;
+}
+
+export type AgentTool = (
+  params: Record<string, unknown>,
+  context: AgentToolContext,
+) => unknown | Promise<unknown>;
+
+export type AgentOutcomeStatus =
+  | 'success' | 'partial_success' | 'done' | 'give_up' | 'timeout' | 'failure';
+
+export interface AgentOutcome {
+  status: AgentOutcomeStatus;
+  summary: string;
+  evidence: Array<{ kind: string; description: string; data: unknown }>;
+  metrics: {
+    turns: number;
+    tool_calls: number;
+    actions_succeeded: number;
+    actions_failed: number;
+  };
+  tools_called: string[];
+  timestamp: string;
+}
+
+/** Declarative input consumed by `car-runtime/agent-loop`. */
+export interface AgentLoopConfig {
+  agentId?: string;
+  agentName: string;
+  identity: string;
+  toolSchemas?: AgentToolSchema[];
+  tools?: Record<string, AgentTool>;
+  policies?: Array<[string, string, string?, string?, string?, string?]>;
+  defaultModel?: string | null;
+  maxTokens?: number;
+  maxTurns?: number;
+  targetOutcome?: string;
+  standingGoal?: string | null;
+  intervalSecs?: number;
+}
+
+export interface AgentLoopOptions {
+  maxTurns?: number;
+}
+
 /** Persistent runtime instance with state, memory, tools, and policies. */
 /**
  * Optional settings for `coderStart`. Every field is independently omittable;
@@ -58,6 +113,24 @@ export interface CoderStartOptions {
    * hypothesis, the other buys a retry.
    */
   transientRetries?: number | undefined | null;
+  /**
+   * Farm a **foreman** session's subtasks across every reachable CAR instance
+   * that can serve this repository, instead of this machine alone. The
+   * merge-verify gate and delivery stay on the orchestrating host — a peer
+   * returns a patch and this host gates it — so a distributed run still
+   * produces a gated pull request.
+   *
+   * Only the foreman engine decomposes a goal into subtasks, so any other
+   * engine runs locally and says so. Off by default: it spends agent quota on
+   * other people's machines.
+   */
+  distributed?: boolean | undefined | null;
+  /**
+   * Restrict placement to these instances by name. Empty or omitted means
+   * every instance that reports it can serve the repository. Ignored unless
+   * `distributed` is set.
+   */
+  workers?: Array<string> | undefined | null;
   /**
    * A `coder.discuss` conversation this run was distilled from. Its agreed
    * constraints ride into contract derivation, so a rule stated once in the
@@ -68,9 +141,41 @@ export interface CoderStartOptions {
   discussionId?: string | undefined | null;
 }
 
+export interface DaemonRpcError extends Error {
+  /** Numeric JSON-RPC error code returned by the daemon. */
+  code: number;
+  /** Daemon-provided diagnostic text. */
+  message: string;
+  /** Optional JSON-RPC error data returned by the daemon. */
+  data?: unknown;
+}
+
 export class CarRuntime {
   constructor();
 
+  /**
+   * Invoke any daemon JSON-RPC method with a JSON-encoded params value.
+   * `daemonCall` is the call-by-name escape hatch; use the typed wrappers as the primary API.
+   * The result is returned as JSON. Daemon rejections are `DaemonRpcError`;
+   * transport failures reject without a synthetic numeric code.
+   */
+  daemonCall(method: string, paramsJson: string): Promise<string>;
+
+  /** Host-management-token twin of `daemonCall`; the method allowlist remains enforced. */
+  daemonCallHostManagement(method: string, paramsJson: string): Promise<string>;
+
+  /** Register a server-initiated JSON-RPC request handler. */
+  registerDaemonHandler(
+    method: string,
+    handler: (paramsJson: string) => Promise<string>,
+  ): void;
+
+  /** Register a server-initiated JSON-RPC notification handler. */
+  registerDaemonNotificationHandler(
+    method: string,
+    handler: (paramsJson: string) => void,
+  ): void;
+
   // --- Memory persistence ---
 
   /**
@@ -142,7 +247,54 @@ export class CarRuntime {
     adapter?: string,
     verifyCommand?: Array<string>,
     unionVerifyCommand?: Array<string>,
-    maxAttempts?: number
+    maxAttempts?: number,
+    distributed?: boolean,
+    workers?: Array<string>
+  ): Promise<string>;
+
+  // --- Fleet ---
+
+  /**
+   * This instance's agents, capabilities, and models — one `InstanceInventory`
+   * JSON object. The same report peers receive over A2A, plus this session's
+   * own registered tools and learned skills.
+   */
+  fleetInventory(): Promise<string>;
+
+  /**
+   * Every agent, capability, and model across this daemon and every reachable
+   * CAR instance, folded so one row names every instance that offers it.
+   * `includeRemote` defaults to true. `timeoutMs` bounds each peer
+   * individually: a sleeping machine appears as an unreachable row carrying the
+   * reason, never a missing one. Returns `FleetComposite` JSON.
+   */
+  fleetComposite(includeRemote?: boolean, timeoutMs?: number): Promise<string>;
+
+  /** Whether this instance takes farmed-out coding work. `{ config, profile }` JSON. */
+  fleetWorkerGet(): Promise<string>;
+
+  /**
+   * Enroll (or withdraw) this instance as a fleet worker. **Operator-only, and
+   * a real grant**: enrolling lets a trusted peer run a coding CLI against the
+   * checkouts named in `repos`. Only the fields supplied change.
+   *
+   * The limits belong to this machine, not the caller: `dispatchesPerHour`
+   * budgets one peer's spend (concurrency is not a spend bound),
+   * `maxSubtaskSecs` caps the timeout a sender asks for, and `allowedTools` is
+   * intersected with whatever the dispatch requests. `fetchMissingBase` makes
+   * this machine a **runner**: rather than decline a base commit it lacks, it
+   * fetches from `fetchRemote` (its own, default `origin`).
+   */
+  fleetWorkerSet(
+    acceptsWork?: boolean,
+    repos?: Array<string>,
+    maxParallel?: number,
+    localParallel?: number,
+    dispatchesPerHour?: number,
+    maxSubtaskSecs?: number,
+    allowedTools?: Array<string>,
+    fetchMissingBase?: boolean,
+    fetchRemote?: string
   ): Promise<string>;
 
   // --- Tools & policies ---
@@ -152,7 +304,8 @@ export class CarRuntime {
 
   /**
    * The tools currently registered on this runtime, as a JSON array of full
-   * `ToolSchema` objects sorted by name.
+   * `ToolSchema` objects sorted by name. Every schema includes its runtime-
+   * assigned `source` (`builtin|user_defined|subprocess|mcp`).
    *
    * Counterpart to `registerTool` / `registerToolSchema`, which had none: a
    * caller could add tools but never ask what was actually in effect, so a
@@ -296,7 +449,8 @@ export class CarRuntime {
   // --- Memory / Facts (graph-backed) ---
 
   /**
-   * Add a fact. `kind` is typically "pattern" or "constraint".
+   * Add a fact. `kind` is typically "pattern" or "constraint". Optional
+   * `factId`, ordered `tags`, and `source` are preserved by the daemon.
    *
    * In Daemon mode, rejects with the daemon-unreachable error
    * instead of silently returning 0 (#146).
@@ -306,9 +460,16 @@ export class CarRuntime {
     body: string,
     kind: string,
     confidence?: number | null,
+    factId?: string | null,
+    tags?: string[] | null,
+    source?: string | null,
   ): Promise<number>;
 
-  /** Query facts via graph spreading activation. Returns a JSON array. */
+  /**
+   * Query facts via graph spreading activation. Returns a JSON array whose
+   * rows include `fact_id` (null for graph nodes without one), `subject`,
+   * `body`, `kind`, `confidence`, `tags`, and `source`.
+   */
   queryFacts(query: string, k?: number | null): string;
 
   /**
@@ -462,7 +623,37 @@ export class CarRuntime {
   syncStatus(requestJson: string): Promise<string>;
   /** `sync.append` — record an op on any surface: `{ surface, payload, scope? }` (B6). */
   syncAppend(requestJson: string): Promise<string>;
-  /** `agents.peers` — the agents this runtime can message, from the daemon's live connection table. */
+  /** `host.agents` — current host agent registry snapshot. */
+  hostAgents(): Promise<string>;
+  /** `host.events` — recent host events, newest last; omit `limit` for the daemon default. */
+  hostEvents(limit?: number): Promise<string>;
+  /** `host.approvals` — pending host approvals. */
+  hostApprovals(): Promise<string>;
+  /** `host.register_agent` — register an agent on this connection. */
+  hostRegisterAgent(requestJson: string): Promise<string>;
+  /** `host.unregister_agent` — unregister an agent owned by this connection. */
+  hostUnregisterAgent(requestJson: string): Promise<string>;
+  /** `host.set_status` — publish status for an agent owned by this connection. */
+  hostSetStatus(requestJson: string): Promise<string>;
+  /** `host.register_device` — register a device on this connection. */
+  hostRegisterDevice(requestJson: string): Promise<string>;
+  /** `host.update_device` — update a device owned by this connection. */
+  hostUpdateDevice(requestJson: string): Promise<string>;
+  /** `host.devices` — current host device registry snapshot. */
+  hostDevices(): Promise<string>;
+  /** `host.notify` — emit a user-facing host notification. */
+  hostNotify(requestJson: string): Promise<string>;
+  /** `host.request_approval` — request approval for a gated action. */
+  hostRequestApproval(requestJson: string): Promise<string>;
+  /** `host.resolve_approval` — resolve one pending host approval. */
+  hostResolveApproval(requestJson: string): Promise<string>;
+  // `host.subscribe` event delivery is deferred to the callback-aware
+  // daemon-session API; subscribing without a consumer would drop the stream.
+  /**
+   * `agents.peers` — visible peers as JSON. Each row distinguishes the
+   * kind-level `can_receive` capability from the current `reachable` delivery
+   * preflight; the send remains authoritative.
+   */
   agentsPeers(requestJson: string): Promise<string>;
   /** `agents.message` — send text to one peer: `{ to, body, summary? }`. The sender is derived server-side. */
   agentsMessage(requestJson: string): Promise<string>;
@@ -795,6 +986,21 @@ export class CarRuntime {
    * of silently serving a different model (Parslee-ai/car#888). Absent on
    * the common path.
    *
+   * `fallback_from` is an ARRAY of every candidate the chain moved past,
+   * in the order it tried them: `[{ candidate, reason }, ...]`, where
+   * `reason` is one of `"credential_rejected"`, `"credential_absent"`,
+   * `"rate_limited"`, `"quota_exhausted"`, `"timed_out"` or `"failed"`.
+   * Absent when the first candidate served. Before this, a run whose
+   * backbone changed because of a rate limit or a timeout recorded no
+   * cause anywhere, so a surprising result got attributed to the code
+   * rather than to the model swap (Parslee-ai/car#1351).
+   *
+   * `reason` is classified from the runtime's typed error, not from error
+   * prose. `"credential_rejected"` is deliberately BROADER than
+   * `auth_fallback_from`: it covers a provider refusing an API key, whose
+   * remedy is to fix the key, not to sign in. Do not derive one field
+   * from the other.
+   *
    * **Note:** intent is not exposed on the tracked path until the
    * positional argument list is converted to an options object —
    * this method already takes 9 positional parameters and adding
@@ -1462,7 +1668,10 @@ export class CarRuntime {
 
   /** Structured audit query over the event log (G2). `queryJson` is an
    * EventQuery object (kinds/actionId/proposalId/since/until/dataMatches/limit);
-   * returns `{count, events}` as a JSON string, most-recent-first. */
+   * returns `{count, events}` as a JSON string, most-recent-first.
+   * `ActionFailed.data` includes `params_digest`, `expected_effects`, and
+   * `error_class` (`timeout|rejected_by_policy|tool_error|validation|unknown`),
+   * never raw parameters. `ActionSucceeded.data` includes the first two. */
   eventQuery(queryJson: string): Promise<string>;
 
   /** Get/set the event-log retention policy (G2). Pass a
@@ -1498,21 +1707,39 @@ export class CarRuntime {
    * `cost_overage` alert. */
   metricsAlerts(thresholdsJson?: string): Promise<string>;
 
-  /** Watch-only self-heal detector status as JSON: cadence, last tick, source
-   * `route`, validated `source_checkout` or `refusal_reason`, detector IDs,
-   * active/dismissed counts, and `filing_mode: "watch-only"`. */
+/** Self-healing repair loop status: enabled/why-not, cadence, targets,
+   * rejected targets, review panel, engine. */
+  healStatus(): Promise<string>;
+  /** Run one self-healing repair sweep now. May open a pull request; never merges. */
+  healRun(): Promise<string>;
+/** Self-heal status as JSON: cadence, `auto_fix_enabled`, `max_concurrent`,
+   * `max_per_day`, `max_rounds_per_key`, optional `auto_fix_refusal_reason`,
+   * last tick, source route/refusal,
+   * detector counts, and `filing_mode` (`watch-only` or `pr-only`). */
+
   selfhealStatus(): Promise<string>;
 
   /** List active (not dismissed) self-heal detections as JSON. Each includes
-   * `route` and an optional `local_issue_path`. `queryJson` optionally carries
-   * `kind`, `severity`, `since`, `offset`, and `limit` (bounded to 500). */
+   * `route` and an optional `local_issue_path`. Recurring tool failures add
+   * `eligible`, a secret-safe `reconstructed_call` (`tool` plus exact `params`),
+   * optional owner-private `reconstructed_call_path`, `auto_fix_attempts`,
+   * `auto_fix_exhausted`, `auto_fix_in_progress`, and
+   * `last_auto_fix_attempt` (including `exit_code` and `failure_class`). Remote
+   * deduplication adds `auto_fix_awaiting_review`, `auto_fix_parked`,
+   * `remote_pr_number`, and `remote_pr_url`.
+   * `queryJson` carries optional `kind`, `severity`,
+   * `since`, `offset`, and `limit` (max 500). */
   selfhealDetections(queryJson?: string): Promise<string>;
 
-  /** Append a dismissal marker for a stable detection dedup key. This does not
-   * delete history, file an issue, use network, or remediate anything. */
+  /** Append a dismissal marker for a stable detection dedup key without
+   * deleting history. */
   selfhealDismiss(dedupKey: string): Promise<string>;
 
-  /** Run one non-overlapping watch-only detection tick immediately. */
+  /** Start one bounded template-owned coder round for an eligible recurring
+   * tool failure. Returns the durable attempt result as JSON. */
+  selfhealFix(dedupKey: string): Promise<string>;
+
+  /** Run one non-overlapping detection tick and default-on auto-fix hook. */
   selfhealRun(): Promise<string>;
 
   /** Execution log counts and approximate retained native bytes. Returns JSON. */
@@ -1611,9 +1838,10 @@ export class CarRuntime {
    * automatically.
    *
    * Tools registered via the schemaless `registerTool(name)` bypass type
-   * validation; this is the opt-in upgrade path.
+   * validation; this is the opt-in upgrade path. The daemon assigns
+   * `source = "user_defined"`; callers cannot claim another origin.
    *
-   * `schemaJson` matches:
+   * `schemaJson` carries the caller-settable fields:
    * ```json
    * {
    *   "name": "read_file",
@@ -2596,10 +2824,21 @@ export function reapStaleAgents(
  * register an `agent.chat` handler to serve conversational turns, and/or
  * a `registerToolHandler` for explicit tool `data` parts.
  *
+ * `allow_non_loopback_bind` (boolean, default `false`) is required to bind
+ * anything but loopback. This listener serves NO authentication — there
+ * is no auth parameter, and its router is `NoAuth` — and without
+ * `share_session_runtime` its runtime registers the agent-basics
+ * filesystem tools, so a reachable bind publishes `write_file` /
+ * `edit_file` to anyone who can route to the port. A wildcard bind
+ * (`0.0.0.0:...`) is refused too. To be reachable by other CAR daemons
+ * you want the peer-authenticated, messaging-only listener `car-server`
+ * already runs by default, not this.
+ *
  * Returns `'{"bound":"127.0.0.1:8731"}'` on success. Errors if a
- * server is already running, the bind fails, `share_session_runtime`
- * is set but no session runtime is available (e.g. invoked from a
- * non-WS path), or `paramsJson` is malformed.
+ * server is already running, the bind fails, the bind is non-loopback
+ * without `allow_non_loopback_bind`, `share_session_runtime` is set but no
+ * session runtime is available (e.g. invoked from a non-WS path), or
+ * `paramsJson` is malformed.
  */
 export function startA2AServer(rt: CarRuntime, paramsJson: string): Promise<string>;
 

package/package.json

@@ -1,9 +1,23 @@
 {
   "name": "car-runtime",
-  "version": "0.52.1",
+  "version": "0.53.0",
   "description": "Common Agent Runtime — a deterministic execution layer for AI agents",
   "main": "index.js",
   "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "require": "./index.js",
+      "default": "./index.js"
+    },
+    "./agent-loop": {
+      "types": "./agent-loop.d.ts",
+      "import": "./agent-loop.mjs",
+      "require": "./agent-loop.js",
+      "default": "./agent-loop.js"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
     "car-server": "bin/car-server"
   },
@@ -36,6 +50,9 @@
   "files": [
     "index.js",
     "index.d.ts",
+    "agent-loop.js",
+    "agent-loop.mjs",
+    "agent-loop.d.ts",
     "install.js",
     "assets.json",
     "bin/car-server",
@@ -45,7 +62,8 @@
   ],
   "scripts": {
     "install": "node install.js",
-    "prepack": "node sync-docs.js"
+    "prepack": "node sync-docs.js",
+    "test": "node --test test/install.test.js"
   },
   "license": "SEE LICENSE IN LICENSE",
   "private": false