@sema-agent/core 7.5.2 → 7.6.0

package/dist/core/mcp-failure.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The closed set of failure classes ({@link McpFailure.kind}):
+ *  · `connect_refused`   — a connect-phase errno (ECONNREFUSED / ENOTFOUND / EAI_AGAIN / EHOSTUNREACH /
+ *                          ENETUNREACH / UND_ERR_CONNECT_TIMEOUT): the request provably never left;
+ *  · `connection_failed` — any other errno / undici code on the cause chain (a reset or a timeout
+ *                          mid-exchange): the request may have run;
+ *  · `connection_closed` — the SDK reported the transport closed (`McpError` `ConnectionClosed`): in
+ *                          flight the fate is unknowable, and for a server already known dead the
+ *                          request was never attempted — the two are told apart by `delivered`;
+ *  · `http_status`       — the HTTP endpoint answered with a status instead of an MCP response
+ *                          (`httpStatus` carries the number: 401/403 = re-authorize, 5xx = down);
+ *  · `not_mcp_response`  — the HTTP endpoint answered something that is not an MCP payload and no status;
+ *  · `spawn_failed`      — a stdio server process could not be started (a missing/unexecutable command);
+ *  · `timeout`           — the request timed out (the SDK's per-call timer, the total ceiling, or the
+ *                          idle watchdog — `details` names which);
+ *  · `protocol`          — the server ANSWERED with an MCP/JSON-RPC error (a version mismatch, a rejected
+ *                          capability, an ordinary `-32603`): the exchange happened;
+ *  · `invalid_config`    — the declaration itself could not be dialed (a malformed `url`): a fault to
+ *                          fix in the spec, never an outage to wait out;
+ *  · `unknown`           — the thrown value carried no structure this table reads.
+ */
+export declare const MCP_FAILURE_KINDS: readonly ["connect_refused", "connection_failed", "connection_closed", "http_status", "not_mcp_response", "spawn_failed", "timeout", "protocol", "invalid_config", "unknown"];
+export type McpFailureKind = (typeof MCP_FAILURE_KINDS)[number];
+/** The closed set of delivery verdicts ({@link McpFailure.delivered}). */
+export declare const MCP_DELIVERY_VERDICTS: readonly ["yes", "no", "unknown"];
+export type McpDelivered = (typeof MCP_DELIVERY_VERDICTS)[number];
+/** Where the failure was judged: at the dial (connect + initial listing), where an errno on a stdio
+ *  transport is the child process failing to spawn, or on a request over an established connection. */
+export type McpFailureSite = {
+    phase: "connect";
+    transport: "stdio" | "http" | undefined;
+} | {
+    phase: "request";
+};
+/**
+ * The one MCP failure record. Both fields are always present; `httpStatus` rides only with
+ * `kind === "http_status"`.
+ */
+export interface McpFailure {
+    /**
+     * @contract mcp.failure.kind — the failure's CLASS, one of {@link MCP_FAILURE_KINDS}, decided by
+     * {@link classifyMcpFailure} from the thrown value's structure alone (never from its message). It is
+     * the SAME word on every face: the per-server status's and the wiring manifest's `errorCode`, the
+     * thrown request error's `details.code`, and the `tool_end` frame's `errorCode`. Closed: a consumer
+     * switching on it is complete; a new class is a new word for consumers, never a re-meaning of one.
+     */
+    kind: McpFailureKind;
+    /**
+     * @contract mcp.failure.delivered — whether the request REACHED the server, as a first-class fact
+     * beside the class: `"yes"` = the server answered (a `protocol` rejection proves the exchange
+     * happened); `"no"` = provably never sent (a connect-phase errno, a spawn failure, a malformed
+     * declaration, a server already known dead — safe to retry or abandon, nothing executed); `"unknown"`
+     * = the client stopped waiting or lost the pipe mid-exchange (a timeout, an in-flight close, a reset,
+     * an HTTP status from a gateway in front of the server) — the request MAY have executed, so a
+     * write-capable tool's side effects must be verified before a retry. Two failures with the same
+     * `kind` can differ here (`connection_closed` in flight vs. against a dead server), which is why the
+     * verdict is its own field and not folded into the class.
+     */
+    delivered: McpDelivered;
+    /** The HTTP status the endpoint answered with; present iff `kind === "http_status"`. */
+    httpStatus?: number;
+}
+/**
+ * The first errno-shaped / undici-shaped `code` on an error's cause chain (`E[A-Z_]+`, `UND_ERR_*`,
+ * Node's `ERR_*`). `fetch` reports every network failure as a bare `TypeError: fetch failed` with the
+ * real cause nested underneath (and an AggregateError when a host resolved to several addresses), so
+ * the code is never on the thrown error itself. The E-prefixed alternative allows `_`: Node's
+ * DNS-temporary-failure errno is literally `EAI_AGAIN`.
+ */
+export declare function networkErrorCode(err: unknown, depth?: number): string | undefined;
+/** One row of the classifier: `when` reads structure only; `failure` mints the record. */
+export interface McpFailureRule {
+    /** The row's name, for the discrimination pins (one pin per row) and for a reader of a verdict. */
+    readonly name: string;
+    readonly when: (err: unknown, at: McpFailureSite) => boolean;
+    readonly failure: (err: unknown, at: McpFailureSite) => McpFailure;
+}
+/**
+ * The ORDERED classifier. First match wins; the final row matches everything. The order is part of
+ * the contract — the SDK's typed errors go first because they are an answer FROM the exchange (an
+ * McpError is never a transport failure, whatever its text says), then the HTTP transport's typed
+ * error, then the cause-chain codes from most specific (a configuration fault, a spawn) to least
+ * (a connect-phase errno, any other network code).
+ */
+export declare const FAILURE_CLASSIFIER: ReadonlyArray<McpFailureRule>;
+/**
+ * Classify one MCP failure into {@link McpFailure} by the first matching row of
+ * {@link FAILURE_CLASSIFIER}. Total: every input maps to a record.
+ */
+export declare function classifyMcpFailure(err: unknown, at: McpFailureSite): McpFailure;
+/**
+ * What a transport-level HTTP failure can be said to be, in words for a model-facing line: the
+ * condition to name, and the delivery verdict. `undefined` for every failure that is NOT of the HTTP
+ * transport family (an McpError is an answer FROM the server; a bare error with no structure is
+ * `unknown` and gets no transport story). Shared with the A2A client leg, which faces the SAME `fetch`
+ * layer and owes the same outcome contract — one classifier, so the two protocols cannot drift on what
+ * "the request never reached them" means.
+ */
+export interface HttpTransportFailure {
+    condition: string;
+    delivered: McpDelivered;
+    httpStatus?: number;
+}
+export declare function describeHttpTransportFailure(err: unknown): HttpTransportFailure | undefined;

package/dist/core/mcp-failure.js

@@ -0,0 +1,128 @@
+import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+export const MCP_FAILURE_KINDS = [
+    "connect_refused",
+    "connection_failed",
+    "connection_closed",
+    "http_status",
+    "not_mcp_response",
+    "spawn_failed",
+    "timeout",
+    "protocol",
+    "invalid_config",
+    "unknown",
+];
+export const MCP_DELIVERY_VERDICTS = ["yes", "no", "unknown"];
+const NETWORK_CODES_NEVER_DELIVERED = new Set([
+    "ECONNREFUSED",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "UND_ERR_CONNECT_TIMEOUT",
+]);
+export function networkErrorCode(err, depth = 0) {
+    if (depth > 5 || !(err instanceof Error))
+        return undefined;
+    const code = err.code;
+    if (typeof code === "string" && /^(?:E[A-Z_]+|UND_ERR_[A-Z_]+)$/.test(code))
+        return code;
+    if (err instanceof AggregateError) {
+        for (const inner of err.errors) {
+            const found = networkErrorCode(inner, depth + 1);
+            if (found !== undefined)
+                return found;
+        }
+    }
+    return networkErrorCode(err.cause, depth + 1);
+}
+const isNodeErrCode = (code) => code.startsWith("ERR_");
+export const FAILURE_CLASSIFIER = [
+    {
+        name: "sdk connection closed",
+        when: (err) => err instanceof McpError && err.code === ErrorCode.ConnectionClosed,
+        failure: () => ({ kind: "connection_closed", delivered: "unknown" }),
+    },
+    {
+        name: "sdk request timeout",
+        when: (err) => err instanceof McpError && err.code === ErrorCode.RequestTimeout,
+        failure: () => ({ kind: "timeout", delivered: "unknown" }),
+    },
+    {
+        name: "server answered with a protocol error",
+        when: (err) => err instanceof McpError,
+        failure: () => ({ kind: "protocol", delivered: "yes" }),
+    },
+    {
+        name: "http endpoint answered a status",
+        when: (err) => err instanceof StreamableHTTPError && typeof err.code === "number" && err.code > 0,
+        failure: (err) => ({ kind: "http_status", delivered: "unknown", httpStatus: err.code }),
+    },
+    {
+        name: "http endpoint answered a non-mcp payload",
+        when: (err) => err instanceof StreamableHTTPError,
+        failure: () => ({ kind: "not_mcp_response", delivered: "unknown" }),
+    },
+    {
+        name: "malformed declaration",
+        when: (err, at) => at.phase === "connect" && err instanceof Error && err.code === "ERR_INVALID_URL",
+        failure: () => ({ kind: "invalid_config", delivered: "no" }),
+    },
+    {
+        name: "node error code, not a network errno",
+        when: (err) => {
+            const code = networkErrorCode(err);
+            return code !== undefined && isNodeErrCode(code);
+        },
+        failure: () => ({ kind: "unknown", delivered: "unknown" }),
+    },
+    {
+        name: "stdio spawn failed",
+        when: (err, at) => at.phase === "connect" && at.transport === "stdio" && networkErrorCode(err) !== undefined,
+        failure: () => ({ kind: "spawn_failed", delivered: "no" }),
+    },
+    {
+        name: "connect-phase errno",
+        when: (err) => {
+            const code = networkErrorCode(err);
+            return code !== undefined && NETWORK_CODES_NEVER_DELIVERED.has(code);
+        },
+        failure: () => ({ kind: "connect_refused", delivered: "no" }),
+    },
+    {
+        name: "network errno past the connect phase",
+        when: (err) => networkErrorCode(err) !== undefined,
+        failure: () => ({ kind: "connection_failed", delivered: "unknown" }),
+    },
+    {
+        name: "no structure",
+        when: () => true,
+        failure: () => ({ kind: "unknown", delivered: "unknown" }),
+    },
+];
+export function classifyMcpFailure(err, at) {
+    for (const rule of FAILURE_CLASSIFIER)
+        if (rule.when(err, at))
+            return rule.failure(err, at);
+    return { kind: "unknown", delivered: "unknown" };
+}
+export function describeHttpTransportFailure(err) {
+    const f = classifyMcpFailure(err, { phase: "request" });
+    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 };
+        case "not_mcp_response":
+            return { condition: "its HTTP endpoint answered something that is not an MCP response", delivered: f.delivered };
+        case "connect_refused":
+            return { condition: `its HTTP endpoint could not be reached (${networkErrorCode(err)})`, delivered: f.delivered };
+        case "connection_failed":
+            return { condition: `the connection to its HTTP endpoint failed (${networkErrorCode(err)})`, delivered: f.delivered };
+        case "connection_closed":
+        case "spawn_failed":
+        case "timeout":
+        case "protocol":
+        case "invalid_config":
+        case "unknown":
+            return undefined;
+    }
+}

package/dist/core/mcp.d.ts

@@ -1,4 +1,5 @@
 import { type ProtocolId } from "./protocol-table.js";
+import { type McpDelivered, type McpFailureKind } from "./mcp-failure.js";
 import type { AgentTool } from "../internal/harness-types.js";
 import type { ImageContent, TextContent } from "../internal/llm.js";
 import { type McpImageResizer } from "./image-downsample.js";
@@ -258,11 +259,13 @@ export interface McpServerStatus {
     };
     toolNames?: string[];
     error?: string;
-    /** Present iff `status === "failed"` — the failure's CLASS, judged from the thrown error object at
-     *  connect time ({@link mcpFailureCodeOf}; the closed set is {@link MCP_FAILURE_CODES} plus the
-     *  `http_<status>` form). A consumer keys an action off THIS (a `http_401` is a re-authorization
-     *  door, a `spawn_failed` is a missing binary) instead of parsing the neutralized `error` text. */
-    errorCode?: McpFailureCode;
+    /** Present iff `status === "failed"` — the connect-time failure record, spread flat: {@link McpFailure.kind}
+     *  as `errorCode`, {@link McpFailure.delivered} as `delivered`, and `httpStatus` when the kind is
+     *  `http_status`. A consumer keys an action off THESE (a `http_status` 401 is a re-authorization door,
+     *  a `spawn_failed` is a missing binary) instead of parsing the neutralized `error` text. */
+    errorCode?: McpFailureKind;
+    delivered?: McpDelivered;
+    httpStatus?: number;
     /**
      * RB-437-a — set to `true` once core OBSERVES this server's transport close during the task; absent
      * otherwise (never `false`: absence means "no close was observed", which is not the same as "alive").
@@ -380,78 +383,6 @@ export declare function describeMcpSpecErrorCode(code: unknown): string | undefi
  * ours, and is left alone). Exported for unit testing; not part of the package index.
  */
 export declare function collapseMcpErrorPrefix(message: string): string;
-/** The first errno-shaped `code` on an error's cause chain. `fetch` reports every network failure as a
- *  bare `TypeError: fetch failed` with the real cause nested underneath (and an AggregateError when a
- *  host resolved to several addresses), so the code is never on the thrown error itself.
- *  Exported for unit testing (RB-449 mcp-1); not part of the package index (src/index.ts re-exports are
- *  explicit and do not name it — see the sibling `collapseMcpErrorPrefix`/`classifyDirReadInvalidParams`
- *  comments for the same "exported for tests only" convention). */
-export declare function networkErrorCode(err: unknown, depth?: number): string | undefined;
-/** What {@link describeHttpTransportFailure} could establish about a transport-level HTTP failure:
- *  the condition to name in the model-facing copy, whether the request can be said NOT to have reached
- *  the remote, and the HTTP status when the endpoint answered with one. */
-export interface HttpTransportFailure {
-    condition: string;
-    /** `"no"` = provably never delivered (a connect-phase errno); `"unknown"` = the request may have run. */
-    delivered: "no" | "unknown";
-    httpStatus?: number;
-}
-/**
- * RB-437-b — a streamable-HTTP failure that never became an MCP exchange at all: the POST failed at the
- * network layer (endpoint gone / unresolvable), or the endpoint answered with something that is not an
- * MCP response. The SDK surfaces the first as `fetch`'s bare `TypeError: fetch failed` and the second as
- * a `StreamableHTTPError`; NEITHER carries the server name, the MCP context or an outcome — while the
- * stdio path for the same event (the server went away) has all three. Returns the condition to name and
- * whether the request can be said not to have reached the server, or `undefined` when the failure is not
- * of this class (an McpError is an answer FROM the server: the exchange happened, so it is never one).
- *
- * Exported (not on the package index) for the A2A client leg, which faces the SAME `fetch` layer and owes
- * the same outcome contract — one classifier, so the two protocols cannot drift on what "the request never
- * reached them" means.
- */
-export declare function describeHttpTransportFailure(err: unknown): HttpTransportFailure | undefined;
-/**
- * The closed vocabulary of MCP connect-failure classes a per-server status record may carry
- * ({@link McpServerStatus.errorCode}, relayed onto the wiring manifest's `mcp[]` read face). The
- * transport family is named by the failure's SHAPE wherever the SDK exposes one (error class, JSON-RPC
- * code, errno on the cause chain, HTTP status), so a consumer can map a class to an action without
- * parsing the neutralized error string. Two words are the exception and are text-derived, because
- * undici and the SDK surface those two conditions as bare messages with no code: `network` (a
- * `TypeError` whose message matches `fetch failed|terminated|network` and carries no errno) and the
- * non-`McpError` arm of `connection_closed` (a message matching `not connected|connection closed`).
- * A wording change in those libraries moves such a failure to `unknown`, never to a wrong word; the
- * classifier table pins both regexes. An HTTP endpoint that answered with a status is
- * reported in the `http_<status>` form (`http_401` = the endpoint wants (re-)authorization, `http_5xx` =
- * the endpoint is down) — a template member of the type beside these fixed words. Additive-only: a new
- * word here is a new arm for consumers, never a re-meaning of an existing one.
- *  · `connect_refused`   — a connect-phase errno (ECONNREFUSED / ENOTFOUND / …): the request provably never left;
- *  · `connection_failed` — a network errno past the connect phase (reset / timed out mid-exchange);
- *  · `network`           — the HTTP request failed at the network layer with no errno on the cause chain;
- *  · `not_mcp_response`  — the HTTP endpoint answered something that is not an MCP payload (no status to name);
- *  · `spawn_failed`      — a stdio server process could not be started (a missing/unexecutable command);
- *  · `connection_closed` — the transport closed during the handshake (the server process exited, the stream ended);
- *  · `timeout`           — the handshake's request timed out;
- *  · `protocol`          — the server answered the handshake with an MCP/JSON-RPC error (a version mismatch, a
- *                          rejected capability, …) — `error` carries the named condition;
- *  · `invalid_config`    — the declaration itself could not be dialed (a malformed `url`): a configuration
- *                          fault to fix in the spec, never an outage to wait out;
- *  · `unknown`           — none of the above could be established from the thrown value.
- */
-export declare const MCP_FAILURE_CODES: readonly ["connect_refused", "connection_failed", "network", "not_mcp_response", "spawn_failed", "connection_closed", "timeout", "protocol", "invalid_config", "unknown"];
-export type McpFailureCode = (typeof MCP_FAILURE_CODES)[number] | `http_${number}`;
-/**
- * Classify one connect-time failure into {@link McpFailureCode}. Reads the thrown value's SHAPE
- * (error class, JSON-RPC code, errno on the cause chain, HTTP status) first; only the two
- * message-shaped conditions named on {@link MCP_FAILURE_CODES} (`network`, the non-`McpError`
- * `connection_closed`) are decided by a fixed regex over the message, and no other word can be chosen
- * by message text — a remote's own wording can at most leave a failure at `unknown`.
- * `transport` disambiguates the errno family: on a stdio server an errno is the child
- * process failing to spawn, on an HTTP server it is the socket; a caller that could not establish the
- * kind passes `undefined` and the errno family reads as the transport-neutral `connection_failed`.
- * Total: every input maps to a word, and `unknown` is the honest word for a value this table cannot
- * read (a caller must not receive a guess).
- */
-export declare function mcpFailureCodeOf(err: unknown, transport: "stdio" | "http" | undefined): McpFailureCode;
 export { normalizeNameSegment as normalizeMcpName, clampNameSegment } from "./protocol-naming.js";
 export * from "./image-downsample.js";
 /**
@@ -483,6 +414,19 @@ export interface ProtocolHttpAuth {
  * turns it into a skipped peer instead of a failed task.
  */
 export declare function resolveProtocolHttpHeaders(protocol: ProtocolId, t: ProtocolHttpAuth, principal?: string): Record<string, string> | undefined;
+/** `kind` is the dial's ONE read of `spec.transport.kind` (taken by the caller beside the dial and threaded
+ *  here, to the idle bucket and to the failure classifier alike): a nested `transport` object is the
+ *  caller's, and a getter that answered differently to two readers would otherwise connect over one
+ *  transport and be judged under another. An unknown kind takes the non-stdio branch, as it always did. */
+/**
+ * The MCP HTTP transport's `fetch`: every request the transport makes — the POST, the SSE GET (initial and
+ * resumed), the DELETE, the auth flows — goes to the endpoint the declaration NAMED and follows no redirect.
+ * `fetch`'s default follows a 3xx silently and then reports only the last hop, which is the one shape under
+ * which the delivery verdict would lie (a connect refusal on the redirect target reading "never sent" while
+ * the declared endpoint had received the POST); a 3xx now surfaces as the SDK's HTTP-status error, and a
+ * body or a credential never travels to a host the declaration did not name. Exported for its pin only.
+ */
+export declare const declaredEndpointFetch: typeof fetch;
 interface McpContentItem {
     type: string;
     text?: string;