car-runtime 0.24.0 → 0.25.0

package/index.d.ts

@@ -160,8 +160,14 @@ export class CarRuntime {
   /**
    * Set replan configuration on this runtime.
    * `maxReplans` = 0 disables replanning (default).
+   * `replanOnRejected` (default false): when true, validator/policy/capability
+   * rejections (not just runtime failures) also trigger rollback + replan.
    */
-  setReplanConfig(maxReplans: number, delayMs?: number | null): Promise<void>;
+  setReplanConfig(
+    maxReplans: number,
+    delayMs?: number | null,
+    replanOnRejected?: boolean | null,
+  ): Promise<void>;
 
   // --- State ---
 
@@ -326,9 +332,17 @@ export class CarRuntime {
   /**
    * Generate with full tracking. Returns JSON with `text`, `tool_calls`,
    * `usage`, `model_used`, `latency_ms`, `time_to_first_token_ms`,
-   * `trace_id`. `time_to_first_token_ms` is wall-clock to the first
-   * sampled token (populated by local Candle/MLX paths; `null` for
-   * non-streaming remote calls).
+   * `trace_id`, `stop_reason`. `time_to_first_token_ms` is wall-clock to
+   * the first sampled token (populated by local Candle/MLX paths; `null`
+   * for non-streaming remote calls). `stop_reason` is the raw provider
+   * termination reason (OpenAI `finish_reason`, Anthropic `stop_reason`,
+   * Google `finishReason`); `null` for local backends or providers that
+   * don't report one. A value of `"length"`/`"max_tokens"`/`"MAX_TOKENS"`
+   * means the output was truncated at the token cap. On local Qwen3
+   * hybrid-thinking models it is also set to `"thinking_recovered"` when
+   * reasoning consumed the whole token budget and the runtime retried
+   * with reasoning suppressed to produce a direct answer, or
+   * `"thinking_truncated"` when even that retry was empty (car-releases#60).
    *
    * **Note:** intent is not exposed on the tracked path until the
    * positional argument list is converted to an options object —
@@ -481,7 +495,10 @@ export class CarRuntime {
   /**
    * Unified registry (local + remote). Returns JSON array of
    * `{ id, name, provider, capabilities, param_count, size_mb,
-   *   context_length, available, is_local, public_benchmarks }`.
+   *   context_length, available, is_local, max_output_tokens,
+   *   public_benchmarks }`. `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?,
    * measured_at? }]` with score on a 0.0–1.0 scale; ships empty in
    * the built-in catalog and is populated via curated registry data.
@@ -1531,6 +1548,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,
@@ -1549,6 +1575,151 @@ export function optimize(proposalJson: string): string;
 
 export function equivalent(proposal1Json: string, proposal2Json: string): boolean;
 
+/**
+ * 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 ---
 
 /**

package/package.json

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