@sema-agent/core 5.19.0 → 5.21.0

package/dist/core/runner/session-rule-policy.d.ts

@@ -2,9 +2,67 @@ import type { ExecutionEnv } from "../../internal/harness-types.js";
 import type { ToolEffect } from "../types.js";
 import { type NamedToolPolicy } from "../tool-policy.js";
 import type { SessionPermissionRules } from "../session-policy-store.js";
+/** Tool names whose write target is the `file_path`/`path` arg ({@link fileArgPath}).
+ *
+ *  REF-B3 — the ONE definition of that narrower set. Production consumer today:
+ *  `createActiveSkillScopePolicy` (runner/active-skill-scope.ts, manifest `allowPaths`). The
+ *  `allowDirs`/fs-write faces consume the superset {@link PATH_CONFINABLE_WRITE_TOOLS} instead.
+ *
+ *  BOUNDARY: this set stays `file_path`-keyed — its members' write target is read by {@link fileArgPath}.
+ *  `NotebookEdit` (whose target is `notebook_path`) lives in the superset
+ *  {@link PATH_CONFINABLE_WRITE_TOOLS} below, NOT here: `createActiveSkillScopePolicy` reads THIS set and
+ *  deliberately keeps fail-closed-denying notebooks under a manifest `allowPaths` fence (widening the
+ *  skill face is a separate capability decision with its own review). */
 export declare const PATH_WRITE_TOOLS: ReadonlySet<string>;
+/** The FULL path-confinable write-tool set: {@link PATH_WRITE_TOOLS} plus `NotebookEdit`, whose write
+ *  target is `notebook_path` and is extracted by the shared tool-aware {@link writeTargetPath} ([886]①b —
+ *  notebook_path outranks a decoy `file_path` for that tool).
+ *
+ *  REF-B3 — the ONE spelling of "tools this codebase can confine by path". Consumers:
+ *  {@link createSessionRulePolicy} (below, `allowDirs`) and `createFsWriteGatePolicy`
+ *  (core/fs-write-gate-policy.ts), which used to rebuild `[...PATH_WRITE_TOOLS, "NotebookEdit"]` inline.
+ *  A fourth spelling survives as a LITERAL in core/tool-policy.ts (the transcript-dir gate) because THIS
+ *  module imports tool-policy.ts — that one is a documented coordinate held in sync by a source-scan pin
+ *  (SW-10), not a silent copy.
+ *
+ *  SW-10 relax (ruled 2026-08-04): `NotebookEdit` was previously absent from the session-rule face's
+ *  covered set, so an `allowDirs` confinement denied it OUTRIGHT via the "mutating but not path-confinable"
+ *  arm — a capability GAP relative to the fs-write gate, which has always proven the tool confinable.
+ *  Both faces now share this set and the same target extractor, so the session face confines notebooks by
+ *  path instead of refusing them. The fail-closed deny for every OTHER non-confinable mutating tool
+ *  (bash, deployment-authored write tools, unknown effects) is unchanged. */
 export declare const PATH_CONFINABLE_WRITE_TOOLS: ReadonlySet<string>;
+/** Path-segment-aware containment, FAMILY-AWARE ([K-PLATFORM-SWEEP] MAJOR#2: canonical keys are
+ *  backslash-form on a win32 env — the "/"-hardcoded suffix rejected every legitimate write there).
+ *  Compare in "/" form with drive-letter case folded; never keyed on process.platform (the env may be
+ *  remote and of the OTHER family than the host).
+ *
+ *  REF-B3 — exported as the single source for the policy modules that fence WRITES by an allowlist of
+ *  directories: active-skill-scope.ts (manifest `allowPaths`) and fs-write-gate-policy.ts (`acceptDirs`
+ *  /`exemptDirs`), plus the K-PLATFORM sweep tests. The line here used to read "exported ONLY for the
+ *  K-PLATFORM sweep tests", which was already false when written (fs-write-gate-policy.ts imports it in
+ *  production), and active-skill-scope.ts carried a byte-identical private twin — comment included — so
+ *  a platform-family fix had to be remembered at two coordinates.
+ *
+ *  The sibling implementation is `within()` in tools/fs/safety.ts (the fs-tool root fence). Those stay
+ *  separate functions on purpose — that one is private to the fence and keyed on canonical roots — but
+ *  they must never disagree on a verdict; the empty-root arm below is that alignment. */
 export declare function isWithin(root: string, p: string): boolean;
+/**
+ * Build the per-session deny-narrowing policy. For each tool call:
+ *  - `toolDeny` → deny the listed tools.
+ *  - `toolAllow` (if set) → deny any tool NOT listed (a narrowing allowlist).
+ *  - `commandAllow`/`commandDeny` → delegate to {@link createCoarseCommandNamePolicy} (argv[0] names; only
+ *    speaks about shell tools). allowlist mode denies the un-listed/un-parseable; blocklist mode asks on the
+ *    un-parseable bypass surface (the gate decides).
+ *  - `allowDirs` (if set) → a WRITE tool must land inside one of the dirs (resolved via `canonicalizeTarget`,
+ *    so a symlink can't smuggle a write out); a write-capable tool that cannot be path-confined (e.g. `bash`)
+ *    is DENIED while `allowDirs` is set (fail-closed, mirrors active-skill-scope MAJOR-2).
+ * Returns `allow` when nothing constrains the call. `env`/`rootPath` are the task's real exec env + root, so
+ * matching sees the actual filesystem (a remote/E2B task resolves in its container). RB-108: a relative
+ * TARGET prefers the call's live tracked cwd ({@link ToolCallRequest.cwd}) when the engine stamps one;
+ * `allowDirs` entries always resolve against `rootPath`.
+ */
 export declare function createSessionRulePolicy(rules: SessionPermissionRules, opts: {
     env: ExecutionEnv;
     rootPath?: string;

package/dist/core/runner/strict-output-schema.d.ts

@@ -1,4 +1,5 @@
 import type { TSchema } from "typebox";
+/** Port of 204 `Lqn` — derive the strict form of a whole schema (root must be `type:"object"`). */
 export declare function deriveStrictSchema(schema: unknown): {
     ok: true;
     schema: Record<string, unknown>;
@@ -6,15 +7,29 @@ export declare function deriveStrictSchema(schema: unknown): {
     ok: false;
     reason: string;
 };
+/** Exposed for callers that only need validity (no derivation). Runs the size guard first. */
 export declare function validateJsonSchemaShape(schema: unknown): string | null;
-export type CompiledOutputSchema = {
+export type CompiledOutputSchema = 
+/** The schema is not a valid JSON Schema (or too large) — callers must FAIL FAST, never run silently. */
+{
     error: string;
-} | {
+}
+/** Strict derivation succeeded: `modelSchema` is the tightened form to hand the model. */
+ | {
     modelSchema: TSchema;
     strict: true;
-} | {
+}
+/** Valid but outside the strict subset: serve the schema as-is; `fallbackReason` is the observable why. */
+ | {
     modelSchema: TSchema;
     strict: false;
     fallbackReason: string;
 };
+/**
+ * Validate + strict-derive a structured-output schema (CC 2.1.205 semantics):
+ *   invalid / oversized schema → `{error}` (the caller throws — no silent acceptance);
+ *   in-subset schema → `{modelSchema: strictForm, strict:true}` (`additionalProperties:false` stamped);
+ *   valid-but-unsupported schema → `{modelSchema: original, strict:false, fallbackReason}` (observable).
+ * A derivation CRASH also falls back non-strict (CC's inner try/catch), never fails the task.
+ */
 export declare function compileOutputSchema(schema: TSchema): CompiledOutputSchema;

package/dist/core/runner/synthetic-tools.d.ts

@@ -2,20 +2,42 @@ import { type TSchema } from "typebox";
 import type { AgentTool } from "../../internal/harness-types.js";
 import type { SkillManifest } from "../types.js";
 import type { ActiveSkillScope } from "./active-skill-scope.js";
+/** Reserved name of the injected structured-output tool (CC 2.1.187 `StructuredOutput`; batch-A rename — old
+ *  "submit_output" is canonicalized for pre-rename durable state). */
 export declare const OUTPUT_TOOL_NAME = "StructuredOutput";
+/** Reserved name of the injected blocked-report signal tool (design/108 PascalCase: `report_blocked`→`ReportBlocked`). */
 export declare const REPORT_BLOCKED_TOOL_NAME = "ReportBlocked";
+/** Name of the injected code-review findings echo tool (CC 2.1.207 parity — 锚 pretty.js:361412 `BCe`). */
 export declare const REPORT_FINDINGS_TOOL_NAME = "ReportFindings";
+/** Default `submit_output` retries (council OS3); total attempts = retries + 1. Overridable via `TaskSpec.outputRetries`. */
 export declare const OUTPUT_DEFAULT_RETRIES = 2;
+/**
+ * Resolve the per-task cap on *consecutive failed* `submit_output` attempts. The task fails with
+ * `output.invalid` when the failure streak EXCEEDS this value, so total attempts = cap + 1
+ * (default 2 → 3 attempts; `outputRetries: 0` → cap 0 → fail on the first invalid submit). Illegal
+ * values (NaN/Infinity/negative) fall back to the default; fractional values floor down.
+ */
 export declare function resolveOutputRetries(outputRetries?: number): number;
 export interface BlockedRef {
     reason?: string;
 }
+/** Captures the validated object a `submit_output` call submitted (structured output, 1.41). `set` is
+ *  flipped so we can tell "model submitted {}" from "never called". Mirrors `BlockedRef`. */
 export interface OutputRef {
     value?: unknown;
     set?: boolean;
 }
+/**
+ * @param strictSchema CC 2.1.205 parity (strict-output-schema.ts): the STRICT derivation of `schema` when
+ *   it converted (`additionalProperties:false` stamped, subset-validated). It becomes the tool's
+ *   `parameters` — both the model-visible wire schema (CC sends it as `strictInputJSONSchema`) and the
+ *   validation schema (the strict form only TIGHTENS the caller's schema, so anything it accepts is valid
+ *   under the original — CC's Ajv-against-original validation agrees on every accepted submission).
+ *   Absent (fallback / legacy callers) → the caller's schema is served as-is, the pre-205 behavior.
+ */
 export declare function createOutputTool(ref: OutputRef, schema: TSchema, strictSchema?: TSchema): AgentTool;
 export declare function createReportBlockedTool(ref: BlockedRef): AgentTool;
+/** One reported finding (the CC 207 wire shape — see {@link createReportFindingsTool}). */
 export interface ReportedFinding {
     file: string;
     line?: number;
@@ -25,33 +47,124 @@ export interface ReportedFinding {
     verdict?: "CONFIRMED" | "PLAUSIBLE";
     outcome?: "fixed" | "skipped" | "no_change_needed";
 }
+/** Build the injected `ReportFindings` echo tool (CC 2.1.207 parity — description verbatim from 锚
+ *  pretty.js:361413; `effect: "read"` mirrors CC `isReadOnly()`/`isConcurrencySafe()` → parallel-safe). */
 export declare function createReportFindingsTool(): AgentTool;
+/** Reserved name of the injected skill-loading tool (present only when `spec.skills` is non-empty). */
 export declare const SKILL_TOOL_NAME = "Skill";
+/** Per-skill LOAD gate on `SkillSpec.content` (CC 2.1.207 parity: CC's only size door at invoke
+ *  time is a 1MB file-load gate — an over-limit skill is REJECTED WHOLE, never truncated; the
+ *  invoked body itself enters context untruncated). Sema skills are spec-supplied content, so the
+ *  equivalent gate sits at spec assembly (prepare-task): an oversized skill is excluded from both
+ *  the disclosure block and the tool, with an operator-visible config error. The compaction-time
+ *  retention caps live in the engine's compaction module — a different door, deliberately. */
 export declare const SKILL_CONTENT_MAX_CHARS: number;
+/** Total listing-block cap in UTF-8 BYTES — [c209-C] R2 C4①: the old 8000-CHAR cap measured a
+ *  different coordinate than the bundle's `ATTACHMENT_BYTE_CAP` (8192 UTF-8 bytes) and counted only
+ *  the description lines (fence framing + name-only tail rode free), so a near-cap frame could
+ *  exceed the bundle cap, get clip-mangled every boundary, never pass the intact-survival commit
+ *  predicate, and REPLAY FOREVER. The cap is now enforced byte-exact over the WHOLE rendered block
+ *  (fences, headers, markers, joiners included), so `buildSkillsBlock` output always fits the
+ *  bundle cap solo and an intact commit is always reachable. MUST stay ≤ ATTACHMENT_BYTE_CAP
+ *  (turn-attachments.ts; not imported here — that module imports this one — pinned by test instead). */
 export declare const SKILLS_BLOCK_MAX_BYTES = 8000;
+/** Total per-invoke cap for a skill's inlined attachments (`SkillSpec.files`) — an ATTACHMENT-face
+ *  budget, distinct from the (gone) body truncation door: the body itself is delivered untruncated
+ *  at invoke time (CC parity), while attachments are reference material riding along — bounded and
+ *  truncation-disclosed. */
 export declare const SKILL_ATTACHMENTS_MAX_CHARS = 50000;
+/** Per-attachment cap on the PATH rendered in its `###` header — a single pathological path must not
+ *  eat the attachments budget on its own. Overflow is truncated with an ellipsis. */
 export declare const SKILL_ATTACHMENT_PATH_MAX_CHARS = 512;
 interface SkillLike {
     name: string;
     description: string;
     content: string;
+    /** Optional Gate-3 runtime capability manifest (design/77 §3) — carried through so a successful
+     *  `skill` load can push its scope frame. Skills without one stay unscoped (backward-compatible). */
     manifest?: SkillManifest;
+    /** Optional attachments (SkillSpec.files): disclosed as paths in the block, delivered inline on
+     *  invoke under {@link SKILL_ATTACHMENTS_MAX_CHARS}. Same caller-trusted contract as `content`
+     *  (see the module note above) — core never writes them to disk (deployment's half). */
     files?: Array<{
         path: string;
         content: string;
     }>;
 }
+/** [c209-C] The metadata slice of a skill the LISTING faces consume (disclosure block + the
+ *  skills_listing turn attachment): name, description, attachment paths — never the body. The
+ *  Prepared seam projects `SkillSpec`s down to this shape so the run loop's announce lane holds no
+ *  skill content. `SkillLike` is structurally assignable (its `files` entries simply carry an extra
+ *  `content` the listing renderers never read). */
 export interface SkillListingEntry {
     name: string;
     description: string;
     files?: Array<{
         path: string;
     }>;
+    /** RB-316 — the skill's rank in the DEPLOYMENT'S DECLARATION order (`TaskSpec.skills`, first-wins
+     *  dedupe applied, 0 = declared first). Lower = higher priority. Used ONLY to decide which skills keep
+     *  their descriptions when the block overflows its byte budget ({@link buildSkillsBlock} tier B); the
+     *  DISPLAY order stays name-sorted, so adding this never moves a line.
+     *
+     *  Why declaration order: CC 220's `sbs` (@317547) takes a priority function and is called with
+     *  `uNt(name)` (@608552 → @402383) = usage count decayed by recency of last use, and additionally
+     *  pins every `bundled` skill's description unconditionally. Core has NEITHER axis — no cross-session
+     *  skill-usage store, and no bundled/user distinction (every skill arrives through the same
+     *  caller-supplied `TaskSpec.skills`). Declaration order is the one priority statement the deployment
+     *  can actually make here, and it is the same statement 220's bundled-pin encodes ("these matter most,
+     *  keep their descriptions"). Absent ⇒ the entry's array index is used, i.e. the pre-RB-316 behavior. */
     declaredRank?: number;
 }
+/** Dedupe by name (first occurrence wins) and sort by name — one deterministic list shared by the
+ *  disclosure block and the tool, so what the prompt promises is exactly what the tool serves. */
 export declare function normalizeSkills(skills: SkillLike[] | undefined): SkillLike[];
+/** [c209-C] The skills listing's lead line — single-sourced so the run loop's durable-resume
+ *  transcript probe (MED-3② skills arm, runtask) matches EXACTLY what the initial frame carries
+ *  (probing the bare `<skills>` fence would be more collision-prone in model-quoted text). */
 export declare const SKILLS_LISTING_PROBE_HEADER = "The following skills are available for this task.";
+/** [c209-C] One skill's disclosure line — `- name: description[(files 尾缀)]` with the per-skill
+ *  description cap. Single-sourced so the skills_listing DELTA frame (turn-attachments) renders adds
+ *  with byte-identical line shape to the initial `<skills>` block. */
 export declare function skillListingLine(s: SkillListingEntry): string;
+/** Render the `<skills>` disclosure block (metadata only — bodies stay behind the tool).
+ *  [c209-C] REVERSAL: no longer composed into the stable system prompt — this is now the RENDERER for
+ *  the `skills_listing` initial frame (first-user-turn reminder / boundary re-announce), so the
+ *  cached prefix carries zero skill bytes (design/C §2.3; CC 209 classic ships the same listing as a
+ *  first-turn reminder; Q6: 8KB cap ≈ CC's observed 5.9KB listing).
+ *
+ *  [c209-C] R2 C4① — the cap is BYTE-EXACT over the whole rendered block (see
+ *  {@link SKILLS_BLOCK_MAX_BYTES}): three honesty tiers, each chosen with the LATER tiers' fixed
+ *  overhead (cap marker / name-only tail / overflow count line) already reserved so the final
+ *  render can never blow the budget it was sized against —
+ *    A. everything fits → every skill gets its full `- name: description` line (byte-identical to
+ *       the pre-C4 render for every block that was legal under the old cap);
+ *    B. RB-316 (CC 220 `sbs` @317547-317586) — reserve the cap marker + EVERY skill's name-only line
+ *       first, then spend the remaining slack on descriptions in PRIORITY order
+ *       ({@link SkillListingEntry.declaredRank}), admitting each description whose incremental cost
+ *       still fits and skipping (not stopping at) the ones that do not. Every skill stays listed;
+ *       the ones that lose their description are the low-priority ones, not the alphabetically late
+ *       ones. This replaces the pre-RB-316 "longest full-line PREFIX" cut, which had two defects the
+ *       anchor does not: the surviving set was decided by name sort order (a skill named `zip-deploy`
+ *       lost its description to `aardvark-lint` for no reason connected to either skill), and one
+ *       oversized description truncated the block at itself instead of being skipped over;
+ *    C. even all-name-only overflows (pathological name census) → list what fits and close with an
+ *       honest `(… +N more skills …)` count line — the tool still serves all of them. */
 export declare function buildSkillsBlock(skills: ReadonlyArray<SkillListingEntry>): string | undefined;
+/**
+ * The injected `skill` tool: returns a skill's full body as a tool result.
+ *
+ * When a {@link ActiveSkillScope} is supplied (design/77 §3 Gate-3) and the loaded skill carries a
+ * `manifest`, a successful load PUSHES a scope frame onto the per-task LIFO stack, so the rest of the
+ * invocation is deny-narrowed to the manifest's tools/paths. Nested loads (a skill whose body loads
+ * another skill) STACK and compose MONOTONICALLY as the INTERSECTION of every active frame's
+ * `allowTools` — a child can only narrow further, never re-grant. Frames are popped at task end (and
+ * the test/lifecycle may pop explicitly via `scope.pop()` to model a skill frame closing). Skills with
+ * NO manifest push nothing (unscoped, backward-compatible).
+ *
+ * v1 lifetime is heuristic (design/77 §3 residual): the model controls its own turns, so push-on-load
+ * is the trigger and the worst case (a frame never popped) is simply continued narrowing — never a
+ * widening, so it stays safe-by-construction.
+ */
 export declare function createSkillTool(skills: SkillLike[], scope?: ActiveSkillScope): AgentTool;
 export {};

package/dist/core/runner/teardown-bounded.d.ts

@@ -1,7 +1,41 @@
+/**
+ * RB-470 (blackboard [2310], the D4 never-settle class) — bounded await for BEST-EFFORT teardown /
+ * cleanup legs on a run's settle path.
+ *
+ * The defect class: `resume()`/`runTask` settle only when the run body returns, and the body's tail
+ * (after the event queue closed) plus the prepare-throw cleanup path both awaited external entities
+ * (adapter `destroy()`, MCP client close, registry rows minted by EARLIER runs, session-store
+ * `forget`) with no bound. Every one of those sites already caught THROWS ("best-effort … must not
+ * mask the original error") — but a promise that never settles is not a throw, and one wedged
+ * adapter turned into: for-await done, `result()` never settles (②型, process alive), or — when the
+ * wedge happened before the queue closed — a zero-handle pure-logic hang (the 2.12.0 exit-13 shape).
+ * The session lock releases in the run IIFE's finally, so one wedged run also poisoned every later
+ * same-session resume.
+ *
+ * The remedy is the same doctrine as the workflow journal drain (batch-4 F2): a best-effort leg gets
+ * a BOUNDED terminal await — generous, disclosed on timeout, never silent (§C1), and the settle path
+ * proceeds. The abandoned leg keeps running (nothing can cancel a wedged promise); the incident
+ * report says exactly that, so a leaked env/process is attributable instead of anonymous.
+ *
+ * Timer discipline (RB-447, with-retry.ts same doctrine): the race timer is deliberately NOT
+ * unref'd — the caller awaits this in FOREGROUND control flow, and an unref'd timer lets an
+ * otherwise-empty event loop exit mid-wait, which un-settles the very await this module exists to
+ * bound. The timer is itself bounded, and cleared the moment the leg settles.
+ */
+/** Generous ceiling for one teardown leg — cleanup that has not settled after this long is wedged,
+ *  not slow (the legs are process kills, fd closes, store forgets; none is legitimately minutes). */
 export declare const TEARDOWN_LEG_MAX_MS = 15000;
+/** Test hook (fs-atomic TxnLockTimings precedent): shrink the budget so wedge pins need no real 15s. */
 export declare function setTeardownLegBudgetForTests(ms: number | undefined): void;
+/** The typed timeout incident — `leg` names the site so a leak is attributable from the report alone. */
 export declare class TeardownLegTimeoutError extends Error {
     readonly leg: string;
     constructor(leg: string, budgetMs: number);
 }
+/**
+ * Run one best-effort teardown leg with the bound above. NEVER throws: a throw OR a timeout is
+ * routed to `report` (wire it to `deps.onError` where available) and the caller proceeds —
+ * exactly the contract every wrapped site already claimed in prose, now including the never-settle
+ * arm it could not previously keep.
+ */
 export declare function settleTeardownLeg(leg: () => Promise<unknown> | unknown, label: string, report?: (err: Error) => void): Promise<void>;

package/dist/core/runner/tool-disclosure.d.ts

@@ -3,61 +3,288 @@ import type { AgentMessage, AgentTool, AgentToolResult, AgentToolUpdateCallback,
 import type { Model } from "../../internal/llm.js";
 import type { ToolSpec } from "../types.js";
 import type { ToolFingerprintInput } from "../cache-break-detector.js";
+/**
+ * Deferred-tool dynamic disclosure (design/36). A deployment with hundreds of tools / several MCP
+ * servers can't inline every full JSON Schema into every request — turn-1 cache-creation tokens
+ * explode and any tool-description drift breaks the prefix cache. Instead, deferred tools ship as
+ * lightweight placeholders ({name, one-line hint, empty params}); a resident `tool_search` lets the
+ * model activate them by name or keyword, at which point core MATERIALIZES their full schema into the
+ * next request's tools[] (client-side, provider-agnostic — no Anthropic `tool_reference` beta) and
+ * announces them via the search's own result content (tail of the log; the cache prefix is untouched).
+ *
+ * This module is pure tool/registry logic: prepare-task owns the harness wiring and supplies a
+ * `rematerialize` callback (which calls `harness.setTools` + refreshes the design/31 fingerprint).
+ */
 export declare const TOOL_SEARCH_NAME = "ToolSearch";
+/** Default keyword-search result cap (design/116 W1-2 = CC ToolSearchTool.ts:28-32 `max_results` default 5). */
 export declare const TOOL_SEARCH_DEFAULT_MAX_RESULTS = 5;
+/**
+ * design/168 — how many times in a row ONE placeholder may answer the IDENTICAL invalid-arguments
+ * shape before the lane declares the loop unproductive and stops re-teaching. Three, because the
+ * corrective round is worth paying for twice (the first rejection hands over the schema; a second
+ * covers a model that needed the restatement) and a third identical failure is evidence that the
+ * schema was never what was missing.
+ */
 export declare const DEFERRED_NO_PROGRESS_LIMIT = 3;
+/**
+ * The stable machine code the no-progress terminal carries on its tool-result `details.noProgress`
+ * (and verbatim in its model-facing text, so a transcript reader and a log reader see one string).
+ * Names the CONDITION, not the blame: the caller and the tool's declaration cannot be reconciled on
+ * this route — the classic producer is a constrained decoder bound to the placeholder's empty
+ * advertised schema.
+ */
 export declare const DEFERRED_SCHEMA_INCOMPATIBLE_CODE = "tool.deferred_schema_incompatible";
+/** A deferred tool as the search ranks it: stable name + the one-line hint + full description for scoring. */
 export interface DeferredToolInfo {
     name: string;
     hint: string;
     description: string;
 }
+/** First line of a description, trimmed to a single short hint for a placeholder / announcement. */
 export declare function deferHint(description: string, max?: number): string;
+/**
+ * Neutralize a tool name before it appears in ANY model-facing text (design/36 minor #5). A tool name is
+ * externally influenced — an untrusted MCP server can return one containing newlines (to inject a fake
+ * `<system-reminder>`/instruction line), backticks/quotes (to corrupt the JSON or markdown the model is
+ * told to emit), or angle brackets (to break a delimiter). Strip control chars, CR/LF, `` ` ``, `"`, `<`, `>`.
+ * For a normal name (`[A-Za-z0-9_.-]`, incl. MCP `server__tool`) this is a no-op.
+ *
+ * MUST wrap a tool name at EVERY site where it reaches the model — placeholder text, the search tool's
+ * announcement, anywhere. A bare interpolation is a prompt-injection hole (council BUG, design/36).
+ */
 export declare function safeName(name: string): string;
+/**
+ * Decide which tool names are deferred. THIS CONTRACT IS THE SINGLE AUTHORITY on the default-mode
+ * source list (TaskSpec/RunnerDeps JSDoc points here), so every arm the body implements is named:
+ * deterministic by default = explicit `ToolSpec.defer === true`, plus every REMOTE-PROTOCOL tool name
+ * (MCP servers AND A2A peers — most numerous / most drift-prone), plus `deferNames`, i.e. the
+ * already-mounted wire names from `TaskSpec.deferTools` and from BUILT-INS that declare their own
+ * `defer` (a built-in ToolSpec never reaches `specs`, so its declared deferral has to arrive here as a
+ * mounted name — this is why the shared-memory pair defaults to deferred). With `deferMode: "auto"`, ADDITIONALLY
+ * defer the remaining user tools when their combined inlined schema would exceed ~10% of the model's
+ * context window — an explicit opt-in (council minor #6), because an implicit threshold makes the same
+ * TaskSpec yield different tools[] across models/contexts. Explicit `defer` always wins — except
+ * against an alwaysLoad pin (RB-400-a), which exempts a name from every deferral source.
+ */
 export declare function classifyDeferred(opts: {
     specs: ReadonlyArray<ToolSpec>;
+    /** Every namespaced tool a remote protocol materialized for this task (MCP servers AND A2A peers —
+     *  the caller unions them). The constant-defer arm is about the SHAPE of a remote roster (many tools,
+     *  schemas the deployment does not control, drift between tasks), which is the same for every protocol
+     *  in the table: naming one protocol here left the next one inlined by omission, with nobody deciding
+     *  that. Only an alwaysLoad pin exempts a name. */
     protocolToolNames: ReadonlyArray<string>;
     fullTools: ReadonlyArray<ToolFingerprintInput>;
     deferMode?: "auto";
     model: Model;
+    /** [1044]② TaskSpec.deferTools — defer ALREADY-MOUNTED tools by wire name (built-ins included;
+     *  `ToolSpec.defer` only reaches caller specs). Caller pre-filters to mounted names. */
     deferNames?: ReadonlyArray<string>;
+    /** RB-400-a — inline-pin names (`TaskSpec.alwaysLoadTools` + the MCP tools whose server declared
+     *  `_meta["anthropic/alwaysLoad"]`, caller-collected; A2A has no such per-skill declaration, so the
+     *  task-level list is a peer's only inline-keep channel): exempt from EVERY deferral source below.
+     *  `ToolSpec.alwaysLoad` rides the specs directly and needs no entry here. */
     alwaysLoadNames?: ReadonlyArray<string>;
 }): Set<string>;
+/** Build the registry the search ranks over (deferred tools only — non-deferred are already visible). */
 export declare function buildDeferredRegistry(deferred: ReadonlySet<string>, tools: ReadonlyArray<{
     name: string;
     description: string;
 }>): Map<string, DeferredToolInfo>;
+/**
+ * RB-403 — the direct-call lane a placeholder may carry. The upstream defer gate is SHAPE
+ * validation, not activation state: a call whose arguments validate against the REAL tool's
+ * declared schema runs the real tool directly (activation is only about whether the model has
+ * been SHOWN the schema, never an execution gate). Governance cannot be laundered through this
+ * lane: policy/effect/irreversibility gates key on the tool NAME maps built from the real
+ * declarations, and the engine's approval pipeline runs before any execute — the placeholder
+ * object on the harness list plays no part in adjudication.
+ */
 export interface PlaceholderDirectCall {
+    /**
+     * RB-414 — resolve the real tool AT CALL TIME, never from a prepare-time snapshot. The mounted
+     * roster is a LIVE array: an MCP refresh splices a server's name domain out and pushes freshly
+     * materialized tool objects back in, so a Map captured when the placeholder was built would hand
+     * this lane the WITHDRAWN object (stale schema shape gate, stale transport client) long after the
+     * roster moved on. Returns `undefined` when the name no longer resolves — a withdrawn name has no
+     * direct lane, and the caller falls back to the teaching rejection.
+     */
     resolveReal: () => PlaceholderDirectTarget | undefined;
+    /**
+     * RB-415① — the scheduling declaration this placeholder carries while it stands in for the real
+     * tool. Mirrors the REAL tool's own `executionMode` (see the mirror rationale in
+     * {@link createPlaceholderTool}); absent ⇒ the engine's fail-closed default, exactly as it would
+     * be for the real tool once activated.
+     */
     executionMode?: ToolExecutionMode;
+    /**
+     * design/168 — does THIS name sit on the static face right now, i.e. will it never be swapped for
+     * the real tool's declaration? The lane's model-facing rejection text reads it to say where the
+     * schema it hands back actually lives (this result only, versus this result AND every later
+     * request's tools block). Absent ⇒ the swap posture.
+     *
+     * A FUNCTION, evaluated per call, for the same reason `resolveReal` is (RB-414): the answer is not
+     * a prepare-time constant. The run-wide strategy is, but the per-tool exemption on top of it reads
+     * the LIVE roster — an MCP refresh can replace a tool with a declaration that no longer fits the
+     * result-text carrier (or one that now does), and a boolean captured when the placeholder was built
+     * would then describe the wrong carrier.
+     */
     staticFace?: () => boolean;
+    /**
+     * Activation side effects (active-set add + rematerialize + boundary delta announcement).
+     * Idempotent; awaited BEFORE the invoke so the next boundary already shows the full schema.
+     * RB-415② — MUST be atomic: a thrown rematerialize has to leave the active set as it found it.
+     *
+     * RB-431 — returns the announcement text this activation has to CARRY, or `undefined` when it has
+     * none (already active, or nothing rides on this name). The ToolSearch lane announces on its own
+     * result content; a direct call makes no ToolSearch call at all, so a face whose only carrier is
+     * that result — today the agent-type roster of a deferred delegation tool — had no way to reach
+     * the model on this leg. The text is appended to THIS call's result (see
+     * {@link createPlaceholderTool}), the same channel discipline: tail of the log, cache prefix
+     * untouched, emitted only after the rematerialize succeeded.
+     */
     activate: () => Promise<string | undefined>;
 }
+/** The live view of the real tool behind a placeholder, resolved per call (see {@link PlaceholderDirectCall.resolveReal}). */
 export interface PlaceholderDirectTarget {
+    /** The REAL tool's declared parameter schema — the shape gate for a direct call. */
     parameters: TSchema;
+    /** Invoke the real tool; the result passes through VERBATIM (structured details intact).
+     *  RB-416 — `onUpdate` is part of the contract: the engine hands every execute a progress sink,
+     *  and dropping it here silently mutes streaming progress (MCP `notifications/progress`) for any
+     *  tool reached through this lane, while the SAME tool streams normally once activated. */
     invoke: (toolCallId: string, params: unknown, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<unknown>) => Promise<AgentToolResult<unknown>>;
 }
+/**
+ * design/168 — can the STATIC face carry this declaration at all? Static's only in-context schema
+ * carrier is result TEXT, so a declaration that cannot be serialized, or that the model-facing error
+ * bound would truncate into non-JSON, has no carrier there. Such a tool is exempted per-tool from the
+ * static face (it materializes into the tools block on activation, the swap way) rather than being
+ * announced as callable with a schema the model never actually receives. `undefined` (a name the live
+ * roster no longer resolves) is not renderable either.
+ */
 export declare function staticSchemaRenderable(schema: TSchema | undefined): boolean;
+/** A placeholder AgentTool for a deferred tool: visible name + hint, empty params. Without `direct`,
+ *  every call is the teaching rejection; with it, a schema-valid call runs the real tool (RB-403). */
 export declare function createPlaceholderTool(info: DeferredToolInfo, direct?: PlaceholderDirectCall): AgentTool;
+/** Keyword score of a query against a deferred tool: name hits weigh more than description/hint hits. */
 export declare function scoreToolMatch(query: string, info: DeferredToolInfo): number;
+/** The argument shapes `tool_search` accepts (design/116 W1-2, CC-canonical): `query` (+ optional
+ *  `max_results`). RB-482 #5 (ruled 2026-08-03): the pre-design/116 `select` ARRAY arm is retired —
+ *  durable-replay compat was already sacrificed by the RB-476-A ruling (replay resolution included);
+ *  the CC-canonical `select:A,B,C` string prefix inside `query` is the live selection form. */
 export interface ToolSearchArgs {
     query?: string;
     max_results?: number;
 }
+/**
+ * Resolve a tool_search request to deferred-tool names (design/116 W1-2, CC ToolSearchTool.ts form).
+ * Query forms, checked in order:
+ *   ① `select:A,B,C` prefix (case-insensitive prefix, CC ToolSearchTool.ts:363) — comma-split EXACT
+ *     name activation against the registry's names; misses are reported in `missing` (never silently
+ *     eaten) and the result is NOT truncated by `max_results` (explicit selection gets everything).
+ *   ② bare tool name (case-insensitive equality, CC:199-204) — selects that tool directly; handles
+ *     models sending a name instead of the select: prefix (seen from subagents/post-compaction).
+ *   ③ keyword search — scored matches capped at `max_results` (CC default 5).
+ * RB-482 #5: the pre-design/116 `select` ARRAY arm is retired (see {@link ToolSearchArgs}) — a stale
+ * replayed array argument now resolves like an empty query (nothing matched, honestly).
+ */
 export declare function resolveToolSearchDetailed(args: ToolSearchArgs, registry: ReadonlyMap<string, DeferredToolInfo>): {
     matched: string[];
     missing: string[];
 };
+/** Names-only view of {@link resolveToolSearchDetailed} — the deterministic replay core used by
+ *  {@link extractDiscoveredToolNames} (and kept as the stable exported signature). */
 export declare function resolveToolSearch(args: ToolSearchArgs, registry: ReadonlyMap<string, DeferredToolInfo>): string[];
+/**
+ * Stateless recompute of the activated-tool set from the message log (design/36 §2.3). The in-process
+ * `active` Set is the primary source within one process, but a RESUMED session (new process) starts with
+ * an empty Set — without this, previously-activated tools would revert to placeholders. Two carriers,
+ * both deterministic and both replayed here:
+ *
+ *  ① every prior `tool_search` call's arguments, re-resolved through `resolveToolSearch` — unless that
+ *    call's OWN result carries the error flag (RB-450 S4: a denied/blocked search never reached execute
+ *    and staged nothing; a call with no result at all keeps the historic credit);
+ *  ② RB-431 — a SUCCESSFUL call on a deferred name, which is an activation in its own right: the
+ *    RB-403 direct lane runs `activate()` BEFORE it invokes the real tool, so a result that came back
+ *    without an error flag can only have come from a call that passed the shape gate and activated.
+ *    No new carrier had to be minted for this: the toolCall part and its result are already in the
+ *    transcript. Before this arm, a direct activation left NO trace at all — the next leg reverted the
+ *    tool to a placeholder (losing one turn's schema) and, for the roster-bearing delegation tool, kept
+ *    its listing face deferred so the boundary producer stayed silent as well.
+ *
+ * ② is deliberately keyed on the ERROR FLAG rather than on re-running the shape gate: the error flag is
+ * the only signal that distinguishes "the lane ran" from "the call never reached it". Every non-execution
+ * outcome the engine can produce for a placeholder call — the teaching rejection (a throw), a policy
+ * denial or hook block, an abort, invalid arguments — is flagged as an error, and none of them activated
+ * anything. It is an UNDER-approximation in one direction only: an activation whose real tool then failed
+ * (or threw) is not counted, so that name reverts to a placeholder and the model re-activates on demand —
+ * self-healing, exactly like the design/116 keyword-cap note below, never a widening. The shape-INVALID
+ * direct call (ruled 2026-08-03) activates too and is flagged as an error, so it lands in that same
+ * under-approximated class by construction: within the process the in-memory `active` set carries it, and
+ * a replay that loses it costs the corrected call — which succeeds, and is itself carrier ②. The one way to
+ * forge a positive is a deployment `tool_result` hook that rewrites a rejection's error flag to false,
+ * which is the deployment editing its own transcript.
+ *
+ * design/116 W1-2 note: pre-116 checkpoints whose KEYWORD queries activated up to 25 tools re-derive at
+ * the new default cap (5) — the extra tools revert to placeholders, which is self-healing (the model
+ * re-activates on demand), never a widening. Exact-name and `select:`-prefix activations replay unchanged.
+ *
+ * The retired `{select:[…]}` ARRAY no longer replays: it resolves to nothing here, so those names revert
+ * to placeholders on the same self-healing path. This is the READ half of a deliberate split — the write
+ * lane (`createToolSearchTool.execute`) REFUSES the dead key loudly, because there a message can still
+ * change what the caller does; here it cannot, and erroring would only turn an old transcript into a
+ * resume that cannot start. Recompute is total: no shape of persisted arguments makes it throw.
+ */
 export declare function extractDiscoveredToolNames(messages: ReadonlyArray<AgentMessage>, registry: ReadonlyMap<string, DeferredToolInfo>): string[];
+/**
+ * Build the resident `tool_search` tool. On a search that NEWLY activates deferred tools it (1) adds them
+ * to the monotonic `active` Set, (2) calls `rematerialize` (prepare-task swaps placeholders→full schema
+ * via `harness.setTools` and refreshes the design/31 fingerprint), and (3) returns the "now available"
+ * announcement as its OWN result content — the delta lands at the tail of the log, never in the cache prefix.
+ */
 export declare function createToolSearchTool(opts: {
     registry: ReadonlyMap<string, DeferredToolInfo>;
     active: Set<string>;
     rematerialize: (active: ReadonlySet<string>) => Promise<void>;
+    /** RB-28 terminal fix — listing ride-along on the design/36 channel: when an activation newly
+     *  materializes a listing-bearing tool (the deferred delegation tool whose description points at an
+     *  agent-types listing that the deferred leg's boundary producer never ships), the caller returns
+     *  the listing text here and it rides THIS search's own result content — tail of the log, cache
+     *  prefix untouched, same channel the activation announcement already uses. */
     listingRide?: (newlyActivated: readonly string[]) => string | undefined;
+    /** [1413]②b (TOOLS-PERFECT): the names callable DIRECTLY right now (mounted non-deferred + activated),
+     *  computed at call time (setTools swaps mutate the surface). Lets the miss note tell the model
+     *  "Workflow is already available — call it" instead of a generic not-found that reads as absence
+     *  (observed: the model treated the miss as unavailability and only recovered by guessing). */
     mountedNames?: () => ReadonlySet<string>;
+    /** DD-5 — whether the placeholders on this task carry the RB-403 direct-call lane
+     *  (`TaskSpec.deferSelfResolve` not disabled). Selects which of the two teaching postures below is
+     *  true for this task; defaults to the direct-lane posture, matching the spec field's own default. */
     directCallEnabled?: boolean;
+    /** RB-450 S3 — run this tool's activation critical section on the CALLER's serializer instead of a
+     *  private one. The `active` set and `rematerialize` are shared with the RB-403 direct-call lane,
+     *  which activates from a placeholder's own execute; both lanes must queue on ONE section or a
+     *  concurrent batch lets the direct lane stage a name while this section is still pending (and
+     *  vice versa, so a rollback here cannot be observed as "already active" there). Absent ⇒ a private
+     *  chain, which still gives the standalone factory its own same-instance guarantee. */
+    /**
+     * Is this deferred name still on the LIVE roster? The registry is a prepare-time snapshot, but the
+     * roster is not: an MCP refresh splices a server's name domain out, and a name that was deferred at
+     * prepare can be gone. Without this test an exact `select:` still resolves through the stale
+     * registry, the activation section adds the name to `active`, the rematerialize "succeeds" while
+     * mounting nothing, and the result announces a tool that does not exist — an uncallable name the
+     * model has been told is now available. Absent ⇒ every registry name is assumed live (the standalone
+     * factory has no roster to consult), which is the prior behavior.
+     */
     isMounted?: (name: string) => boolean;
     serializeActivation?: <T>(section: () => Promise<T>) => Promise<T>;
+    /** design/168 "static" materialization (ruled 2026-08-05): resolve a deferred name's REAL declared
+     *  parameter schema, read from the live roster at call time. Presence switches this face to the
+     *  static posture: activation never swaps the placeholder in the tools block, so the result text
+     *  BELOW is the schema's only in-context carrier — each matched tool's schema is inlined into the
+     *  result (newly-activated AND already-active alike, so a post-compaction re-select recovers it),
+     *  and every "full schemas are loaded" claim about the tools block is dropped as false. Absent ⇒
+     *  the swap posture (activation rewrites the tools block; prior wording, unchanged). */
     staticSchemaFor?: (name: string) => TSchema | undefined;
 }): AgentTool;

package/dist/core/runner/tool-output-projection.d.ts

@@ -1,3 +1,9 @@
+/**
+ * design/157 B15 一期 (R4 相位抽取) — the `tool_end` output/structured projection, verbatim from
+ * `runtask.ts`'s runLocked R4 phase. Pure functions over the harness `AgentToolResult`: zero closure
+ * state, zero runtask coupling — the ONLY module-level input is the size cap below. Event-sequence
+ * snapshot pin (recorded before/after the move, byte-equal) guards the projection semantics.
+ */
 export declare const toolOutputFrom: (result: unknown) => {
     output: unknown;
     truncated: boolean;