car-runtime 0.47.0 → 0.48.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). */
@@ -472,6 +514,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 +548,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 +675,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 +867,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 +1069,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
@@ -1528,10 +1629,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 +1865,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 +1890,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 +3017,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 +3102,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.48.0",
   "description": "Common Agent Runtime — a deterministic execution layer for AI agents",
   "main": "index.js",
   "types": "index.d.ts",