car-runtime 0.24.1 → 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) ---
 
@@ -1548,6 +1607,15 @@ export function a2aServerStatus(): string;
  * `JSON.stringify([{ name: "echo", parameters: { type: "object",
  * properties: { msg: { type: "string" } }, required: ["msg"] } }])`.
  * When both are given, `toolSchemasJson` takes precedence.
+ *
+ * Returns a JSON string:
+ * `{ valid, issues, simulated_state, execution_levels, conflicts,
+ * evidence }`. `evidence` is the verifier's declared scope (survey
+ * "Code as Agent Harness" §5.2.2): `{ checks: [{ name, ran, verifies,
+ * cannot_verify, findings }], assumptions, untested_regions,
+ * residual_risks, confidence }` — so a `valid: true` verdict can be read
+ * with its scope (what was checked, what was not, coverage confidence)
+ * rather than as a blanket guarantee.
  */
 export function verify(
   proposalJson: string,
@@ -1566,6 +1634,158 @@ 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
+ * code-centric harness substrate). `versionsJson` is a JSON object mapping
+ * state key → current version (from the runtime's versioned state store);
+ * `stateJson` (optional) maps key → current value for value-level
+ * assumption checks.
+ *
+ * Returns the `TransactionReport` JSON: `{ consistent: boolean, conflicts:
+ * [{ kind, key, actions, explanation, resolution }] }` where `kind` is
+ * `"write_write" | "read_write" | "stale_assumption"`. Detects write-write
+ * races and read-write hazards between unordered actions, and stale
+ * assumptions (an action planned against a key at a version/value the
+ * shared state has since moved past — belief divergence). Each conflict
+ * carries a human-actionable explanation and a suggested resolution.
+ */
+export function transactionCheck(
+  proposalJson: string,
+  versionsJson?: string | null,
+  stateJson?: string | null,
+): string;
+
+/**
+ * Compute harness-level evaluation metrics (survey "Code as Agent Harness"
+ * §5.2.1) from a JSONL tail of a session's event log (one event per line).
+ * Returns the `HarnessMetrics` JSON with six operational-substrate
+ * dimensions — `trajectory_efficiency` (actions, tokens, cost, wall-clock,
+ * success_rate), `verification_strength` (validated/rejected, rejection_rate),
+ * `recovery` (replans, branch decisions, rejected alternatives),
+ * `state_consistency` (changes, snapshots, rollbacks), `safety`
+ * (permission escalations/denials/approvals), and `replayability` — to
+ * complement task-success accuracy when comparing harness variants.
+ */
+export function harnessMetrics(eventsJsonl: string): string;
+
+// --- Agentic Harness Engineering: Evolution Agent (survey §3.5, §5.2.3) ---
+//
+// A governed meta-agent that proposes harness mutations from telemetry and
+// gates their adoption. Every mutation carries a change contract; promotion
+// is regression-gated; safety-affecting changes require human approval.
+
+/**
+ * Diagnose harness telemetry into governed mutation proposals. `metricsJson`
+ * is a `HarnessMetrics` (from {@link harnessMetrics}); `configJson`
+ * optionally overrides the diagnosis thresholds. Returns a JSON array of
+ * `HarnessMutation`, each `{ id, rationale, contract: { component,
+ * target_failure, predicted_improvement, invariants, falsifying_eval,
+ * rollback } }`. Nothing is applied — proposals must pass
+ * {@link evolutionEvaluate} and, when safety-affecting, human approval.
+ */
+export function evolutionDiagnose(
+  metricsJson: string,
+  configJson?: string | null,
+): string;
+
+/**
+ * Regression-gate a candidate harness mutation. `mutationJson` is a
+ * `HarnessMutation`; `baselineJson`/`candidateJson` are `HarnessMetrics`
+ * measured before/after applying it on held-out telemetry. Returns the
+ * `PromotionDecision` JSON `{ decision: "promote" | "needs_approval" |
+ * "reject", reason }` — a mutation is promoted only if its target improved
+ * without regressing guarded metrics; safety-affecting mutations route to
+ * `needs_approval` even when they pass.
+ */
+export function evolutionEvaluate(
+  mutationJson: string,
+  baselineJson: string,
+  candidateJson: string,
+  configJson?: string | null,
+): string;
+
+/**
+ * Apply a mutation's concrete patch to a `HarnessConfig` under governed
+ * authorization (survey §3.5/§5.2.3). `humanApproved=true` applies under the
+ * HITL path — the only path that may land a safety-affecting mutation;
+ * otherwise `decisionJson` (a `PromotionDecision`) must be `promote` and the
+ * mutation must be non-safety. Returns `{ config, rollback }` (the updated
+ * config and the inverse patch that restores it), or throws when refused.
+ */
+export function evolutionApply(
+  configJson: string,
+  mutationJson: string,
+  decisionJson?: string | null,
+  humanApproved?: boolean,
+): string;
+
+// --- Permission-tier gate (survey "Code as Agent Harness" §3.4.3, §5.2.5) ---
+//
+// The harness as safety governor: classify each action's risk tier
+// (read_only | sandbox_edit | full_access), gate it against the session's
+// granted standing tier, and record human-in-the-loop approvals as durable,
+// auditable state (a JSONL ledger keyed by a stable action fingerprint).
+
+/**
+ * Classify each action in a proposal into its minimum required permission
+ * tier. Returns a JSON array of `{ action_id, tool, required_tier }` where
+ * `required_tier` is `"read_only" | "sandbox_edit" | "full_access"`.
+ */
+export function permissionClassify(proposalJson: string): string;
+
+/**
+ * Evaluate each action against a granted standing tier, consulting the
+ * durable approval ledger JSONL at `ledgerPath` when supplied. Returns a
+ * JSON array of per-action decisions, each `{ decision, required, granted,
+ * action_id, fingerprint, ... }` where `decision` is `"allow" |
+ * "needs_approval" | "deny"`. A `needs_approval` decision means autonomy is
+ * suspended pending a human decision; resolve it with
+ * {@link permissionRecordForFingerprint}.
+ */
+export function permissionEvaluate(
+  proposalJson: string,
+  grantedTier: string,
+  ledgerPath?: string | null,
+): string;
+
+/**
+ * Record a durable human-in-the-loop approval (`approve=true`) or rejection
+ * for the operation an action represents, appending it to the JSONL ledger
+ * at `ledgerPath`. The decision persists and overrides future evaluations
+ * of the same operation. Returns the stored approval record JSON.
+ */
+export function permissionRecordDecision(
+  actionJson: string,
+  approve: boolean,
+  reviewer: string,
+  reason: string,
+  evidence: string | undefined | null,
+  ledgerPath: string,
+): string;
+
+/**
+ * Like {@link permissionRecordDecision} but keyed by an explicit
+ * `fingerprint` (from a prior `needs_approval` decision) with an annotating
+ * `requiredTier`. Returns the stored approval record JSON.
+ */
+export function permissionRecordForFingerprint(
+  fingerprint: string,
+  requiredTier: string,
+  approve: boolean,
+  reviewer: string,
+  reason: string,
+  evidence: string | undefined | null,
+  ledgerPath: string,
+): string;
+
 // --- Multi-agent coordination ---
 
 /**
@@ -1690,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>;
 
@@ -1818,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) ---
 
@@ -1923,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.24.1",
+  "version": "0.26.0",
   "description": "Common Agent Runtime — a deterministic execution layer for AI agents",
   "main": "index.js",
   "types": "index.d.ts",