car-runtime 0.46.0 → 0.47.0

package/index.d.ts

@@ -59,6 +59,14 @@ export interface CoderStartOptions {
    * hypothesis, the other buys a retry.
    */
   transientRetries?: number | undefined | null;
+  /**
+   * A `coder.discuss` conversation this run was distilled from. Its agreed
+   * constraints ride into contract derivation, so a rule stated once in the
+   * discussion does not have to be restated in the intent, and the session
+   * records the provenance. An unknown id is a clear error — never a silently
+   * ungrounded run.
+   */
+  discussionId?: string | undefined | null;
 }
 
 export class CarRuntime {
@@ -937,9 +945,93 @@ export class CarRuntime {
    */
   coderApproveMerge(sessionId: string, approve: boolean): Promise<string>;
 
-  /** Cancel a session: stop the loop, abandon, remove the worktree. */
+  /**
+   * Cancel a session: stop the loop, abandon, remove the worktree. Returns
+   * `{state, already_terminal, message}`.
+   *
+   * An already-finished session **succeeds** rather than rejecting: `state`
+   * keeps its pre-existing name and type, `already_terminal` is `true`, and
+   * `message` names what already happened. Callers that cancel unconditionally
+   * on shutdown depend on that — rejecting would turn a quiet exit into a
+   * protocol error whenever the session raced to terminal first.
+   */
   coderCancel(sessionId: string): Promise<string>;
 
+  /**
+   * The current session list AND registration for `coder.session_changed` on
+   * this connection, atomically (registered under the same lock the list is
+   * snapshotted under, so nothing slips through the gap). Notifications are
+   * WebSocket-only, same contract as `coder.subscribe`.
+   *
+   * Each row carries the full summary: the pre-existing
+   * `{session_id, state, intent, repo, engine, iterations, updated_at, live,
+   * 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).
+   *
+   * Pass `renew: true` for the lease-renewal form: it re-registers and answers
+   * `{ was_registered }` — `false` means this connection had been shed and
+   * should take a full snapshot — and builds NO summaries, so it is cheap
+   * enough to call on a timer. The default form is unchanged.
+   */
+  coderWatch(renew?: boolean | undefined | null): Promise<string>;
+
+  /** Stop receiving `coder.session_changed` on this connection. */
+  coderUnwatch(): Promise<string>;
+
+  /**
+   * Redraft a PROPOSED outcome contract from a plain-English request (e.g.
+   * "also verify the Windows path"). Legal only in `contract_proposed`;
+   * nothing executes and the session stays at the gate either way. Unlimited
+   * rounds.
+   *
+   * Returns `{state, revised, contract, baseline, baseline_gates_nothing,
+   * message}`. **Check `revised` before trusting `contract`**: on a redraft
+   * that does not validate, the previous contract comes back byte-identical
+   * with `revised: false` and a `message` explaining why, and the daemon emits
+   * a `contract_revision_rejected` event.
+   */
+  coderReviseContract(sessionId: string, request: string): Promise<string>;
+
+  /**
+   * Open a repo-grounded, strictly **read-only** discussion — a thinking
+   * surface for working out what a change should be, before a run exists.
+   * Bound at `PermissionTier::ReadOnly` with every write/shell escalation
+   * auto-denied, so it can never touch the repo. Returns
+   * `{discussion_id, repo, repo_summary}`; a non-git path is a clear error.
+   */
+  coderDiscussStart(repo: string): Promise<string>;
+
+  /**
+   * Send one operator message. Returns `{ok, seq}` where `seq` is the first
+   * event this turn emits; the reply streams as `coder.discuss.event`
+   * (WebSocket-only, same contract as `coder.event`).
+   */
+  coderDiscussSend(discussionId: string, text: string): Promise<string>;
+
+  /**
+   * Distill the discussion into `{discussion_id, proposed_intent,
+   * constraints}`. **Starts nothing** — no worktree, no branch, no session.
+   * The caller shows `proposed_intent` (never the transcript) for the operator
+   * to edit, then passes it to `coderStart` with `discussion_id` so the agreed
+   * constraints reach contract derivation. Callable repeatedly.
+   */
+  coderDiscussPromote(discussionId: string): Promise<string>;
+
+  /** Free an in-memory discussion. Discussions do not survive a daemon restart. */
+  coderDiscussClose(discussionId: string): Promise<string>;
+
+  /**
+   * Open discussions: `{discussions: [{discussion_id, repo, created_at,
+   * turns}]}`. Also the capability probe — a daemon predating this surface
+   * answers JSON-RPC `-32601`.
+   */
+  coderDiscussList(): Promise<string>;
+
   /**
    * Managed projects + in-daemon declarative agents (the non-developer path).
    *
@@ -1942,6 +2034,30 @@ export function resumeWorkflow(pausedJson: string, inputJson: string): Promise<s
  * resumable runs after a restart. */
 export function listPausedWorkflows(runsDir: string): string;
 
+/** Bind (or clear) the memory namespace for subsequent daemon connections
+ * (car-releases#81). Returns the namespace now in effect, or `null` for the
+ * daemon's shared graph.
+ *
+ * Prefer this over setting `CAR_MEMORY_NAMESPACE` when the namespace is
+ * per-project. An env var cannot carry a per-project value: the host learns
+ * which project it is *after* the process starts, and on **bun** a JS-side
+ * `process.env` write never reaches the C `environ` this library reads — the
+ * write is silently ignored and the session falls back to the shared graph.
+ *
+ * Blank or `null` clears the override, falling back to `CAR_MEMORY_NAMESPACE`
+ * and then the shared graph.
+ *
+ * **Takes effect on the next connection.** The namespace is negotiated during
+ * `session.auth`, so an already-established connection keeps the graph it
+ * bound. Call this before your first CAR call, or disconnect afterwards to
+ * force a rebind — otherwise you keep writing to the previous project's
+ * graph. */
+export function setMemoryNamespace(namespace?: string | null): string | null;
+
+/** The memory namespace currently in effect — the explicit override if set,
+ * otherwise `CAR_MEMORY_NAMESPACE`, otherwise `null` (shared graph). */
+export function getMemoryNamespace(): string | null;
+
 /** NLP (F4): identify the dominant language of `text`. Returns
  * `{language, backend}` JSON (Apple NaturalLanguage on macOS, pure-Rust
  * fallback elsewhere). */
@@ -2145,10 +2261,25 @@ export function sendA2AMessage(rt: CarRuntime, paramsJson: string): Promise<stri
  * `{ 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,
+ * cannot_verify, findings, tier }], 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.
+ *
+ * Each issue is `{ action_id, severity, message, tier }`. `tier` is the
+ * **evidence tier** — `"decision_procedure" | "heuristic" | "sampled"` —
+ * naming which kind of check produced the finding, so you don't have to
+ * pattern-match the message to tell them apart. All of `verify`'s
+ * findings are `decision_procedure` (set membership, the STRIPS-style
+ * forward walk, write-conflict detection) except the
+ * repeated-identical-call rule, which is `heuristic`: the count is
+ * exact, "runaway loop" is a proxy, and a legitimate 3× poll trips it.
+ * The tier is orthogonal to `severity` (how bad, not how derived), and
+ * `decision_procedure` is not a proof or a soundness claim — it means
+ * the check decides the property it reports over the inputs it was
+ * given, which for the state-dependent checks is a forward model built
+ * only from *declared* effects. Each `CheckRecord` carries the same
+ * `tier` as the findings it contributed.
  */
 export function verify(
   proposalJson: string,
@@ -2652,8 +2783,13 @@ export function cascadeDecide(
  *
  * `statsJson` is aggregate counters (parsed by serde — keys are snake_case):
  * `{ total_facts, structured_facts, total_edges, total_retrievals,
- * helpful_retrievals, conflicts_resolved, outstanding_outdated, facts_created,
- * facts_superseded }` (omitted fields default to 0). Returns the report JSON:
+ * total_proactive_injections, helpful_retrievals, conflicts_resolved,
+ * outstanding_outdated, facts_created, facts_superseded }` (omitted fields
+ * default to 0). `total_retrievals` counts DELIBERATE recalls only;
+ * harness-initiated proactive injections are reported separately as
+ * `total_proactive_injections` and never feed ranking (car#816).
+ * `helpful_retrievals` is always 0 today — `record_fact_helpful` has no
+ * production caller — so read a 0 there as "not wired", not "nothing helped". Returns the report JSON:
  * `{ representation_fidelity, retrieval_precision, update_correctness,
  * long_horizon_stability, overall }` (each 0..1), `bottleneck` (one of
  * `"representation" | "retrieval" | "update_correctness" |
@@ -2849,11 +2985,76 @@ export function evolutionApply(
 // (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"`.
+//
+// Two axes, not one. The tier answers "who may authorize this?" and says
+// nothing about whether the effect can be undone — a `git push`, a production
+// INSERT, and a charged card are all `full_access` with three different
+// rollback contracts. Every row below therefore carries a `reversibility`
+// alongside its `required_tier`.
+//
+// The matching Action IR fields (any `proposalJson` this package accepts, and
+// the full spec in docs/agent-ir-spec.md):
+//
+//   "reversibility": "reversible" | "compensable" | "irreversible"
+//       Optional. The rollback contract for this action's effects.
+//       `reversible` is undone by restoring the scope it ran in;
+//       `compensable` needs a compensating action run against it;
+//       `irreversible` cannot be undone once it reaches the world.
+//       **Defaults to "irreversible"** when omitted — deliberately, because
+//       the default decides what the runtime believes about an unclassified
+//       action and the two directions fail asymmetrically. Guessing
+//       "reversible" wrongly means silently believing a sent email can be
+//       unsent; guessing "irreversible" wrongly means over-asking for an
+//       approval on something recoverable, which is annoying, visible, and
+//       fixed locally by annotating the action.
+//
+//   "compensation": { "type": "tool", "tool": string, "parameters"?: object }
+//                 | { "type": "action_ref", "action_id": string }
+//       Optional. How to undo the action once it has run — the action-level
+//       analogue of car-workflow's saga CompensationHandler. Meaningful only
+//       with `"reversibility": "compensable"`; omitted from the serialized
+//       form when absent, so older consumers see the payload they saw before.
+//       Declaring one is a *claim*: nothing checks that the named tool is a
+//       true inverse, exactly as nothing checks `expected_effects`.
+//
+// Nothing in the runtime enforces on either field yet — they are typed,
+// classified, and audited. Do not read `"reversible"` as a promise that the
+// runtime will undo anything for you: rollback restores the state map and
+// leaves whatever a tool wrote to disk where it is. See
+// docs/proposals/shepherd-substrate-adoption.md.
+
+/**
+ * Classify each action in a proposal on both authorization-adjacent axes.
+ * Returns a JSON array of `{ action_id, tool, required_tier, reversibility,
+ * missing_compensation }`. The keys live inside a JSON string, so they stay
+ * snake_case — napi-rs camelCases function and parameter names, not payload
+ * contents.
+ *
+ * - `required_tier` — **who may authorize this**: `"read_only" |
+ *   "sandbox_edit" | "full_access"`.
+ * - `reversibility` — **can this be undone**: `"reversible" | "compensable" |
+ *   "irreversible"`. Independent of the tier and not derived from it:
+ *   `read_secret` is `full_access` and perfectly reversible (a read leaves
+ *   nothing to undo), while `send_email` and `deploy_service` are both
+ *   `full_access` and differ completely. This is the classifier's answer from
+ *   the tool name and flattened parameters — **not** an echo of the action's
+ *   declared `reversibility` field, which defaults to `"irreversible"` and so
+ *   would tell you only what you sent. It is a keyword heuristic: an
+ *   unrecognized tool comes back `"irreversible"`, deliberately.
+ * - `missing_compensation` — the action **declared** `"compensable"` and
+ *   supplied no `compensation`, the one incoherent combination the IR cannot
+ *   exclude by construction. Keyed off the declared field, so it stays `false`
+ *   for proposals that never opted into the axis.
+ *
+ * Severity ascends `"reversible" < "compensable" < "irreversible"`, so the
+ * rollback contract of a whole batch is the worst row — a plan is only as
+ * recoverable as its least recoverable step. (The daemon's `permission.classify`
+ * returns that roll-up precomputed as `declared_rollback_contract`, over the
+ * *declared* fields; this function returns a bare array with nowhere to hang
+ * it, so compute it from the column you care about.)
+ *
+ * Nothing in the runtime gates on the second axis yet — it is typed,
+ * classified, and audited, not enforced.
  */
 export function permissionClassify(proposalJson: string): string;
 
@@ -2861,10 +3062,17 @@ 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" |
+ * action_id, fingerprint, reversibility, ... }` where `decision` is `"allow" |
  * "needs_approval" | "deny"`. A `needs_approval` decision means autonomy is
  * suspended pending a human decision; resolve it with
  * {@link permissionRecordForFingerprint}.
+ *
+ * `reversibility` is orthogonal to `decision` and rides on **every** row, the
+ * `allow`s included: the gate's verdict says whether the action may run, not
+ * whether it could be taken back afterwards, and a caller that only learns the
+ * rollback contract of the actions it was stopped on is missing exactly the
+ * rows an incident review reads first. Same field, labels, and classifier as
+ * the `PermissionDecision` event the engine writes to its audit log.
  */
 export function permissionEvaluate(
   proposalJson: string,

package/package.json

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