car-runtime 0.25.0 → 0.27.0

package/index.d.ts

@@ -49,6 +49,19 @@ export class CarRuntime {
    */
   loadMemory(path: string): Promise<number>;
 
+  /**
+   * Stream one delta of a chat turn back to the daemon as an
+   * `agent.chat.event` notification (the agent-chat surface). Called from an
+   * `agent.chat` handler (see `registerChatHandler`) to emit the reply
+   * incrementally; the daemon rewrites each event to `agents.chat.event` for
+   * the host that issued `agents.chat`, keyed by `sessionId`.
+   *
+   * `kind` is one of `token` | `tool_call` | `done` | `error`. `delta` carries
+   * the text for `token` (and the final text/status for `done`/`error`); omit
+   * it for a bare signal.
+   */
+  chatEvent(sessionId: string, kind: string, delta?: string | undefined | null): Promise<void>;
+
   /**
    * Persist memory graph to a JSON file (backward-compatible flat format).
    * Returns the number of records written.
@@ -667,12 +680,30 @@ export class CarRuntime {
   /** Set update preferences (JSON `UpdatePreferences` shape). Returns stored prefs JSON. */
   updatePrefsSet(prefsJson: string): Promise<string>;
 
-  /** Route a prompt. Returns the routing decision as JSON. */
-  routeModel(prompt: string): Promise<string>;
+  /**
+   * Route a prompt. Returns the routing decision as JSON, including
+   * `candidates`: the advisory ranking of every scored model
+   * (`{ model_id, reliability, score, selected, in_band }`) so callers can see
+   * why a model won and what the alternatives cost in reliability terms. Empty
+   * on explicit-model and cold-start paths where no ranking occurred.
+   */
+  routeModel(prompt: string, intentJson?: string | null): Promise<string>;
 
   /** Per-model performance profiles. Returns JSON. */
   modelStats(): Promise<string>;
 
+  /**
+   * Persistent outcome scoreboard, folded from the durable outcome ledger.
+   * Returns JSON `{ rows: [{ model_id, success_count, fail_count,
+   * inconclusive_count, total_input_tokens, total_output_tokens, avg_quality,
+   * avg_latency_ms, success_rate, tokens_per_success, usd_per_success }],
+   * total_successes, total_failures, total_inconclusive, total_usd,
+   * overall_usd_per_success, model_count, receipts }`. Rows are sorted
+   * cheapest-correct-outcome first. The cross-session, outcome-denominated view
+   * (unlike `modelStats`, the live in-memory profiles).
+   */
+  outcomeScoreboard(): Promise<string>;
+
   // --- Execution ---
 
   /** Count of events in this runtime's execution log. */
@@ -1081,6 +1112,15 @@ export interface IntentHint {
    * then `prefer_quality`, then `prefer_local`.
    */
   prefer_quality?: boolean;
+  /**
+   * The operation is high-stakes — consequential or irreversible (e.g. the
+   * session is authorized for FullAccess actions). Forces the strongest
+   * quality posture regardless of task or any cost/latency preference: never
+   * economize on what you can't take back. Highest precedence — wins over
+   * `prefer_fast`, `prefer_quality`, and `prefer_local`. The daemon sets this
+   * automatically for FullAccess-granted sessions.
+   */
+  high_stakes?: boolean;
 }
 
 // --- Voice streaming (stored-callback pattern) ---
@@ -1155,6 +1195,32 @@ export function registerVoiceEventHandler(
   onEvent: (sessionId: string, eventJson: string) => void,
 ): void;
 
+/**
+ * Register the JS handler that serves daemon-initiated `agent.chat`
+ * reverse-calls — the agent-chat surface. A supervised agent (running in
+ * `--serve` mode, attached via `session.auth`) calls this once; the daemon
+ * reverse-calls `agent.chat` for every host `agents.chat`, the bridge acks
+ * `{accepted:true}` immediately, and fires this handler.
+ *
+ * `handlerFn(paramsJson)` receives `{"session_id":"...","prompt":"...",
+ * "attachments":[...]?,"context":{...}?}` as a JSON string. Run one
+ * conversational turn — keep a per-`session_id` message thread, run the
+ * agent loop, and stream the reply back via `CarRuntime.chatEvent` — then
+ * return. It is fire-and-forget (the ack already went back), so a rejected
+ * Promise is logged, not surfaced to the host. Process-wide setter,
+ * symmetric to `registerVoiceEventHandler`; pair with
+ * `unregisterChatHandler` to clear.
+ */
+export function registerChatHandler(
+  handlerFn: (paramsJson: string) => void,
+): void;
+
+/**
+ * Clear the registered `agent.chat` handler. Subsequent reverse-calls are
+ * refused so the daemon learns this agent is no longer conversational.
+ */
+export function unregisterChatHandler(): void;
+
 /**
  * Register the JS `tools.execute` handler for `submitProposal`
  * (Parslee-ai/car-releases#38). When the daemon dispatches a
@@ -1401,6 +1467,13 @@ export function resumeWorkflow(pausedJson: string, inputJson: string): Promise<s
 /** Static analysis on a workflow definition. Returns verification report JSON. */
 export function verifyWorkflow(workflowJson: string): string;
 
+/**
+ * Build the external-item automation recipe (poll → dedup → per-item agent →
+ * deliver) from an `AutomationSpec` JSON into a runnable workflow JSON. Hand the
+ * result to `runWorkflow`, typically on a schedule. Stateless.
+ */
+export function buildAutomationWorkflow(specJson: string): string;
+
 export interface StartMeetingResponse {
   id: string;
   title: string;
@@ -1486,12 +1559,19 @@ export function reapStaleAgents(
 // --- car-a2a server lifecycle ---
 //
 // Expose CAR as an Agent2Agent (A2A) v1.0 peer programmatically,
-// without shelling out to `car-server --a2a-bind`. Process-global
-// state holds the bound listener and join handle so a later
-// `stopA2aServer` / `a2aServerStatus` call reaches the right server.
+// without shelling out to `car-server --a2a-bind`. These proxy to the
+// daemon the `CarRuntime` is connected to, so each takes the runtime as
+// its first argument.
+//
+// NOTE ON NAMING: napi-rs (heck) splits at digit→letter boundaries, so
+// the Rust `start_a2a_server` camelCases to `startA2AServer` (the `a2a`
+// segment becomes `A2A`), NOT `startA2aServer`. The exported names are
+// `startA2AServer` / `stopA2AServer` / `a2AServerStatus` /
+// `sendA2AMessage` / `a2ADispatch`. (Earlier versions of this file
+// declared `…A2a…`, which did not exist at runtime — car-releases#65.)
 
 /**
- * Start an A2A listener.
+ * Start an A2A listener on the daemon `rt` is connected to.
  *
  * `paramsJson` shape:
  * ```jsonc
@@ -1510,31 +1590,49 @@ export function reapStaleAgents(
  * the calling `CarRuntime`'s session runtime instead of spawning a
  * fresh one. Tools registered on the session via
  * `registerToolSchema` then appear on the Agent Card's `skills`
- * list, and A2A peer `message/send` calls for those tools route
- * back to the handler installed via `registerToolHandler`. This is
+ * list, and A2A peer `message/send` calls that carry an explicit
+ * tool invocation (a `data` part `{ "tool": "...", "parameters": {...} }`)
+ * route back to the handler installed via `registerToolHandler`. This is
  * the canonical path for host-language agents to project themselves
  * over A2A. Default `false` preserves the legacy fresh-Runtime
  * behaviour (only `register_agent_basics` tools, dispatch in Rust).
  *
+ * A purely *conversational* `message/send` (free text, no tool `data`
+ * part) is routed to the host's `agent.chat` handler — the daemon
+ * reverse-calls `agent.chat` on this session, aggregates the streamed
+ * reply, and returns it as the A2A agent message (car-releases#65). So
+ * register an `agent.chat` handler to serve conversational turns, and/or
+ * a `registerToolHandler` for explicit tool `data` parts.
+ *
  * 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.
  */
-export function startA2aServer(paramsJson: string): Promise<string>;
+export function startA2AServer(rt: CarRuntime, paramsJson: string): Promise<string>;
 
 /**
  * Stop the running A2A listener. Returns `'{"stopped":true}'` on
  * success. Errors if no server is running.
  */
-export function stopA2aServer(): string;
+export function stopA2AServer(rt: CarRuntime): Promise<string>;
 
 /**
  * Report whether the A2A listener is up. Always returns a JSON
  * object — `{"running":true,"bound":"...","uptime_secs":N}` when
  * running, `{"running":false}` otherwise.
  */
-export function a2aServerStatus(): string;
+export function a2AServerStatus(rt: CarRuntime): Promise<string>;
+
+/**
+ * Send a message to a remote A2A peer at `endpoint`.
+ *
+ * `paramsJson` shape: `{ endpoint, message, blocking?, ingest_a2ui?,
+ * route_auth?, allow_untrusted_endpoint? }`. The daemon enforces a
+ * loopback-or-explicit-allow rule on `endpoint` — non-loopback URLs
+ * require `allow_untrusted_endpoint: true`.
+ */
+export function sendA2AMessage(rt: CarRuntime, paramsJson: string): Promise<string>;
 
 // --- Verification (stateless) ---
 
@@ -1575,6 +1673,13 @@ export function optimize(proposalJson: string): string;
 
 export function equivalent(proposal1Json: string, proposal2Json: string): boolean;
 
+/**
+ * Wire protocol version this binding speaks to the `car-server` daemon,
+ * exchanged via the `server.handshake` RPC. Bumped only on a
+ * backward-incompatible JSON-RPC change — independent of the package semver.
+ */
+export function protocolVersion(): number;
+
 /**
  * Check a proposal for transactional conflicts against the current shared
  * state (survey "Code as Agent Harness" §4.3/§5.2.4 — the shared
@@ -1844,6 +1949,34 @@ export function createTask(
   systemPrompt?: string | null,
 ): string;
 
+/**
+ * Preview the durable OS-level schedule (launchd plist + crontab line) a task
+ * would install, without installing it. `program` + `argsJson` (a JSON string
+ * array) are the command the OS runs to execute the task once. Returns
+ * `{ label, launchdPlist, launchdError, crontabLine, crontabError }`.
+ */
+export function renderOsSchedule(taskJson: string, program: string, argsJson: string): string;
+
+/**
+ * Install a durable OS-level schedule (launchd on macOS, crontab on Linux) so
+ * the task fires even when the CAR daemon is down. Idempotent. Returns the
+ * installed-schedule JSON.
+ */
+export function installOsSchedule(taskJson: string, program: string, argsJson: string): string;
+
+/** Remove a task's OS-level schedule (full label or bare task id). Returns `{ label, removed }`. */
+export function uninstallOsSchedule(labelOrId: string): string;
+
+/** List labels of all CAR-managed OS-level schedules on this host (JSON string array). */
+export function listOsSchedules(): string;
+
+/**
+ * Reap orphaned OS-level schedules — uninstall every CAR-managed launchd/cron
+ * entry whose task is gone from `~/.car/tasks/` or whose trigger is no longer
+ * schedulable. Returns the reconcile report `{ removed, kept, errors }`.
+ */
+export function reconcileOsSchedules(): string;
+
 /** Run a task once using the registered agent runner. */
 export function runTask(taskJson: string): Promise<string>;
 
@@ -1972,7 +2105,7 @@ export function visionOcr(argsJson: string): Promise<string>;
  * both in one process gives you two task stores (task ids are
  * unique per dispatcher).
  */
-export function a2aDispatch(method: string, paramsJson: string): Promise<string>;
+export function a2ADispatch(rt: CarRuntime, method: string, paramsJson: string): Promise<string>;
 
 // --- Lifecycle-managed agents (car_registry::supervisor) ---
 
@@ -2077,6 +2210,20 @@ export function agentsStop(id: string, signal?: string | null): Promise<string>;
  */
 export function agentsRestart(id: string): Promise<string>;
 
+/**
+ * Block until a managed agent reaches one of `targetsJson` (a JSON string array
+ * of statuses like `["running"]` or `["stopped","errored"]`; default
+ * `["running"]`) or `timeoutSecs` (default 30) elapses, polling every `pollMs`
+ * (default 200). Returns the matching `ManagedAgent` JSON; rejects on timeout or
+ * unknown id.
+ */
+export function agentsWait(
+  id: string,
+  targetsJson?: string | null,
+  timeoutSecs?: number | null,
+  pollMs?: number | null,
+): Promise<string>;
+
 /**
  * Read a window of an agent's logs under
  * `~/.car/logs/<id>.{stdout,stderr}.log`.
@@ -2193,12 +2340,26 @@ export function agentsHealthExternal(
  *     "allowed_tools"?: string[],      // tool allowlist; [] denies all
  *     "max_turns"?: number,            // turn cap
  *     "timeout_secs"?: number,         // hard deadline (default 300s)
- *     "mcp_endpoint"?: string          // MCP server URL passed via
+ *     "mcp_endpoint"?: string,         // MCP server URL passed via
  *                                      // --mcp-config; daemon callers
  *                                      // auto-fill from car-server's
  *                                      // bound /mcp URL. "" opts out.
+ *     "attachments"?: [               // images attached to the prompt
+ *       { "path": string,             // abs path on the daemon's fs
+ *         "media_type"?: string }     // advisory; the runner derives
+ *     ]                               // the real type from content
  *   }
  *
+ * `attachments` are image files the runner hands to the CLI in its
+ * native form: Claude Code reads + inlines a base64 image block on
+ * stdin, Codex passes each via `--image`, Gemini references it with
+ * `@path`. Paths must be readable by the daemon process. The runner
+ * caps reads at 32 MB and (on the read/stage paths) verifies the bytes
+ * are a real image by magic signature, deriving `media_type` from
+ * content — non-image / oversized / unreadable paths are skipped, so a
+ * file that isn't an image is never inlined. Adapters whose CLI lacks
+ * image input ignore them.
+ *
  * Returns JSON `InvokeResult`:
  *
  *   {
@@ -2208,6 +2369,7 @@ export function agentsHealthExternal(
  *     "tool_calls": number,            // tool_use blocks observed
  *     "duration_ms": number,
  *     "total_cost_usd"?: number,       // would-be API cost (subscription users don't pay)
+ *     "dropped_attachments"?: number,  // images dropped (unreadable/oversized/not an image); omitted when 0
  *     "is_error": boolean,
  *     "error"?: string
  *   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "car-runtime",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "Common Agent Runtime — a deterministic execution layer for AI agents",
   "main": "index.js",
   "types": "index.d.ts",