car-runtime 0.48.0 → 0.49.0

package/index.d.ts

@@ -474,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>;
 
@@ -1558,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?}`.

package/package.json

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