car-runtime 0.53.0 → 0.55.0-nightly.20260920

package/README.md

@@ -21,6 +21,46 @@ Both the `.node` module **and** the `car-server` daemon binary are
 included. Supported platforms: macOS (14+) arm64/x64, Linux
 x64/arm64 glibc, Windows x64.
 
+## Daemon/package compatibility
+
+The npm package and the daemon use a versioned JSON-RPC wire protocol. Read
+`carProtocolVersion` from `car-runtime/package.json` when compatibility must be
+checked before the native module loads; `protocolVersion()` returns the same
+number at runtime:
+
+```javascript
+const pkg = require('car-runtime/package.json');
+const { protocolVersion } = require('car-runtime');
+
+if (protocolVersion() !== pkg.carProtocolVersion) {
+  throw new Error('car-runtime package metadata does not match its native binding');
+}
+```
+
+The daemon handshake fails closed and names both wire versions when the client
+and daemon are incompatible. `CarHost.app` can update its bundled daemon
+independently of project dependencies, so update this package in the project
+that loads it; while CAR is pre-1.0, pinning the package to the daemon's CAR
+release is the safest choice (`npm install car-runtime@<version>`). A caret
+range does not cross a `0.x` minor release.
+
+## Call the daemon
+
+`CarRuntime` connects lazily. Params and results are JSON strings; generated typed
+wrappers such as `agentsList` share the same governed connection.
+
+```javascript
+async function daemonCallExample() {
+// BEGIN CALL_DAEMON_FIVE_LINES
+  const { CarRuntime } = (await import('car-runtime')).default;
+  const car = new CarRuntime();
+  car.registerDaemonHandler('tools.execute', async () => JSON.stringify({ ok: true }));
+  const methods = JSON.parse(await car.daemonCall('capabilities.list', '{}'));
+  return { car, methods, agents: JSON.parse(await car.agentsList('{}')) };
+// END CALL_DAEMON_FIVE_LINES
+}
+```
+
 ## Start the daemon
 
 ```bash
@@ -95,13 +135,18 @@ main({
 });
 ```
 
-`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
+`runAgent(config, goal)` is also exported for embedding and tests. Its
+`AgentOutcome.run_id` is the durable key accepted by `runsGetTrace`; it is
+`null` when an older daemon has no `runs.*` surface or did not acknowledge the
+start. `runChatTurn` keeps returning bare text by default; pass
+`{ includeRunId: true }` as its final options argument to receive
+`{ text, run_id }`. `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

package/agent-loop.d.ts

@@ -1,4 +1,6 @@
 import type {
+  AgentChatTurnOptions,
+  AgentChatTurnResult,
   AgentLoopConfig,
   AgentLoopOptions,
   AgentOutcome,
@@ -13,6 +15,18 @@ export function runAgent(
   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 | undefined,
+  options: AgentChatTurnOptions & { includeRunId: true },
+): Promise<AgentChatTurnResult>;
+
 export function runChatTurn(
   runtime: CarRuntime,
   config: AgentLoopConfig,
@@ -22,6 +36,7 @@ export function runChatTurn(
   sessionId: string,
   messages: Record<string, unknown>[],
   requestedModel?: string | null,
+  options?: AgentChatTurnOptions & { includeRunId?: false },
 ): Promise<string>;
 
 export function main(config: AgentLoopConfig): Promise<void>;

package/agent-loop.js

@@ -157,7 +157,7 @@ async function inferTurn(rt, { model, maxTokens, toolSchemas, messages, toolChoi
 
 /**
  * Run the agent once toward `goal`. Returns an AgentOutcome-shaped object:
- *   { status, summary, evidence[], metrics{}, tools_called[] }
+ *   { status, summary, evidence[], metrics{}, tools_called[], run_id }
  * `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.
@@ -166,7 +166,7 @@ async function inferTurn(rt, { model, maxTokens, toolSchemas, messages, toolChoi
  * 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.
+ * the run for CarHost while older daemons report `run_id: null` and still run.
  */
 async function runAgent(config, goal, { maxTurns } = {}) {
   const { CarRuntime, executeProposal } = runtimeApi();
@@ -198,7 +198,7 @@ async function runAgent(config, goal, { maxTurns } = {}) {
   // 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
+  // older build) makes this throw, and the run must continue with a null id. NEVER
   // print here — the last stdout line in --json mode must stay the AgentOutcome
   // (run_scenarios.py parses it).
   let runId = null;
@@ -209,7 +209,9 @@ async function runAgent(config, goal, { maxTurns } = {}) {
       agent_name: config.agentName,
       outcome_description: config.targetOutcome ?? '',
     })));
-    runId = started.run_id ?? null;
+    runId = typeof started.run_id === 'string' && started.run_id.length > 0
+      ? started.run_id
+      : null;
   } catch { /* daemon lacks runs.* — degrade to untraced behavior */ }
 
   // Local Qwen3 models default to "thinking" (they emit a long <think> block
@@ -329,13 +331,17 @@ async function runAgent(config, goal, { maxTurns } = {}) {
   // 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.
+  // start, leaving runId null) just skips completion and returns the null id.
   if (runId !== null) {
     try {
       await rt.runsComplete(JSON.stringify({ run_id: runId, outcome }));
     } catch { /* daemon lacks runs.* — nothing to report to */ }
   }
 
+  // `run_id` is package return metadata, not part of the daemon's car-ir
+  // AgentOutcome. Add it only after runs.complete so the wire shape stays
+  // unchanged. Null reports an older daemon or unacknowledged runs.start.
+  outcome.run_id = runId;
   return outcome;
 }
 
@@ -371,9 +377,15 @@ function parseArgs(argv) {
 // 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. */
+/**
+ * Run one chat turn against a persistent `messages` thread; stream via
+ * chatEvent. The default return stays the historical bare string. Callers that
+ * need to inspect the durable trace opt into `{ includeRunId: true }` and get
+ * `{ text, run_id }` instead.
+ */
 async function runChatTurn(
   rt, config, toolSchemas, tools, toolTimeouts, sessionId, messages, requestedModel = null,
+  options = {},
 ) {
   const { executeProposal } = runtimeApi();
   const turnsCap = config.maxTurns ?? 8;
@@ -399,7 +411,9 @@ async function runChatTurn(
       agent_name: config.agentName,
       outcome_description: config.targetOutcome ?? '',
     })));
-    runId = started.run_id ?? null;
+    runId = typeof started.run_id === 'string' && started.run_id.length > 0
+      ? 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 };
@@ -462,20 +476,20 @@ async function runChatTurn(
   // 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.
+  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));
   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;
+  return options?.includeRunId ? { text: finalText, run_id: runId } : finalText;
 }
 
 /** Set up the long-lived chat runtime: register tools/policies + the agent.chat handler. */