car-runtime 0.26.0 → 0.28.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.
@@ -631,7 +644,15 @@ export class CarRuntime {
    * invoked }` JSON. `maxSubtasks` caps the split (clamped to [1, 10]; null =
    * default 5). With `invoke: true`, each subtask's chosen agent runs.
    */
-  declagentRouteSplit(need: string, invoke: boolean, maxSubtasks?: number | undefined | null): Promise<string>;
+  declagentRouteSplit(
+    need: string,
+    invoke: boolean,
+    maxSubtasks?: number | undefined | null,
+    decompositionMode?: "vanilla" | "sad" | string | undefined | null,
+    sadHints?: number | undefined | null,
+    sadIterations?: number | undefined | null,
+    sadConvergenceJaccard?: number | undefined | null
+  ): Promise<string>;
   /**
    * Read-only view of the learned routing topology: per-agent success stats
    * and directed agent→agent edge weights. Returns `{ agents, edges }` JSON.
@@ -645,6 +666,21 @@ export class CarRuntime {
    * null = default 5).
    */
   discoveryResolve(need: string, limit?: number | undefined | null): Promise<string>;
+  /**
+   * Compose a decompose/retrieve/plan route over all discoverable services.
+   * Returns `{ plan, decomposition, candidates, metadata }` JSON. Planning only;
+   * callers invoke returned targets through existing governed surfaces.
+   */
+  discoveryRouteCompose(
+    need: string,
+    maxSubtasks?: number | undefined | null,
+    decompositionMode?: "vanilla" | "sad" | string | undefined | null,
+    sadHints?: number | undefined | null,
+    sadIterations?: number | undefined | null,
+    sadConvergenceJaccard?: number | undefined | null,
+    candidatesPerStep?: number | undefined | null,
+    rerank?: boolean
+  ): Promise<string>;
 
   /**
    * Build a concrete onboarding plan (machine summary, top pick, alternatives,
@@ -674,7 +710,7 @@ export class CarRuntime {
    * 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): Promise<string>;
+  routeModel(prompt: string, intentJson?: string | null): Promise<string>;
 
   /** Per-model performance profiles. Returns JSON. */
   modelStats(): Promise<string>;
@@ -819,6 +855,14 @@ export class CarRuntime {
   /** Returns JSON `{exists: boolean, key, service}` without exposing the value. */
   secretStatus(key: string, service?: string | null): string;
 
+  /**
+   * List the NAMES of secrets stored through this surface. Returns JSON
+   * `{secrets: [{service, key, exists}]}` — never the values. Backed by the
+   * `~/.car/secret_index.json` name index, joined with a live existence check
+   * (`exists` is `null` if the backend couldn't be probed).
+   */
+  secretList(): string;
+
   // -------------------------------------------------------------------------
   // OS permission preflight
   // -------------------------------------------------------------------------
@@ -1182,6 +1226,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
@@ -2301,12 +2371,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`:
  *
  *   {
@@ -2316,6 +2400,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.26.0",
+  "version": "0.28.0",
   "description": "Common Agent Runtime — a deterministic execution layer for AI agents",
   "main": "index.js",
   "types": "index.d.ts",