car-runtime 0.55.0 → 0.56.1-nightly.20261007

package/README.md

@@ -112,6 +112,7 @@ const result = await executeProposal(rt, proposal, async (callJson) => {
   // Dispatch to your tool implementation.
   return JSON.stringify({ stdout: 'ok' });
 });
+await rt.close(); // disconnect is an alias; a later call reconnects lazily
 ```
 
 ## Packaged agent loop
@@ -135,7 +136,10 @@ main({
 });
 ```
 
-`runAgent(config, goal)` is also exported for embedding and tests. Its
+`runAgent(config, goal)` is also exported for embedding and tests. Pass one
+long-lived runtime as `config.runtime` to reuse its daemon connection across
+runs; otherwise the loop creates and closes a runtime for each call. `serveChat`
+uses the same option and returns the runtime it is serving on. 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
@@ -143,7 +147,11 @@ start. `runChatTurn` keeps returning bare text by default; pass
 `{ 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
+chat runs, and uses request-shaped inference with prompt-cache breakpoints.
+Each inference is recorded before its requested actions with assistant text,
+normalized tool-call IDs, model id, token usage, and duration; `runsGetTrace`
+returns those model turns interleaved with action turns. Recording is
+best-effort, so an older daemon without the method still runs the agent. 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

package/agent-loop.d.ts

@@ -39,7 +39,14 @@ export function runChatTurn(
   options?: AgentChatTurnOptions & { includeRunId?: false },
 ): Promise<string>;
 
+export function serveChat(config: AgentLoopConfig): Promise<CarRuntime>;
+
 export function main(config: AgentLoopConfig): Promise<void>;
 
-declare const agentLoop: { main: typeof main; runAgent: typeof runAgent; runChatTurn: typeof runChatTurn };
+declare const agentLoop: {
+  main: typeof main;
+  runAgent: typeof runAgent;
+  runChatTurn: typeof runChatTurn;
+  serveChat: typeof serveChat;
+};
 export default agentLoop;

package/agent-loop.js

@@ -138,6 +138,40 @@ function makeToolCallback(tools, toolTimeouts = {}, onFinish = null) {
 // single full re-write of the prefix, and every surviving turn then reads at
 // ~0.1x.
 //
+// Registration belongs to the daemon connection, not to an individual run.
+// Remember what this package installed so a caller-owned runtime can serve
+// hundreds of sequential runs without appending the same policy hundreds of
+// times. Weak keys ensure this bookkeeping never keeps a runtime/socket alive.
+const RUNTIME_REGISTRATION = new WeakMap();
+
+async function prepareRuntime(rt, toolSchemas, policies) {
+  let state = RUNTIME_REGISTRATION.get(rt);
+  if (!state) {
+    state = { basicsAttempted: false, tools: new Set(), policies: new Set() };
+    RUNTIME_REGISTRATION.set(rt, state);
+  }
+  if (!state.basicsAttempted) {
+    state.basicsAttempted = true;
+    try { await rt.registerAgentBasics(); } catch { /* unsupported on this daemon — fine */ }
+  }
+  for (const schema of toolSchemas) {
+    if (state.tools.has(schema.name)) continue;
+    await rt.registerTool(schema.name);
+    state.tools.add(schema.name);
+  }
+  for (const policy of policies || []) {
+    const fingerprint = JSON.stringify(policy);
+    if (state.policies.has(fingerprint)) continue;
+    await rt.registerPolicy(...policy);
+    state.policies.add(fingerprint);
+  }
+}
+
+async function closeRuntime(rt) {
+  if (typeof rt.close === 'function') await rt.close();
+  else if (typeof rt.disconnect === 'function') await rt.disconnect();
+}
+
 /** 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({
@@ -155,6 +189,28 @@ async function inferTurn(rt, { model, maxTokens, toolSchemas, messages, toolChoi
   })));
 }
 
+/** Record one completed inference before any requested action executes. */
+async function recordModelTurn(rt, runId, turnIndex, tracked, fallbackModel) {
+  if (runId === null || typeof rt.runsRecordModelTurn !== 'function') return;
+  try {
+    await rt.runsRecordModelTurn(JSON.stringify({
+      run_id: runId,
+      turn_index: turnIndex,
+      assistant_text: tracked.text || '',
+      requested_tool_calls: (tracked.tool_calls || []).map((call) => ({
+        id: call.id || '',
+        name: call.name || '',
+        arguments: call.arguments ?? {},
+      })),
+      model_id: tracked.model_used || fallbackModel || 'unknown',
+      token_usage: tracked.usage ?? null,
+      duration_ms: Number.isSafeInteger(tracked.latency_ms) && tracked.latency_ms >= 0
+        ? tracked.latency_ms
+        : 0,
+    }));
+  } catch { /* older daemon or transient trace failure — inference still counts */ }
+}
+
 /**
  * Run the agent once toward `goal`. Returns an AgentOutcome-shaped object:
  *   { status, summary, evidence[], metrics{}, tools_called[], run_id }
@@ -168,8 +224,19 @@ async function inferTurn(rt, { model, maxTokens, toolSchemas, messages, toolChoi
  * `rt.runsComplete`. Both are best-effort and never print, so the daemon traces
  * the run for CarHost while older daemons report `run_id: null` and still run.
  */
-async function runAgent(config, goal, { maxTurns } = {}) {
-  const { CarRuntime, executeProposal } = runtimeApi();
+async function runAgent(config, goal, options = {}) {
+  const { CarRuntime } = runtimeApi();
+  const ownsRuntime = config.runtime == null;
+  const rt = config.runtime ?? new CarRuntime();
+  try {
+    return await runAgentWithRuntime(rt, config, goal, options);
+  } finally {
+    if (ownsRuntime) await closeRuntime(rt);
+  }
+}
+
+async function runAgentWithRuntime(rt, config, goal, { maxTurns } = {}) {
+  const { executeProposal } = runtimeApi();
   const turnsCap = maxTurns ?? config.maxTurns ?? 8;
   const toolSchemas = [...(config.toolSchemas || []), FINISH_SCHEMA];
   const tools = { finish: ({ answer }) => ({ answer }), ...(config.tools || {}) };
@@ -180,15 +247,9 @@ async function runAgent(config, goal, { maxTurns } = {}) {
     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);
+  // Tools and declarative policies live on the daemon connection. Register
+  // each exact entry once when the caller reuses a runtime across runs.
+  await prepareRuntime(rt, toolSchemas, config.policies);
 
   // Run-trace bracket (open). Tell the daemon a run is starting so CarHost can
   // trace it: prompt -> CLI outcome -> verifier verdict -> AgentOutcome. The
@@ -258,16 +319,16 @@ async function runAgent(config, goal, { maxTurns } = {}) {
     }
 
     const calls = tracked.tool_calls || [];
+    // Normalize ids before tracing so the recorded decision carries the same
+    // ids proposal execution and subsequent tool_results use.
+    calls.forEach((c, i) => { c.id = c.id || `a${i}`; });
+    await recordModelTurn(rt, runId, turns, tracked, config.defaultModel);
     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]));
 
@@ -432,13 +493,16 @@ async function runChatTurn(
       messages,
     });
     const calls = tracked.tool_calls || [];
+    calls.forEach((c, i) => { c.id = c.id || `a${i}`; });
+    await recordModelTurn(
+      rt, runId, turns + 1, tracked, selectedModel ?? config.defaultModel,
+    );
     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.
@@ -495,15 +559,19 @@ async function runChatTurn(
 /** 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 ownsRuntime = config.runtime == null;
+  const rt = config.runtime ?? 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);
+  try {
+    await prepareRuntime(rt, toolSchemas, config.policies);
+  } catch (error) {
+    if (ownsRuntime) await closeRuntime(rt);
+    throw error;
+  }
 
   if (typeof registerChatHandler !== 'function') {
     console.error(`[${config.agentName}] car-runtime has no agent.chat support — chat disabled (update car-runtime).`);
@@ -536,6 +604,21 @@ async function serveChat(config) {
   return rt;
 }
 
+function shutdownLatch() {
+  let resolve;
+  const promise = new Promise((r) => { resolve = r; });
+  const onSignal = () => resolve();
+  process.once('SIGINT', onSignal);
+  process.once('SIGTERM', onSignal);
+  return {
+    promise,
+    cleanup() {
+      process.removeListener('SIGINT', onSignal);
+      process.removeListener('SIGTERM', onSignal);
+    },
+  };
+}
+
 async function main(config) {
   const args = parseArgs(process.argv.slice(2));
 
@@ -544,24 +627,39 @@ async function main(config) {
     // "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));
+    let chatRuntime = null;
+    const ownsRuntime = config.runtime == null;
+    const shutdown = shutdownLatch();
+    try {
+      try { chatRuntime = 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-trace bracket on the same long-lived
+            // chat runtime, so standing service does not grow daemon sockets.
+            const runConfig = chatRuntime ? { ...config, runtime: chatRuntime } : config;
+            const o = await runAgent(runConfig, goal);
+            console.error(`[${config.agentName}] ${o.status} — ${o.summary}`);
+          } catch (e) { console.error(`[${config.agentName}] error:`, e); }
+          const delay = new Promise((resolve) => {
+            const timer = setTimeout(() => resolve(false), everyMs);
+            timer.unref?.();
+          });
+          const stopped = await Promise.race([
+            shutdown.promise.then(() => true),
+            delay,
+          ]);
+          if (stopped) return;
+        }
+      } else {
+        await shutdown.promise;
       }
-    } 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);
+    } finally {
+      shutdown.cleanup();
+      if (ownsRuntime && chatRuntime) await closeRuntime(chatRuntime);
     }
     return;
   }
@@ -589,4 +687,4 @@ async function main(config) {
   process.exit(outcome.status === 'failure' ? 1 : 0);
 }
 
-module.exports = { main, runAgent, runChatTurn };
+module.exports = { main, runAgent, runChatTurn, serveChat };

package/agent-loop.mjs

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