/**
 * MCP (Model Context Protocol) type definitions.
 *
 * 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;
    method: string;
    params?: Record<string, unknown>;
}
export interface JsonRpcNotification {
    jsonrpc: "2.0";
    method: string;
    params?: Record<string, unknown>;
}
export interface JsonRpcResponse {
    jsonrpc: "2.0";
    id: string | number;
    result?: unknown;
    error?: JsonRpcError;
}
export interface JsonRpcError {
    code: number;
    message: string;
    data?: unknown;
}
export type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;
/** Authentication configuration for MCP servers */
export interface MCPAuthConfig {
    /** Authentication type */
    type: "oauth" | "apikey";
    /** Credential ID for OAuth (references agent.db) */
    credentialId?: string;
    /** Token endpoint URL — persisted for proactive token refresh */
    tokenUrl?: string;
    /** Client ID — persisted for token refresh */
    clientId?: string;
    /** Client secret — persisted for token refresh */
    clientSecret?: string;
}
/** Base server config with shared options */
export interface MCPServerConfigBase {
    /** Whether this server is enabled (default: true) */
    enabled?: boolean;
    /**
     * Whether an explicit runtime MCP consumer should connect this server
     * 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 */
    oauth?: {
        clientId?: string;
        clientSecret?: string;
        redirectUri?: string;
        callbackPort?: number;
        callbackPath?: string;
    };
}
/** Stdio server configuration */
export interface MCPStdioServerConfig extends MCPServerConfigBase {
    type?: "stdio";
    command: string;
    args?: string[];
    env?: Record<string, string>;
    /**
     * When true, the child process is NOT given the host environment. Only a
     * minimal OS allowlist (PATH/HOME/temp/locale) plus any explicit `env` keys
     * are passed. Used for third-party plugin-bundle MCP servers so they cannot
     * read host secrets from the inherited environment.
     */
    noInheritEnv?: boolean;
    cwd?: string;
}
/** HTTP server configuration (Streamable HTTP transport) */
export interface MCPHttpServerConfig extends MCPServerConfigBase {
    type: "http";
    url: string;
    headers?: Record<string, string>;
}
/** SSE server configuration (deprecated, use HTTP) */
export interface MCPSseServerConfig extends MCPServerConfigBase {
    type: "sse";
    url: string;
    headers?: Record<string, string>;
}
export type MCPServerConfig = MCPStdioServerConfig | MCPHttpServerConfig | MCPSseServerConfig;
export declare const MCP_CONFIG_SCHEMA_URL = "https://raw.githubusercontent.com/Yeachan-Heo/gajae-code/main/packages/coding-agent/src/config/mcp-schema.json";
/** Root mcp.json/.mcp.json file structure */
export interface MCPConfigFile {
    $schema?: string;
    mcpServers?: Record<string, MCPServerConfig>;
    disabledServers?: string[];
}
/** MCP implementation info */
export interface MCPImplementation {
    name: string;
    version: string;
}
/** MCP client capabilities */
export interface MCPClientCapabilities {
    roots?: {
        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 */
export interface MCPServerCapabilities {
    tools?: {
        listChanged?: boolean;
    };
    resources?: {
        subscribe?: boolean;
        listChanged?: boolean;
    };
    prompts?: {
        listChanged?: boolean;
    };
    logging?: Record<string, never>;
    experimental?: Record<string, unknown>;
}
/** Initialize request params */
export interface MCPInitializeParams {
    protocolVersion: string;
    capabilities: MCPClientCapabilities;
    clientInfo: MCPImplementation;
}
/** Initialize response result */
export interface MCPInitializeResult {
    protocolVersion: string;
    capabilities: MCPServerCapabilities;
    serverInfo: MCPImplementation;
    instructions?: string;
}
/** MCP tool definition */
export interface MCPToolDefinition {
    name: string;
    description?: string;
    inputSchema: {
        type: "object";
        properties?: Record<string, unknown>;
        required?: string[];
        [key: string]: unknown;
    };
}
/** tools/list response */
export interface MCPToolsListResult extends MCPCacheHints {
    tools: MCPToolDefinition[];
    nextCursor?: string;
}
/** tools/call params */
export interface MCPToolCallParams {
    name: string;
    arguments?: Record<string, unknown>;
}
/** Content types in tool results */
export interface MCPTextContent {
    type: "text";
    text: string;
}
export interface MCPImageContent {
    type: "image";
    data: string;
    mimeType: string;
}
export interface MCPResourceContent {
    type: "resource";
    resource: {
        uri: string;
        mimeType?: string;
        text?: string;
        blob?: string;
    };
}
export type MCPContent = MCPTextContent | MCPImageContent | MCPResourceContent;
/** tools/call response */
export interface MCPToolCallResult {
    content: MCPContent[];
    isError?: boolean;
    /** MCP result metadata, encoded as `_meta` on the wire. */
    _meta?: Record<string, unknown>;
}
/** Expected configured-server transport or protocol failure. */
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 */
    request<T = unknown>(method: string, params?: Record<string, unknown>, options?: MCPRequestOptions): Promise<T>;
    /** Send a notification (no response expected) */
    notify(method: string, params?: Record<string, unknown>): Promise<void>;
    /** Close the transport */
    close(): Promise<void>;
    /** Whether close must finish before reconnect can safely spawn a replacement. */
    readonly closeBeforeReconnect?: boolean;
    /** Whether the transport is connected */
    readonly connected: boolean;
    /** Event handlers */
    onClose?: () => void;
    onError?: (error: Error) => void;
    onNotification?: (method: string, params: unknown) => void;
    /** Handler for server-to-client requests (e.g. roots/list). Returns result or throws a JsonRpcError. */
    onRequest?: (method: string, params: unknown) => Promise<unknown>;
}
/** Transport factory function */
export type TransportFactory = (config: MCPServerConfig) => Promise<MCPTransport>;
/** Connected MCP server state */
export interface MCPServerConnection {
    /** Server name from config */
    name: string;
    /** Original config */
    config: MCPServerConfig;
    /** Transport instance */
    transport: MCPTransport;
    /** Server info from initialize */
    serverInfo: MCPImplementation;
    /** Server capabilities */
    capabilities: MCPServerCapabilities;
    /** Cached tools (populated on demand) */
    tools?: MCPToolDefinition[];
    /** Source metadata (for display) */
    _source?: SourceMeta;
    /** Cached resources (populated on demand) */
    resources?: MCPResource[];
    /** Cached resource templates (populated on demand) */
    resourceTemplates?: MCPResourceTemplate[];
    /** Server instructions from initialize */
    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 {
    server: MCPServerConnection;
    tool: MCPToolDefinition;
}
/** Annotations for resources, templates, and content blocks */
export interface MCPAnnotations {
    audience?: ("user" | "assistant")[];
    priority?: number;
    lastModified?: string;
}
/** A concrete resource exposed by an MCP server */
export interface MCPResource {
    uri: string;
    name: string;
    title?: string;
    description?: string;
    mimeType?: string;
    size?: number;
    annotations?: MCPAnnotations;
}
/** A parameterized resource template (RFC 6570 URI template) */
export interface MCPResourceTemplate {
    uriTemplate: string;
    name: string;
    title?: string;
    description?: string;
    mimeType?: string;
    annotations?: MCPAnnotations;
}
/** Result of resources/list */
export interface MCPResourcesListResult extends MCPCacheHints {
    resources: MCPResource[];
    nextCursor?: string;
}
/** Result of resources/templates/list */
export interface MCPResourceTemplatesListResult extends MCPCacheHints {
    resourceTemplates: MCPResourceTemplate[];
    nextCursor?: string;
}
/** A single content item from resources/read */
export interface MCPResourceContentItem {
    uri: string;
    mimeType?: string;
    text?: string;
    blob?: string;
}
/** Result of resources/read */
export interface MCPResourceReadResult extends MCPCacheHints {
    contents: MCPResourceContentItem[];
}
/** Params for resources/read */
export interface MCPResourceReadParams {
    uri: string;
}
/** Params for resources/subscribe and resources/unsubscribe */
export interface MCPResourceSubscribeParams {
    uri: string;
}
/** An argument definition for an MCP prompt */
export interface MCPPromptArgument {
    name: string;
    description?: string;
    required?: boolean;
}
/** A prompt definition exposed by an MCP server */
export interface MCPPrompt {
    name: string;
    title?: string;
    description?: string;
    arguments?: MCPPromptArgument[];
}
/** Result of prompts/list */
export interface MCPPromptsListResult extends MCPCacheHints {
    prompts: MCPPrompt[];
    nextCursor?: string;
}
/** Audio content in prompt messages */
export interface MCPAudioContent {
    type: "audio";
    data: string;
    mimeType: string;
}
/** Content type union for prompt messages */
export type MCPPromptContent = MCPTextContent | MCPImageContent | MCPAudioContent | MCPResourceContent;
/** A single message in a prompt result */
export interface MCPPromptMessage {
    role: "user" | "assistant";
    content: MCPPromptContent | MCPPromptContent[];
}
/** Params for prompts/get */
export interface MCPGetPromptParams {
    name: string;
    arguments?: Record<string, string>;
}
/** Result of prompts/get */
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";
    readonly RESOURCES_LIST_CHANGED: "notifications/resources/list_changed";
    readonly RESOURCES_UPDATED: "notifications/resources/updated";
    readonly PROMPTS_LIST_CHANGED: "notifications/prompts/list_changed";
};
/** Extract a JsonRpcError from a thrown value. Preserves `.code` and `.message` from Error instances or plain objects. */
export declare function toJsonRpcError(error: unknown): JsonRpcError;