car-runtime 0.52.0 → 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