@combycode/llm-sdk 1.7.0 → 2.0.0

package/dist/plugins/mcp/client.d.ts

@@ -5,7 +5,9 @@
 import type { HookBus } from '../../bus/hook-bus';
 import type { McpTransport } from './transport';
 import type { TraceContext } from '../../network/types';
-import type { McpCallResult, McpCompletionRef, McpCompletionResult, McpGetPromptResult, McpInitializeResult, McpLogLevel, McpPrompt, McpResource, McpResourceContent, McpResourceTemplate, McpTask, McpTaskMetadata, McpToolDef } from './types';
+import { type McpEra } from './protocol-version';
+import { McpSubscription, type McpServerEvent, type McpSubscriptionFilter } from './subscriptions';
+import type { McpCallResult, McpCompletionRef, McpCompletionResult, McpDiscoverResult, McpGetPromptResult, McpInitializeResult, McpLogLevel, McpPrompt, McpResource, McpResourceContent, McpResourceTemplate, McpTask, McpTaskMetadata, McpToolDef } from './types';
 export interface McpClientOptions {
     clientInfo?: {
         name: string;
@@ -29,23 +31,92 @@ export interface McpClientOptions {
         hooks: HookBus;
         server: string;
     };
-    /** Send a `ping` every N ms to keep the connection alive (0/undefined = off). */
+    /** Send a `ping` every N ms to keep the connection alive (0/undefined = off).
+     *  Ignored on a 2026-07-28 session, where `ping` no longer exists. */
     keepAliveMs?: number;
+    /** How to negotiate the protocol revision.
+     *
+     *  - `'auto'` (default) — probe `server/discover`; anything that is not positive evidence of a
+     *    modern server falls back to the `initialize` handshake.
+     *  - `'legacy'` — skip the probe and run the handshake, byte-identical to pre-2.0 behaviour.
+     *    Use this for a server that mishandles unknown methods.
+     *  - a version string (e.g. `'2026-07-28'`) — adopt that revision directly, no probe.
+     *
+     *  Fallback is a DENYLIST: every JSON-RPC error falls back to the handshake except a
+     *  `-32022` naming only modern versions we do not share. Transport/network errors are never
+     *  treated as an era verdict — an outage must not silently downgrade the wire. */
+    protocolMode?: 'auto' | 'legacy' | (string & {});
+    /** Cap on `input_required` retry rounds before giving up (default 10, matching every other SDK).
+     *  A handler that never satisfies the server would otherwise loop forever. */
+    inputRequiredMaxRounds?: number;
+    /** Honour the server's `ttlMs` / `cacheScope` hints on list and read results (2026-07-28).
+     *
+     *  **Off by default.** Caching changes when a caller observes a server-side change, which is the
+     *  caller's call to make. A server that sends no hints caches nothing either way, so this is a
+     *  no-op against every pre-2026 server. Cache entries are dropped automatically on the matching
+     *  `*_changed` notification. */
+    cacheResults?: boolean;
 }
 export declare class McpClient {
     private readonly transport;
     private readonly opts;
     private serverInfo;
     private pingTimer;
+    private negotiatedVersion;
+    private discovery;
+    private readonly cache;
+    private readonly subscriptions;
     constructor(transport: McpTransport, opts?: McpClientOptions);
-    /** The server's `initialize` result, or null before `connect()`. */
+    /** Drop cached list/read results. Called automatically on the matching `*_changed`
+     *  notification; exposed because a caller may know the server moved before it says so. */
+    invalidateCache(method?: string): void;
+    /** The server's `initialize` result, or null before `connect()`.
+     *
+     *  On a 2026-07-28 session there is no `initialize`, so this is SYNTHESISED from the
+     *  `server/discover` result (capabilities, instructions, and the `_meta` serverInfo stamp).
+     *  Deliberate: the shape a caller reads must not depend on which wire was negotiated
+     *  (CONSTITUTION.md R2 — absorb the difference, never expose a union). */
     get info(): McpInitializeResult | null;
+    /** The revision actually negotiated. Defaults to the handshake-era version until `connect()`. */
+    get protocolVersion(): string;
+    /** Which wire this session speaks. `'handshake'` for 2025-11-25 and earlier. */
+    get era(): McpEra;
+    /** The raw `server/discover` result on a modern session; `null` on a handshake session.
+     *  Carries the fields that have no handshake equivalent (`supportedVersions`, `ttlMs`,
+     *  `cacheScope`). */
+    get discoverResult(): McpDiscoverResult | null;
     /** Open the transport, run the initialize handshake, and start listening for
      *  server-initiated messages. */
     connect(): Promise<McpInitializeResult>;
+    /** The pre-2026 path, unchanged: `initialize` + `notifications/initialized`. */
+    private handshake;
+    /** One `server/discover` at `version`. No retry, no adoption — the caller decides.
+     *
+     *  The transport is told the version FIRST because on HTTP it is not just bookkeeping:
+     *  a modern server routes by the `MCP-Protocol-Version` header, so a probe sent without
+     *  it lands on the legacy handler and is rejected with `400 Missing session ID` — the
+     *  connection fails outright instead of negotiating. Invisible over stdio, which has no
+     *  headers; found against mcp-py 2.0.0 Streamable HTTP (2026-08-09). */
+    private sendDiscover;
+    /** Install a discover result as the live session. */
+    private adoptModern;
+    /** `mode: 'auto'` — probe modern, fall back to the handshake on anything that is not positive
+     *  evidence of a modern server.
+     *
+     *  The fallback is a DENYLIST, matching mcp-py 2.0.0 `client/_probe.py`: every JSON-RPC error
+     *  falls back EXCEPT a `-32022` whose `supported` list is modern-only and disjoint from ours —
+     *  that one is a real incompatibility and must surface. Transport/network failures are rethrown
+     *  untouched: an outage is not an era verdict, and silently downgrading the wire because a
+     *  socket blipped would be the worst possible failure mode. */
+    private negotiateAuto;
     /** List every tool the server exposes (follows cursor pagination). */
     listTools(): Promise<McpToolDef[]>;
-    /** Follow cursor pagination for a list method, collecting `field` from each page. */
+    /** Follow cursor pagination for a list method, collecting `field` from each page.
+     *
+     *  When result caching is enabled and the server sent a `ttlMs`, the assembled list is reused
+     *  until it expires. A paginated list is only as fresh as its shortest-lived page, so the
+     *  effective TTL is the MINIMUM across pages — taking the last page's value would let an early,
+     *  more volatile page go stale unnoticed. */
     private paginate;
     /** Invoke a tool by its (un-namespaced) server name.
      *  Pass `trace` when the call originates from an AgentLoop run so that
@@ -57,14 +128,35 @@ export declare class McpClient {
     listResourceTemplates(): Promise<McpResourceTemplate[]>;
     /** Read a resource's contents by URI. */
     readResource(uri: string): Promise<McpResourceContent[]>;
-    /** Subscribe to updates for a resource (server sends `notifications/resources/updated`). */
+    /** Subscribe to updates for a resource (server sends `notifications/resources/updated`).
+     *
+     *  Handshake era only — 2026-07-28 replaces per-resource subscription with the single
+     *  `subscriptions/listen` stream. */
     subscribeResource(uri: string): Promise<void>;
     unsubscribeResource(uri: string): Promise<void>;
+    /** Open a `subscriptions/listen` stream (2026-07-28) — the single channel that replaces
+     *  `resources/subscribe` and the standalone notification stream.
+     *
+     *  Every kind is **opt-in**: the server may not send what was not requested, and it acknowledges
+     *  with the subset it actually honoured — which can be narrower than what was asked for. Check
+     *  `subscription.honored` / `isHonored(kind)` rather than assuming the request was granted.
+     *
+     *  Events are level triggers ("this changed, re-fetch if you care"), so they carry no payload
+     *  beyond the change itself. When result caching is on, the matching entries are dropped before
+     *  `onEvent` runs, so a handler that immediately re-lists sees fresh data.
+     *
+     *  Requires a modern session and a duplex transport (stdio / WebSocket) — see
+     *  `sendLongLivedRequest` on the HTTP transport for why. */
+    listen(filter: McpSubscriptionFilter, onEvent: (event: McpServerEvent) => void): Promise<McpSubscription>;
     /** List the server's prompts (follows cursor pagination). */
     listPrompts(): Promise<McpPrompt[]>;
     /** Render a prompt by name with arguments → its messages. */
     getPrompt(name: string, args?: Record<string, string>): Promise<McpGetPromptResult>;
-    /** Set the server's log verbosity (it then sends `notifications/message`). */
+    /** Set the server's log verbosity (it then sends `notifications/message`).
+     *
+     *  Handshake era only — `logging/setLevel` was removed at 2026-07-28, where verbosity rides in
+     *  each request's `_meta` instead. Throws rather than silently no-opping: a caller who asked for
+     *  debug logging and got none would have no way to tell. */
     setLogLevel(level: McpLogLevel): Promise<void>;
     /** Argument autocompletion for a prompt or resource template. */
     completeArgument(ref: McpCompletionRef, argument: {
@@ -85,8 +177,53 @@ export declare class McpClient {
         pollIntervalMs?: number;
         timeoutMs?: number;
     }): Promise<McpTask>;
-    /** Low-level escape hatch: send any request method. */
+    /** Low-level escape hatch: send any request method. Carries the modern-era identity
+     *  envelope like every other request. */
     request(method: string, params?: unknown): Promise<unknown>;
+    /** Every request goes through here.
+     *
+     *  At 2026-07-28 there is no handshake and no session id, so each request states its
+     *  own identity: `_meta` MUST carry the protocol version and the client capabilities
+     *  (client info is optional). Only `server/discover` used to build that envelope, so
+     *  every later call on a modern session was rejected:
+     *
+     *    -32602 params._meta must be an object carrying the required
+     *           'io.modelcontextprotocol/protocolVersion' and
+     *           'io.modelcontextprotocol/clientCapabilities' envelope keys
+     *
+     *  Unreachable without a real 2026-07-28 server — no public one exists yet; found by
+     *  running mcp-py 2.0.0 over stdio (2026-08-09).
+     *
+     *  Handshake-era sessions are untouched: identity lives in `initialize` there, and an
+     *  unexpected `_meta` is exactly the sort of thing an older server can reject. */
+    private send;
+    /** Stamp the modern identity envelope onto a request's params.
+     *
+     *  Shared by `send()` and the long-lived `subscriptions/listen`, because EVERY request
+     *  needs it — and the long-lived path is the one where a missing envelope hides: the
+     *  rejection arrives as the stream's end rather than a thrown error, so `listen()`
+     *  returned a subscription that looked alive and delivered nothing. */
+    private withEnvelope;
     close(): Promise<void>;
+    /** Resolve an `input_required` result to a terminal one.
+     *
+     *  The dispatcher is `handleServerRequest` — the SAME path that serves a handshake-era server
+     *  pushing `sampling/createMessage` at us. That is the whole point of routing MRTR through here:
+     *  a caller wires up sampling once and it works on either wire, without knowing which is in play.
+     *
+     *  Skips instantly when `resultType` is absent or `'complete'`, so the handshake path pays
+     *  nothing. */
+    private driveInputRequired;
+    /** Guard a method the 2026-07-28 revision removed. Naming the negotiated version and the
+     *  replacement matters: without it the caller sees a bare -32601 from the server and has no way
+     *  to know the method existed until the session happened to negotiate modern. */
+    private requireHandshakeEra;
+    /** Map a change notification onto the cache entries it invalidates. Same vocabulary on both
+     *  eras — these methods ride the `subscriptions/listen` stream at 2026-07-28 and the
+     *  back-channel before it, but the meaning ("refetch if you care") is identical. */
+    private invalidateOnChange;
+    /** Same invalidation as `invalidateOnChange`, driven from a typed listen-stream event. */
+    private invalidateForEvent;
+    private clientInfo;
     private handleServerRequest;
 }

package/dist/plugins/mcp/input-required.d.ts

@@ -0,0 +1,35 @@
+/** Multi-round-trip requests (MRTR, SEP-2322) — the 2026-07-28 replacement for the server→client
+ *  back-channel.
+ *
+ *  On the handshake wire a server that needs sampling/elicitation/roots PUSHES a request at us
+ *  mid-call. At 2026-07-28 there is no back-channel: the server instead RETURNS
+ *  `resultType: 'input_required'` carrying the requests it needs answered, and the client re-issues
+ *  the *same* call with the answers plus the server's opaque `requestState`.
+ *
+ *  Both mechanisms feed the SAME callbacks — a caller who wired up sampling once gets it on either
+ *  wire without knowing which is in play. Algorithm mirrors mcp-py 2.0.0 `client/_input_required.py`.
+ */
+import type { McpInputRequest } from './types';
+/** Cap on retry rounds before the driver gives up. Matches the TypeScript SDK's default; the C#
+ *  and Go SDKs use the same value as a hard constant. */
+export declare const DEFAULT_INPUT_REQUIRED_MAX_ROUNDS = 10;
+/** Answer one embedded request through the client's sampling / elicitation / roots handling. */
+export type InputRequestDispatcher = (key: string, request: McpInputRequest) => Promise<unknown>;
+/** Re-issue the original call with the collected answers and the latest state. */
+export type InputRequiredRetry<T> = (responses: Record<string, unknown> | undefined, requestState: string | undefined) => Promise<T>;
+/** True when a result is the server asking for more input rather than a final answer.
+ *
+ *  The discriminant is `resultType`. Per spec an ABSENT `resultType` MUST be read as `'complete'`:
+ *  servers on earlier revisions never send the field, and treating absent as anything else would
+ *  make every legacy result look like a question. */
+export declare function isInputRequired(result: unknown): boolean;
+/** Drive an `input_required` result to a terminal one.
+ *
+ *  Each round either answers every embedded request and retries with the responses, or — when the
+ *  server sent state but no questions — backs off and retries empty. `requestState` is echoed back
+ *  byte-exact and never inspected: it is the server's sealed continuation token. */
+export declare function runInputRequiredDriver<T>(first: T, opts: {
+    dispatch: InputRequestDispatcher;
+    retry: InputRequiredRetry<T>;
+    maxRounds?: number;
+}): Promise<T>;

package/dist/plugins/mcp/jsonrpc.d.ts

@@ -9,6 +9,13 @@ export declare const McpErrorCode: {
     readonly MethodNotFound: -32601;
     readonly InvalidParams: -32602;
     readonly InternalError: -32603;
+    /** A routing header disagrees with the request body. */
+    readonly HeaderMismatch: -32020;
+    /** The server requires a client capability this client did not declare. */
+    readonly MissingRequiredClientCapability: -32021;
+    /** The server does not speak the requested revision; `data.supported` lists the ones it does.
+     *  The ONE error carrying era information, so negotiation reads it specifically. */
+    readonly UnsupportedProtocolVersion: -32022;
 };
 /** A JSON-RPC / transport level error (server unreachable, error response,
  *  timeout). Tool execution failures arrive as a normal result with

package/dist/plugins/mcp/oauth.d.ts

@@ -27,6 +27,9 @@ export interface McpOAuthClientMetadata {
     grant_types?: string[];
     response_types?: string[];
     token_endpoint_auth_method?: string;
+    /** OIDC Registration §2 application type (SEP-837). Defaults to `'native'` at registration, since
+     *  an MCP client is normally a local process with a loopback redirect. Set explicitly to override. */
+    application_type?: 'web' | 'native';
 }
 /** Consumer-implemented storage + interactive redirect. */
 export interface McpAuthProvider {
@@ -51,7 +54,24 @@ export interface AuthServerMetadata {
     authorization_endpoint: string;
     token_endpoint: string;
     registration_endpoint?: string;
+    /** The authorization server's issuer identifier (RFC 8414), used to validate the RFC 9207 `iss`
+     *  returned with the authorization code. */
+    issuer?: string;
+    /** RFC 9207: the server states it returns `iss` on authorization responses. When true, a response
+     *  WITHOUT `iss` is rejected — otherwise an attacker could simply strip the parameter to dodge
+     *  the check. */
+    authorization_response_iss_parameter_supported?: boolean;
 }
+/** Validate the RFC 9207 authorization-response issuer.
+ *
+ *  This is the mix-up-attack defence: without it a malicious authorization server can hand back a
+ *  code minted by a DIFFERENT server, and the client will dutifully redeem it — replaying the
+ *  user's credentials against a party they never intended to authorize.
+ *
+ *  Comparison is **exact string equality** per RFC 9207 §2.4 (RFC 3986 §6.2.1) — deliberately NOT
+ *  URL-normalised. Normalising would make `https://as.example.com` and `https://as.example.com/`
+ *  compare equal, and that leniency is precisely what an attacker looks for. */
+export declare function validateAuthorizationResponseIss(iss: string | undefined, meta: Pick<AuthServerMetadata, 'issuer' | 'authorization_response_iss_parameter_supported'>): void;
 /** Security options for the OAuth flow.  All fields default to the most
  *  restrictive posture.  Re-exported from `url-guard` for consumer convenience. */
 export type { SsrfGuardOptions as McpOAuthSecurityOptions };
@@ -114,7 +134,7 @@ export declare class McpOAuth {
     reauthorize(): Promise<boolean>;
     /** Finish the interactive flow: exchange the callback code for tokens.
      *  The `returnedState` MUST match the state persisted during redirect (CSRF guard). */
-    finish(code: string, returnedState: string): Promise<void>;
+    finish(code: string, returnedState: string, iss?: string): Promise<void>;
     private startRedirect;
     private tryRefresh;
     private ensureMetadata;

package/dist/plugins/mcp/protocol-version.d.ts

@@ -0,0 +1,61 @@
+/** MCP protocol-version registry and era helpers.
+ *
+ *  MCP has two ERAS, not just two versions:
+ *    - **handshake** (2024-11-05 … 2025-11-25) — `initialize` + `notifications/initialized`, an
+ *      `Mcp-Session-Id`, and a server→client back-channel (ping, logging/setLevel,
+ *      resources/subscribe, push sampling / roots / elicitation).
+ *    - **modern** (2026-07-28+) — no handshake and no session id. One `server/discover` probe,
+ *      then every request carries its own identity in `_meta` and routing headers.
+ *
+ *  Both are supported and neither is preferred: real servers overwhelmingly still speak
+ *  2025-11-25, so the handshake path must keep working byte-for-byte. See CONSTITUTION.md
+ *  standing decisions (2026-08-08).
+ */
+/** Every released revision, oldest to newest. Verified against mcp-py 2.0.0
+ *  (`mcp_types/version.py`, KNOWN_PROTOCOL_VERSIONS). */
+export declare const MCP_KNOWN_PROTOCOL_VERSIONS: readonly ["2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25", "2026-07-28"];
+/** Revisions reachable via the `initialize` handshake. */
+export declare const MCP_HANDSHAKE_PROTOCOL_VERSIONS: readonly ["2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25"];
+/** Revisions that use the stateless per-request envelope (`server/discover`). */
+export declare const MCP_MODERN_PROTOCOL_VERSIONS: readonly ["2026-07-28"];
+/** Newest revision reachable via the handshake — what we offer in `initialize`. */
+export declare const MCP_LATEST_HANDSHAKE_VERSION = "2025-11-25";
+/** Newest per-request-envelope revision — what the `server/discover` probe asks for. */
+export declare const MCP_LATEST_MODERN_VERSION = "2026-07-28";
+/** Which wire a negotiated version implies. */
+export type McpEra = 'handshake' | 'modern';
+/** Version strings are an ENUMERATED SET, not an ordered scalar.
+ *
+ *  Released revisions happen to be dates that sort lexicographically, but future identifiers are
+ *  not guaranteed to be date-shaped, and an unrecognised peer string must compare conservatively
+ *  rather than accidentally (`'zzz' > '2025-11-25'` is true and meaningless). So era questions go
+ *  through the lists above — never through `<` / `>`. Upstream calls this out explicitly, having
+ *  been bitten by it. An unknown version reads as `handshake`: the older, safer wire. */
+export declare function mcpEraOf(version: string): McpEra;
+/** True when `version` is a revision this client can speak on the modern wire. */
+export declare function isModernMcpVersion(version: string): boolean;
+/** True when `version` is a revision reachable via the `initialize` handshake. */
+export declare function isHandshakeMcpVersion(version: string): boolean;
+/** The newest modern revision BOTH sides speak, or undefined if they share none. */
+export declare function newestMutualModernVersion(theirs: readonly string[]): string | undefined;
+/** Required on every modern request: the revision this request is written at. */
+export declare const MCP_PROTOCOL_VERSION_META_KEY = "io.modelcontextprotocol/protocolVersion";
+/** Required on every modern request: what the client can do (replaces the handshake exchange). */
+export declare const MCP_CLIENT_CAPABILITIES_META_KEY = "io.modelcontextprotocol/clientCapabilities";
+/** Optional client identity, display-only. */
+export declare const MCP_CLIENT_INFO_META_KEY = "io.modelcontextprotocol/clientInfo";
+/** Server identity stamped on modern results, display-only (absent and malformed both read as
+ *  "unknown" rather than failing the connection). */
+export declare const MCP_SERVER_INFO_META_KEY = "io.modelcontextprotocol/serverInfo";
+/** Stamped on every `subscriptions/listen` stream frame; the value is that request's JSON-RPC id,
+ *  which is how a frame is attributed to one subscription. */
+export declare const MCP_SUBSCRIPTION_ID_META_KEY = "io.modelcontextprotocol/subscriptionId";
+export declare const MCP_PROTOCOL_VERSION_HEADER = "mcp-protocol-version";
+export declare const MCP_METHOD_HEADER = "mcp-method";
+export declare const MCP_NAME_HEADER = "mcp-name";
+/** Methods whose primary subject goes in the `Mcp-Name` routing header, and the param it comes
+ *  from. Lets an intermediary route/authorize without parsing the body. */
+export declare const MCP_NAME_BEARING_METHODS: Readonly<Record<string, string>>;
+/** Header values must be ASCII; a tool name or URI may not be. Encode out-of-range characters
+ *  rather than emitting a header the runtime will reject. */
+export declare function encodeMcpHeaderValue(value: string): string;

package/dist/plugins/mcp/result-cache.d.ts

@@ -0,0 +1,31 @@
+/** Opt-in response cache honouring the 2026-07-28 `ttlMs` / `cacheScope` hints (SEP-2578).
+ *
+ *  A server tells the client how long a list/read result stays fresh. Without this, `listTools()`
+ *  re-fetches on every call — the churn this hint exists to remove.
+ *
+ *  Deliberately conservative:
+ *   - **Off unless asked for.** Caching changes when a caller observes a server change; that is the
+ *     caller's decision, not ours.
+ *   - **No hint, no caching.** `ttlMs` absent (every pre-2026 server) means nothing is stored, so
+ *     behaviour is byte-identical to before.
+ *   - **`ttlMs: 0` means immediately stale**, which is a real instruction — not a missing value to
+ *     be replaced with a default.
+ *   - **`cacheScope` is recorded, never used to widen sharing.** This cache lives inside one client
+ *     with one credential, so `public` buys nothing here; storing the scope keeps the entry honest
+ *     if the cache is ever shared.
+ */
+import type { McpCacheHints } from './types';
+export declare class McpResultCache {
+    private readonly entries;
+    /** Cache key: the method plus its arguments. Two `resources/read` calls for different URIs are
+     *  different entries. */
+    static key(method: string, params?: unknown): string;
+    get(key: string, now?: number): unknown | undefined;
+    /** Store only when the server actually asked for it. Returns whether anything was stored. */
+    set(key: string, value: unknown, hints: McpCacheHints | undefined, now?: number): boolean;
+    /** Drop everything — e.g. after a `*_changed` notification says the server moved on. */
+    clear(): void;
+    /** Drop every entry for one method, leaving the others. */
+    clearMethod(method: string): void;
+    get size(): number;
+}

package/dist/plugins/mcp/subscriptions.d.ts

@@ -0,0 +1,69 @@
+/** `subscriptions/listen` (2026-07-28, SEP-2575) — one stream for every change notification.
+ *
+ *  At 2026-07-28 the per-resource `resources/subscribe` RPC and the standalone notification channel
+ *  are both replaced by a single long-lived `subscriptions/listen` request. The client names the
+ *  notification kinds it wants; **every kind is opt-in and the server MUST NOT send one that was
+ *  not asked for**. The server acknowledges with the subset it actually honoured, which can be
+ *  smaller than what was requested — so "I asked for it" never implies "I will receive it".
+ *
+ *  Every frame on the stream is stamped with the listen request's id under
+ *  `io.modelcontextprotocol/subscriptionId`, which is how frames are attributed to a subscription.
+ *
+ *  Events are **level triggers**: "this changed, re-fetch if you care". They carry no payload
+ *  beyond the fact of the change, so consecutive identical events collapse safely.
+ */
+/** The notification kinds a client may opt into. Mirrors the wire `SubscriptionFilter`. */
+export interface McpSubscriptionFilter {
+    toolsListChanged?: boolean;
+    promptsListChanged?: boolean;
+    resourcesListChanged?: boolean;
+    /** Resource URIs to watch — the replacement for the `resources/subscribe` RPC. */
+    resourceSubscriptions?: string[];
+}
+/** A change the server announced. Level triggers: re-fetch if you care. */
+export type McpServerEvent = {
+    type: 'tools_list_changed';
+} | {
+    type: 'prompts_list_changed';
+} | {
+    type: 'resources_list_changed';
+} | {
+    type: 'resource_updated';
+    uri: string;
+};
+/** The notification methods that ride a listen stream at 2026-07-28. */
+export declare const MCP_LISTEN_STREAM_METHODS: readonly ["notifications/tools/list_changed", "notifications/prompts/list_changed", "notifications/resources/list_changed", "notifications/resources/updated"];
+/** The ack frame that carries the honoured subset. */
+export declare const MCP_SUBSCRIPTIONS_ACKNOWLEDGED = "notifications/subscriptions/acknowledged";
+/** The event a raw stream frame announces, or undefined when it carries none. */
+export declare function eventFromWire(method: string, params: unknown): McpServerEvent | undefined;
+/** The subscription id stamped on a frame, or undefined when it is not a listen frame. */
+export declare function subscriptionIdFrom(params: unknown): string | number | undefined;
+/** A live subscription: the honoured filter once acknowledged, plus event delivery. */
+export declare class McpSubscription {
+    readonly id: string | number;
+    readonly requested: McpSubscriptionFilter;
+    private readonly onEvent;
+    private readonly onClose;
+    /** The subset the server agreed to send. `null` until the ack arrives — and it can be NARROWER
+     *  than what was requested, so check it rather than assuming. */
+    honored: McpSubscriptionFilter | null;
+    private closed;
+    private endState;
+    constructor(id: string | number, requested: McpSubscriptionFilter, onEvent: (event: McpServerEvent) => void, onClose: () => void);
+    /** Feed a raw stream frame. Returns true when it belonged to this subscription. */
+    handleFrame(method: string, params: unknown): boolean;
+    /** True when the server acknowledged this kind. Unacknowledged ⇒ do not expect events. */
+    isHonored(kind: keyof McpSubscriptionFilter): boolean;
+    /** Set once the stream ends: `undefined` for a clean server-side teardown, otherwise the error
+     *  that killed it. A subscription that stopped delivering is otherwise indistinguishable from one
+     *  where nothing has changed yet. */
+    get ended(): {
+        error?: unknown;
+    } | null;
+    /** True while the subscription can still deliver. */
+    get active(): boolean;
+    /** Called by the transport when the underlying stream finishes. */
+    markEnded(error?: unknown): void;
+    close(): void;
+}

package/dist/plugins/mcp/transport-http.d.ts

@@ -26,11 +26,18 @@ export declare class HttpTransport extends BaseJsonRpcTransport implements McpTr
     private nextHttpId;
     private sessionId;
     private protocolVersion;
+    /** Handshake until negotiation says otherwise — an un-negotiated connection must behave exactly
+     *  as it did before 2026 support existed. */
+    private era;
     private eventAbort;
     private lastEventId;
+    /** Live `subscriptions/listen` streams, so `close()` can tear them down. Without this a closed
+     *  client would leave the POST hanging until the server gave up on it. */
+    private readonly streamAborts;
     constructor(config: McpHttpConfig, deps: HttpTransportDeps);
     start(): Promise<void>;
     setProtocolVersion(version: string): void;
+    setEra(era: 'handshake' | 'modern'): void;
     /** Open the server->client GET SSE stream (best-effort: a 405 means the server
      *  is request/response only). Reconnects with backoff + Last-Event-ID until
      *  close(). Runs in the background. */
@@ -43,8 +50,32 @@ export declare class HttpTransport extends BaseJsonRpcTransport implements McpTr
     close(): Promise<void>;
     /** Send a JSON-RPC response back via POST (used by handleRequest from base). */
     protected sendMessage(obj: unknown): Promise<void>;
+    /** Open a long-lived request whose RESPONSE BODY is the event stream.
+     *
+     *  This is how `subscriptions/listen` works on Streamable HTTP: unlike an ordinary call, the POST
+     *  does not return a single JSON-RPC message — the server holds the response open and writes
+     *  notification frames as they occur, closing it only when the subscription ends. So it goes
+     *  through `fetchStream` (streaming response) rather than the buffered `post()` path, which would
+     *  surface the frames only after the stream closed.
+     *
+     *  Frames are routed exactly like the GET channel's, so the client sees no difference between the
+     *  two. The eventual JSON-RPC response has no pending entry to settle — its only meaning is "the
+     *  stream ended", which is reported through `onEnd`. */
+    sendLongLivedRequest(method: string, params?: unknown, onEnd?: (error?: unknown) => void): Promise<number>;
     private headers;
+    /** Modern-era routing headers: `Mcp-Method` on every request, plus `Mcp-Name` carrying the
+     *  method's subject (tool name / prompt name / resource URI) so a gateway can route and
+     *  authorize without parsing the body. No-op on the handshake wire. */
+    private routingHeaders;
     /** Base headers + any OAuth bearer + per-call extras. */
     private authedHeaders;
     private post;
 }
+/** Extract the JSON-RPC response matching `id` from a JSON or SSE body. */
+/** The media-type ESSENCE of a Content-Type: type/subtype, lowercased, parameters stripped.
+ *
+ *  A substring test misroutes anything that merely *contains* the token — `application/json` with a
+ *  vendor parameter mentioning it, or a hypothetical `application/vnd.text/event-stream+json` —
+ *  while still needing to cope with the ordinary `text/event-stream; charset=utf-8`. Comparing the
+ *  essence handles both. Matches the fix upstream shipped in mcp-ts 1.30. */
+export declare function mediaTypeEssence(contentType: string): string;

package/dist/plugins/mcp/transport-stdio.d.ts

@@ -9,8 +9,10 @@ export declare class StdioTransport extends BaseJsonRpcTransport implements McpT
     private proc;
     private buffer;
     private readonly timeoutMs;
+    private readonly maxBufferSize;
     constructor(config: McpStdioConfig, opts?: {
         timeoutMs?: number;
+        maxBufferSize?: number;
     });
     start(): Promise<void>;
     setProtocolVersion(): void;

package/dist/plugins/mcp/transport-ws.d.ts

@@ -1,6 +1,16 @@
 /** WebSocket MCP transport — JSON-RPC messages as text frames over a duplex
  *  socket (naturally bidirectional). Uses the engine's `connect` so it shares
- *  the engine's WebSocket factory + hooks. Cross-env (browser + Node/Bun). */
+ *  the engine's WebSocket factory + hooks. Cross-env (browser + Node/Bun).
+ *
+ *  **NON-STANDARD, and deliberately kept.** The MCP SDK removed its own WebSocket transport in
+ *  `mcp` 2.0.0, reasoning that it "was never part of the MCP specification". Ours stays: it is
+ *  public API we shipped, and deleting an exported transport on an upstream style call would break
+ *  consumers for no protocol reason (CONSTITUTION.md R7 — an upstream deletion is not our
+ *  deletion). Treat it as a supported extra rather than a spec transport: the server has to opt
+ *  into JSON-RPC over a socket, and the standard transports remain stdio and Streamable HTTP.
+ *
+ *  Practical upside of keeping it: being duplex, it supports `subscriptions/listen` today —
+ *  which Streamable HTTP does not yet. */
 import type { EngineConnect } from '../../network/types';
 import type { McpTransport } from './transport';
 import { BaseJsonRpcTransport } from './base-transport';

package/dist/plugins/mcp/transport.d.ts

@@ -21,6 +21,17 @@ export interface McpTransport {
     setHandlers(handlers: IncomingMcpHandlers): void;
     /** Record the negotiated protocol version (HTTP sets a header; stdio ignores). */
     setProtocolVersion?(version: string): void;
+    /** Record the negotiated ERA. At `'modern'` (2026-07-28+) the wire is stateless: no
+     *  `Mcp-Session-Id`, and every request carries `Mcp-Method` / `Mcp-Name` routing headers so an
+     *  intermediary can route without parsing the body. Optional — stdio has no headers to set. */
+    setEra?(era: 'handshake' | 'modern'): void;
+    /** Send a long-lived request (`subscriptions/listen`) and return its id, without arming the
+     *  normal response timeout.
+     *
+     *  `onEnd` fires when the stream finishes — cleanly (the server tore the subscription down) or
+     *  with the error that killed it. A subscription that stops delivering is otherwise invisible to
+     *  the caller. */
+    sendLongLivedRequest?(method: string, params?: unknown, onEnd?: (error?: unknown) => void): Promise<string | number>;
     /** Open the server->client channel (HTTP GET SSE stream). Stdio is already
      *  duplex, so this is a no-op there. Call after the initialize handshake. */
     listen?(): Promise<void> | void;

package/dist/plugins/mcp/types.d.ts

@@ -52,7 +52,40 @@ export type McpContentBlock = {
     type: string;
     [k: string]: unknown;
 };
-export interface McpCallResult {
+/** One server→client request embedded in an `input_required` result: a `sampling/createMessage`,
+ *  `elicitation/create` or `roots/list`, in JSON-RPC request shape. Identical in content to what a
+ *  handshake-era server pushes over the back-channel — only the delivery differs. */
+export interface McpInputRequest {
+    method: string;
+    params?: unknown;
+}
+/** Client-side caching directives carried by 2026-07-28 list/read results (`CacheableResult`).
+ *
+ *  Optional here because every pre-2026 server omits them, and a server that sends no hints must
+ *  behave exactly as before (CONSTITUTION.md R3). */
+export interface McpCacheHints {
+    /** How long (ms) the client MAY reuse this result. **`0` means immediately stale** — re-fetch
+     *  every time — so it is NOT the same as "absent" and must not be coerced to a default. */
+    ttlMs?: number;
+    /** `'public'`: no user-specific data, any cache may serve it across authorization contexts.
+     *  `'private'`: reusable only within the same authorization context. */
+    cacheScope?: 'private' | 'public';
+}
+/** The 2026-07-28 multi-round-trip fields (SEP-2322).
+ *
+ *  Upstream models this as a separate `InputRequiredResult` type, making every result a union. We
+ *  attach it as OPTIONAL fields on the existing results instead (CONSTITUTION.md R2): code reading
+ *  `result.content` keeps compiling, and callers who never meet a modern server never see them. */
+export interface McpInputRequiredFields {
+    /** `'complete'` | `'input_required'`. **Absent MUST be read as `'complete'`** — earlier revisions
+     *  never send it. Open by R1: a future revision may add a third kind. */
+    resultType?: 'complete' | 'input_required' | (string & {});
+    /** Server-assigned key → the request to answer. Present when the server has questions. */
+    inputRequests?: Record<string, McpInputRequest>;
+    /** Opaque continuation token. Echoed back byte-exact and never inspected. */
+    requestState?: string;
+}
+export interface McpCallResult extends McpInputRequiredFields {
     content: McpContentBlock[];
     isError?: boolean;
     structuredContent?: Record<string, unknown>;
@@ -92,7 +125,7 @@ export interface McpPromptMessage {
     role: 'user' | 'assistant';
     content: McpContentBlock;
 }
-export interface McpGetPromptResult {
+export interface McpGetPromptResult extends McpInputRequiredFields {
     description?: string;
     messages: McpPromptMessage[];
 }
@@ -180,6 +213,25 @@ export interface McpInitializeResult {
     serverInfo: McpServerInfo;
     instructions?: string;
 }
+/** Result of the 2026-07-28 `server/discover` probe — the modern replacement for the `initialize`
+ *  handshake. Shape verified against mcp-py 2.0.0 (`_v2026_07_28.DiscoverResult`).
+ *
+ *  `McpClient.info` synthesises an `McpInitializeResult` from this, so a caller never has to branch
+ *  on the era (CONSTITUTION.md R2). This type exposes the fields that have no handshake equivalent. */
+export interface McpDiscoverResult {
+    capabilities: Record<string, unknown>;
+    /** Revisions the server speaks; the client picks one from this list. */
+    supportedVersions: string[];
+    /** How long (ms) the client MAY cache this result. `0` = treat as immediately stale. */
+    ttlMs?: number;
+    /** `public` = cacheable across authorization contexts; `private` = same context only. */
+    cacheScope?: 'private' | 'public';
+    instructions?: string;
+    /** Absent on servers implementing an earlier revision, which MUST be read as `'complete'`. */
+    resultType?: string;
+    /** Carries the display-only `io.modelcontextprotocol/serverInfo` stamp. */
+    _meta?: Record<string, unknown>;
+}
 export interface McpHttpConfig {
     /** Streamable-HTTP MCP endpoint URL. Cross-env (browser needs server CORS). */
     url: string;