car-runtime 0.25.0 → 0.26.0

package/index.d.ts

@@ -667,12 +667,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. */
+  /**
+   * 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): 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 +1099,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) ---
@@ -1401,6 +1428,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 +1520,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 +1551,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 +1634,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 +1910,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 +2066,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 +2171,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`.

package/package.json

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