@sema-agent/core 5.19.0 → 5.21.0

package/dist/core/retention.d.ts

@@ -1,34 +1,85 @@
+/** A store's retention capability declaration. Absent ⇒ read fail-closed as `"none"`. */
 export type RetentionDeclaration = "managed" | "none";
+/** The declaration face a storage implementation carries (structural — every store interface's
+ *  optional `retention` field conforms). `"managed"` is a PROMISE to honor
+ *  {@link ManagedRetentionCapability}; `"none"` is the honest default for stores that cannot delete
+ *  on schedule (all bundled in-memory/TTL stores declare it). */
 export interface RetentionDeclaring {
     readonly retention?: RetentionDeclaration;
 }
+/**
+ * The deployment's managed-retention policy ({@link import("./types.js").RunnerDeps.retentionPolicy}).
+ * Core consumes it ONLY for the startup capability validation (and exposes it to the deployment's
+ * scheduler); the engine never deletes data on the task path. Administrative locking rides the
+ * locked-config plane (key `"retentionPolicy"`), not a field here — one lock mechanism, not two.
+ */
 export interface RetentionPolicy {
+    /** Retention horizon in days. Fail-loud validated: non-finite or negative refuses the deployment
+     *  (`config.retention_policy`); `0` is absurd-but-evaluable (delete-eligible immediately) and legal. */
     maxAgeDays: number;
 }
+/**
+ * What a `retention: "managed"` store PROMISES (contract TYPE — core ships no implementation; the
+ * server half consumes this. Reference implementation of the cascade: the server's session-purge
+ * order contract). Every method is expected to be:
+ *  - **tenant-domain scoped**: work is enumerated and executed per retention domain (tenant/scope),
+ *    never as one global sweep;
+ *  - **idempotent**: a retried invocation after a crash re-converges (already-deleted rows are
+ *    counted, not errors);
+ *  - **tombstoned**: deletions leave tombstones so replicas/backups converge instead of resurrecting;
+ *  - **audited**: every destructive call returns a receipt the scheduler persists (append-only).
+ */
 export interface ManagedRetentionCapability {
+    /** Enumerate the retention domains (tenant/scope keys) this store holds data for. */
     listRetentionDomains(): Promise<readonly string[]>;
+    /** CAS-fenced checkpoint expiry for one domain: `pending → expired` strictly by deadline, exactly
+     *  one winner per row across replicas, AND release the associated session pins (the reap/unpin
+     *  split is the documented gap this contract closes). */
     expireCheckpoints(input: {
         domain: string;
         cutoffMs: number;
     }): Promise<RetentionReceipt>;
+    /** Lineage-aware transcript/session deletion: a session tree is deleted only when no live
+     *  reference (fork child, background child, workflow run, pending checkpoint) still points into
+     *  it — references are re-checked inside the deletion transaction, never assumed from a prior
+     *  scan. */
     deleteExpiredSessions(input: {
         domain: string;
         cutoffMs: number;
     }): Promise<RetentionReceipt>;
+    /** Delete offloaded tool results whose owning sessions are gone (or past the horizon), skipping
+     *  refs still reachable from live transcripts. */
     deleteOrphanToolResults(input: {
         domain: string;
         cutoffMs: number;
     }): Promise<RetentionReceipt>;
 }
+/** Audit receipt of one destructive retention call (append-only material for the scheduler). */
 export interface RetentionReceipt {
     domain: string;
+    /** Rows destroyed by THIS call (idempotent retries count already-gone rows as 0, not errors). */
     deleted: number;
+    /** Rows intentionally skipped (live lineage references, legal-hold marks — hold semantics are the
+     *  scheduler's: when a hold mark exists for a domain, the scheduler skips the domain entirely and
+     *  records the skip; this field carries the per-row remainder). */
     skipped: number;
+    /** Tombstones written for the deleted rows. */
     tombstones: number;
 }
+/**
+ * Startup validation (and per-prepare backstop): with the retention policy LOCKED and configured,
+ * every wired store must declare `retention: "managed"` — a locked policy over a store that cannot
+ * delete is refused (`config.retention_capability`), never silently accepted. Also fail-loud
+ * validates the policy value itself (`config.retention_policy`). Exported for deployments to call at
+ * their own startup; the prepare preflight re-runs it on every leg regardless.
+ */
 export declare function assertRetentionCapability(input: {
     policy: RetentionPolicy | undefined;
+    /** Whether locked-config locks the `retentionPolicy` key (locked-config.ts `LockedKey`). */
     locked: boolean;
+    /** The wired stores to check, each with its deployment-facing name for the refusal message.
+     *  Accepts any store object (interfaces that predate the declaration conform structurally with
+     *  no declaration ⇒ read fail-closed as `"none"`); the declaration read is the one narrow. */
     stores: ReadonlyArray<{
         name: string;
         store: object | undefined;

package/dist/core/roles.d.ts

@@ -2,22 +2,76 @@ import type { ThinkingLevel } from "../internal/harness-types.js";
 import type { Model } from "../internal/llm.js";
 import type { ModelRef, ModelRole, ModelRoles } from "./types.js";
 export type { ModelRole, RoleSpec, ModelRoles } from "./types.js";
+/** Resolve a string ModelRef against the catalog (a Model object passes through). */
 export declare function resolveModel(ref: ModelRef, models?: Record<string, Model>): Model;
+/** 档位降档链(强→弱)。解析某档无绑定时沿链向后找第一个有绑定的档(fail-open 可用性优先;绑定缺口
+ *  在部署 catalog 审计面可见)。`ultra` 预留:排在 `max` 前,今天不绑,未来加档零码改。 */
 export declare const DEFAULT_TIER_ORDER: readonly string[];
+/** CC 档位词 → sema 档位(内置固定,兼容层):fable/mythos→max · opus→pro · sonnet→flash · haiku→lite。 */
 export declare const CC_MODEL_TIER_ALIASES: Readonly<Record<string, string>>;
+/**
+ * Expand a deployment's tier bindings into the model catalog: every tier name (and every CC alias whose
+ * tier resolves) becomes a catalog key pointing at the bound Model, so the ENTIRE resolve surface
+ * (`resolveModel` / roles / `@model` mentions / Agent tool `model` / workflow `agent() opts.model`)
+ * accepts tier vocabulary with ZERO per-callsite changes. Called ONCE at Runner construction.
+ *
+ * Rules:
+ * - a tier with no binding falls back DOWN {@link DEFAULT_TIER_ORDER} to the first bound tier
+ *   (e.g. `max` unbound + `pro` bound ⇒ "max" resolves to the pro model — availability over strictness;
+ *   the gap stays visible in the deployment's catalog audit, not silently absent);
+ * - an existing catalog key of the same name WINS (deployment SHADOW semantics, mirroring agents):
+ *   a deployment that already ships a model literally named "pro" keeps it untouched;
+ * - a binding may itself be a catalog name or a Model object (resolved through `resolveModel`);
+ *   an unknown binding name throws at construction (config error surfaces at boot, not first use).
+ */
+/** [1613] the DISPLAY face of a string model ref: a CC tier ALIAS (haiku/sonnet/…) resolves to its
+ *  sema tier name (lite/flash/…) for labels — the alias verbatim reads as a strong claim about a
+ *  specific vendor's model while the actual routing may land anywhere ("haiku" showing over a
+ *  DeepSeek run, clay's field report). A non-alias string is the deployment's own model key — its
+ *  honest name — and passes through unchanged. Display only; routing (`expandTiers`) is untouched. */
 export declare function resolveModelDisplayLabel(ref: string): string;
 export declare function expandTiers(models: Record<string, Model> | undefined, tiers: Record<string, ModelRef> | undefined): Record<string, Model> | undefined;
 export interface ModelMention {
+    /** The matched model name — always one of `allowedNames` — or undefined if none was found. */
     model?: string;
+    /** The message with the matched `@model` token removed and whitespace tidied. */
     cleanedText: string;
 }
+/**
+ * Parse a leading/inline `@model` mention out of a user message, restoring the chat "@-model" UX.
+ * Returns the matched model **name** (a catalog ref the caller resolves), never a Model object — and
+ * **only ever a name from `allowedNames`**. This is the security boundary: untrusted end-user text can
+ * pick *which configured model* to use, but can never inject an arbitrary `baseUrl`/`apiKey`/Model
+ * (see design/11). Matches the first allow-listed mention; the rest of the text is returned cleaned.
+ *
+ * Typical use: `const { model, cleanedText } = parseModelMention(userMsg, Object.keys(deps.models));`
+ * then `runTask({ objective: cleanedText, model })` (omit `model` to fall back to the default role).
+ */
 export declare function parseModelMention(text: string, allowedNames: Iterable<string>): ModelMention;
+/**
+ * Role → 档位默认表(clay 拍 2026-07-11:「role 体系用户不感知」)。配了 `RunnerDeps.tiers` 的部署,
+ * 各 role 未显式配置时自动落到语义档位——用户/壳只感知档位,roles 降级为内部路由层:
+ * - `default` → `pro`(主力档兜底;用户/部署 roles.default / TaskSpec.model 恒可覆盖);
+ * - `summarize` → `flash`(压缩本该便宜;flash 未绑沿降档链到 lite);
+ * - `advisor` → 第一档(`ultra` 起,未绑降档到 max/pro——teacher 用最强的);
+ * - `verifier` → `pro`;
+ * - `subagent`/`team`/`synthesize` 无档位默认 = 走 FALLBACK 继承主模型(LLM 可经 model 参数自选档)。
+ * 未配 tiers 的部署:catalog 无 TIERS_ACTIVE 标记 → 表整体 INERT,行为与从前逐字节一致
+ * (即使 catalog 恰有裸模型名 `pro`/`flash` 也不入档位路由——INERT 靠配置成立,不靠键名运气)。
+ */
 export declare const ROLE_TIER_DEFAULTS: Readonly<Partial<Record<ModelRole, string>>>;
 export interface ResolvedRole {
     model: Model;
+    /** The effective thinking level: explicit `spec.thinking` wins, else the role's default. */
     thinking?: ThinkingLevel;
+    /** The requested role's preset system prompt, if it set one (independent of model fallback). */
     systemPrompt?: string;
 }
+/**
+ * Resolve the model (and default thinking) for a task. Explicit `spec.model` wins; otherwise walk the
+ * `modelRole`'s fallback chain over the merged roles (task overrides runner) and use the first role
+ * that supplies a model. Throws a helpful error if nothing resolves.
+ */
 export declare function resolveTaskModel(spec: {
     model?: ModelRef;
     modelRole?: ModelRole;
@@ -27,6 +81,11 @@ export declare function resolveTaskModel(spec: {
     models?: Record<string, Model>;
     roles?: ModelRoles;
 }): ResolvedRole;
+/**
+ * Resolve a role's model **only if that exact role key is configured** (no fallback chain). Used for
+ * the `summarize` compaction model: override only when a summarize-specific model is set, otherwise
+ * let the caller fall back to the main model (unchanged behavior).
+ */
 export declare function roleModelIfSet(role: ModelRole, spec: {
     roles?: ModelRoles;
 }, deps: {

package/dist/core/runner/active-skill-scope.d.ts

@@ -1,6 +1,8 @@
 import type { ExecutionEnv } from "../../internal/harness-types.js";
 import type { SkillManifest, ToolEffect } from "../types.js";
 import type { ToolPolicy } from "../tool-policy.js";
+/** One active skill frame: either a resolved manifest, or a fail-closed marker that the manifest for a
+ *  loaded skill could not be resolved (→ DENY-ALL while this frame is active). */
 export type ActiveSkillFrame = {
     kind: "manifest";
     manifest: SkillManifest;
@@ -9,16 +11,48 @@ export type ActiveSkillFrame = {
     lineageId: string;
     reason: string;
 };
+/**
+ * The per-task LIFO stack of active skill frames (design/77 §3). Owned by `prepare-task`'s closure;
+ * the injected `skill` tool pushes onto it on a successful load, and a deny-narrowing policy reads it
+ * on every tool call. A simple array is the stack — `push` on load, and the policy reads ALL frames
+ * currently on it (the intersection). v1 keeps lifetime heuristic (see module header).
+ */
 export declare class ActiveSkillScope {
     private readonly frames;
+    /** Push a resolved manifest frame (skill loaded successfully WITH a manifest). */
     push(frame: ActiveSkillFrame): void;
+    /** Pop the most-recently-pushed frame (LIFO). Returns it, or undefined when empty. v1 surfaces this
+     *  for the "next-skill-load pops the previous sibling frame" lifetime — see prepare-task wiring. */
     pop(): ActiveSkillFrame | undefined;
+    /** Snapshot of the live frames (a copy — callers must not mutate the stack through it). */
     active(): readonly ActiveSkillFrame[];
     get size(): number;
 }
+/**
+ * Build the Gate-3 deny-narrowing policy over a live {@link ActiveSkillScope} (design/77 §3). For each
+ * tool call, WHILE any skill frame is active:
+ *  - DENY any tool not in the INTERSECTION of every active frame's `allowTools`.
+ *  - For a WRITE tool with an `allowPaths` constraint on ANY active frame, DENY a write whose
+ *    canonicalized target is outside every listed prefix (reuses {@link canonicalizeTarget}, so a
+ *    symlink can't smuggle a write outside the allowed paths).
+ *  - A frame whose manifest could not be resolved (`kind:"unresolved"`) → DENY-ALL (fail-closed: no
+ *    allowlist means nothing is allowed — NOT the bare task policy).
+ * When NO frame is active, the policy returns `allow` for everything (it only ever subtracts), leaving
+ * the task policy unmodified — so a skill WITHOUT a manifest, or a task before any skill load, behaves
+ * exactly as before (backward-compatible).
+ *
+ * This policy must be composed via `combinePolicies(scopePolicy, taskPolicy)` so its `deny`
+ * short-circuits the fold and a task-policy `allow` can never widen it.
+ *
+ * `env`/`rootPath` are the SAME execution env + tracked cwd the hand tools resolve against, so
+ * `allowPaths` matching sees the task's real filesystem (a remote/E2B task resolves in its container).
+ */
 export declare function createActiveSkillScopePolicy(opts: {
     scope: ActiveSkillScope;
     env: ExecutionEnv;
     rootPath?: string;
+    /** Per-tool side-effect class (the SAME `toolEffects` map prepare-task builds). Lets the scope policy
+     *  fail CLOSED on a mutating tool that `allowPaths` can NOT confine (e.g. `bash` — no parseable path):
+     *  while an `allowPaths` constraint is active, such a tool is DENIED, never allowed to write anywhere. */
     toolEffects?: ReadonlyMap<string, ToolEffect>;
 }): ToolPolicy;

package/dist/core/runner/assemble-result.d.ts

@@ -1,23 +1,36 @@
 import type { AssistantMessage } from "../../internal/llm.js";
 import type { NestedUsage, TaskResult, TaskSpec } from "../types.js";
+/** Per-task usage/cost accumulator (filled across the run loop, surfaced as `TaskResult.stats`). */
 export interface Stats {
     turns: number;
     tokens: number;
+    /** design/97 CORE-8 (②): total tool calls executed (one per `tool_start`). Spread into `TaskResult.stats`. */
     toolCalls: number;
+    /** RB-457-a: prompt tokens that MISSED the cache (Anthropic-protocol `input_tokens` shape). */
     promptTokens: number;
     cachedTokens: number;
     cacheWriteTokens: number;
     cacheWriteTokensLong: number;
     outputTokens: number;
     cacheHitRate?: number;
+    /** RB-457-a: cache-INCLUSIVE prompt total (`promptTokens + cachedTokens + cacheWriteTokens*`) — the
+     *  billing/window/hit-rate denominator. Required (not derived) so a new accumulation site that forgets
+     *  it fails the type check instead of silently reporting a total short by its own leg. */
     totalInputTokens: number;
     costMicroUsd: number;
     nested?: NestedUsage;
+    /** Post-task memory-consolidation usage (design/41); set after the result is assembled. Kept out of
+     *  the budget gate (`overBudget` reads `costMicroUsd`/`tokens`, never this). */
     memory?: {
         tokens: number;
         costMicroUsd: number;
         applied: number;
     };
+    /** design/91: human-review burden (design/89 §2.4 C2). Wall-clock approval-gate wait + count, bucketed by
+     *  `gate.kind`, accumulated across resume legs. Set by the run loop from the per-task human-review
+     *  accumulator (synchronous `resolveAsk` timing + durable resume latency). **NOT an LLM cost** — never
+     *  folded into `costMicroUsd`/`costBreakdown`/the budget gate (same budget-excluded treatment as `memory`).
+     *  Flows straight through to `TaskResult.stats.humanReview` via the public-stats spread; absent ⇒ no gate. */
     humanReview?: {
         count: number;
         totalWaitMs: number;
@@ -29,6 +42,9 @@ export interface Stats {
             toolArg?: string;
         }>;
     };
+    /** TB telemetry B2 (service [397]): engine-mechanism engagement counters. Set by the run loop
+     *  only when ≥1 engaged; flows straight through to `TaskResult.stats.mechanisms` via the
+     *  public-stats spread. */
     mechanisms?: {
         finalVerifyInjected?: true;
         finalVerifyInjections?: number;
@@ -44,42 +60,160 @@ export interface Stats {
             segment: string;
         }>;
     };
+    /** design/80 D-E-core (Part B): within-task compaction LLM cost (micro-USD), accumulated by
+     *  `recordCompactionUsage` as a SEPARATE running total because that cost IS folded into `costMicroUsd`
+     *  (so it can't be re-derived from `costMicroUsd` alone). The {@link costBreakdown.compactionMicroUsd}
+     *  source. Run-loop internal — not a public `TaskResult.stats` field. */
     compactionMicroUsd?: number;
+    /**
+     * design/80 D-E-core (Part B): a thin FINANCE TAXONOMY of the LLM-derived costs the engine actually
+     * prices, decomposing the task's spend into report categories (no new persisted structure — derived from
+     * the cost sources that already exist). CORE = LLM-token-derived ONLY; the SERVICE adds the infra axes it
+     * owns (tool-call / sandbox-walltime / egress — it has the k8s cost data) and composes them with this.
+     * Each category is ≥ 0 and the parts reconcile to the independently-summed LLM total
+     * (`llmRoot + nestedSubagent + compaction` — `memory` is a separate, budget-excluded line, see its doc).
+     * Filled in assembleResult for `llmRoot`/`nestedSubagent`/`compaction`; the `memoryConsolidation` line is
+     * permanently 0 since design/157 B19 retired the runner-integrated consolidation pass (field kept — it is
+     * public stats contract; an engine-plane re-mount per design/138 §7 would fill it again).
+     */
     costBreakdown?: {
+        /** Root-agent LLM cost (micro-USD): `costMicroUsd` MINUS the sub-categories already folded into it
+         *  (compaction). NOT minus nested — nested subagent cost is tracked separately and is NEVER folded into
+         *  `costMicroUsd` (it lands only in `stats.nested`), so subtracting it would under-report the root. */
         llmRootMicroUsd: number;
+        /** Delegated sub-agent (nested) LLM cost (micro-USD) = `stats.nested?.costMicroUsd ?? 0`. */
         nestedSubagentMicroUsd: number;
+        /** Post-task memory-consolidation LLM cost (micro-USD) = `stats.memory?.costMicroUsd ?? 0`. Filled in
+         *  runtask AFTER the (async) consolidation pass sets `stats.memory`; 0 at assembleResult time. */
         memoryConsolidationMicroUsd: number;
+        /** Within-task compaction LLM cost (micro-USD) = the running `compactionMicroUsd` accumulator (the
+         *  category Framing-4 missed). This IS part of `costMicroUsd`, so it is subtracted from `llmRoot`. */
         compactionMicroUsd: number;
     };
 }
+/** design/164 — the two cumulative budget ceilings a task can trip. Tokens outrank cost when both are
+ *  over at the same boundary. */
 export type BudgetAxis = "tokens" | "cost";
+/**
+ * The terminal-state flags the run loop hands {@link assembleResult} — the typed contract between the
+ * loop and result assembly (council design/34 ⑤: exported so it's grep-able and tests can construct it).
+ */
 export interface ResultFlags {
     threw: unknown;
+    /** design/99 MF-25: the EFFECTIVE (resolved) model id that served the task — echoed on `TaskResult.model`. */
     model?: string;
+    /** RB-368 ([2076]): some spend was accounted while the serving model had NO configured price table
+     *  (no `RunnerDeps.pricing` entry, no `Model.cost`). The numeric total is then a fabricated
+     *  undercount — `stats.costMicroUsd`/`costBreakdown` are OMITTED from the public result instead of
+     *  reporting a 0 indistinguishable from "declared free". The internal accumulator (budget gate's
+     *  coordinate) is untouched. */
     unpricedSpend?: boolean;
+    /** RB-430-a (design/101 §E19): prepare-time rewind disclosures to echo on `TaskResult.rewindNotes`.
+     *  Pure pass-through — assembly neither adds nor filters (a rewind that FAILED never reaches here; it
+     *  throws at prepare and lands in the `threw` slot as a terminal errorCode). */
     rewindNotes?: TaskResult["rewindNotes"];
+    /** design/174 final-round: call ids of answered-but-never-collected questions, echoed on
+     *  `TaskResult.strandedHumanAnswers`. Pure pass-through; empty/absent ⇒ the field is omitted. The
+     *  optional `onError` alert is NOT the disclosure — this mandatory result face is. */
     strandedHumanAnswers?: TaskResult["strandedHumanAnswers"];
+    /** RB-439-a: the run's remote-workspace lifecycle failures, echoed on `TaskResult.remoteEnvFailures`.
+     *  Pure pass-through (assembly neither adds nor filters) and INDEPENDENT of the status/errorCode chain:
+     *  a refused `suspendVM` still ends the task exactly the way it did before — this only stops the eleven
+     *  distinct codes from arriving as one anonymous `limits.max_turns_exceeded`. Empty/absent ⇒ the field is omitted. */
     remoteEnvFailures?: TaskResult["remoteEnvFailures"];
+    /** ruled 2026-08-04 — the usage-governance wait hint carried by the platform terminal the run adopted
+     *  (`undefined` for every other cause: an expiring environment has no return time to give, and a store
+     *  failure is not a window). Passed as data rather than read back off `threw` so the seat has a typed
+     *  producer. The assembler still gates it on the SETTLED errorCode, so a hint that arrived alongside a
+     *  higher-ranked terminal is dropped instead of being filed under a code that does not name it —
+     *  see `TaskResult.retryAfterMs` for the in-presence condition this preserves. */
     retryAfterMs?: number;
     abortedForTimeout: boolean;
     abortedForTurns: boolean;
+    /** audit A-1: the abort signal fired DURING the run (user interrupt / timeout / max-turns / budget),
+     *  captured before the run loop's unconditional release-abort. Since the loop now exits CLEANLY on an
+     *  abort (no synthetic stopReason:"aborted" assistant is appended), `final` is the last REAL assistant
+     *  message — this flag is what keeps an interrupted run from being mistaken for a completed one. */
     abortedLive?: boolean;
     budgetHit?: "exceeded" | "precall";
+    /** design/164 — which budget ceiling the hit belongs to. Set together with {@link budgetHit} at every
+     *  site that records one; it picks the terminal code (`limits.max_tokens_exceeded` vs
+     *  `limits.max_cost_exceeded`), so a hit without an axis would be an unattributable terminal. */
     budgetAxis?: BudgetAxis;
     blockedReason?: string;
     conflict?: boolean;
     outputInvalid?: boolean;
+    /** design/72 §2.2 (B): a re-suspend was refused because the task already suspended `maxSuspends` times
+     *  (a resume/restart loop). It aborted the run (no `threw`) but must read as `failed`/`suspend.loop`,
+     *  NOT `suspended` — slotted ABOVE `suspendRef` and the aborted branches (this suspend never minted a
+     *  checkpoint, so `suspendRef` is unset anyway; the ordering makes the intent explicit). */
     suspendLoop?: boolean;
+    /** design/45: the task deliberately suspended at a durable tool gate (capture + abort fired). When set,
+     *  the result is `status:"suspended"` carrying this token/gate — a clean pause, NOT a failure, so it is
+     *  slotted ABOVE the `!final`/aborted branches (slot 8.5: it beats them but yields to a real
+     *  budget/threw failure that happened to coincide). The abort it used sets `final.stopReason="aborted"`
+     *  but does not set `threw`, so it never reaches the `flags.threw` branch. */
     suspendRef?: {
         token: import("../checkpoint-store.js").CheckpointToken;
         gate: import("../checkpoint-store.js").CheckpointGate;
+        /** RB-439-b: how the paused workspace comes back (`"park_only"` = a non-suspendable target that was
+         *  never actually paused). Echoed on `TaskResult.workspaceRestoreMode`; absent for a process-local
+         *  suspend, which captured no remote workspace. */
         restoreMode?: "snapshot" | "park_only";
     };
+    /** design/76 §2.5 (dry-run / shadow) + design/80 D-B (plan-gate): the task deliberately paused at a
+     *  REVIEW-PAUSE gate — `{kind:"needs_review"}` (a profile's dry-run interception produced a predicted
+     *  state-diff a human/judge must REVIEW) OR `{kind:"plan_review"}` (a profile's plan-gate produced a
+     *  proposed PLAN a human must approve/edit/reject). When set, the result is `status:"needs_review"` +
+     *  errorCode `"review.pending"`, carrying this token/gate (keyed off ref-PRESENCE, not `gate.kind`, so it
+     *  serves both review kinds uniformly). It is the DUAL of `suspendRef` but for DIFFERENT semantics (a human
+     *  REVIEW, not a pre-action tool-call APPROVAL), so it has its OWN flag and its OWN assemble slot (8.6,
+     *  between `suspendRef` 8.5 and the aborted branches 9) — **never both set at once** (the commit-side
+     *  discriminant in prepare-task branches on `gate.kind` and sets exactly one). Disjoint from `suspendRef`
+     *  so this branch is reachable: keying status off `suspendRef` alone (reusing it) would report `"suspended"`
+     *  and make this dead code (v4 MAJOR-A). Like `suspendRef`, it used an abort to stop the loop (no `threw`),
+     *  so it never hits the failure branches above. */
     reviewRef?: {
         token: import("../checkpoint-store.js").CheckpointToken;
         gate: import("../checkpoint-store.js").CheckpointGate;
+        /** RB-439-b: the review pause pauses the same workspace the approval pause does — same discriminant. */
         restoreMode?: "snapshot" | "park_only";
     };
 }
+/**
+ * Extract a machine-readable code from a thrown error (e.g. `SessionError.code`, a Node error code).
+ * Walks the `cause` chain because the harness wraps lower-level errors (e.g. a `SessionError("conflict")`
+ * append failure surfaces as an `AgentHarnessError("unknown")` whose cause is the real one) — so we
+ * prefer the first specific code over a generic `"unknown"` wrapper.
+ */
 export declare function errorCodeOf(err: unknown): string | undefined;
+/**
+ * Build the final {@link TaskResult} from the run's terminal state. **The errorCode priority chain is a
+ * public contract** (callers `switch` on these strings) — first match wins, in this exact order
+ * (council design/34 red-line #3, do not reorder):
+ *   1. `outputInvalid`  → `"output.invalid"`
+ *   2. degenerate       → `"output.degenerate"` + `salvagedOutput` (design/39; wins over budget/timeout)
+ *   3. `budgetHit`      → `"limits.max_tokens_exceeded"` | `"limits.max_cost_exceeded"` (by `budgetAxis`;
+ *       the pre-call estimate rejection and the after-spend crossing share the code — the distinction
+ *       lives in `errorMessage`, not in a second code)
+ *   3.5 `suspendLoop`  → `"suspend.loop"` (design/72 §2.2 B — the re-suspend cap; deterministic root
+ *       cause, above `threw` because it owns the abort)
+ *   4. `threw` + walltime → `"limits.max_walltime_exceeded"`
+ *   5. `threw` + turns   → `"limits.max_turns_exceeded"`
+ *   6. `threw` + conflict→ `"conflict"`
+ *   7. `threw` (other)   → `errorCodeOf(threw)`
+ *   8. `blockedReason`   → status `"blocked"` (no errorCode)
+ *   8.5 `suspendRef`     → status `"suspended"` + checkpointToken/gate (design/45 B4 — a deliberate
+ *       durable pause beats the abort it used, but yields to a real budget/threw failure above)
+ *   8.6 `reviewRef`     → status `"needs_review"` + `"review.pending"` + checkpointToken/gate (design/76 §2.5
+ *       — a dry-run post-prediction REVIEW pause; the DUAL of 8.5, between it and the aborts, same red-line:
+ *       a `suspendRef` at 8.5 still wins if both were somehow set, proving slot order — but the commit-side
+ *       discriminant guarantees only one is ever set)
+ *   9. `abortedLive` | stopReason aborted → `"limits.max_walltime_exceeded"` | `"limits.max_turns_exceeded"` | undefined
+ *       (audit A-1: hoisted ABOVE no-final — the loop exits cleanly on abort, so `final` may be a
+ *       normal message or absent; a plain user interrupt carries NO errorCode — switch on `status`)
+ *  10. no `final`        → status `"failed"`
+ *  11. stopReason error  → brain `[code]` prefix (or `"conflict"` from the storage-layer flag)
+ *  12. else              → `"completed"`
+ */
 export declare function assembleResult(spec: TaskSpec, sessionId: string, final: AssistantMessage | undefined, stats: Stats, flags: ResultFlags): TaskResult;

package/dist/core/runner/compaction-call-options.d.ts

@@ -4,16 +4,112 @@ import type { StaleToolResultOffloadOptions, TaskSpec } from "../types.js";
 import type { Context } from "../../internal/llm.js";
 import { type ToolResultStore } from "../tool-result-store.js";
 import type { Prepared } from "./prepare-task.js";
+/**
+ * REF-A2 (car R11) — the maybeCompact call arguments that MUST be assembled identically on all three
+ * of runtask's compaction lanes (turn boundary / prompt-too-long recovery / end-of-task).
+ *
+ * Those lanes carried three hand-copied assemblies whose own comments said "must not silently
+ * diverge" — a discipline enforced only by human diffing. This module makes the identity structural.
+ * It is deliberately NARROW: only the parts that are the same invariant live here. Everything else
+ * the three call sites pass (model source, brain, minTokens, force, trigger, window safety, and the
+ * end-of-task lane's deliberate ABSENCE of `signal`) is a legitimate per-lane difference and stays at
+ * the call site, where its reason is written down.
+ *
+ * Every export is a free function: the turn-boundary lane assembles its call inside `makeTurnBoundary`
+ * (a module-level function with no `this`), so a method would not be reachable from all three sites.
+ * Nothing here reads or writes runner state — pure assembly over `spec` + `Prepared`.
+ */
+/**
+ * Opt-in working-file attachments (LONGRUN-2 / CC 198 post-compact restore parity).
+ *
+ * Blackboard 2026-07-03 (CC parity): post-compact file re-read is DEFAULT ON (CC hard-codes it;
+ * LONGRUN-2 measured ≈2.3 extra read round-trips per compaction without it). `false` opts out; an
+ * object customizes caps. Selection set = most recently READ (CC readFileState semantics) with a
+ * modified-files fallback inside maybeCompact. Returns `undefined` when attachments are off or the
+ * task has no hands (no `readTaskFile` ⇒ nothing can be re-read).
+ */
 export declare function buildWorkingFileAttachments(spec: TaskSpec, prepared: Prepared): MaybeCompactOptions["workingFileAttachments"];
+/**
+ * design/169-A — the CC-form fork seam, assembled identically on all three lanes (REF-A2): the
+ * summary request forks the main lane's latest real request (recorded by prepare-task's provider
+ * shim) instead of re-serializing the conversation into an independent full-price request.
+ * `maybeCompact` consults the accessor per pass and only when the summary model IS the main model;
+ * before the run's first main-loop call the accessor returns `undefined` and the independent form
+ * runs unchanged.
+ *
+ * Lossy-projection guard (SEMA-ONLY — CC has no request-layer reducers): the recorded request is a
+ * PROJECTION of the session, and when ANY default reducer made it lossy (guard-trim message drops,
+ * clearStale content blanking, the aggregate tool-result/media caps, the orphan sweep), that
+ * projection is missing history the summary would PERMANENTLY replace — measured live: a fork of a
+ * trimmed request loses the fact-survival suite's fact; a fork of a clearStale'd request summarizes
+ * `[tool result cleared …]` markers (独立复审 HIGH,已修). That guard lives at the RECORDING side
+ * (prepare-task arms `requestLossyRef` per request build; a lossy request records `undefined`), so
+ * every lane degrades to the independent form — which reads the FULL session — automatically.
+ *
+ * `disable` — the PTL-recovery lane's structural off-switch: the provider just rejected the very
+ * prefix a fork would resend, so a fork attempt there is a guaranteed wasted round-trip before the
+ * internal fallback. The other lanes pass `false`.
+ */
 export declare function forkContextOption(prepared: Prepared, disable: boolean): Pick<MaybeCompactOptions, "forkContext">;
+/**
+ * RB-31 ([1068]) — compaction-boundary center-candidate adoption. Absent (an empty object, NOT a
+ * `centerAdoption: undefined` key) = restate as before; a boundary re-pin hashes the same artifact
+ * identity on every lane.
+ */
 export declare function centerAdoptionOption(prepared: Prepared): Partial<Pick<MaybeCompactOptions, "centerAdoption">>;
+/** design/169-F defaults (object-present, field-absent). Named per the magic-number rule. */
 export declare const STALE_OFFLOAD_DEFAULT_KEEP_RECENT_PER_TOOL = 3;
 export declare const STALE_OFFLOAD_DEFAULT_MIN_SAVINGS_CHARS = 2000;
+/** Resolved (validated, defaulted) knob — see {@link resolveStaleToolResultOffload}. */
 export interface ResolvedStaleToolResultOffload {
     keepRecentPerTool: number;
     minSavingsChars: number;
 }
+/**
+ * design/169-F — validate + default the spec knob. Fail-loud on non-finite/negative/fractional
+ * values (a computed NaN silently re-defaulting is the ||0-fold this repo's engineering code bans);
+ * `undefined` knob ⇒ `undefined` (feature completely off).
+ */
 export declare function resolveStaleToolResultOffload(knob: StaleToolResultOffloadOptions | undefined): ResolvedStaleToolResultOffload | undefined;
+/** The pointer that replaces a stale result's text in the request projection. PURE function of
+ *  (toolName, ref, chars) — that determinism is the DECISION-stability guarantee: a result already
+ *  replaced maps to the same pointer bytes on every later request (no flip-flop, no re-decision
+ *  churn). It is NOT full prefix stability: the verbatim→pointer TRANSITION itself (a result
+ *  crossing the staleness line as newer same-tool results arrive) rewrites that message's bytes
+ *  once, invalidating the provider cache from that position for one request — a bounded,
+ *  once-per-result break the `minSavingsChars` floor is there to amortize.
+ *  Deliberately NOT `offloadPagebackHint` (the design/30 preview's hint): that hint's wording is a
+ *  function of the LIVE reachable-tool set, and this pointer is re-derived per request — a mid-run
+ *  ToolSearch activation would flip its bytes and break the very prefix stability this file pins.
+ *  The reader is named by its real mounted name (独立复审 MED,已修: `read_tool_result` is a
+ *  retired alias — a model following it burned a rejected call first). */
 export declare function buildStaleOffloadPointer(toolName: string, ref: string, chars: number): string;
-export declare function projectStaleToolResults(context: Context, cfg: ResolvedStaleToolResultOffload, store: ToolResultStore, sessionId: string, writtenRefs: Set<string>): Promise<Context>;
+/**
+ * design/169-F — the request-side projection: replace STALE same-tool results with byte-stable
+ * pointers. "Stale" = has ≥ `keepRecentPerTool` NEWER results of the same tool name in this request
+ * — a monotone predicate (a result never gains "recency" back), so a replacement decision made on
+ * one request holds on every later one and re-derivation is deterministic: no run-scoped mutable
+ * decision state is needed for byte stability, only the pointer's purity (see
+ * {@link buildStaleOffloadPointer}) and the store's write-once `put`.
+ *
+ * The session transcript is NEVER touched — this runs on the outgoing {@link Context} only.
+ * Error results, image/document-bearing blocks' non-text parts, already-offloaded previews, and
+ * replacements that would save < `minSavingsChars` are left verbatim. The full text is persisted
+ * under a deterministic content-digested ref (design/30's mint helper over
+ * `<toolCallId>_s<sha256-12 of the text>` — write-once, so re-projection on every turn re-puts a
+ * no-op; the digest exists because tool-call ids carry no cross-turn uniqueness contract),
+ * readable back via `read_tool_result`.
+ */
+export declare function projectStaleToolResults(context: Context, cfg: ResolvedStaleToolResultOffload, store: ToolResultStore, sessionId: string, 
+/** Run-scoped cache of refs already persisted by THIS run (独立复审 MED,已修): without it the
+ *  write-once `put` is still re-issued every request — on the file backend that is a
+ *  write-then-discard round-trip per stale result per turn. Caller owns the Set's lifetime. */
+writtenRefs: Set<string>): Promise<Context>;
+/**
+ * MF-18 修② ([496]③) — fidelity disclosure: the summary INPUT was clipped to the compaction model's
+ * window. Fires pre-call, so the disclosure survives a failed attempt. All three lanes emit the SAME
+ * frame; the end-of-task lane passes `spec.tracer ?? deps.tracer` / `spec.taskId ?? sessionId`
+ * explicitly because `RunState.telemetry` (which holds exactly those two resolved values) is not in
+ * scope inside `finish()`.
+ */
 export declare function emitInputTruncated(tracer: TracerHook | undefined, taskId: string): NonNullable<MaybeCompactOptions["onInputTruncated"]>;

package/dist/core/runner/grounding-signal.d.ts

@@ -1 +1,11 @@
+/**
+ * Deterministic §3.C(3) process-side projection over ONE tool call's args.
+ *
+ * Shape-based, tool-name-agnostic: any tool whose args carry a string `command` field (the
+ * shell-tool family — "Bash" and renamed/white-labeled shells alike) is projected through the
+ * word-face regex; every other tool contributes nothing. Case-sensitive (the faces are lowercase
+ * tool/stdlib names; an uppercase variant is not these tools). A gate-blocked call still counts:
+ * the signal evidences the TASK CLASS (the model reaching for byte-level work), not execution
+ * success — and the misfire cost is bounded by the injection cap.
+ */
 export declare function hasVerifiableStructureSignal(args: unknown): boolean;

package/dist/core/runner/image.d.ts

@@ -1,5 +1,22 @@
 import type { ImageContent } from "../../internal/llm.js";
 import type { ImageInput } from "../types.js";
+/**
+ * Block obviously-internal hosts (loopback / private ranges / link-local incl. cloud metadata / CGNAT / IPv6
+ * ULA, site-local, unspecified, IPv4-mapped, NAT64). Classifies with `net.isIP` rather than a string-prefix
+ * regex — the old regex both UNDER-matched (IPv4-mapped `::ffff:`, NAT64, CGNAT 100.64/10, `::`) and
+ * OVER-matched (any DNS name starting `fc`/`fd`, e.g. `fdpartners.com`). Numeric IPv4 forms (decimal/octal/hex)
+ * are normalized to dotted-decimal by `URL` before this is called, so they're already covered.
+ * Note: this checks the LITERAL host; it does NOT resolve DNS, so a hostname resolving to a private IP is not
+ * caught here (documented limitation — a deployment needing that supplies its own resolve-and-pin guard).
+ */
 export declare function isPrivateHost(host: string): boolean;
+/**
+ * Default SSRF guard for a remote image URL: https only, and no internal/reserved hosts (so an
+ * end-user-supplied `images[].url` can't make the server fetch `169.254.169.254` or a private box).
+ * Note: this checks the URL host literally — it does not resolve DNS, so a hostname that resolves to
+ * a private IP is not caught here; a deployment needing that should supply `RunnerDeps.allowImageUrl`
+ * (e.g. a CDN allowlist or a resolve-and-pin check). Throws on a disallowed URL.
+ */
 export declare function defaultImageUrlGuard(raw: string): void;
+/** Resolve an {@link ImageInput} (inline base64 or a URL to fetch) into a vendored `ImageContent` block. */
 export declare function toImageContent(img: ImageInput, allowUrl?: (url: string) => boolean): Promise<ImageContent>;