@sema-agent/core 7.15.0 → 7.16.0

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

@@ -1,7 +1,7 @@
 import { type TSchema } from "typebox";
 import type { AgentMessage, AgentTool, AgentToolResult, AgentToolUpdateCallback, ToolExecutionMode } from "../../internal/harness-types.js";
 /**
- * Deferred-tool dynamic disclosure (design/36). A deployment with hundreds of tools / several MCP
+ * Deferred-tool dynamic disclosure. 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
@@ -10,13 +10,13 @@ import type { AgentMessage, AgentTool, AgentToolResult, AgentToolUpdateCallback,
  * 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).
+ * `rematerialize` callback (which calls `harness.setTools` + refreshes the 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). */
+/** Default keyword-search result cap (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
+ * 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
@@ -43,14 +43,14 @@ export interface DeferredToolInfo {
 /** 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
+ * Neutralize a tool name before it appears in ANY model-facing text. 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).
+ * announcement, anywhere. A bare interpolation is a prompt-injection hole.
  */
 export declare function safeName(name: string): string;
 /** Build the registry the search ranks over (deferred tools only — non-deferred are already visible). */
@@ -60,7 +60,7 @@ export declare function buildDeferredRegistry(deferred: ReadonlySet<string>, too
     aliases?: readonly string[];
 }>): Map<string, DeferredToolInfo>;
 /**
- * RB-403 — the direct-call lane a placeholder may carry. The upstream defer gate is SHAPE
+ * 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
@@ -70,7 +70,7 @@ export declare function buildDeferredRegistry(deferred: ReadonlySet<string>, too
  */
 export interface PlaceholderDirectCall {
     /**
-     * RB-414 — resolve the real tool AT CALL TIME, never from a prepare-time snapshot. The mounted
+     * 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
@@ -79,19 +79,19 @@ export interface PlaceholderDirectCall {
      */
     resolveReal: () => PlaceholderDirectTarget | undefined;
     /**
-     * RB-415① — the scheduling declaration this placeholder carries while it stands in for the real
+     * 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
+     * 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 FUNCTION, evaluated per call, for the same reason `resolveReal` is: 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
@@ -101,9 +101,9 @@ export interface PlaceholderDirectCall {
     /**
      * 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.
+     * 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
+     * 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
@@ -118,13 +118,13 @@ 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,
+     *  `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
+ * 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
@@ -133,20 +133,20 @@ export interface PlaceholderDirectTarget {
  */
 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). */
+ *  every call is the teaching rejection; with it, a schema-valid call runs the real tool. */
 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 argument shapes `tool_search` accepts (CC-canonical): `query` (+ optional
+ *  `max_results`). The pre-keyword-search `select` ARRAY arm is retired —
+ *  durable-replay compat was already sacrificed by a prior 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).
+ * Resolve a tool_search request to deferred-tool names (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
@@ -154,7 +154,7 @@ export interface ToolSearchArgs {
  *   ② 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
+ * The pre-keyword-search `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>): {
@@ -165,16 +165,16 @@ export declare function resolveToolSearchDetailed(args: ToolSearchArgs, registry
  *  {@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
+ * Stateless recompute of the activated-tool set from the message log. 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
+ *    call's OWN result carries the error flag (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
+ *  ② A SUCCESSFUL call on a deferred name, which is an activation in its own right: the
+ *    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
@@ -187,14 +187,14 @@ export declare function resolveToolSearch(args: ToolSearchArgs, registry: Readon
  * 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
+ * self-healing, exactly like the 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
  * self-declare 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
+ * 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.
  *
@@ -208,14 +208,14 @@ export declare function extractDiscoveredToolNames(messages: ReadonlyArray<Agent
 /**
  * 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"
+ * via `harness.setTools` and refreshes the 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
+    /** Listing ride-along on the deferred-tool 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
@@ -226,12 +226,12 @@ export declare function createToolSearchTool(opts: {
      *  "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
+    /** Whether the placeholders on this task carry the 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,
+    /** 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 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
@@ -247,7 +247,7 @@ export declare function createToolSearchTool(opts: {
      */
     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
+    /** 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

package/dist/core/runner/tool-end-body.d.ts

@@ -17,13 +17,13 @@ import { type McpDelivered } from "../mcp-failure.js";
 import type { RecoveredOrphan } from "../session-reconcile.js";
 import { type StructuredProjector } from "./tool-output-projection.js";
 import type { WriteFamily } from "./turn-attachments.js";
-/** design/134 §3.1b — derive the thin `response` digest from a harness tool result: model-facing text
+/** Derive the thin `response` digest from a harness tool result: model-facing text
  *  content only (never `details` — the H4 thin-projection discipline), capped with a truncation note. */
 export declare function batchResponseDigest(result: unknown): string | undefined;
 /** The `tool_end` body fields projected from a harness tool result — output/truncated/totalChars via
  *  {@link toolOutputFrom} and the CC card via the LEG's projector (`Prepared.structuredProjector`: the engine card set
  *  ∪ the caller rows' declared `renderHints.resultCards`, an undeclared type dropped and announced once per leg —
- *  design/388 L4; handed in because the once-per-leg state lives on the leg). Single construction point for BOTH
+ *  handed in because the once-per-leg state lives on the leg. Single construction point for BOTH
  *  the live loop's frames and the resumed batch's frames (`resolvePendingCall` + the deferred-sibling
  *  close): the resumed frames used to carry only `isError`, so a client rendering tool output from frames
  *  showed an empty body for every durable-approved call. Same projection = same source as the transcript.
@@ -72,7 +72,7 @@ export declare function reconciledToolEndBody(orphan: Pick<RecoveredOrphan, "tex
 /** task #51 F2/F3 — the CANONICAL write-tool → reminder-window mapping (CC qFm :480253-480254
  *  `a.name === bD || a.name === hF` = TaskCreate/TaskUpdate; BFm :480217-480219 = TodoWrite). Live
  *  deployment-alias resolution happens at the call sites (run-local `writeFamilyOf` over the mounted
- *  roster); retired-name normalization is gone (RB-476-A, 5.0.0). */
+ *  roster); retired-name normalization is gone. */
 export declare function writeFamilyOfCanonical(name: string): WriteFamily | undefined;
 /** A `toolResult` transcript message (text content). Used by the resume engine to close pending calls. */
 export declare function toolResultMsg(toolCallId: string, toolName: string, text: string, isError: boolean): AgentMessage;

package/dist/core/runner/tool-face-overlay.d.ts

@@ -1,5 +1,5 @@
 /**
- * design/388 §1.1 / §2.7 — the MCP `toolFaces` OVERLAY: a deployment's per-tool face declaration for a
+ * The MCP `toolFaces` OVERLAY: a deployment's per-tool face declaration for a
  * protocol tool that has no `ToolSpec` of its own (`McpServerSpec.toolFaces`, keyed by the server's RAW
  * tool name like `allowTools` / `toolAxes`). Validated against the MATERIALIZED schema at every listing
  * (the first mount and every RefreshMcpTools): `pathTarget.param` must be a top-level property; an
@@ -16,7 +16,7 @@ import type { AgentTool } from "../../internal/harness-types.js";
 import type { McpServerSpec } from "../mcp-server-spec.js";
 import { type ToolApprovalCard } from "../tool-face.js";
 import { type EngineNotice } from "../engine-notice.js";
-/** The keys each specialised approval card needs on the call (design/388 §2.5 boundary ①: the SHELL owns the
+/** The keys each specialised approval card needs on the call (the SHELL owns the
  *  card's full schema; this is the pre-filter the overlay is validated against). */
 export declare const APPROVAL_CARD_REQUIRED_KEYS: Readonly<Record<ToolApprovalCard, readonly string[]>>;
 export type McpToolFace = NonNullable<McpServerSpec["toolFaces"]>[string];

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

@@ -1,5 +1,5 @@
 /**
- * design/157 B15 一期 (R4 相位抽取) — the `tool_end` output/structured projection, verbatim from
+ * 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.
@@ -14,7 +14,7 @@ export declare const toolOutputFrom: (result: unknown) => {
  *  as a parameter — there is no module-level card set to fall back to. */
 export type StructuredProjector = (result: unknown) => unknown;
 /**
- * L4's run-time half (design/388 §2.4): a per-leg projector — the engine card set plus the leg's declared
+ * L4's run-time half: a per-leg projector — the engine card set plus the leg's declared
  * caller cards — that DROPS an undeclared `details.type` and announces it ONCE per leg
  * (`config.tool_card_undeclared`, audience operator). With no options it is the engine set alone, unannounced —
  * the shape a caller outside a leg (a test, a fixture) uses.