@sema-agent/core 5.20.0 → 5.21.0

package/dist/core/tool-result-budget.d.ts

@@ -1,21 +1,53 @@
 import type { AgentMessage } from "../internal/harness-types.js";
 import { type ToolResultStore } from "./tool-result-store.js";
+/**
+ * Per-message aggregate tool-result budget (design/64 §17.2 / §24 — CC `MAX_TOOL_RESULTS_PER_MESSAGE_CHARS`,
+ * `constants/toolLimits.ts:49`). A single turn's batch of N parallel tool results can each be under the
+ * per-tool offload threshold yet SUM past the model/API limit (10×40K = 400K). This caps the aggregate of
+ * one turn's tool_result batch: while over budget, the LARGEST fresh non-exempt result is offloaded to a
+ * preview (largest-first), repeating until the batch fits.
+ *
+ * **Simpler than CC by construction (§24.2):** a request-only, non-destructive transform (returns a new
+ * array; the durable session keeps full results) applied in the existing `harness.on("context")` hook —
+ * the same per-query point as `clearStaleToolResults` (the mirror of CC's query.ts:379). It is DETERMINISTIC
+ * (stable `ref = tr_<sessionId>_<toolCallId>` + deterministic {@link buildPreview}), so re-running it every
+ * query yields byte-identical previews → prompt-cache safe **without** CC's ContentReplacementState freeze
+ * machine (the determinism IS the freeze), and resume-free (the transcript holds originals; this re-applies
+ * on replay). Reuses design/30's offload store + preview format; with no store it falls back to a
+ * self-contained head+tail truncation preview that still bounds the request.
+ */
+/** CC's per-message cap (chars, not tokens — the "100K token" figure in old notes was unsourced). */
 export declare const AGGREGATE_TOOL_RESULT_BUDGET_CHARS = 200000;
 export interface AggregateBudgetOptions {
+    /** Per-batch char budget. Default {@link AGGREGATE_TOOL_RESULT_BUDGET_CHARS}. */
     budgetChars?: number;
+    /** Tool names exempt from the budget (their own caps bound them) — e.g. read_file, read_tool_result. */
     exemptTools?: ReadonlySet<string>;
+    /** design/30 store for offload+read-back. Absent ⇒ self-contained truncation preview. */
     store?: ToolResultStore;
+    /** Namespaces the stable ref so an offloaded result is globally addressable. */
     sessionId: string;
+    /** service [398] C8: fired once per result actually capped (offloaded OR degraded to a truncation
+     *  preview). `storeFallback` = the model LOST read-back for this result (store.put failed / no store)
+     *  — the silent-degradation face this callback exists for. Must not throw (caller-side contract). */
     onCapped?: (info: {
         tool?: string;
         sizeChars: number;
         storeFallback: boolean;
     }) => void;
+    /** RB-142: fired once per batch that is STILL over budget after both passes — i.e. the cap did what it
+     *  could and the request is going out oversized anyway. Reachable when a batch holds more results than
+     *  the budget can hold even at the minimum preview size (a compact preview has a floor, and N of them
+     *  cannot be smaller than N × that floor). Before this existed the shortfall was entirely silent, so a
+     *  caller could not tell "capped and fits" from "capped and still 2× over". Must not throw. */
     onBudgetUnreachable?: (info: {
         batchChars: number;
         budgetChars: number;
         results: number;
     }) => void;
 }
+/** Default exemptions: tools whose result is self-bounded (read_file errors at its own token cap; the
+ *  offload reader pages small slices). grep/bash/glob/web_fetch/MCP are the risk sources, NOT exempt. */
 export declare const DEFAULT_BUDGET_EXEMPT_TOOLS: ReadonlySet<string>;
+/** Cap each over-budget turn-batch (run of consecutive tool_result messages). Request-only; see file docs. */
 export declare function capAggregateToolResults(messages: AgentMessage[], opts: AggregateBudgetOptions): Promise<AgentMessage[]>;

package/dist/core/tool-result-store.d.ts

@@ -1,21 +1,112 @@
 import type { AgentTool } from "../internal/harness-types.js";
+/**
+ * Pluggable backing store for **offloaded large tool results** (design/30). When a tool returns more
+ * text than the threshold, the full content is moved here and the conversation keeps only a preview +
+ * a `ref`; the model fetches the rest via the injected `read_tool_result` tool. This is the local,
+ * provider-agnostic equivalent of CC's `toolResultStorage` (no Anthropic `cache_edits` dependency).
+ *
+ * Default is {@link InMemoryToolResultStore} (task-scoped, lives only for the run). Inject a durable
+ * implementation (TiDB/blob, keyed by the opaque `ref`) so an offloaded result survives wake/resume;
+ * with the in-memory default, a fetch after a cross-process wake returns undefined and the model is told
+ * the output is no longer available — the preview still stands in context, so it degrades, never crashes.
+ */
 export interface ToolResultStore {
+    /**
+     * Managed-retention declaration (ruled 2026-08-05, retention.ts): `"managed"` promises the
+     * `ManagedRetentionCapability` contract (scheduled, tenant-scoped, audited deletion); `"none"` (or
+     * ABSENT — read fail-closed as `"none"`) states the store cannot delete on schedule. A deployment
+     * with a LOCKED retention policy refuses to start over a `"none"` store. Declaration, never
+     * duck-typing.
+     */
     readonly retention?: import("./retention.js").RetentionDeclaration;
+    /**
+     * Persist full content under a stable `ref`. **Write-once and idempotent**: if `ref` already exists,
+     * keep the existing content and do nothing (the aggregate budget re-runs every query with the same
+     * deterministic ref, so `put` for an already-stored ref MUST be a no-op — re-writing would risk a
+     * non-identical preview and break the prompt cache). A durable backend treats `ref` as the primary key
+     * and should validate/sanitize it (it is composed from sessionId+toolCallId, not raw model input, but a
+     * durable store still owns key hygiene for its storage layer). RB-266: the floor of that hygiene is
+     * NOT per-backend — every implementation rejects the unsafe ref set via {@link assertSafeToolResultRef}
+     * (a volatile backend silently accepting what a durable one rejects is the drift this closes).
+     */
     put(ref: string, content: string): Promise<void> | void;
+    /** Read a slice of the stored content. Unknown `ref` → undefined. */
     get(ref: string, opts?: {
         offset?: number;
         limit?: number;
     }): Promise<ToolResultSlice | undefined> | ToolResultSlice | undefined;
 }
+/**
+ * RB-266 — the ref-safety half of the {@link ToolResultStore} contract, shared by every backend.
+ *
+ * Why it is central and not per-backend: the file backend has always rejected these refs (its path
+ * component guard, `stores/file/fs-atomic.ts:48`), while the in-memory backend accepted them
+ * silently — the SAME ref stored fine in dev and threw in a durable deployment. That is the
+ * "backend outside the shared contract drifts on its own" mechanism (same family as RB-86/MB1 on
+ * MailboxStore), and the honest direction is the strict one: a ref that no durable backend can key
+ * is a defect at the WRITE, not something a volatile backend should quietly absorb.
+ *
+ * The rejected set is deliberately the intersection-unsafe one — empty / `.` / `..` / path
+ * separators / control characters — i.e. refs that are unusable as a key ANYWHERE (they traverse in
+ * a path-backed store and are ambiguous in every other). Backends may still be stricter about their
+ * own storage layer (the file backend additionally enforces a filename charset); that extra
+ * strictness is a backend capability, not part of this contract.
+ *
+ * Read face stays lenient by design: `get` with such a ref returns `undefined` (an unknown ref), it
+ * does NOT throw — the model is told the output is gone and the run degrades instead of crashing.
+ *
+ * RB-273 amends one clause of the above: a backend may be stricter about its own STORAGE LAYER, but not
+ * about which refs it accepts. A ref this function accepts must round-trip on every backend — a backend
+ * whose native key space is narrower (the file one's filename charset) owns an injective ENCODING into
+ * that space, not a rejection. Otherwise the same "dev green / deployment red" split this rule closed
+ * for `..` simply reappears one charset over (it did: a `:` in a provider-minted toolCallId).
+ */
 export declare function assertSafeToolResultRef(ref: string): void;
+/**
+ * RB-273 — the SINGLE mint point for a tool-result `ref`. Three call sites compose the same
+ * `tr_<sessionId>_<toolCallId>` string (`withToolResultOffload` here, the aggregate budget's preview
+ * pass, and the runner's clear-with-offload persist); this is that string's one definition.
+ *
+ * Why it must sanitize: `sessionId` is engine-minted, but **`toolCallId` is PROVIDER-minted** — it is
+ * whatever the model gateway put in the tool-call frame, not something core controls. Providers ship
+ * ids with `:` in them, and nothing stops one shipping a `/`. Composed raw, that produced two distinct
+ * failures, both far from their cause:
+ *   - `/` or a control char ⇒ the ref violates {@link assertSafeToolResultRef} ⇒ `put` THROWS at mint,
+ *     i.e. an offload (a context-economy optimization) turns a working tool call into a failed one;
+ *   - `:` ⇒ accepted by memory/pg, rejected by the file backend's filename charset ⇒ the classic
+ *     dev-green/deployment-red split (`probe-r5-store-parity-matrix`'s last two divergent cells).
+ *
+ * The mapping is IDENTITY for every id already in the native charset — which is all of them in practice
+ * (`toolu_…`, `call_…`, uuids) — so refs minted before this existed are byte-identical afterwards and
+ * the prompt-cache stability the preview rests on is untouched. Only an out-of-charset (or absurdly
+ * long) segment is folded, and then INJECTIVELY: readable base + a sha256 of the RAW segment, the same
+ * construction (and the same reason: two distinct ids must never collide onto one ref, which would
+ * cross-serve one tool's output as another's) as `sanitizeScope` in the file store.
+ *
+ * Read-back of refs minted BEFORE this change is unaffected in both directions: safe ids are unchanged,
+ * and an unsafe one only ever lived in a memory/pg deployment, where the ref the model reads back comes
+ * from the `<persisted-output ref="…">` text already in its context — the read path does not re-mint,
+ * and `get` is keyed on that literal string.
+ */
 export declare function buildToolResultRef(sessionId: string, toolCallId: string): string;
 export interface ToolResultSlice {
     content: string;
+    /** Byte/char offset this slice starts at. */
     offset: number;
+    /** Total chars of the full stored content. */
     totalChars: number;
 }
+/** Default in-memory store (no cross-process durability); write-once per ref.
+ *
+ *  Blackboard 2026-07-03 (clay dogfood: `ReadToolResult(ref)` came back empty for a workflow child's
+ *  offloaded output): the Runner now shares ONE instance across its tasks (instead of a per-task
+ *  island), so a parent can deref a child's ref within the process. A shared long-lived instance
+ *  needs a bound — `maxTotalChars` FIFO-evicts the oldest refs past the cap (an evicted deref lands
+ *  on the existing honest "may have expired" text). Durability across restarts still requires a real
+ *  store (e.g. FileToolResultStore) via `RunnerDeps.toolResultStore`. */
 export declare class InMemoryToolResultStore implements ToolResultStore {
     private readonly opts?;
+    /** put/get only — no scheduled deletion contract: honestly `"none"` (retention.ts). */
     readonly retention: "none";
     private readonly map;
     private totalChars;
@@ -23,41 +114,123 @@ export declare class InMemoryToolResultStore implements ToolResultStore {
         maxTotalChars?: number;
     } | undefined);
     put(ref: string, content: string): void;
+    /** design/80 D-2: true when NOTHING has been offloaded — a durable suspend can then proceed safely even on
+     *  this in-memory store, because a cross-replica resume has no offloaded result to deref to null. */
     isEmpty(): boolean;
     get(ref: string, opts?: {
         offset?: number;
         limit?: number;
     }): ToolResultSlice | undefined;
 }
+/** Marker subclass for the Runner's own shared fallback instance (no injected store). prepare-task
+ *  detects it and wraps a per-task {@link ScopedToolResultStore} around it — an INJECTED store is
+ *  never wrapped (a multi-tenant deployment that injects a durable store owns its own scoping). */
 export declare class RunnerSharedToolResultStore extends InMemoryToolResultStore {
 }
+/**
+ * Per-task view over the Runner-shared fallback (impl-review 2026-07-03, codex 2 BLOCKER):
+ * 1. **Tenant isolation**: refs are namespaced by the task's trust scope (principal), so tenant B's
+ *    `ReadToolResult` can never deref tenant A's ref — the per-task-instance era made this isolation
+ *    implicit; sharing one instance re-opened it. Same-scope cross-task deref (the A2 fix's whole
+ *    point) still works: same scope ⇒ same namespace.
+ * 2. **D-2 durable-suspend gate fidelity**: `isEmpty()` reflects only THIS task's offloads (local put
+ *    count) — matching the per-task-instance semantics the gate was written against — so an unrelated
+ *    prior task's offloaded entry can no longer disable durable suspend for a task that offloaded
+ *    nothing (prepare-task's fail-fast reads `isEmpty()`).
+ */
 export declare class ScopedToolResultStore implements ToolResultStore {
     private readonly inner;
     private readonly scope;
     private localPuts;
+    /** True when the underlying shared store is process-memory (volatile across replicas) — the D-2
+     *  suspend gate treats a NON-empty volatile store as unsafe to durably suspend. */
     readonly volatileBacking: boolean;
     constructor(inner: ToolResultStore, scope: string);
+    /** Length-prefixed namespace — unambiguous for any scope string (no delimiter-injection ambiguity).
+     *  RB-266: the scope segment is percent-ENCODED (injective, and its output charset carries no path
+     *  separator or control character), so a deployment whose trust scope contains one cannot compose a
+     *  key the inner store must reject — the ref-safety rule then applies to the caller's ref alone. */
     private key;
     put(ref: string, content: string): Promise<void> | void;
     get(ref: string, opts?: {
         offset?: number;
         limit?: number;
     }): Promise<ToolResultSlice | undefined> | ToolResultSlice | undefined;
+    /** THIS task's offload count only — the D-2 gate's per-task semantics (see class doc). */
     isEmpty(): boolean;
 }
+/** True when a durable suspend would lose offloaded results held only in process memory (D-2 gate). */
 export declare function isVolatileOffloadStore(store: ToolResultStore): boolean;
+/** Reserved name of the injected large-result reader (design/108 PascalCase: `read_tool_result`→`ReadToolResult`). */
 export declare const OFFLOAD_TOOL_NAME = "ReadToolResult";
+/**
+ * RB-469-d — the runner's clear-with-offload persist, as ONE construction point (the closure used to
+ * live inline in prepare-task). Fire-and-forget by design (the caller returns the ref synchronously),
+ * but a failed put no longer strands the model with a ref pointing at nothing: a tiny lost-marker is
+ * written under the same ref so the page-back face reports the true cause (C6 — "lost at write" and
+ * "expired" are different answers). If the marker write fails too, the generic miss remains.
+ */
 export declare function createOffloadPersist(store: ToolResultStore, sessionId: string): (toolCallId: string, fullText: string) => string;
+/**
+ * RB-374① — the ONE source of the "page the offloaded text back" suggestion sentence, shared by
+ * {@link buildPreview} (offload preview tail) and context-edit's cleared-marker refNote. The two
+ * used to hard-code the same advice in independently drifting wordings, and neither knew whether
+ * the reader tool is even CALLABLE in the current session: with {@link OFFLOAD_TOOL_NAME} deferred
+ * (a design/36 placeholder), the suggestion was a self-referential dead end — the model follows it
+ * and the placeholder rejects with "not active yet".
+ *
+ * `reachableTools` is OPTIONAL: omitted ⇒ byte-identical to the historic sentences (the
+ * determinism/prompt-cache contract of both call sites rests on this default — notably the
+ * per-request aggregate-budget pass, which re-derives previews every query and therefore must
+ * never receive a session-varying set). Passed and missing {@link OFFLOAD_TOOL_NAME} ⇒ the honest
+ * two-step form (activate via ToolSearch first — wording kept close to tool-disclosure.ts's
+ * placeholder hint). The `core` fragment below is deliberately shared by both forms so the two
+ * faces cannot drift apart again (a wording change moves both, and both pins move with it).
+ */
 export declare function offloadPagebackHint(ref: string, form: "preview" | "cleared", reachableTools?: ReadonlySet<string>): string;
+/** Leading marker of an offload preview (see {@link buildPreview}) — single source so the aggregate
+ *  budget (design/64 §17.2) can recognize an already-offloaded result without re-deriving the string. */
 export declare const PERSISTED_OUTPUT_PREFIX = "<persisted-output ref=";
+/** Default per-result offload threshold (chars). ~5K tokens; configurable globally or per tool. */
 export declare const DEFAULT_TOOL_RESULT_THRESHOLD_CHARS = 20000;
+/**
+ * CC 198 per-tool persistence thresholds, mirrored for the first-party mounts (PARITY-SPOT-USAGE-CONSTANTS
+ * 2026-07-10 F1/F2). CC's GIa framework (pretty.js:286716-286721) resolves each tool's persist threshold as
+ * `min(maxResultSizeChars, w6t=50000)`:
+ *   - Read declares `maxResultSizeChars: 1/0` (:478260) → **never persisted**. Read already owns its bound
+ *     (25K-token first-page auto-pagination) and the aggregate budget exempts it — wrapping it in offload
+ *     re-truncated a page the tool had already sized (the F1 two-layer inconsistency). Structural exemption:
+ *     applies even when a deployment sets an explicit global threshold.
+ *   - Bash 30000 (:335231) / Grep 20000 (:333220) / Monitor 1e4 (:450030); everything else first-party
+ *     declares 1e5 (Agent :453402, Glob :333570, TaskOutput :458260, …) → min(1e5, 50000) = 50000.
+ * Unknown tools keep the deployment default ({@link DEFAULT_TOOL_RESULT_THRESHOLD_CHARS}) — we deliberately
+ * do NOT mirror KIa's bare `$xa=400000` undeclared-tool fallback: our aggregate budget is 200K chars, so a
+ * 400K inline result is unrepresentable anyway.
+ */
 export declare function firstPartyOffloadPolicy(toolName: string): {
     offload?: boolean;
     offloadThresholdChars?: number;
 };
+/** Head+tail preview of an offloaded result, pointing at {@link OFFLOAD_TOOL_NAME} via `ref`. Exported so
+ *  the per-message aggregate budget (design/64 §17.2) produces the SAME preview format (deterministic →
+ *  byte-identical across queries → prompt-cache safe). */
 export declare function buildPreview(full: string, ref: string, sizes?: {
     head: number;
     tail: number;
 }, reachableTools?: ReadonlySet<string>): string;
-export declare function withToolResultOffload(tool: AgentTool, store: ToolResultStore, thresholdChars: number, sessionId: string, reachableTools?: () => ReadonlySet<string> | undefined): AgentTool;
+/**
+ * Wrap an {@link AgentTool} so that an oversized text result is offloaded to `store` and replaced with a
+ * preview + `ref` before it ever reaches the session/model. `ref = tr_<toolCallId>` is stable and the
+ * store is write-once: a **same-process** replay keeps an identical (cacheable) preview; a **cross-process**
+ * wake needs a durable store (the default in-memory store loses the full text — the preview still stands).
+ * Image blocks are left untouched; only text is offloaded. Forwards the `onUpdate` progress callback so a
+ * wrapped (e.g. MCP) streaming tool isn't broken.
+ */
+export declare function withToolResultOffload(tool: AgentTool, store: ToolResultStore, thresholdChars: number, sessionId: string, 
+/** RB-374① — LIVE accessor for the session's currently CALLABLE tool set (evaluated per offload,
+ *  so a mid-run ToolSearch activation is reflected by the next preview). Absent/`undefined`-returning
+ *  ⇒ byte-identical historic preview. An accessor (not a snapshot) because the wrap happens at
+ *  prepare time, before the deferred classification exists and before any activation can. */
+reachableTools?: () => ReadonlySet<string> | undefined): AgentTool;
+/** The injected `read_tool_result` tool: pages through an offloaded result. `effect:"read"` (verifier/reconcile-safe). */
 export declare function createReadToolResultTool(store: ToolResultStore): AgentTool;

package/dist/core/tools.d.ts

@@ -1,15 +1,60 @@
 import type { TSchema } from "typebox";
 import type { AgentTool } from "../internal/harness.js";
 import type { ToolExecuteContext, ToolSpec } from "./types.js";
+/**
+ * E1(黑板 [1937],test/server/cli 三方交叉核实): wrap an already-built failure message string into the
+ * `ToolReturn` shape that actually signals failure. A bare `string` return is UNCONDITIONALLY
+ * `isError:false` (see `ToolReturn.isError`'s own doc comment) — the toolkit-wide survey found 120+
+ * sites across fs/web/sql/scheduler/worktree/etc. that build a correct `"Error (...): ..."` message
+ * but then `return` it as a bare string, so the model/UI/metrics see success. Message text is
+ * unchanged; only the envelope changes — call sites keep building strings exactly as before and wrap
+ * the final value: `return errorResult(violationText(...))` / `return errorResult(\`Error (Write): ...\`)`.
+ */
 export declare function errorResult(text: string, details?: unknown): {
     content: string;
     isError: true;
     details?: unknown;
 };
+/** True iff `x` is an `AgentTool` this module's `defineTool` itself constructed — see {@link DEFINE_TOOL_BRAND}. */
 export declare function isDefineToolProduct(x: unknown): x is AgentTool;
+/** RB-362 类修同源章点 — the ONE place the brand is stamped. `defineTool` uses it on its own product;
+ *  the only OTHER legitimate caller is a wrapper that (a) starts from a branded product and (b)
+ *  preserves the AgentTool `execute(toolCallId, rawParams, signal, onUpdate)` contract faithfully
+ *  (e.g. teacher.ts's logging wrapper). A shallow copy that does NOT re-stamp deliberately loses the
+ *  brand — that is the brand's documented survival contract, not an accident. Internal only. */
 export declare function stampDefineToolBrand<T extends object>(tool: T): T;
+/**
+ * RB-409 — a per-call ctx builder a MOUNT hands to {@link defineTool}.
+ *
+ * Why the seat exists: the adapter below feeds the inner `ToolSpec.execute` a `{toolCallId, signal}`
+ * ctx, because `AgentTool.execute(toolCallId, rawParams, signal, onUpdate)` — the contract every
+ * `defineTool` product answers to — has NO ctx parameter at all. There was therefore no runtime
+ * channel through which a Runner could hand a finished product the trusted axes it fills in for a raw
+ * `ToolSpec` (parentTaskId/parentSessionId/taskId/sessionId/principal/…), so a first-party mounted
+ * tool read them as `undefined` on every call and its ctx-first arms were structurally dead. This
+ * closes the gap at MOUNT time instead: the mount — which does hold the Runner's trusted context —
+ * supplies a builder, and the adapter runs it PER CALL, so call-time snapshots (the run's current
+ * model, the live skill scope) stay current rather than freezing at factory time.
+ *
+ * Shape is deliberately the SAME `(ctx) => ctx` one the Runner's `spec.tools` wrapper already applies,
+ * so a mount passes THAT builder itself instead of re-listing the axes — one source for the trusted
+ * seat set, no second table to drift out of sync with it.
+ *
+ * Trust: whatever this returns rides the tool's TRUSTED seat, so a mount must never build one out of
+ * model-supplied arguments. The per-call identity (`toolCallId`/`signal`) is re-stamped AFTER the
+ * builder runs and can never be rewritten by it. A builder that throws surfaces as this tool call's
+ * error (the adapter's existing formatter), never as a loop crash.
+ */
 export type ToolCtxEnricher = (base: ToolExecuteContext) => ToolExecuteContext;
+/**
+ * Optional factory knobs for {@link defineTool}. Internal only — NOT re-exported from `index.ts`
+ * (same posture as {@link isDefineToolProduct}); a caller passes an object literal, which structural
+ * typing accepts without needing the name.
+ */
 export interface DefineToolOptions {
+    /** RB-409 — see {@link ToolCtxEnricher}. Absent ⇒ the inner spec sees exactly the pre-RB-409
+     *  `{toolCallId, signal}` ctx, so every mount that does not opt in stays byte-identical. */
     enrichCtx?: ToolCtxEnricher;
 }
+/** Adapt a friendly ToolSpec into the vendored AgentTool the agent loop expects. */
 export declare function defineTool<TParams extends TSchema = TSchema>(spec: ToolSpec<TParams>, options?: DefineToolOptions): AgentTool<TParams>;