car-runtime 0.47.0 → 0.49.0

package/index.d.ts

@@ -151,6 +151,28 @@ export class CarRuntime {
   /** Register a tool by name. */
   registerTool(name: string): Promise<void>;
 
+  /**
+   * The tools currently registered on this runtime, as a JSON array of full
+   * `ToolSchema` objects sorted by name.
+   *
+   * Counterpart to `registerTool` / `registerToolSchema`, which had none: a
+   * caller could add tools but never ask what was actually in effect, so a
+   * governed or read-only deployment could not prove "only these tools are
+   * callable". Sorted, so two calls with no registration in between are
+   * byte-identical and can be diffed.
+   */
+  listTools(): Promise<string>;
+
+  /**
+   * Remove a tool by name. Resolves to how many were removed — `0` means
+   * nothing matched, which is not an error, so cleanup can call this
+   * unconditionally.
+   *
+   * Drops the tool from both the runtime's registry and its schema map, so
+   * the model stops seeing it and the validator stops accepting it.
+   */
+  unregisterTool(name: string): Promise<number>;
+
   /** Register CAR's built-in agent utility tools. */
   registerAgentBasics(): Promise<void>;
 
@@ -399,6 +421,26 @@ export class CarRuntime {
    * dispatches the chosen components.
    */
   planEvolutionLive(requestJson: string): Promise<string>;
+  /**
+   * `supervision.subscribe` — register this connection as a supervisor of the
+   * admission gate: `{ filter?: { tools?, sessions?, min_reversibility? } }`.
+   *
+   * Intents arrive as `supervision.intent` NOTIFICATIONS on the same socket.
+   * A caller that cannot read notifications should poll `supervisionPending`
+   * instead — subscribing without consuming them blocks every supervised
+   * proposal until it fails closed.
+   */
+  supervisionSubscribe(requestJson: string): Promise<string>;
+  /**
+   * `supervision.unsubscribe` — stop supervising: `{}`. Intents already parked
+   * run out their timeout and fail closed rather than being released, so a
+   * supervisor cannot turn a pending deny into an allow by disconnecting.
+   */
+  supervisionUnsubscribe(requestJson: string): Promise<string>;
+  /** `supervision.pending` — every intent currently parked on a verdict: `{}`. */
+  supervisionPending(requestJson: string): Promise<string>;
+  /** `supervision.decide` — `{ intent_id, decision: { kind: "allow" | "deny" | "escalate", reason? } }`. */
+  supervisionDecide(requestJson: string): Promise<string>;
   /** `sync.status` — roster, journal frontier, stable frontier, state hash (B6). */
   syncStatus(requestJson: string): Promise<string>;
   /** `sync.append` — record an op on any surface: `{ surface, payload, scope? }` (B6). */
@@ -432,15 +474,97 @@ export class CarRuntime {
    * Run one evolution cycle over the daemon's **live** signals — the
    * self-evolution governor's real executor (arXiv 2507.21046). `requestJson`
    * is `{ policy?, dry_run?, harness_baseline_metrics?,
-   * harness_candidate_metrics? }`; the daemon plans over all five live
+   * harness_candidate_metrics?, harness_measure?, context_measure? }`; the daemon plans over all five live
    * components (Memory/Skills/Context from the engine, Harness from the event
    * log, Tools from connector health) and dispatches each `EvolveNow`
    * component: Memory → consolidate (sized by decide_maintenance), Skills →
    * evolve_skills over event-log failure traces, Harness → the HITL-gated
    * harness_evolution loop (pending approvals resolve via
-   * `permission.approve`/`reject` by fingerprint); Context/Tools record
-   * `not_executable`. Returns the cycle record JSON
-   * `{ plan, steps, evolved, pending_approvals? }`.
+   * `permission.approve`/`reject` by fingerprint), Context → the
+   * `context_evolution` loop, which resolves each mutation either through the
+   * opt-in pre-activation grader (`context_measure`) or, for whatever that did
+   * not decide, the diagnose→approve→apply→measure→revert human path. Returns
+   * the cycle record JSON
+   * `{ plan, steps, evolved, out_of_scope, pending_approvals?, measurement? }`,
+   * where each step is `{ component, ran, applied, out_of_scope, outcome }`.
+   *
+   * **Context.** Diagnoses off the engine's own live conversation-layer
+   * saturation and lowers `MemgineConfig.conversation_keep_recent` (halved,
+   * floored at 2) so compaction summarizes more of the older turns. Every
+   * mutation is HITL-gated on the same shared durable `ApprovalLedger` as
+   * harness ones, under its own fingerprint namespace
+   * `context:<component>:<patch-digest>`, resolved by the same
+   * `permission.approve`/`reject`. There **is** a pre-activation regression
+   * gate, opt-in via `context_measure` (see below) — this doc comment used to
+   * say there was none, because the bench replayed a runtime with no memgine
+   * attached and never offered a `recall` tool; bench tasks may now declare a
+   * `memory:` fixture and are then replayed with a real memgine and the shipped
+   * `recall` tool, so the assembled context moves with the knob. A graded
+   * mutation promotes (`applied` with `governance: "promoted"`) or is rejected
+   * (`rejected_by_gate`) with no operator in the loop. On the human-approved
+   * path — and whenever no grade ran — the daemon measures the MARGIN after the
+   * apply: compact under the unchanged value for a baseline
+   * (`conversation_tokens_baseline`), apply, compact again, and revert unless
+   * the tokens fell below that baseline (`rolled_back`, not counted as
+   * applied; `rollback_failed` with `rollback_error` if even the revert did
+   * not take). Comparing against the baseline rather than the uncompacted
+   * layer is what stops the change being credited with savings compaction
+   * would have produced anyway. So context is **not** unattended out of the
+   * box; it becomes unattended for a given change only once that fingerprint
+   * has been approved — and since the ledger is daemon-wide and the
+   * fingerprint names the change, that approval covers the same change on
+   * every engine this daemon evolves. On the unattended cadence a falsified
+   * mutation then backs off exponentially per fingerprint (`in_backoff`)
+   * instead of being re-applied and re-reverted every tick. The step's
+   * `outcome` is a JSON string `{ mechanism: "context_evolution", mutations,
+   * applied, pending, details }`, each detail carrying `mutation`,
+   * `component`, `fingerprint`, `rationale` and one of `pending_approval` |
+   * `applied` | `rolled_back` | `rollback_failed` | `apply_failed` |
+   * `would_apply` | `in_backoff` | `rejected_by_operator` |
+   * `approved_no_patch` | `rejected_by_gate` | `measurement_failed` |
+   * `config_moved_during_measurement` (a graded promotion whose measured base
+   * was moved by something else while the replays ran — nothing applied, both
+   * values reported, no backoff). When `context_measure` was requested the
+   * summary also carries `context_measured: { status: "measured" |
+   * "skipped_dry_run", grade_attempts, model, split, split_seed }`.
+   *
+   * **Tools** is recorded as `out_of_scope` — a decision, not a failure.
+   * Connector remediation means re-running a connector's OAuth or credential
+   * exchange, an access change this loop holds no authority to perform;
+   * reconnect/re-auth stay operator actions via `connectors.*`. Such a step is
+   * `ran: true, applied: false, out_of_scope: true` with the reason in
+   * `outcome`, and the component appears in the top-level `out_of_scope`
+   * array (always present, empty when none). `ran: false` therefore means one
+   * thing only: the mechanism was invoked and errored.
+   *
+   * `harness_measure` `{ model, split?, held_in_fraction?, split_seed?,
+   * max_turns?, tasks_dir? }` opts into **in-daemon measurement**: the daemon
+   * replays the held-out split itself (once for the baseline under the live
+   * `HarnessConfig`, once per measurable mutation under that config plus the
+   * mutation's patch) and feeds the regression gate, so a cycle can promote or
+   * reject unattended. It is mutually exclusive with the two supplied-metrics
+   * params (sending both errors, naming both); `dry_run` measures nothing and
+   * reports `measurement.status = "skipped_dry_run"`; a build with no
+   * in-process evaluator installed errors rather than degrading to HITL;
+   * safety-affecting and patchless mutations are never measured; a failed
+   * replay reports `measurement_failed` and fabricates no metrics.
+   *
+   * `context_measure` takes the SAME request shape and opts into the **Context
+   * pillar's** pre-activation grader: two replays over the same split, one
+   * under the engine's live `MemgineConfig` and one under it plus the
+   * mutation's patch, graded on TASK outcomes by the same gate. The two params
+   * are not mutually exclusive with each other (different pillars, two
+   * independent measurements). `dry_run` performs no replay; a build with no
+   * evaluator installed errors; a patchless mutation is never measured; the
+   * unattended cadence never requests a grade at all, so an idle timer cannot
+   * start spending benchmark replays.
+   * `measurement` is TOP-LEVEL on the response (not only inside the harness
+   * step) and present whenever `harness_measure` was requested, in every
+   * shape it can end in — `measured` / `skipped_dry_run` /
+   * `measurement_failed` with the error. A replay is a paid side effect and
+   * the plan may legitimately never dispatch Harness, so a side effect
+   * reported only from that step is one a caller can be billed for and never
+   * see.
    */
   runEvolutionCycleLive(requestJson: string): Promise<string>;
 
@@ -472,6 +596,27 @@ export class CarRuntime {
    */
   enforceSkillDeploymentLive(requestJson: string): Promise<string>;
 
+  /**
+   * Read the standing permission tier granted to this connection's daemon
+   * session (`read_only` | `sandbox_edit` | `full_access`) — the tier every
+   * {@link submitProposal} on this connection is judged against
+   * (Parslee-ai/car#890).
+   */
+  permissionGetTier(): Promise<string>;
+
+  /**
+   * Set this connection's standing permission tier and return the tier as the
+   * daemon now holds it. `tier` is `read_only` | `sandbox_edit` |
+   * `full_access`.
+   *
+   * Lets a binding client govern its own session — most usefully by tightening
+   * it: dropping to `read_only` makes the runtime escalate any write this
+   * client proposes to a human instead of running it. Raising the tier is
+   * host-gated whenever the daemon runs under a host token, so an agent
+   * connection cannot self-elevate.
+   */
+  permissionSetTier(tier: string): Promise<string>;
+
   /**
    * Ingest a skill through the deployment gate on the daemon (arXiv 2602.12430
    * "Agent Skills" — the loader integration). `requestJson` carries the skill
@@ -485,6 +630,21 @@ export class CarRuntime {
    */
   ingestSkillGoverned(requestJson: string): Promise<string>;
 
+  /**
+   * Adopt an installed skill pack on the daemon through the skill-trust
+   * deployment gate (arXiv 2602.12430 "Agent Skills" — the pack-adoption
+   * call-site). `requestJson` carries `pack` (an `ApprovedSkillPack`),
+   * `requested_tier?` (default `read_only`), and either `manifest?` — the signed
+   * bundle, whose signature trust is derived against the operator's
+   * `.car/config.toml` `trusted_skill_signers` keyring — or `provenance?`
+   * (caller-assembled), plus optional `scanned?`/`vulnerabilities?`/`source?`.
+   * Governance is unconditional: a denied skill never enters the graph. Returns
+   * `{ loaded, pending, refused, requested_tier, provenance, trusted_signers }`;
+   * a pending deny is resolved via `permission.approve`/`permission.reject` by
+   * the returned `fingerprint`, then re-adopted.
+   */
+  adoptSkillPack(requestJson: string): Promise<string>;
+
   /**
    * Save a learned skill with trigger context. Returns the node
    * index.
@@ -597,6 +757,13 @@ export class CarRuntime {
    * with reasoning suppressed to produce a direct answer, or
    * `"thinking_truncated"` when even that retry was empty (car-releases#60).
    *
+   * `auth_fallback_from` is present ONLY when a candidate earlier in the
+   * fallback chain was skipped because its credential was **rejected**
+   * (not merely absent) and a later model then answered. It names that
+   * dead lane, so a caller can tell the user their sign-in lapsed instead
+   * of silently serving a different model (Parslee-ai/car#888). Absent on
+   * the common path.
+   *
    * **Note:** intent is not exposed on the tracked path until the
    * positional argument list is converted to an options object —
    * this method already takes 9 positional parameters and adding
@@ -782,8 +949,24 @@ export class CarRuntime {
   /**
    * Unified registry (local + remote). Returns JSON array of
    * `{ id, name, provider, capabilities, param_count, size_mb,
-   *   context_length, available, is_local, max_output_tokens,
-   *   public_benchmarks, cost }`. `max_output_tokens` is the registry-declared
+   *   context_length, available, is_local, weights_ready, downloads_weights,
+   *   max_output_tokens, public_benchmarks, cost }`. `available` means CAR
+   * can use the model
+   * here — for a local MLX entry with a declared `hf_repo` it is `true`
+   * before a byte is fetched, because it lazy-downloads on first use —
+   * whereas `weights_ready` means the weights are already on disk (remote
+   * models, having none to install, report `true`). Older daemons omit
+   * `weights_ready`; it defaults to `false` rather than failing.
+   * `downloads_weights` is `true` only for entries whose weights CAR fetches
+   * before use (GGUF, MLX, whisper.cpp); when it is `false` — OS-provided
+   * models such as `windows/speech-synthesis:os` and
+   * `apple/foundation:default`, server-backed local models such as
+   * `vllm-mlx/*` and Ollama, and every remote entry — there is nothing to
+   * install, so `weights_ready` is meaningless and the CLI renders
+   * `INSTALLED` as `-`. Do not substitute `is_local`: those first four are
+   * all local and all download nothing. Older daemons omit
+   * `downloads_weights`; it defaults to `false` rather than failing.
+   * `max_output_tokens` is the registry-declared
    *   per-model output ceiling (`null` when the entry omits it; callers
    *   then fall back to a fraction of `context_length`).
    * `public_benchmarks` is `[{ name, score, harness?, source_url?,
@@ -968,10 +1151,10 @@ export class CarRuntime {
    * error}` plus `needs_you` (`"contract" | "question" | "approval" | "auth" |
    * null`), `needs_you_label` (the daemon-owned wording, so every client says
    * the same thing), `question_prompt`, `auth_message`, `auth_wait_secs`,
-   * `failure_kind` (`"budget_exhausted" | "auth_required" | "error"` when
-   * failed), `worktree` (only when it still exists on disk), `project`,
-   * `result_branch`, `model`, `discussion_id`, and `next_seq` (live only —
-   * the `coder.subscribe` cursor).
+   * `failure_kind` (`"budget_exhausted" | "auth_required" | "infrastructure" |
+   * "error"` when failed), `worktree` (only when it still exists on disk),
+   * `project`, `result_branch`, `model`, `discussion_id`, and `next_seq` (live
+   * only — the `coder.subscribe` cursor).
    *
    * Pass `renew: true` for the lease-renewal form: it re-registers and answers
    * `{ was_registered }` — `false` means this connection had been shed and
@@ -1457,11 +1640,60 @@ export class CarRuntime {
   mailAccounts(): string;
 
   /**
-   * Returns JSON inbox snapshot. `accountIdsCsv` is an optional
-   * comma-separated filter; omit to query all known accounts.
+   * Returns JSON inbox snapshot
+   * `{ available, backend, reason?, summaries: InboxSummary[] }` — per-account
+   * unread/total counts, not message rows. Use `mailMessages` for rows.
+   * `accountIdsCsv` is an optional comma-separated filter; omit to query all
+   * known accounts.
    */
   mailInbox(accountIdsCsv?: string | null): string;
 
+  /**
+   * Enumerate every mailbox (folder) of the given accounts, nested ones
+   * included on BOTH backends. Returns
+   * `{ available, backend, reason?, mailboxes: Mailbox[] }` where `Mailbox`
+   * is `{ account_id, name, full_name, unread, total }`.
+   *
+   * `full_name` is the selector to pass back as `MessageQuery.mailbox` — the
+   * slash-joined path on macOS, the folder id on Microsoft Graph. Graph's
+   * `/me/mailFolders` is root-only, so nested folders come from a bounded
+   * `childFolders` walk (depth 8, at most 64 requests); a tree deeper or
+   * wider than that is truncated.
+   *
+   * An `accountIdsCsv` that matches no account returns `available: false`
+   * with a reason, not an empty list.
+   */
+  mailMailboxes(accountIdsCsv?: string | null): string;
+
+  /**
+   * Read message rows, newest first. `queryJson` is a `MessageQuery`:
+   * `{account_ids?: string[], mailbox?: string | null, limit?: number,
+   * since?: string, include_body?: boolean}`. Every field defaults, and
+   * `mailbox: null` means INBOX — so `"{}"` reproduces the pre-existing
+   * INBOX-only read.
+   *
+   * "Newest first" is GLOBAL, not per account: rows from every matched
+   * account are merged into one date-ordered list before `limit` applies, so
+   * `limit: 1` across two accounts returns the newer message rather than
+   * whichever account the backend listed first.
+   *
+   * Returns `{ available, backend, reason?, messages: MessageSummary[] }`;
+   * each row carries a stable opaque `id` accepted by `mailMessageBody`, and
+   * a `mailbox` holding the mailbox as the backend RESOLVED it (a query for
+   * `"travel"` comes back stamped `"Travel/2026"`), so rows match
+   * `mailMailboxes` output. An unresolvable mailbox or an unmatched
+   * `account_ids` returns `available: false` with a reason, never an empty
+   * list.
+   */
+  mailMessages(queryJson: string): string;
+
+  /**
+   * Fetch one message body by the `id` from a `mailMessages` row. Returns
+   * `{ available, backend, reason?, id, content_type, body, truncated }`;
+   * bodies are cut at 100,000 characters with `truncated: true`.
+   */
+  mailMessageBody(messageId: string): string;
+
   /**
    * Send mail. `sendRequestJson` is `{to, subject, body, ...}` per the
    * provider contract. Returns JSON `{ok, message_id?}`.
@@ -1528,10 +1760,25 @@ export class CarRuntime {
 /**
  * Execute a proposal through a CarRuntime with a JS tool callback.
  * The callback receives
- * `{"tool":"name","params":{...},"action_id":"<id>"}` as a JSON
- * string and must return a JSON string. `action_id` is the
+ * `{"tool":"name","params":{...},"action_id":"<id>","request_id":"<id>","timeout_ms":<ms|null>,"session_id":"<id>|null","attempt":<n>}`
+ *
+ * `attempt` is the engine's retry counter, 1-based — which retry you are
+ * serving. (Correlate a specific in-flight call by `request_id` instead.) It
+ * was hardcoded to 1 on the wire and dropped here before car#928.
+ *
+ * `session_id` is the daemon-stamped execution session (car#904) — the
+ * attribution key for which mission a callback belongs to. Null when the
+ * caller has no session. Prefer it over reconstructing attribution from
+ * `action_id`, which is client-authored and not unique across concurrent or
+ * retried attempts.
+ * as a JSON string and must return a JSON string. `action_id` is the
  * originating `Action.id` from the proposal — useful for routing
  * when the same callback closes over multiple in-flight calls.
+ * `request_id` is the daemon's callback-routing id, which a
+ * `tools.cancel` notification repeats so the host can abort the right
+ * in-flight call. `timeout_ms` is the action's declared budget in
+ * milliseconds when the action declared one (`null` otherwise); the
+ * host's tool runner may use it to bound its own work.
  *
  * `sessionId`, when provided, scopes per-action policy validation to
  * the named session opened via `CarRuntime.openSession()`. Global
@@ -1749,6 +1996,13 @@ export function registerVoiceEventHandler(
  * Promise is logged, not surfaced to the host. Process-wide setter,
  * symmetric to `registerVoiceEventHandler`; pair with
  * `unregisterChatHandler` to clear.
+ *
+ * The handler may call any runtime method and should run the turn inline.
+ * NAPI dispatches through a non-blocking `ThreadsafeFunction` and `chatEvent`
+ * is async, so this side never had the reentrancy hazard that made the same
+ * surface unusable from Python before Parslee-ai/car#905 — noted here because
+ * the two bindings' handlers now carry the same contract for the same reason,
+ * arrived at differently.
  */
 export function registerChatHandler(
   handlerFn: (paramsJson: string) => void,
@@ -1767,11 +2021,27 @@ export function unregisterChatHandler(): void;
  * this handler.
  *
  * `handlerFn(callJson)` receives
- * `{"tool":"name","params":{...},"action_id":"<id>"}` as a JSON
- * string and MUST return a Promise resolving to the tool's
+ * `{"tool":"name","params":{...},"action_id":"<id>","request_id":"<id>","timeout_ms":<ms|null>,"session_id":"<id>|null","attempt":<n>}`
+ *
+ * `attempt` is the engine's retry counter, 1-based — which retry you are
+ * serving. (Correlate a specific in-flight call by `request_id` instead.) It
+ * was hardcoded to 1 on the wire and dropped here before car#928.
+ *
+ * `session_id` is the daemon-stamped execution session (car#904) — the
+ * attribution key for which mission a callback belongs to. Null when the
+ * caller has no session. Prefer it over reconstructing attribution from
+ * `action_id`, which is client-authored and not unique across concurrent or
+ * retried attempts.
+ * as a JSON string and MUST return a Promise resolving to the tool's
  * JSON-encoded result. Throwing rejects the daemon-side action
  * with a -32000 JSON-RPC error.
  *
+ * `request_id` is the daemon's callback-routing id, repeated by the
+ * `tools.cancel` notification so the host can abort the right
+ * in-flight call. `timeout_ms` is the action's declared budget in
+ * milliseconds when the action declared one (`null` otherwise); the
+ * host's tool runner may use it to bound its own work.
+ *
  * `action_id` carries the originating `Action.id` from the
  * proposal so process-wide handlers can route concurrent
  * callbacks back to the right per-call closure. Empty string when
@@ -2878,6 +3148,16 @@ export function simulateWithPredictions(
  * `state_consistency` (changes, snapshots, rollbacks), `safety`
  * (permission escalations/denials/approvals), and `replayability` — to
  * complement task-success accuracy when comparing harness variants.
+ *
+ * The optional `task_pass_rate` field — and its two companions,
+ * `task_pass_denominator` (how many tasks that rate is over) and
+ * `tasks_unrunnable` (how many the runner could not measure) — are **always
+ * absent** from this result: end-task success is not in the event stream (the
+ * log records what ran, not whether the task was satisfied), and inventing any
+ * of the three here would hand the regression gate a fabricated number. Only a
+ * runner holding the task suite and its grading criteria can supply them —
+ * `car-bench-harness --metrics-out` does. Absent means *not measured*, never
+ * zero.
  */
 export function harnessMetrics(eventsJsonl: string): string;
 
@@ -2953,9 +3233,30 @@ export function evolutionDiagnose(
  * `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.
+ * "reject" | "incomparable", 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.
+ *
+ * Reliability is guarded twice, because the two available measures are
+ * different quantities. `task_pass_rate` is end-task success and is checked
+ * first, but only when BOTH documents carry it (absent on either side = not
+ * measured, so the guard does not fire rather than defaulting to 0.0 or 1.0).
+ * `trajectory_efficiency.success_rate` is tool-attempt success and is always
+ * checked. A candidate that cuts tokens by abandoning hard tasks earlier holds
+ * a perfect attempt-level rate while solving fewer tasks — only the first guard
+ * sees that.
+ *
+ * Before either guard, the two pass rates must be over the SAME task set.
+ * `HarnessMetrics` carries two optional companions to `task_pass_rate`:
+ * `task_pass_denominator` (how many tasks the rate is over) and
+ * `tasks_unrunnable` (how many the runner could not measure). When both
+ * documents carry a denominator and they differ, the result is
+ * `incomparable` — no verdict, nothing applied. That is not pedantry: a
+ * harness that loses a capability also loses the ability to *measure* the
+ * tasks needing it, so those tasks leave the denominator and the surviving
+ * rate goes up. Both fields are optional and absent from documents written
+ * before they existed, in which case the check is skipped rather than
+ * failing.
  */
 export function evolutionEvaluate(
   mutationJson: string,

package/package.json

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