@sema-agent/core 7.54.1 → 7.55.0

package/dist/core/mcp-failure.js

@@ -142,20 +142,28 @@ export const FAILURE_CLASSIFIER = [
     },
 ];
 export function classifyMcpFailure(err, at) {
-    for (const rule of FAILURE_CLASSIFIER) {
-        if (!rule.when(err, at))
-            continue;
-        const read = rule.reads(err);
-        const dialled = at.phase === "connect" && !CONNECT_KEEPS_THE_TABLE_VERDICT.has(read.kind);
-        return { ...read, delivered: dialled ? "no" : DELIVERED_BY_KIND[read.kind] };
-    }
-    return { kind: "unknown", delivered: "unknown" };
+    const read = classOf(err, at);
+    const dialled = at.phase === "connect" && !CONNECT_KEEPS_THE_TABLE_VERDICT.has(read.kind);
+    return { ...read, delivered: dialled ? "no" : DELIVERED_BY_KIND[read.kind] };
+}
+function classOf(err, at) {
+    for (const rule of FAILURE_CLASSIFIER)
+        if (rule.when(err, at))
+            return rule.reads(err);
+    return { kind: "unknown" };
 }
-export function describeHttpTransportFailure(err) {
-    const f = classifyMcpFailure(err, { phase: "request" });
+function answersLostSession(read, at) {
+    return at.phase === "request" && at.session === true && read.kind === "http_status" && read.httpStatus === 404;
+}
+export function describeHttpTransportFailure(err, at = { phase: "request" }) {
+    const f = classifyMcpFailure(err, at);
     switch (f.kind) {
         case "http_status":
-            return { condition: `its HTTP endpoint answered ${f.httpStatus} instead of an MCP response`, delivered: f.delivered, httpStatus: f.httpStatus };
+            return {
+                condition: sessionGone(err, at) ? LOST_SESSION : `its HTTP endpoint answered ${f.httpStatus} instead of an MCP response`,
+                delivered: f.delivered,
+                httpStatus: f.httpStatus,
+            };
         case "not_mcp_response":
             return { condition: "its HTTP endpoint answered something that is not an MCP response", delivered: f.delivered };
         case "connect_refused": {
@@ -176,3 +184,10 @@ export function describeHttpTransportFailure(err) {
             return undefined;
     }
 }
+export function sessionGone(err, at) {
+    return answersLostSession(classOf(err, at), at);
+}
+export const LOST_SESSION = "the server reported the session the request was sent on gone (its HTTP endpoint answered 404 to the session id it issued)";
+export function namingLostSession(err, at, text) {
+    return sessionGone(err, at) ? `${LOST_SESSION}: ${text}` : text;
+}

package/dist/core/mcp-listing-drift.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The gate a connection's listing records for an entry no listing of THAT connection reached — one it carries from the connection it
+ * replaced, after a walk that stopped early. Such an entry keeps its tool mounted but vouches for nothing: no minted gate equals it, so the
+ * tool is not sent until a listing of this connection reaches it.
+ */
+export declare const UNPROVEN_GATE = "unproven";
+/** The gate of one minted tool: the raw name it is sent under (two raw names can mint one tool name), its axis (the minted name left out), the listing-derived members of the tool object, and its task-support refusal. */
+export declare function mcpToolGate(remoteName: string, axis: {
+    readonly name: string;
+} | undefined, face: object, taskRequired: boolean): string;

package/dist/core/mcp-listing-drift.js

@@ -0,0 +1,6 @@
+import { canonicalize } from "./canonical-json.js";
+export const UNPROVEN_GATE = "unproven";
+export function mcpToolGate(remoteName, axis, face, taskRequired) {
+    const gates = axis === undefined ? null : Object.fromEntries(Object.entries(axis).filter(([key]) => key !== "name"));
+    return canonicalize({ remoteName, axis: gates, face, taskRequired });
+}

package/dist/core/mcp-server-link.d.ts

@@ -0,0 +1,173 @@
+/**
+ * How a tool call finds its server's connection. The connection under a server is not for life: a re-dial replaces it — at the host's
+ * request, or because the server dropped the session a call was sent on (`sessionGone`) — and the tools already mounted keep reaching
+ * the server. One rule decides where a mounted tool may be sent ({@link reach}): only on the server's LIVE connection, and only while the
+ * latest listing taken on that connection — by this leg or by another holder of a pooled one — through this leg's intake, mints the tool
+ * the gate it was mounted with (mcp-listing-drift.ts). The listing is compared, never adopted: the leg's roster stays the leg's own. No connection ⇒ the
+ * server is down; another gate ⇒ the tool is refused before it runs, until a re-dial or refresh re-folds the roster. Neither the connection
+ * a tool was minted around nor whoever opened the re-dial that replaced it enters the answer.
+ *
+ * A call that finds its session gone recovers once ({@link callThroughLink}). The re-dials of a server go one at a time ({@link Flights}):
+ * a host verb that finds one running is refused; a call joins the one running, and starts one only for the connection that lost its
+ * session while that connection is still the live one — a call that lost its session on a connection already replaced is sent on the
+ * replacement, so a late 404 never closes a connection other calls have moved to.
+ */
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { McpExchangeOutcome } from "./mcp-failure.js";
+/** Mutable per-server liveness flag, shared between a server's tool closures and its transport-close hook.
+ *  `pendingElicitations` (RB-199 FO-1 codex review): a live count of in-flight `onElicit` waits on THIS
+ *  server — the idle watchdog ({@link armMcpIdleWatchdog}) reads it before aborting a call (incremented when the wait starts,
+ *  decremented in a `finally`): elicitation is a nested incoming request the
+ *  server sends WHILE the outer callTool stays open (the elicitation handler's own LIVE-ONLY note in mcp.ts:
+ *  "the handler runs WHILE the agent's `callTool` awaits the server, so the connection is held")
+ *  — a human answering a form legitimately produces no progress notifications on the outer call for
+ *  as long as they take, and the HTTP idle default (5min) is well within normal human response time. */
+export interface ServerHealth {
+    dead: boolean;
+    /**
+     * THE liveness writer for this server — one lifecycle-aware function every observation goes through,
+     * so no site can record an outage the engine itself caused. It writes `McpServerStatus.liveness`
+     * on the SAME record the merge stage pushes into `MaterializedMcp.statuses` (never a second copy), and
+     * it is SILENT while the task is tearing down, for the reason `announceClose` is: our own dispose
+     * closes every transport, and stamping "this server died" on the way out is a lie a consumer reading
+     * the statuses afterwards cannot tell from the truth.
+     *
+     * Same slot discipline as `announce.fn`: filled by the merge stage (which is where the lifecycle flag
+     * lives), and DISARMED when this handle is deliberately replaced — a re-dial's own close is not an
+     * outage either, and the in-flight calls it fails belong to a connection we chose to replace.
+     */
+    observe?: (outcome: McpExchangeOutcome) => void;
+    pendingElicitations: number;
+    /** Stamped on EVERY
+     *  elicitation close (finally, unconditional — not just when the count returns to 0). Closes a race
+     *  the count alone cannot: an idle check can land microseconds after the count drops to 0 but before
+     *  the server has had any real chance to reply to the outer call — that check must still treat the
+     *  close as fresh activity, not silence. 0 = never closed. */
+    lastElicitationClosedAt: number;
+}
+/** Identity-tagged abort reason for {@link armMcpIdleWatchdog}'s own `.abort()` calls (independent review
+ *  hardening): attribution reads `signal.reason === IDLE_WATCHDOG_ABORT_REASON`, a single atomic identity
+ *  check, rather than re-reading two separate `.aborted` booleans after the fact and inferring which fired
+ *  first — closes a theoretical (unconfirmed in review) same-tick interleaving window between the idle
+ *  timer's own abort and an unrelated outer-signal abort landing in an already-queued microtask. */
+export declare const IDLE_WATCHDOG_ABORT_REASON: unique symbol;
+/**
+ * RB-199 FO-1 (independent review, "sweep the class"): a reusable idle watchdog shared by EVERY
+ * agent-reachable MCP request that can otherwise hang on nothing but the huge total-ceiling default —
+ * callTool AND the three resource tools (list/read/directory), all of which had only the single
+ * `mcpToolTimeoutMs()` bound before this RB. Elicitation-aware by construction (server-scoped
+ * `health.pendingElicitations`/`lastElicitationClosedAt` — see the ServerHealth docstring): a pending
+ * elicitation on ANY call to this server can legitimately stall the server's single request-processing
+ * turn, so it freezes the clock for every idle watchdog on that server, not just the call that issued it.
+ * `rearm()` is the reset-on-liveness hook — callTool's `onprogress` calls it every notification (the only
+ * MCP method family with a progress channel); a caller with no progress channel (resource calls have
+ * none — `resources/*` carries no `_meta.progressToken`) may still call it once per unit of real
+ * evidence-of-life it does have (e.g. `readDirViaExtension` calls it once per page received).
+ */
+export declare function armMcpIdleWatchdog(health: ServerHealth, idleMs: number, outerSignal: AbortSignal | undefined): {
+    combinedSignal: AbortSignal;
+    idleSignal: AbortSignal;
+    rearm: () => void;
+    dispose: () => void;
+};
+/** One `tools/list` entry as the lenient listing parse keeps it (mcp.ts `LenientListToolsResultSchema`) — every field the intake
+ *  pipeline actually reads (`intakeListedTools`), `inputSchema` UNVALIDATED (see that schema's docstring). */
+export interface LenientListedTool {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+    annotations?: unknown;
+    _meta?: unknown;
+    /** codex review (RB-199 FO-2 follow-up, confirmed HIGH): carried through UNVALIDATED (same posture as
+     *  inputSchema) so `cacheMcpToolMetadata` (mcp.ts) can restore what `client.listTools()` used to do for
+     *  free. Not fed through core's own gate — see that function's docstring for why. */
+    outputSchema?: unknown;
+    execution?: unknown;
+}
+/**
+ * The server's listing as one connection knows it, from whichever of its holders listed last (each leg of a pooled run lists on the
+ * shared connection) — what every holder's mounted tools are checked against, each through its own leg's intake, and what a leg mounts.
+ *
+ * Three rules, all here and nowhere else. Listings answer in the order they were opened: an answer that arrives after a later-opened one
+ * was recorded is superseded and records nothing. A walk that stopped early cannot prove a tool gone: an incomplete answer speaks only for
+ * the names it reached, and every other name keeps its entry from the listing before it (on a new connection, from what the connection it
+ * replaced knew — `carried`). And an entry vouches for a tool's gate only if a listing of THIS connection reached it: one carried across
+ * from the connection this one replaced keeps its tool mounted but stays `unproven` (its tool is not sent) until a listing of this
+ * connection reaches it — a reconnect is exactly when a declaration may have changed. The entries kept are the server's raw ones, not what
+ * an intake accepted, so a tool the walk did reach and the intake then dropped is gone, and every kept entry goes through the intake again.
+ * Accepted cost: an entry this connection listed earlier and a later walk did not reach is still read as it was listed — a tool the server
+ * withdrew or re-declared on an unreached page, with no reconnect between, is read as before until a walk reaches it (as it would be if
+ * nothing had listed again); calling a withdrawn one fails at the server.
+ */
+export declare class ConnectionListing<T extends {
+    readonly name: string;
+}> {
+    private opened;
+    private recorded;
+    private entries;
+    private unprovenNames;
+    /** Open a listing, before its request goes out: its place in the order. */
+    open(): number;
+    /** The answer of the listing opened at `at`, as the server's listing (`view`), with the names it kept from before (`kept`) and the kept names no listing of this connection reached (`unproven`); recorded unless a listing opened after it already answered. */
+    answer(at: number, entries: readonly T[], incomplete: boolean, carried?: readonly T[]): {
+        readonly recorded: boolean;
+        readonly view: readonly T[];
+        readonly kept: ReadonlySet<string>;
+        readonly unproven: ReadonlySet<string>;
+    };
+    latest(): {
+        readonly at: number;
+        readonly entries: readonly T[];
+        readonly unproven: ReadonlySet<string>;
+    };
+}
+/** A server's connection with its health record, as a call dispatches on it. */
+export interface McpLiveConnection {
+    readonly client: Client;
+    readonly health: ServerHealth;
+    /** Minted tool name → the gate the connection's latest listing ({@link ConnectionListing}) mints it, through this leg's intake. */
+    gates(): ReadonlyMap<string, string>;
+}
+export interface McpServerLink {
+    /** The connection the materialization holds for the server now; `undefined` while it holds none (a re-dial's old one is gone and the new one has not landed, or the last dial failed). */
+    live(): McpLiveConnection | undefined;
+    /** Recover the session `lost` lost: join the re-dial running for the server, or start one while `lost` is still the live connection. Settles when there is nothing left to wait for. */
+    recover(lost: McpLiveConnection): Promise<unknown>;
+}
+/** Why a tool may not be sent on a live connection: its listing mints the tool another gate or none (`changed`), or no listing of the connection has reached it (`unreached`). */
+export type McpListingRefusal = "changed" | "unreached";
+/** Where the tool `name` minted with `gate` may be sent now: the live connection, `"gone"` when there is none (or it closed), or why its listing does not vouch for the tool ({@link McpListingRefusal}). */
+export declare function reach(link: McpServerLink, name: string, gate: string): McpLiveConnection | "gone" | McpListingRefusal;
+/** An attempt whose session was found gone: the connection it was sent on, and its failure as it would have been thrown then. */
+export declare class Resendable {
+    readonly on: McpLiveConnection;
+    readonly error: unknown;
+    constructor(on: McpLiveConnection, error: unknown);
+}
+/**
+ * One tool call through the link. `send` makes one attempt on a connection (`resent` on the second) and answers {@link Resendable} for a
+ * lost session. Such a call is recovered once: it waits for the shared re-dial — or for its own `signal`, which ends the call at once —
+ * and is sent again only on a connection that replaced the lost one and where {@link reach} says it may go. A call that is not sent again,
+ * whatever the reason (no replacement, a declined re-dial that left the lost connection in place, a replacement whose listing does not
+ * vouch for the tool, its abort), ends with its first attempt's failure; a second lost session ends with that one. `gone` and an
+ * {@link McpListingRefusal} answer only a call that was never sent.
+ */
+export declare function callThroughLink<R extends object>(link: McpServerLink, name: string, gate: string, signal: AbortSignal | undefined, send: (on: McpLiveConnection, resent: boolean) => Promise<R | Resendable>, gone: () => never): Promise<R | McpListingRefusal>;
+/** The answer to a call {@link reach} refused before it was sent: the pre-send refusal record (`delivered: "no"`; `code` beside `error`, as the revocation refusal's). */
+export declare function listingRefusal(refusal: McpListingRefusal, remoteName: string, server: string): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    details: Record<string, string>;
+    terminate: false;
+    isError: true;
+};
+/** The runs of one kind of work that may only run once at a time per key (a server's re-dial). */
+export declare class Flights<V> {
+    private readonly open;
+    /** The flight running under `key`, or `undefined`. */
+    running(key: string): Promise<V> | undefined;
+    /** Start `run` as the flight of `key`; it leaves the table when it settles. The caller has checked that none is running. */
+    start(key: string, run: () => Promise<V>): Promise<V>;
+}

package/dist/core/mcp-server-link.js

@@ -0,0 +1,127 @@
+import { UNPROVEN_GATE } from "./mcp-listing-drift.js";
+import { inlineUntrusted } from "./untrusted-text.js";
+export const IDLE_WATCHDOG_ABORT_REASON = Symbol("mcp-idle-watchdog-abort");
+export function armMcpIdleWatchdog(health, idleMs, outerSignal) {
+    const idleController = new AbortController();
+    let timer;
+    const rearm = () => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        const armedAt = Date.now();
+        timer = setTimeout(() => {
+            if (health.pendingElicitations > 0 || health.lastElicitationClosedAt > armedAt) {
+                rearm();
+                return;
+            }
+            idleController.abort(IDLE_WATCHDOG_ABORT_REASON);
+        }, idleMs);
+    };
+    rearm();
+    return {
+        combinedSignal: outerSignal !== undefined ? AbortSignal.any([outerSignal, idleController.signal]) : idleController.signal,
+        idleSignal: idleController.signal,
+        rearm,
+        dispose: () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        },
+    };
+}
+export class ConnectionListing {
+    opened = 0;
+    recorded = -1;
+    entries = [];
+    unprovenNames = new Set();
+    open() {
+        return this.opened++;
+    }
+    answer(at, entries, incomplete, carried) {
+        const reached = new Set(entries.map((e) => e.name));
+        const fresh = this.recorded === -1;
+        const before = incomplete ? (fresh ? (carried ?? []) : this.entries).filter((e) => !reached.has(e.name)) : [];
+        const view = before.length > 0 ? [...entries, ...before] : entries;
+        const kept = new Set(before.map((e) => e.name));
+        const unproven = fresh ? kept : new Set([...this.unprovenNames].filter((n) => kept.has(n)));
+        if (at < this.recorded)
+            return { recorded: false, view, kept, unproven };
+        this.recorded = at;
+        this.entries = view;
+        this.unprovenNames = unproven;
+        return { recorded: true, view, kept, unproven };
+    }
+    latest() {
+        return { at: this.recorded, entries: this.entries, unproven: this.unprovenNames };
+    }
+}
+export function reach(link, name, gate) {
+    const live = link.live();
+    if (live === undefined || live.health.dead)
+        return "gone";
+    const listed = live.gates().get(name);
+    if (listed === UNPROVEN_GATE)
+        return "unreached";
+    return listed === gate ? live : "changed";
+}
+export class Resendable {
+    on;
+    error;
+    constructor(on, error) {
+        this.on = on;
+        this.error = error;
+    }
+}
+export async function callThroughLink(link, name, gate, signal, send, gone) {
+    const first = reach(link, name, gate);
+    if (first === "gone")
+        gone();
+    if (typeof first === "string")
+        return first;
+    const res = await send(first, false);
+    if (!(res instanceof Resendable))
+        return res;
+    if (!(await settlesFirst(link.recover(res.on), signal)))
+        throw res.error;
+    const next = reach(link, name, gate);
+    if (typeof next === "string" || next === res.on)
+        throw res.error;
+    const again = await send(next, true);
+    if (again instanceof Resendable)
+        throw again.error;
+    return again;
+}
+export function listingRefusal(refusal, remoteName, server) {
+    const changed = refusal === "changed";
+    const code = changed ? "mcp.tool_declaration_changed" : "mcp.tool_listing_unreached";
+    return {
+        content: [{ type: "text", text: `The call to tool ${inlineUntrusted(remoteName)} was refused before it was sent: MCP server "${inlineUntrusted(server)}" ${changed ? "no longer declares this tool the way it was mounted (its safety declaration changed, or a complete listing no longer lists it)" : "has not listed this tool since it was reconnected (the re-listing stopped before it reached the tool), so whether the server still declares it the way it was mounted is unknown"}. The server did not execute it. Every call to this tool is refused the same way until a listing of the connection reaches the tool, so don't retry it.` }],
+        details: { error: code, code, delivered: "no", server },
+        terminate: false,
+        isError: true,
+    };
+}
+function settlesFirst(work, signal) {
+    const settled = work.then(() => true, () => true);
+    if (signal === undefined)
+        return settled;
+    if (signal.aborted)
+        return Promise.resolve(false);
+    return new Promise((resolve) => {
+        const stop = () => resolve(false);
+        signal.addEventListener("abort", stop, { once: true });
+        void settled.then((v) => {
+            signal.removeEventListener("abort", stop);
+            resolve(v);
+        });
+    });
+}
+export class Flights {
+    open = new Map();
+    running(key) {
+        return this.open.get(key);
+    }
+    start(key, run) {
+        const flight = run().finally(() => this.open.delete(key));
+        this.open.set(key, flight);
+        return flight;
+    }
+}

package/dist/core/mcp-server-spec.d.ts

@@ -1,6 +1,6 @@
 import { type ReceiptFault } from "./mods/kernel/receive.js";
 import type { ToolContentOrigin, ToolEffect } from "./tool-spec.js";
-import type { ToolFamily, ToolPathTarget, ToolRenderHints, ToolRuleFace } from "./tool-face.js";
+import type { ToolFamily, ToolHostTarget, ToolPathTarget, ToolRenderHints, ToolRuleFace } from "./tool-face.js";
 /** Definition of an MCP server to connect to for the duration of one task, then discard. */
 export interface McpServerSpec {
     /** Stable name; tool names are namespaced as `mcp__<server>__<tool>` (the protocol prefix, then this name as the peer segment) to avoid collisions. */
@@ -82,7 +82,8 @@ export interface McpServerSpec {
     /**
      * design/388 §1.1 / §2.7 — the OPTIONAL per-tool FACE overlay for this server's tools (keyed by the server's
      * RAW tool name, like {@link allowTools} / {@link toolAxes}): a deployment lets an MCP tool enter a specialised
-     * approval card, be confirmed by path, carry a display name / summary, or narrow its rule vocabulary. TRUSTED
+     * approval card, be confirmed by path, carry a display name / summary, or narrow its rule vocabulary (a `hostTarget` is
+     * refused here: host rules are written for the engine's fetch tool name only, which no MCP tool answers to). TRUSTED
      * (the deployment writes it). It is read once by `readToolFaces` at the preparation door and at `materializeMcpTools`: a
      * declaration that does not fit on its own (a member the types do not have, a member of the wrong kind, a word outside a
      * closed table, a reserved approval card, an empty tool name) refuses the entry under `config.tool_face_invalid` — the whole
@@ -94,6 +95,7 @@ export interface McpServerSpec {
     toolFaces?: Record<string, {
         family?: ToolFamily;
         pathTarget?: ToolPathTarget;
+        hostTarget?: ToolHostTarget;
         renderHints?: ToolRenderHints;
         ruleFace?: ToolRuleFace;
     }>;

package/dist/core/mcp-session-end.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Ending an MCP HTTP session. A Streamable HTTP connection owns a SESSION on the server, and the transport's own `close()` only aborts
+ * the local fetches — the server keeps the session until it reaps it. The protocol has the client end the session with a DELETE, so
+ * the transport this engine dials with ends its session in its own `close()`: first the DELETE (bounded), then the close. Every way a
+ * connection is let go — a run's end, a re-dial, a dial that failed or was stopped, the pool's last release, the SDK closing a
+ * handshake it rejected — closes the transport, so every way ends the session, with no helper to remember at each site. A stdio
+ * transport has no session; its close is unchanged.
+ *
+ * The session-end request is courtesy, not a condition of closing: a server that refuses it (405 — it keeps its sessions), no longer
+ * knows the session (404), cannot be reached or does not answer within {@link MCP_SESSION_END_WAIT_MS} costs the close that long at most
+ * and nothing else — the close runs regardless and aborts a request still in the air.
+ */
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { McpRequestSite } from "./mcp-failure.js";
+/** The longest a close waits for the server to answer the request that ends its session. */
+export declare const MCP_SESSION_END_WAIT_MS = 2000;
+/** The Streamable HTTP transport this engine dials with: closing it ends the server's session first. */
+export declare class SessionEndingTransport extends StreamableHTTPClientTransport {
+    private closing;
+    /** One close however many ask: a second caller (the SDK closes a transport it rejected, and so does the dial after it) waits for the first's, rather than aborting its DELETE. */
+    close(): Promise<void>;
+    private endSessionThenClose;
+}
+/** Where a request about to be sent on `client` is judged (`sessionGone` in mcp-failure.ts): under the session the server issued, when the connection holds one. Read before the request goes out — what counts is the session it carried. */
+export declare function requestSite(client: Client): McpRequestSite;

package/dist/core/mcp-session-end.js

@@ -0,0 +1,29 @@
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+export const MCP_SESSION_END_WAIT_MS = 2_000;
+export class SessionEndingTransport extends StreamableHTTPClientTransport {
+    closing;
+    close() {
+        this.closing ??= this.endSessionThenClose();
+        return this.closing;
+    }
+    async endSessionThenClose() {
+        if (this.sessionId !== undefined) {
+            let timer;
+            const wait = new Promise((resolve) => {
+                timer = setTimeout(resolve, MCP_SESSION_END_WAIT_MS);
+                timer.unref();
+            });
+            try {
+                await Promise.race([this.terminateSession().catch(() => undefined), wait]);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        await super.close();
+    }
+}
+export function requestSite(client) {
+    const transport = client.transport;
+    return transport instanceof StreamableHTTPClientTransport && transport.sessionId !== undefined ? { phase: "request", session: true } : { phase: "request" };
+}

package/dist/core/mcp-startup-request.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The options of the FIRST TOOL LISTING of an MCP dial: the phase's bound, and the run's abort for as long as the listing is in the air.
+ * The abort is what lets a run that was cancelled stop waiting on a server that never answers it (the bound alone is a minute at the
+ * SDK's default); the dial then fails like any dial that did not finish.
+ *
+ * The listing runs on a connection the pool may share, so the abort cannot hang the transport up — it ends the listing request only. The
+ * SDK's request keeps a listener on the signal it is given for the life of that signal, and an abort that reaches it later sends the
+ * server a `notifications/cancelled` for a request long answered. So the request is given a signal of its own that follows the run's
+ * only while the listing is in flight. (The handshake owns its transport until it lands and stops by closing it — see the dial.)
+ */
+/** What the SDK's request takes of a startup call. */
+export interface StartupRequestOptions {
+    timeout?: number;
+    signal?: AbortSignal;
+}
+/** Run one startup request under `bound` (milliseconds, absent = the SDK's default) and, when given, the run's `abort`. Throws the abort's reason at once when it already fired. */
+export declare function underStartupBound<T>(bound: number | undefined, abort: AbortSignal | undefined, request: (options: StartupRequestOptions | undefined) => Promise<T>): Promise<T>;

package/dist/core/mcp-startup-request.js

@@ -0,0 +1,17 @@
+export async function underStartupBound(bound, abort, request) {
+    if (abort === undefined)
+        return request(bound !== undefined ? { timeout: bound } : undefined);
+    abort.throwIfAborted();
+    const inFlight = new AbortController();
+    const follow = () => inFlight.abort(abort.reason);
+    abort.addEventListener("abort", follow, { once: true });
+    try {
+        return await request({ ...(bound !== undefined ? { timeout: bound } : {}), signal: inFlight.signal });
+    }
+    catch (err) {
+        throw abort.aborted ? abort.reason : err;
+    }
+    finally {
+        abort.removeEventListener("abort", follow);
+    }
+}

package/dist/core/mcp.d.ts

@@ -144,7 +144,7 @@ export interface MaterializedMcp {
      * [cc216] Tools DROPPED at intake because the server advertised a schema no provider accepts
      * ({@link mcpToolSchemaProblem}) — without the drop, one malformed tool schema riding the wire
      * fails the WHOLE model request (provider 400), bricking the task for every healthy tool
-     * (CC 2.1.216 ships the same intake prune, `tengu_mcp_drop_invalid_tool_schemas`).
+     * (the reference ships the same intake prune, `tengu_mcp_drop_invalid_tool_schemas` (cli296.js:218844)).
      *
      * HONEST REACH (pinned in mcp-dropped-tools.test.ts): listings arrive through the lenient reader
      * (`listToolsLenient` — raw request, no SDK-client zod pass), so a string-root or otherwise odd
@@ -177,7 +177,7 @@ export interface MaterializedMcp {
      */
     statuses: McpServerStatus[];
     /**
-     * RefreshMcpTools (CC 2.1.218 parity, anchored to the CLI form) — re-read the tool list of one server (or
+     * `RefreshMcpTools` (cli296.js:157909) — re-read the tool list of one server (or
      * every CONNECTED server when `server` is omitted) over the EXISTING connection. NEVER dials or
      * re-dials: a dead/never-connected server reports `not_connected` (so does one whose connection closed while the walk was reading); a live listTools failure
      * reports `failed` (the connection is left as-is). A refreshed entry carries the NEW intake
@@ -198,7 +198,7 @@ export interface MaterializedMcp {
      * cache seeding cannot drift between a first connect and a re-dial: one function, not one
      * convention.
      *
-     * ONE SERVER, NAMED — CC 2.1.259's control-channel request carries a REQUIRED `serverName` and has
+     * ONE SERVER, NAMED — the reference's control-channel request carries a REQUIRED `serverName` and has
      * no all-servers form, and an all-servers arm would close HEALTHY connections to re-dial them (a
      * stdio server owning a device or a port is exactly the one that cannot be re-dialed while its
      * predecessor still holds the device). CLOSE-THEN-DIAL, so a re-dial that FAILS leaves the server
@@ -370,7 +370,7 @@ export interface McpServerStatus {
     liveness?: McpServerLiveness;
 }
 /**
- * design/108 ① (CC 2.1.187 parity) — the GLOBAL `mcp__` marker prefix. CC names every MCP tool
+ * design/108 ① — the GLOBAL `mcp__` marker prefix. CC names every MCP tool
  * `mcp__<server>__<tool>` so a consumer (permission allowlist, bypass-exempt, the flywheel's whitelist) can
  * identify an MCP-originated tool by prefix ALONE, without knowing the per-deployment server names. Exported so
  * downstream consumers share one source (the durable-resume canonicalizer is retired — RB-476-A).
@@ -401,8 +401,8 @@ export declare function truncateMcpErrorText(s: string): string;
  */
 export declare const MCP_TOOL_TIMEOUT_DEFAULT_MS = 100000000;
 /**
- * The bounds EVERY `MCP_*` millisecond knob resolves into — CC 223-same (`MNs` @354067 and the idle leg
- * `Pyd` @354076 both clamp into `[1000, 2147483647]`; the constants were already ported here, the clamp
+ * The bounds EVERY `MCP_*` millisecond knob resolves into: both the timeout and the idle leg clamp into
+ * `[1000, 2147483647]`; the constants were already ported here, the clamp
  * was not).
  *
  * The ceiling is not cosmetic: `setTimeout` stores its delay in a signed 32-bit field, so a larger value
@@ -434,7 +434,7 @@ export declare function mcpToolTimeoutMs(): number;
  */
 export declare function mcpToolTotalTimeoutMs(perCallMs: number): number;
 /**
- * RB-199 FO-1 (form-one audit, CC 2.1.220): a server that goes SILENT — alive, transport open, no error,
+ * RB-199 FO-1 (form-one audit): a server that goes SILENT — alive, transport open, no error,
  * no close, just never responds and never emits progress — has no bound tighter than the (deliberately
  * enormous, ~27.8h-default) total ceiling above. CC bounds this with a SEPARATE idle watchdog distinct
  * from its total ceiling (`j7u` @345484: stdio 30min / http-sse 5min).
@@ -475,8 +475,8 @@ export { normalizeNameSegment as normalizeMcpName, clampNameSegment } from "./pr
 export * from "./image-downsample.js";
 /**
  * design/116 W5-2 — compact, jq-friendly type signature for a `structuredContent` value, e.g.
- * `{title: string, items: [{id: number}]}`. Port of CC 2.1.187 `inferCompactSchema` (services/mcp/client.ts,
- * beside the structuredContent branch at client.ts:2676-2683): depth-2, first array element as the element
+ * `{title: string, items: [{id: number}]}`. Port of the reference's compact-schema inference:
+ * depth-2, first array element as the element
  * type, ≤10 object entries then `, ...`.
  */
 export declare function inferCompactSchema(value: unknown, depth?: number): string;
@@ -535,7 +535,7 @@ export declare function mapContent(content: Array<McpContentItem>, serverName?:
  * `\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). */
+/** One tool's schema-normalization outcome. */
 export type McpSchemaNormalizeResult = {
     outcome: "unchanged";
 } | {
@@ -548,7 +548,7 @@ export type McpSchemaNormalizeResult = {
     reason: string;
 };
 /**
- * RB-199 FO-2 (form-one audit, CC 2.1.220 `zyo` @336616-336654): flatten a root-level `anyOf`/`oneOf`/
+ * RB-199 FO-2 (form-one audit): flatten a root-level `anyOf`/`oneOf`/
  * `allOf` combinator into a plain `{type:"object", properties, required}` shape a provider's tool-schema
  * validator accepts, INSTEAD of leaving `mcpToolSchemaProblem` below to drop the whole tool. Without this,
  * a server advertising the common "zod union" combinator shape (structurally VALID JSON Schema — the
@@ -576,7 +576,7 @@ export declare function normalizeMcpToolSchema(schema: unknown): McpSchemaNormal
  * CORE-authored reason string when the schema would be rejected at the provider wire, else
  * `undefined` (tool is kept). Deliberately CONSERVATIVE (fail-open): only shapes that are
  * *structurally* unusable are dropped — anything a provider might accept rides through. An ABSENT
- * schema is fine (intake defaults it to `{type:"object"}` below). CC 2.1.216 gates the same prune
+ * schema is fine (intake defaults it to `{type:"object"}` below). The reference gates the same prune
  * per-server via remote config (its rollout mechanism, not the mechanism itself); sema's gate is
  * the deterministic predicate alone. RB-199 FO-2: run {@link normalizeMcpToolSchema} on the schema
  * FIRST — a root-level anyOf/oneOf/allOf reaching this gate unflattened is exactly the shape this
@@ -616,7 +616,7 @@ reminderDisclosure?: {
 }, poolOpts?: {
     pool: McpConnectionPool;
     ownsPool?: boolean;
-}, promptSections?: PromptSectionDisposer, dialable?: (spec: McpServerSpec) => boolean): Promise<MaterializedMcp>;
+}, promptSections?: PromptSectionDisposer, dialable?: (spec: McpServerSpec) => boolean, signal?: AbortSignal): Promise<MaterializedMcp>;
 /**
  * Fold the caller's AUTHORITATIVE per-tool override (design F: caller = trust root) over the server-hint axis.
  * Unlike server hints, the caller may RAISE or LOWER any axis: `effect` sets the repeat-safety class (lower to