@sema-agent/core 5.53.0 → 5.55.0

package/dist/core/mcp.d.ts

@@ -85,6 +85,39 @@ export interface McpDroppedTool {
     tool: string;
     reason: string;
 }
+/**
+ * The completeness verdict of a walked STANDARD MCP list method (`tools/list`, `resources/list` — see
+ * {@link walkMcpListPages}). ABSENT means the walk reached the end of pagination and the aggregated
+ * listing IS the server's full list. PRESENT means it is not, and the listing must not be presented —
+ * or DIFFED — as if it were: an entry missing from a truncated listing is unproven-absent, not
+ * withdrawn (that inference is exactly what made a paginating server's second-page tools read as
+ * `removed`).
+ *  - `page_cap` — {@link MAX_MCP_LIST_PAGES} pages were walked with a cursor still pending;
+ *  - `cursor_loop` — the server handed back a cursor already used in this walk (a paginator that does
+ *    not advance); the walk stops rather than spinning to the cap re-appending the same page;
+ *  - `cursor_invalid` — the server sent a `nextCursor` that is not a string (`null` excepted: that is
+ *    JSON's absent optional). It cannot be followed and it is not proof of the end, so the walk stops
+ *    and says so instead of certifying a short listing as complete;
+ *  - `page_error` — a CONTINUATION page failed. The pages already retrieved are kept and the failure
+ *    text carried. A FIRST-page failure is never this: it still throws (a caller's "no listing at all"
+ *    must not degrade into "an empty listing");
+ *  - `budget_exhausted` — CORE stopped the walk: the time this listing is allowed to spend
+ *    ({@link walkMcpListPages}'s `budgetMs`) had too little left to fund another request
+ *    ({@link MIN_MCP_PAGE_BUDGET_MS}), so none was sent. Distinct from `page_error` on purpose — the
+ *    server neither failed nor was asked. Issuing that request anyway would hand the SDK a
+ *    near-zero timeout, and its -32001 would arrive here wearing the server's failure clothes.
+ * `error` is SERVER-authored text — neutralize it before it rides any model/operator face.
+ */
+export interface McpListingIncomplete {
+    reason: "page_cap" | "cursor_loop" | "cursor_invalid" | "page_error" | "budget_exhausted";
+    /** Pages actually retrieved before the walk stopped (≥ 1 — a zero-page walk throws instead). */
+    pages: number;
+    error?: string;
+    /** The walk's total time budget in ms. Present ONLY on `budget_exhausted`, where it is the whole
+     *  actionable content of the verdict (which bound to raise); every other reason leaves it absent
+     *  rather than reporting a budget that had nothing to do with the stop. */
+    budgetMs?: number;
+}
 /** Tools materialized from one or more MCP servers, plus a disposer to disconnect them. */
 export interface MaterializedMcp {
     tools: AgentTool[];
@@ -125,10 +158,17 @@ export interface MaterializedMcp {
         pendingRemovals: string[];
     };
     /**
-     * One entry per server that failed to connect / list its tools and was SKIPPED (fail-open,
-     * design/29). The task proceeds with the healthy servers' tools — a single bad server (missing
-     * stdio command, unreachable URL) must never brick every task in the scenario. The Runner forwards
-     * these to `onError(phase:"mcp")`. Empty when every server connected.
+     * The OPERATOR warning lane for this materialization (the Runner forwards each entry to
+     * `onError(phase:"mcp")`). Empty when every server connected and listed completely. Two populations,
+     * distinguishable by the `code` each Error carries — a consumer must NOT read mere presence as "this
+     * server was skipped":
+     *  - `mcp.server_unavailable` — a server that failed to connect / list its tools and was SKIPPED
+     *    (fail-open, design/29): the task proceeds with the healthy servers' tools, because a single bad
+     *    server (missing stdio command, unreachable URL) must never brick every task in the scenario;
+     *  - `mcp.listing_incomplete` — a server that DID connect but whose `tools/list` pagination walk did
+     *    not reach the end ({@link McpListingIncomplete}): its tools past the stopping point are not
+     *    mounted this task, which is a capability loss the operator must see rather than infer from a
+     *    short tool list.
      */
     warnings: Error[];
     /**
@@ -186,7 +226,13 @@ export interface MaterializedMcp {
     dispose: () => Promise<void>;
 }
 /** [1605] One per-server entry of {@link MaterializedMcp.refresh}. `added`/`removed` are namespaced
- *  (`mcp__<server>__<tool>`) names; `tools`/`axes`/`dropped` are present only on `"refreshed"`. */
+ *  (`mcp__<server>__<tool>`) names; `tools`/`axes`/`dropped` are present only on `"refreshed"`.
+ *  The model-facing refresh receipt renders each `dropped` entry with ITS OWN `reason` (schema
+ *  gate, same-listing name collision, …) — never a blanket label; a consumer matching that receipt
+ *  text should key on the tool name, not on any fixed reason wording. Note the startup-time
+ *  sibling: two DECLARED servers whose names normalize to one prefix refuse the whole mount at
+ *  connect (`config.mcp_server_name_collision`, both original spellings named) — a deployment
+ *  carrying such a pair learns at the first materialize, with the rename spelled out in the error. */
 export interface McpRefreshResult {
     server: string;
     /** The server's namespaced-name prefix (`mcp__<normalized-server>__`) — the consumer's SPLICE
@@ -199,11 +245,37 @@ export interface McpRefreshResult {
     status: "refreshed" | "not_connected" | "failed" | "revoked";
     toolCount: number;
     added: string[];
+    /**
+     * Names that were mounted before this refresh and are no longer in the roster it returns — i.e. an
+     * assertion that the server withdrew them. It is therefore EMPTY whenever {@link listingIncomplete}
+     * is present, and empty as a FACT rather than a policy: an incomplete walk cannot prove absence, so
+     * it retains what it could not prove gone (see `listingIncomplete`) and nothing leaves. `added` is
+     * unaffected — a name that IS in the partial listing was really listed, whether or not the walk
+     * finished (#381).
+     */
     removed: string[];
     tools?: AgentTool[];
     axes?: McpToolAxis[];
     dropped?: McpDroppedTool[];
+    /**
+     * Set on `not_connected` / `failed` / `revoked`; ALSO set on a `"refreshed"` entry whose listing walk
+     * did not finish (see {@link listingIncomplete}) — a refresh that produced usable tools is not a
+     * failure, so the status stays `refreshed` and the incompleteness rides here.
+     */
     error?: string;
+    /**
+     * #381 — present when this entry's `tools/list` walk did NOT reach the end of pagination. `tools` is
+     * then a MERGE: everything the partial listing did return, plus the previously-mounted entries whose
+     * absence it cannot prove (so the consumer's replace-the-whole-prefix swap withdraws nothing, and
+     * `removed: []` describes a roster that really lost nothing). Absent on a complete walk and on every
+     * non-`refreshed` status.
+     *
+     * RESIDUAL, honest: the model-facing `RefreshMcpTools` receipt renders a refreshed entry's line from
+     * added/removed/excluded/dropped only, so this fact reaches the STRUCTURED face (`details.results`)
+     * and the operator, not the receipt text — rendering it there is a prepare-task change, filed rather
+     * than smuggled in here.
+     */
+    listingIncomplete?: McpListingIncomplete;
 }
 /** design/99 §E9 — projected per-server MCP status (see {@link MaterializedMcp.statuses}). NOTE: `serverInfo`
  *  and `error` are SERVER-controlled strings (verbatim from the remote) — UNTRUSTED; a consumer rendering them
@@ -416,6 +488,30 @@ interface McpContentItem {
     };
 }
 export declare function mapContent(content: Array<McpContentItem>, serverName?: string, imageResizer?: McpImageResizer): Promise<Array<TextContent | ImageContent>>;
+/**
+ * Connect to each MCP server, list its tools, and wrap them as AgentTools.
+ * Tools are namespaced `mcp__<server>__<tool>` (CC parity) to avoid collisions. The model sees each
+ * tool's real JSON-Schema (`inputSchema`), which the agent loop validates natively.
+ *
+ * Fail-open (design/29): a server that fails to connect or list tools is SKIPPED — its error is
+ * returned in `warnings`, the healthy servers still materialize. A single misconfigured server
+ * (bad stdio command, unreachable URL) never bricks the whole task.
+ *
+ * Call `dispose()` when the task finishes — connections are task-scoped, never persisted.
+ */
+/**
+ * Invisible / format / private-use / unassigned characters stripped out of every model-facing string a
+ * server advertises — CC `MZg` :144247. CC spells this as the property class BELOW followed by five
+ * explicit ranges (zero-width U+200B–U+200F, bidi embedding U+202A–U+202E, bidi isolates U+2066–U+2069,
+ * the BOM, and the BMP private-use area); on this engine's Unicode data every one of those code points
+ * is already `Cf` or `Co`, so the class alone is byte-equivalent to CC's expression and the source stays
+ * free of literal invisible characters (a file carrying them is a grep blind spot, and this repo has
+ * paid for that once already). The equivalence is asserted by a pin, not assumed — a Unicode-data change
+ * that moved any of those ranges out of the class would open exactly the hole this strips.
+ *
+ * `\p{Cc}` is deliberately NOT here: newlines and tabs are legitimate description formatting.
+ */
+export declare const MCP_INVISIBLE_TEXT_RE: RegExp;
 /** One tool's schema-normalization outcome (CC 220 `zyo` @336616-336654's return shape). */
 export type McpSchemaNormalizeResult = {
     outcome: "unchanged";
@@ -465,6 +561,28 @@ export declare function normalizeMcpToolSchema(schema: unknown): McpSchemaNormal
  * to catch, and this gate alone does not catch it (no type key ⇒ passes the root-type check; the
  * combinator's own structure is legal JSON Schema ⇒ passes validateJsonSchemaShape too).
  */
+/**
+ * A schema defect the operator must HEAR about but that must not cost the tool its mount — returns a
+ * core-authored sentence, or `undefined` when there is nothing to say.
+ *
+ * Today that is exactly one thing: a TOP-LEVEL parameter name outside `[a-zA-Z0-9_.-]{1,64}`. A name
+ * like `"user name"` is rejected at the Anthropic wire, and because the tool table rides EVERY request
+ * it takes the whole request down with it — while the operator previously got nothing at all pointing
+ * at the cause (no warning, no drop record, just a task that stopped working). CC checks the identical
+ * names against the identical expression (`EX_`/`_xo` :325793/:325824, reported as `check:"propertyKey"`).
+ *
+ * WHY AN ADVISORY AND NOT A DROP, stated because the sibling structural gate above does drop: CC's own
+ * disposition here is keep-and-warn — its drop arm sits behind a rollout flag that ships OFF (`Xyd` /
+ * `Yyd` :354641/:354622, an empty remote-config list ⇒ false), so CC's shipped behavior is to keep the
+ * tool and warn "requests that include it may fail". The difference from the structural half is real
+ * and not a technicality: a schema with no object root is unusable everywhere, whereas this charset is
+ * ONE provider's rule, and this engine is bring-your-own-model. Dropping here would delete a working
+ * tool from a deployment whose provider accepts the name — a Chinese- or Japanese-named parameter is
+ * the ordinary case, not a hostile one. Detection was the gap; removal was never the mandate.
+ *
+ * TOP-LEVEL only, like CC: a nested property name is not what the provider validates.
+ */
+export declare function mcpToolSchemaAdvisory(schema: unknown): string | undefined;
 export declare function mcpToolSchemaProblem(schema: unknown): string | undefined;
 export declare function materializeMcpTools(specs: McpServerSpec[], principal?: string, onElicit?: OnElicit, imageResizer?: McpImageResizer, // design/116 CONFIRM-1 seam: deployment-injected; default = auto-detected sharp
 reminderDisclosure?: {
@@ -490,6 +608,97 @@ export declare function applyCallerAxisOverride(name: string, hint: McpToolAxis
  *  for the discrimination nails; the message is SERVER-authored and is only ever classified here, never
  *  trusted as instructions. */
 export declare function classifyDirReadInvalidParams(message: string): "not_found" | "not_directory";
+/**
+ * The content key {@link walkMcpListPages}'s cursor-loop arm uses to recognize an entry it already
+ * collected: the entry's own JSON, which is what the server sent and what a re-served page repeats
+ * verbatim. `undefined` for anything unserializable — an entry that cannot be keyed is never treated as
+ * a repeat, so the failure direction is "kept, and disclosed by the lane that judges it" rather than
+ * "silently gone".
+ *
+ * NOT a semantic identity: two spellings of the same entry (different key order, a description the
+ * server re-rendered) read as different entries here and both survive. That is the safe direction —
+ * this key only ever authorizes a DELETION, so it must be exact and never clever.
+ *
+ * Exported for the walker's own unit pins (same reason {@link walkMcpListPages} is): its bound is a
+ * behavior, and a pin that re-declared the bound locally would pass while the real one drifted.
+ */
+export declare function listEntryFingerprint(entry: unknown): string | undefined;
+/**
+ * #381 — walk a paginated MCP list method to the END (`{cursor?}` → `{items, nextCursor?}`), bounded.
+ *
+ * Every spec-standard MCP list method is paginated the same way: absence of `nextCursor` means "that
+ * was the last page". A single request therefore returns the WHOLE list only for servers that choose
+ * not to paginate — and a server may start paginating at any time, with no protocol change and no
+ * malice, the moment its list outgrows its own page size. Treating page one as the complete list is
+ * both a capability loss (the rest is never mounted) and, at any call site that DIFFS two listings, an
+ * active falsehood about the server's inventory.
+ *
+ * Contract:
+ *  - page ONE is fetched with the caller's own historic parameters (`cursor === undefined`), so a
+ *    non-paginating server's wire traffic is byte-identical to before;
+ *  - a FIRST-page failure propagates unchanged — every caller's failure shape (skipped server,
+ *    `failed` refresh, per-server attributed aggregate error) is built on that throw;
+ *  - a CONTINUATION failure keeps the pages already retrieved and reports {@link McpListingIncomplete}
+ *    (`page_error`) — fail-open WITH disclosure, the same law {@link readDirViaExtension} follows —
+ *    except an ABORT, which still propagates (a cancelled walk is not a short listing);
+ *  - a repeated cursor stops the walk (`cursor_loop`) instead of spinning to the cap, AND undoes the
+ *    entries that page re-served (a paginator that does not advance is typically one answering with a
+ *    page already collected, and keeping it is how one entry gets listed twice) — judged by
+ *    `identityOf` where the caller can key its entries, whole-page otherwise; an unreadable cursor
+ *    stops the walk as `cursor_invalid` rather than passing for the end of the listing;
+ *  - {@link MAX_MCP_LIST_PAGES} pages with a cursor still pending stops it too (`page_cap`);
+ *  - a remainder too short to fund a real request stops it as `budget_exhausted` — core's own doing,
+ *    named as such (see {@link MIN_MCP_PAGE_BUDGET_MS}).
+ * SIZE, stated rather than assumed: a single page has never been bounded here (a server could always
+ * answer with an arbitrarily long list), and walking multiplies that existing exposure by at most the
+ * page cap — a bounded multiplier, not a new unbounded surface. Per-entry admission stays where it
+ * already is (the intake schema gate, which also drops a name a later page repeats).
+ *
+ * TIME, the reason `budgetMs` exists (codex review, confirmed): the page cap bounds REQUESTS, not
+ * latency. Giving every page its own full request timeout would let a server that stalls each page hold
+ * a connect (or a refresh) for up to twenty timeouts — twenty minutes at the SDK's 60s default, where
+ * an unpaginated listing cost one. So the WALK gets the budget a single listing used to have: page one
+ * is issued with the full amount (byte-identical to the pre-walk request) and each continuation gets
+ * only what is left. ACCEPTED COST, stated: a genuinely slow server whose pages together outlast that
+ * bound is truncated where a single-request listing would not have been — but that truncation is
+ * DISCLOSED, while the alternative is an undisclosed twenty-fold latency ceiling on the task's startup
+ * path. The bound is the caller's own configured request timeout, not a new knob, so a deployment that
+ * needs more already has the dial. `fetchPage` receives the remaining budget and MUST spend it as that
+ * request's timeout — the deadline is cooperative, since only the caller can pass a timeout to its own
+ * transport — and must REPORT that same number if the request then times out: a page cut off at 3ms
+ * whose failure text names the whole listing budget describes a wait that never happened.
+ *
+ * NOT merged with {@link readDirViaExtension}, which walks the same way but owns CC-anchored
+ * first-page `InvalidParams` discrimination (not-a-directory vs not-found) and its own three-state
+ * flags; folding it in here would put that CC semantics into the standard-method path where it has no
+ * meaning.
+ *
+ * Exported for the walker's own unit pins — its arms are failure/deadline states that no fixture server
+ * can drive deterministically. Every production consumer goes through the three call sites in this file.
+ */
+export declare function walkMcpListPages<T>(fetchPage: (cursor: string | undefined, remainingMs: number) => Promise<{
+    items: T[];
+    nextCursor?: string;
+    cursorInvalid?: boolean;
+}>, opts: {
+    budgetMs: number;
+    onPage?: () => void;
+    signal?: AbortSignal;
+    /** A key for one entry's CONTENT — equal keys mean the same listing entry, served again.
+     *  `undefined` for an entry the caller cannot key. Used ONLY by the cursor-loop arm, to tell a
+     *  re-served page from a page that merely arrived with a broken cursor; absent ⇒ that arm cannot
+     *  tell them apart and falls back to dropping the whole page (see it for the trade).
+     *
+     *  CONTENT, not name: an entry's name is what the CALLERS' admission gates key on, and they judge
+     *  each entry on its own (a tool whose schema they refuse is dropped, and a later entry of the same
+     *  name is then free to mount). Keying this on the name would let this walk delete the second
+     *  entry before any of that ran — the only admissible definition of a tool, removed on the theory
+     *  that a name cannot appear twice, which is a rule the layer below owns and applies differently. */
+    fingerprintOf?: (item: T) => string | undefined;
+}): Promise<{
+    items: T[];
+    incomplete?: McpListingIncomplete;
+}>;
 /**
  * RB-408 G12 — `tools/call` result parse that accepts the MCP `2026-07-28` widening of
  * `structuredContent` from "a JSON object" to ANY JSON value (the same revision that relaxes