@gajae-code/coding-agent 0.13.3 → 0.14.0

package/dist/types/runtime-mcp/protocol.d.ts

@@ -0,0 +1,278 @@
+/**
+ * MCP protocol generation model ("MCP v2", specification 2026-07-28).
+ *
+ * Canonical authority (verified against the primary sources, not secondary
+ * summaries):
+ * - https://modelcontextprotocol.io/specification/2026-07-28/basic
+ * - https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http
+ * - https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning
+ * - https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/mrtr
+ * - https://modelcontextprotocol.io/specification/2026-07-28/server/discover
+ * - https://modelcontextprotocol.io/specification/2026-07-28/server/utilities/caching
+ * - schema source of truth: modelcontextprotocol/specification schema/2026-07-28/schema.ts
+ *
+ * 2026-07-28 ("modern" era) removes the initialize/initialized handshake,
+ * protocol sessions (`Mcp-Session-Id`), the standalone GET SSE stream, and
+ * `Last-Event-ID` replay from the core request path. Every request carries its
+ * protocol version, client identity, and client capabilities in `_meta`, and
+ * Streamable HTTP mirrors selected fields into `MCP-Protocol-Version`,
+ * `Mcp-Method`, and `Mcp-Name` headers.
+ */
+/** The modern (stateless) protocol revision implemented by this client. */
+export declare const MCP_PROTOCOL_VERSION_2026_07_28 = "2026-07-28";
+/** Legacy (initialize handshake) revision this client speaks for compatibility. */
+export declare const MCP_PROTOCOL_VERSION_LEGACY = "2025-03-26";
+/** Modern-era revisions this client can speak, most preferred first. */
+export declare const MCP_MODERN_PROTOCOL_VERSIONS: readonly string[];
+/** Protocol generation: modern = per-request metadata (2026-07-28+), legacy = initialize handshake. */
+export type MCPProtocolEra = "modern" | "legacy";
+/**
+ * Per-server protocol preference from configuration.
+ * - `auto`: attempt modern first; bounded, observable legacy fallback per the
+ *   specification's era-detection rules. Default when unset.
+ * - `2026-07-28`: strict modern-only; never initializes a legacy session.
+ * - `legacy`: bounded compatibility mode; always uses the legacy handshake.
+ */
+export type MCPProtocolPreference = "auto" | "2026-07-28" | "legacy";
+export declare const MCP_PROTOCOL_PREFERENCES: readonly MCPProtocolPreference[];
+export declare function isMCPProtocolPreference(value: unknown): value is MCPProtocolPreference;
+/** Resolve the effective preference; `auto` when unset. */
+export declare function resolveMCPProtocolPreference(value: MCPProtocolPreference | undefined): MCPProtocolPreference;
+/** True when a version string names a modern-era revision (date-based, >= 2026-07-28). */
+export declare function isModernProtocolVersion(version: string): boolean;
+/** Headers do not match the request body, or required headers are missing/malformed. */
+export declare const MCP_ERROR_HEADER_MISMATCH = -32020;
+/** The request requires a client capability the client did not declare. */
+export declare const MCP_ERROR_MISSING_REQUIRED_CLIENT_CAPABILITY = -32021;
+/** The server does not implement the requested protocol version. */
+export declare const MCP_ERROR_UNSUPPORTED_PROTOCOL_VERSION = -32022;
+/** Standard JSON-RPC method-not-found (modern servers pair it with HTTP 404). */
+export declare const JSONRPC_ERROR_METHOD_NOT_FOUND = -32601;
+/** Standard JSON-RPC invalid-params (modern servers reject missing `_meta` with it). */
+export declare const JSONRPC_ERROR_INVALID_PARAMS = -32602;
+export declare const MCP_META_PROTOCOL_VERSION = "io.modelcontextprotocol/protocolVersion";
+export declare const MCP_META_CLIENT_INFO = "io.modelcontextprotocol/clientInfo";
+export declare const MCP_META_CLIENT_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities";
+export declare const MCP_META_SERVER_INFO = "io.modelcontextprotocol/serverInfo";
+/** Client identity advertised in modern per-request `_meta`. */
+export interface MCPModernClientContext {
+    protocolVersion: string;
+    clientInfo: {
+        name: string;
+        version: string;
+    };
+    /** Capabilities relevant to requests, e.g. `{ roots: {...}, elicitation: {...} }`. */
+    capabilities: Record<string, unknown>;
+}
+/**
+ * Build the `_meta` object every modern request MUST carry. Callers merge this
+ * into `params._meta`, preserving any pre-existing keys (e.g. `progressToken`).
+ */
+export declare function buildModernRequestMeta(context: MCPModernClientContext): Record<string, unknown>;
+/** Merge modern `_meta` into request params without clobbering existing keys. */
+export declare function withModernMeta(params: Record<string, unknown>, context: MCPModernClientContext): Record<string, unknown>;
+/** RFC 9110 field-value safe set: visible ASCII, space, and horizontal tab. */
+export declare function isPlainAsciiHeaderValue(value: string): boolean;
+/**
+ * Encode a value for `Mcp-Name` / `Mcp-Param-{Name}` headers: plain ASCII when
+ * safe, otherwise the `=?base64?<base64-utf8>?=` sentinel. Values already
+ * matching the sentinel pattern MUST also be encoded to avoid ambiguity.
+ */
+export declare function encodeMcpHeaderValue(value: string): string;
+/**
+ * Build the mirrored headers a modern Streamable HTTP request MUST carry:
+ * `MCP-Protocol-Version` (must equal the `_meta` version), `Mcp-Method`, and —
+ * for `tools/call`, `resources/read`, `prompts/get` — `Mcp-Name`.
+ */
+export declare function buildModernMcpHeaders(input: {
+    protocolVersion: string;
+    method: string;
+    params?: Record<string, unknown>;
+}): Record<string, string>;
+/** A validated binding from a tool inputSchema property to an `Mcp-Param-*` header. */
+export interface McpHeaderParamBinding {
+    /** Exact property path (chain of `properties` keys) in the call arguments. */
+    propertyPath: string[];
+    /** The `name` portion of the `Mcp-Param-{name}` header. */
+    headerName: string;
+    /** Primitive type of the annotated property. */
+    propertyType: "string" | "integer" | "boolean";
+}
+export interface XMcpHeaderBindingsResult {
+    bindings: McpHeaderParamBinding[];
+    /** Human-readable reasons the tool definition is invalid for HTTP mirroring. */
+    violations: string[];
+}
+/**
+ * Collect `x-mcp-header` bindings from a tool `inputSchema`, enforcing the
+ * specification constraints: field-name token syntax, primitive (non-number)
+ * types, case-insensitive uniqueness, and static reachability via `properties`
+ * chains only. Any violation invalidates the tool definition for HTTP clients.
+ */
+export declare function collectXMcpHeaderBindings(inputSchema: unknown): XMcpHeaderBindingsResult;
+/**
+ * Extract `Mcp-Param-{name}` headers from tool call arguments per validated
+ * bindings. Missing or null values omit the header, per the specification.
+ */
+export declare function buildXMcpParamHeaders(bindings: readonly McpHeaderParamBinding[], args: Record<string, unknown>): Record<string, string>;
+/** Failure classes for a modern probe request. */
+export type MCPProbeFailureClass = 
+/** Recognized modern JSON-RPC error: the server speaks a modern revision. */
+"modern-error"
+/** 4xx without a recognized modern error body: legacy-era server signal. */
+ | "legacy-signal"
+/** 401/403 (and WWW-Authenticate challenges): never a downgrade signal. */
+ | "auth-failure"
+/** Anything else (5xx, network, malformed payload): not a downgrade signal. */
+ | "other-failure";
+export interface MCPProbeClassification {
+    class: MCPProbeFailureClass;
+    /** Protocol-defined modern error code when recognized. */
+    modernErrorCode?: number;
+    /** `data.supported` from an UnsupportedProtocolVersionError, when present. */
+    supportedVersions?: string[];
+    /** `data.requested` from an UnsupportedProtocolVersionError, when present. */
+    requestedVersion?: string;
+}
+/**
+ * Classify a failed modern probe per the specification's era-detection rules:
+ * recognized modern JSON-RPC errors identify a modern server; a 400/404/405
+ * without one identifies a legacy server; auth and security failures are never
+ * era signals and must never authorize a downgrade.
+ */
+export declare function classifyMcpProbeFailure(status: number, parsedBody: unknown): MCPProbeClassification;
+/** Lifecycle state of a protocol feature, mirroring the specification's feature lifecycle. */
+export type MCPFeatureLifecycle = "active" | "deprecated" | "removed";
+export interface MCPProtocolFeatureState {
+    feature: string;
+    lifecycle: MCPFeatureLifecycle;
+    /** Secret-free explanation shown in diagnostics. */
+    note?: string;
+}
+/** How the effective era/version was reached. */
+export type MCPNegotiationState = 
+/** No negotiation attempt has completed yet. */
+"pending"
+/** Modern era confirmed (probe or direct modern request succeeded). */
+ | "modern"
+/** Modern era after selecting a mutually supported version from UnsupportedProtocolVersionError. */
+ | "modern-version-retry"
+/** Legacy era via era detection (legacy server signal) under `auto`. */
+ | "legacy-fallback"
+/** Legacy era because configuration forced it (`legacy`) or the transport is stdio. */
+ | "legacy-forced"
+/** Negotiation failed; the connection could not be established. */
+ | "failed";
+/** Machine-readable reasons a legacy fallback was engaged (never auth/security driven). */
+export type MCPDowngradeReason = 
+/** `protocol: "legacy"` configured explicitly. */
+"preference-legacy"
+/** stdio transport has no per-request HTTP signals; legacy handshake retained. */
+ | "stdio-transport"
+/** Probe returned 400/404/405 without a recognized modern error body. */
+ | "legacy-server-signal"
+/** A modern server advertised only legacy-era versions in `supported`. */
+ | "server-advertised-legacy-only";
+/**
+ * One authoritative, secret-free observation of a server's negotiated protocol
+ * state. Consumed by `/extensions` (#4291) and customization doctor (#4288);
+ * contains no credentials, tokens, metadata documents, or header values.
+ */
+export interface MCPProtocolObservation {
+    /** Configured preference (defaults to `auto`). */
+    preference: MCPProtocolPreference;
+    /** Effective protocol version in use, once negotiated. */
+    effectiveVersion: string | null;
+    /** Effective era, once negotiated. */
+    era: MCPProtocolEra | null;
+    /** How the effective state was reached. */
+    negotiation: MCPNegotiationState;
+    /** Why a legacy fallback engaged; null unless `negotiation` is a legacy state. */
+    downgradeReason: MCPDowngradeReason | null;
+    /** Versions the server advertised (via server/discover or version errors). */
+    supportedVersions: string[];
+    /** Self-reported server identity (display only; never security-relevant). */
+    serverInfo: {
+        name: string;
+        version: string;
+    } | null;
+    /** Lifecycle visibility for protocol features (legacy session behavior, etc). */
+    features: MCPProtocolFeatureState[];
+    /** v2 capability state observed for this connection. */
+    capabilities: {
+        /** server/discover answered (optional per spec; absence does not block calls). */
+        discover: "yes" | "no" | "unknown";
+        /** Server advertised tools capability. */
+        tools: boolean;
+        /** Server advertised resources capability. */
+        resources: boolean;
+        /** Server advertised prompts capability. */
+        prompts: boolean;
+    };
+}
+/** Initial observation before negotiation completes. */
+export declare function createMCPProtocolObservation(preference: MCPProtocolPreference): MCPProtocolObservation;
+/** Legacy session/transport features reported as deprecated under the feature lifecycle. */
+export declare function legacyEraFeatureStates(): MCPProtocolFeatureState[];
+/** Finalize an observation for a negotiated modern connection. */
+export declare function modernEraObservation(input: {
+    preference: MCPProtocolPreference;
+    effectiveVersion: string;
+    negotiation: "modern" | "modern-version-retry";
+    supportedVersions?: string[];
+    serverInfo?: {
+        name: string;
+        version: string;
+    } | null;
+    capabilities?: {
+        tools?: boolean;
+        resources?: boolean;
+        prompts?: boolean;
+    };
+    discover: "yes" | "no" | "unknown";
+}): MCPProtocolObservation;
+/** Finalize an observation for a negotiated legacy connection. */
+export declare function legacyEraObservation(input: {
+    preference: MCPProtocolPreference;
+    effectiveVersion: string;
+    negotiation: "legacy-fallback" | "legacy-forced";
+    downgradeReason: MCPDowngradeReason;
+    serverInfo?: {
+        name: string;
+        version: string;
+    } | null;
+    capabilities?: {
+        tools?: boolean;
+        resources?: boolean;
+        prompts?: boolean;
+    };
+}): MCPProtocolObservation;
+/** Cache scope hint: public results may cross authorization contexts; private must not. */
+export type MCPCacheScope = "public" | "private";
+/** Server-supplied caching hints carried on cacheable `complete` results. */
+export interface MCPCacheHints {
+    /** Milliseconds the result may be considered fresh; absent/negative means 0. */
+    ttlMs?: number;
+    cacheScope?: MCPCacheScope;
+}
+/** Normalize raw hints: negative ttlMs is treated as 0 per the specification. */
+export declare function normalizeMcpCacheHints(raw: unknown): MCPCacheHints | undefined;
+/** Result type marker for interim input requests. */
+export declare const MCP_RESULT_TYPE_INPUT_REQUIRED = "input_required";
+export declare const MCP_RESULT_TYPE_COMPLETE = "complete";
+/** Input request methods a server may embed in an InputRequiredResult. */
+export declare const MCP_INPUT_REQUEST_METHODS: Set<string>;
+export interface MCPInputRequiredData {
+    inputRequests: Record<string, {
+        method: string;
+        params?: Record<string, unknown>;
+    }>;
+    requestState?: string;
+}
+/**
+ * Extract MRTR input data from a JSON-RPC result. Returns null when the result
+ * is a normal `complete` result (including legacy results with no resultType,
+ * which the specification requires clients to treat as `"complete"`).
+ * Throws on a malformed `input_required` payload.
+ */
+export declare function extractMcpInputRequired(result: unknown): MCPInputRequiredData | null;

package/dist/types/runtime-mcp/scope-config.d.ts

@@ -0,0 +1,29 @@
+import { type UpsertMCPServerResult } from "./config-writer";
+import type { MCPConfigFile, MCPServerConfig } from "./types";
+export type MCPConfigScope = "user" | "project";
+/** Resolved scope + path + parsed config (provenance for diagnostics). */
+export interface ScopeMCPConfigSnapshot {
+    scope: MCPConfigScope;
+    path: string;
+    config: MCPConfigFile;
+}
+/** Resolve the canonical file path for a native MCP config scope. */
+export declare function resolveScopeMCPConfigPath(scope: MCPConfigScope, cwd?: string): string;
+/** Read a native MCP config for a scope. Returns an empty config when absent. */
+export declare function readScopeMCPConfig(scope: MCPConfigScope, cwd?: string): Promise<ScopeMCPConfigSnapshot>;
+/** Add a server, or overwrite an existing one only when `force` is set. */
+export declare function upsertScopeMCPServer(scope: MCPConfigScope, name: string, config: MCPServerConfig, options?: {
+    force?: boolean;
+}, cwd?: string): Promise<ScopeMCPConfigSnapshot & {
+    result: UpsertMCPServerResult;
+}>;
+/** Remove a server from a scope (throws when the name does not exist). */
+export declare function removeScopeMCPServer(scope: MCPConfigScope, name: string, cwd?: string): Promise<ScopeMCPConfigSnapshot>;
+/** Get a specific server config from a scope. */
+export declare function getScopeMCPServer(scope: MCPConfigScope, name: string, cwd?: string): Promise<{
+    scope: MCPConfigScope;
+    path: string;
+    config: MCPServerConfig | undefined;
+}>;
+/** Read the disabled-servers denylist for a scope. */
+export declare function readScopeDisabledServers(scope: MCPConfigScope, cwd?: string): Promise<string[]>;

package/dist/types/runtime-mcp/tool-bridge.d.ts

@@ -9,10 +9,20 @@ import type { SourceMeta } from "../capability/types";
 import type { CustomTool, CustomToolContext, CustomToolResult, RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import type { MCPPoolLease } from "./pool";
-import type { MCPContent, MCPServerConnection, MCPToolDefinition } from "./types";
+import type { MCPContent, MCPInputRequestHandler, MCPServerConnection, MCPToolDefinition } from "./types";
 /** Reconnect callback: tears down stale connection, returns new one or null. */
 export type MCPReconnect = () => Promise<MCPServerConnection | null>;
 type MCPToolTarget = MCPServerConnection | MCPPoolLease;
+/** Options shared by MCPTool and DeferredMCPTool. */
+export interface MCPToolOptions {
+    /** Shared lease policy: never retry the original request after transport/auth failure. */
+    noReplay?: boolean;
+    /**
+     * Lazy resolver for the modern MRTR `input_required` handler, registered by the
+     * owning manager/runtime. Resolved per call so late registration still applies.
+     */
+    inputHandler?: () => MCPInputRequestHandler | undefined;
+}
 export declare function isRetriableConnectionError(error: unknown): boolean;
 /** Details included in MCP tool results for rendering */
 export interface MCPToolDetails {
@@ -57,12 +67,8 @@ export declare class MCPTool implements CustomTool<TSchema, MCPToolDetails> {
     readonly mcpServerName: string;
     private connection;
     /** Create MCPTool instances for all tools from an MCP server lease/connection. */
-    static fromTools(target: MCPToolTarget, tools: MCPToolDefinition[], reconnect?: MCPReconnect, options?: {
-        noReplay?: boolean;
-    }): MCPTool[];
-    constructor(target: MCPToolTarget, tool: MCPToolDefinition, reconnect?: MCPReconnect | undefined, options?: {
-        noReplay?: boolean;
-    });
+    static fromTools(target: MCPToolTarget, tools: MCPToolDefinition[], reconnect?: MCPReconnect, options?: MCPToolOptions): MCPTool[];
+    constructor(target: MCPToolTarget, tool: MCPToolDefinition, reconnect?: MCPReconnect | undefined, options?: MCPToolOptions);
     renderCall(args: unknown, _options: RenderResultOptions, theme: Theme): import("@gajae-code/tui").Component;
     renderResult(result: CustomToolResult<MCPToolDetails>, options: RenderResultOptions, theme: Theme, args?: unknown): import("@gajae-code/tui").Component;
     execute(_toolCallId: string, params: unknown, _onUpdate: AgentToolUpdateCallback<MCPToolDetails> | undefined, _ctx: CustomToolContext, signal?: AbortSignal): Promise<CustomToolResult<MCPToolDetails>>;
@@ -85,12 +91,8 @@ export declare class DeferredMCPTool implements CustomTool<TSchema, MCPToolDetai
     /** Server name */
     readonly mcpServerName: string;
     /** Create DeferredMCPTool instances for all tools from an MCP server */
-    static fromTools(serverName: string, tools: MCPToolDefinition[], getConnection: () => Promise<MCPServerConnection>, source?: SourceMeta, reconnect?: MCPReconnect, options?: {
-        noReplay?: boolean;
-    }): DeferredMCPTool[];
-    constructor(serverName: string, tool: MCPToolDefinition, getConnection: () => Promise<MCPServerConnection>, source?: SourceMeta, reconnect?: MCPReconnect | undefined, options?: {
-        noReplay?: boolean;
-    });
+    static fromTools(serverName: string, tools: MCPToolDefinition[], getConnection: () => Promise<MCPServerConnection>, source?: SourceMeta, reconnect?: MCPReconnect, options?: MCPToolOptions): DeferredMCPTool[];
+    constructor(serverName: string, tool: MCPToolDefinition, getConnection: () => Promise<MCPServerConnection>, source?: SourceMeta, reconnect?: MCPReconnect | undefined, options?: MCPToolOptions);
     renderCall(args: unknown, _options: RenderResultOptions, theme: Theme): import("@gajae-code/tui").Component;
     renderResult(result: CustomToolResult<MCPToolDetails>, options: RenderResultOptions, theme: Theme, args?: unknown): import("@gajae-code/tui").Component;
     execute(_toolCallId: string, params: unknown, _onUpdate: AgentToolUpdateCallback<MCPToolDetails> | undefined, _ctx: CustomToolContext, signal?: AbortSignal): Promise<CustomToolResult<MCPToolDetails>>;

package/dist/types/runtime-mcp/transports/http.d.ts

@@ -1,4 +1,5 @@
 import type { MCPHttpServerConfig, MCPRequestOptions, MCPSseServerConfig, MCPTransport } from "../../runtime-mcp/types";
+import { type MCPModernClientContext, type MCPProtocolEra } from "../protocol";
 /**
  * HTTP transport for MCP servers.
  * Uses POST for requests, supports SSE responses.
@@ -16,6 +17,14 @@ export declare class HttpTransport implements MCPTransport {
     get connected(): boolean;
     get closeBeforeReconnect(): false;
     get url(): string;
+    /** Negotiated protocol era (defaults to legacy until the client negotiates). */
+    get era(): MCPProtocolEra;
+    /**
+     * Select the protocol era. Modern mode requires the per-request client
+     * context (protocol version, identity, capabilities) mirrored into `_meta`
+     * and HTTP headers on every request.
+     */
+    setProtocolMode(era: MCPProtocolEra, modernContext?: MCPModernClientContext): void;
     /**
      * Mark transport as connected.
      * HTTP doesn't need persistent connection, but we track state.

package/dist/types/runtime-mcp/types.d.ts

@@ -1,10 +1,12 @@
 /**
  * MCP (Model Context Protocol) type definitions.
  *
- * Based on MCP specification 2025-03-26:
- * https://modelcontextprotocol.io/specification/2025-03-26/
+ * Legacy sessionful surface based on MCP specification 2025-03-26; the modern
+ * stateless generation (2026-07-28, "MCP v2") is modeled in ./protocol.ts.
+ * https://modelcontextprotocol.io/specification/2026-07-28/
  */
 import type { SourceMeta } from "../capability/types";
+import type { MCPCacheHints, MCPProtocolObservation, MCPProtocolPreference } from "./protocol";
 export interface JsonRpcRequest {
     jsonrpc: "2.0";
     id: string | number;
@@ -47,15 +49,23 @@ export interface MCPServerConfigBase {
     enabled?: boolean;
     /**
      * Whether an explicit runtime MCP consumer should connect this server
-     * automatically when that consumer starts (default: true). Normal standalone
-     * `gjc`, `gjc --tmux`, and print-mode sessions do not consume `gjc mcp`
-     * registrations today.
+     * automatically when that consumer starts (default: true). Ordinary
+     * standalone `gjc`, `gjc --tmux`, and print-mode sessions honor autoload for
+     * conventional registrations; `autoload: false` keeps a server configured
+     * for on-demand `/mcp` connection. `--no-mcp` opts a session out entirely.
      */
     autoload?: boolean;
     /** Connection timeout in milliseconds (default: 30000) */
     timeout?: number;
     /** Pool identity mode. W2 defaults to one physical connection per session. */
     sharing?: "per-session" | "shared";
+    /**
+     * Protocol preference for remote (http/sse) servers: `auto` (default) negotiates
+     * the modern 2026-07-28 stateless protocol first with a bounded, observable
+     * legacy fallback; `2026-07-28` is strict modern-only; `legacy` forces the
+     * bounded compatibility handshake. Ignored by stdio servers (always legacy-era).
+     */
+    protocol?: MCPProtocolPreference;
     /** Authentication configuration (optional) */
     auth?: MCPAuthConfig;
     /** OAuth configuration for servers requiring explicit client credentials */
@@ -113,6 +123,10 @@ export interface MCPClientCapabilities {
         listChanged?: boolean;
     };
     sampling?: Record<string, never>;
+    /** Form-mode elicitation support (modern MRTR `elicitation/create` input requests). */
+    elicitation?: {
+        form?: Record<string, never>;
+    };
     experimental?: Record<string, unknown>;
 }
 /** MCP server capabilities */
@@ -155,7 +169,7 @@ export interface MCPToolDefinition {
     };
 }
 /** tools/list response */
-export interface MCPToolsListResult {
+export interface MCPToolsListResult extends MCPCacheHints {
     tools: MCPToolDefinition[];
     nextCursor?: string;
 }
@@ -195,12 +209,66 @@ export interface MCPToolCallResult {
 export declare class MCPExpectedFailure extends Error {
     constructor(cause?: unknown);
 }
+/** HTTP-level request failure carrying structured detail for era classification. */
+export declare class MCPHttpRequestError extends Error {
+    /** HTTP status code. */
+    readonly status: number;
+    /** Parsed JSON body when the error payload was JSON; undefined otherwise. */
+    readonly body: unknown;
+    constructor(status: number, message: string, body?: unknown);
+}
+/** JSON-RPC error response failure carrying the protocol error code. */
+export declare class MCPJsonRpcError extends Error {
+    readonly code: number;
+    readonly data?: unknown;
+    constructor(code: number, message: string, data?: unknown);
+}
 export interface MCPRequestOptions {
     /** Abort signal (e.g. Escape-to-interrupt) */
     signal?: AbortSignal;
     /** Shared lease policy: never retry the original request after transport/auth failure. */
     noReplay?: boolean;
+    /**
+     * Handler for modern MRTR `input_required` results (elicitation, roots, sampling).
+     * When absent, an `input_required` result fails explicitly instead of hanging.
+     */
+    inputHandler?: MCPInputRequestHandler;
+    /** Extra mirrored headers for modern requests (`Mcp-Param-*` from x-mcp-header bindings). */
+    mcpParamHeaders?: Record<string, string>;
+}
+/** Context for one server input request gathered during a modern MRTR exchange. */
+export interface MCPInputRequestContext {
+    /** Server being called. */
+    serverName: string;
+    /** Original client request method (`tools/call`, `prompts/get`, `resources/read`). */
+    originMethod: string;
+    /**
+     * Stable correlation id shared by the initial request and its exactly-once
+     * retry, fencing the accepted input to this exchange.
+     */
+    correlationId: string;
+    /** Request-scoped abort signal (cancellation/timeout of the original call). */
+    signal?: AbortSignal;
 }
+/**
+ * Outcome of gathering one server input request. `result` values are placed in
+ * the retry's `inputResponses` under the request key. `failed` outcomes abort
+ * the MRTR exchange with an explicit error — except elicitation decline/cancel,
+ * which the handler expresses as an ElicitResult-shaped `result`.
+ */
+export type MCPInputRequestHandlerResult = {
+    kind: "result";
+    result: unknown;
+} | {
+    kind: "failed";
+    reason: "declined" | "cancelled" | "timeout" | "unavailable" | "error";
+    message?: string;
+};
+/** Handler for one server input request inside an `input_required` result. */
+export type MCPInputRequestHandler = (key: string, request: {
+    method: string;
+    params?: Record<string, unknown>;
+}, context: MCPInputRequestContext) => Promise<MCPInputRequestHandlerResult>;
 /** Transport interface - abstracts stdio/http */
 export interface MCPTransport {
     /** Send a request and wait for response */
@@ -246,6 +314,15 @@ export interface MCPServerConnection {
     instructions?: string;
     /** Cached prompts (populated on demand) */
     prompts?: MCPPrompt[];
+    /**
+     * Authoritative protocol observation for this connection (preference,
+     * negotiated era/version, downgrade decision, deprecation state). Secret-free.
+     */
+    protocol: MCPProtocolObservation;
+    /** Freshness deadline (ms epoch) for the cached tool catalog, from server ttlMs hints. */
+    toolsFreshUntil?: number;
+    /** Cache scope of the cached tool catalog; private entries never cross credential identities. */
+    toolsCacheScope?: "public" | "private";
 }
 /** MCP tool with server context */
 export interface MCPToolWithServer {
@@ -278,12 +355,12 @@ export interface MCPResourceTemplate {
     annotations?: MCPAnnotations;
 }
 /** Result of resources/list */
-export interface MCPResourcesListResult {
+export interface MCPResourcesListResult extends MCPCacheHints {
     resources: MCPResource[];
     nextCursor?: string;
 }
 /** Result of resources/templates/list */
-export interface MCPResourceTemplatesListResult {
+export interface MCPResourceTemplatesListResult extends MCPCacheHints {
     resourceTemplates: MCPResourceTemplate[];
     nextCursor?: string;
 }
@@ -295,7 +372,7 @@ export interface MCPResourceContentItem {
     blob?: string;
 }
 /** Result of resources/read */
-export interface MCPResourceReadResult {
+export interface MCPResourceReadResult extends MCPCacheHints {
     contents: MCPResourceContentItem[];
 }
 /** Params for resources/read */
@@ -320,7 +397,7 @@ export interface MCPPrompt {
     arguments?: MCPPromptArgument[];
 }
 /** Result of prompts/list */
-export interface MCPPromptsListResult {
+export interface MCPPromptsListResult extends MCPCacheHints {
     prompts: MCPPrompt[];
     nextCursor?: string;
 }
@@ -347,6 +424,21 @@ export interface MCPGetPromptResult {
     description?: string;
     messages: MCPPromptMessage[];
 }
+/** Result of the optional modern `server/discover` request. */
+export interface MCPDiscoverResult extends MCPCacheHints {
+    /** Protocol versions the server supports. */
+    supportedVersions: string[];
+    /** Capabilities the server supports. */
+    capabilities: MCPServerCapabilities;
+    /** Optional natural-language usage guidance. */
+    instructions?: string;
+    /** Result metadata; `io.modelcontextprotocol/serverInfo` carries the identity. */
+    _meta?: Record<string, unknown>;
+}
+/** Decoded `server/discover` payload with the extracted server identity. */
+export interface MCPDiscoverResultLite extends MCPDiscoverResult {
+    serverInfo?: MCPImplementation;
+}
 /** MCP server notification method names */
 export declare const MCPNotificationMethods: {
     readonly TOOLS_LIST_CHANGED: "notifications/tools/list_changed";

package/dist/types/sdk/acp/adapter.d.ts

@@ -1,4 +1,6 @@
-import { SdkClient, SdkClientError, type SdkFrame } from "../client";
+import { type SdkClient, SdkClientError } from "../client";
+import type { AbortScope } from "../host/control/operations";
+import { type SessionAttachment, type SessionRouter } from "../router";
 import { ACP_SESSION_RECONNECT } from "../session-reconnect";
 import type { SessionLifecycleMcpServer } from "./mcp";
 type JsonObject = Record<string, unknown>;
@@ -14,9 +16,11 @@ export interface AcpProviderRegistration {
     definitions: unknown;
 }
 export interface AcpSdkAdapterOptions {
-    url: string;
-    token: string;
+    /** Broker lifecycle transport only. Live session work requires `router` plus an opaque attachment. */
     client?: SdkClient;
+    router?: SessionRouter;
+    attachment?: SessionAttachment;
+    sessionId?: string;
     connection?: AcpReverseConnection;
     providers?: AcpProviderRegistration[];
     /** Lease IDs persisted by the ACP host across a WebSocket reconnect. */
@@ -34,7 +38,7 @@ export declare class AcpSdkAdapterError extends Error {
  */
 export declare function acpMcpLaunchFailure(error: unknown, mcpServers: SessionLifecycleMcpServer[]): unknown;
 export type AcpReconnectFailedHandler = (error: SdkClientError) => void;
-export type AcpFrameHandler = (frame: SdkFrame) => void;
+export type AcpFrameHandler = (frame: Record<string, unknown>) => void;
 export { ACP_SESSION_RECONNECT };
 /**
  * Pure ACP-to-SDK adapter. It deliberately owns neither an AgentSession nor an
@@ -44,6 +48,10 @@ export declare class AcpSdkAdapter {
     #private;
     constructor(options: AcpSdkAdapterOptions);
     static connect(options: AcpSdkAdapterOptions): Promise<AcpSdkAdapter>;
+    acceptAttachment(attachment: SessionAttachment): void;
+    revokeAttachment(attachment: SessionAttachment): void;
+    attachmentReady(attachment: SessionAttachment): Promise<void>;
+    acceptFrame(frame: Record<string, unknown>): void;
     get leaseIds(): ReadonlyMap<string, string>;
     get connectionId(): string | undefined;
     onReconnectFailed(handler: AcpReconnectFailedHandler): () => void;
@@ -51,11 +59,24 @@ export declare class AcpSdkAdapter {
     start(): Promise<void>;
     close(): Promise<void>;
     prompt(params: JsonObject | string): Promise<unknown>;
-    cancel(): Promise<unknown>;
+    /**
+     * Ends the active turn with a C04 terminal abort. The default `scope:"turn"`
+     * only stops the current turn, matching the SDK `turn.abort` default and
+     * other ACP clients' cancel behavior; `scope:"owned"` additionally stops
+     * exact causal owned work (background Bash/task jobs, detached subagents) so
+     * an external client can terminate everything a turn spawned. Paseo keeps
+     * owned cancels through its provider config env
+     * (`GJC_ACP_ABORT_SCOPE=owned`) without source changes. A fresh bounded
+     * idempotency key per call keeps terminal-abort replay deterministic across
+     * retries.
+     */
+    cancel(scope?: AbortScope): Promise<unknown>;
     setModel(params: JsonObject | string): Promise<unknown>;
     control(operation: string, input?: JsonObject): Promise<unknown>;
     query(query: string, input?: JsonObject, cursor?: string): Promise<unknown>;
     global(operation: string, input?: JsonObject, idempotencyKey?: string): Promise<unknown>;
+    /** Uses lifecycle endpoint credentials only inside the ACP session owner. */
+    lifecycle(operation: string, input?: JsonObject, idempotencyKey?: string): Promise<unknown>;
     sdkControl(params: {
         operation: string;
         input?: JsonObject;