MCP clients

/**
 * Returns true when the AS metadata advertises iss support (`authorization_response_iss_parameter_supported`).
 */
export declare function authorizationServerSupportsIss(asMetadata: Record<string, unknown> | null | undefined): boolean;

/**
 * MCP 2026-07-28 authorization-conformance helpers.
 *
 * Covers:
 *  - RFC 9207 `iss` parameter validation (SEP-2468) to prevent OAuth mix-up attacks
 *  - OpenID Connect Dynamic Client Registration `application_type` selection
 *  - Issuer re-registration helpers (SEP-2352)
 *
 * Designed to be invoked by callers that drive the MCP OAuth flow themselves;
 * the `@modelcontextprotocol/sdk` exposes the necessary hooks.
 */
export declare class MCPAuthError extends Error {
    constructor(message: string);
}

/** Persist in host-owned storage, never in model/tool output. Contains no credentials or task payload. */
export interface MCPPersistedTaskReference {
    version: 1;
    providerName: string;
    endpoint: string;
    taskId: string;
    identity: {
        tenantId: string;
        userId: string;
        sessionId: string;
    };
}

export interface MCPTaskSnapshot {
    handle: string;
    status: "running" | "input-required" | "completed" | "cancelled" | "failed";
    pollAfterMs?: number;
    inputRequests?: Record<string, unknown>;
    result?: ToolResult;
    error?: Record<string, unknown>;
    /** Cancellation acknowledgement is not proof that remote work stopped. */
    cancellationRequested?: boolean;
}

export declare class MCPToolError extends Error {
    readonly result: ToolResult;
    constructor(result: ToolResult);
}

/**
 * Connects to an MCP (Model Context Protocol) server and exposes its tools
 * as native Agentium ToolDef[] that any Agent can use.
 *
 * Supports stdio and HTTP (Streamable HTTP) transports.
 * Requires: npm install @modelcontextprotocol/sdk
 */
export declare class MCPToolProvider {
    readonly name: string;
    constructor(config: MCPToolProviderConfig);
    connect(): Promise<void>;
    /**
     * Returns tools from this MCP server as Agentium ToolDef[].
     * Optionally filter by tool names to reduce token usage.
     *
     * @param filter - Tool names to include (without the server name prefix).
     *                 If omitted, returns all tools.
     *
     * @example
     * // All tools
     * await mcp.getTools()
     *
     * // Only specific tools (pass the original MCP tool names, not prefixed)
     * await mcp.getTools({ include: ["get_latest_release", "search_repositories"] })
     *
     * // Exclude specific tools
     * await mcp.getTools({ exclude: ["push_files", "create_repository"] })
     */
    getTools(filter?: {
        include?: string[];
        exclude?: string[];
    }): Promise<ToolDef[]>;
    /** Refresh the tool list from the MCP server. */
    refresh(): Promise<void>;
    /** Disconnects immediately; transports acquired by an unfinished factory are closed on arrival. */
    close(): Promise<void>;
}

export interface MCPToolProviderConfig {
    name: string;
    /**
     * Transport type:
     * - `"stdio"` — spawn a local MCP server process
     * - `"http"` — Streamable HTTP transport
     * - `"sse"` — SSE transport with async responses (POST → 202, response via SSE stream).
     *   Use this when the server has separate `/sse` and `/messages` endpoints.
     */
    transport: "stdio" | "http" | "sse" | "custom";
    /** Host supplied transport; a fresh instance is required after close. */
    transportFactory?: () => Transport | Promise<Transport>;
    /** For stdio transport: command to spawn */
    command?: string;
    /** For stdio transport: args for the command */
    args?: string[];
    /** For stdio transport: environment variables */
    env?: Record<string, string>;
    /** For http/sse transport: server URL (for SSE, the SSE endpoint URL) */
    url?: string;
    /** For http/sse transport: custom headers */
    headers?: Record<string, string>;
}

/** Explicit SDK v2 adapter. Construction/root import performs no connection or SDK loading. */
export declare class MCPV2ToolProvider {
    readonly name: string;
    constructor(config: MCPV2ToolProviderConfig);
    connect(): Promise<void>;
    get protocolVersion(): string | undefined;
    getTools(filter?: {
        include?: string[];
        exclude?: string[];
    }): Promise<ToolDef[]>;
    refresh(): Promise<void>;
    /** Host-side controls: caller must retain the owning run identity. Handles are local to this connection. */
    getTask(handle: string, ctx: RunContext): Promise<MCPTaskSnapshot>;
    cancelTask(handle: string, ctx: RunContext): Promise<MCPTaskSnapshot>;
    respondToTask(handle: string, responses: Record<string, unknown>, ctx: RunContext): Promise<void>;
    /** Forget local state only. Remote execution is unaffected; cancel explicitly first when required. */
    releaseTask(handle: string, ctx: RunContext): void;
    /** Export a remote reference for an explicitly authenticated HTTP task. Local handles stay ephemeral. */
    exportTaskReference(handle: string, ctx: RunContext): MCPPersistedTaskReference;
    /** Reauthorize at the remote endpoint before creating a new handle for the current run.
     * The host must load the reference from owned storage; no task payload or grant is restored.
     */
    resumeTask(reference: MCPPersistedTaskReference, ctx: RunContext): Promise<MCPTaskSnapshot>;
    close(): Promise<void>;
}

export interface MCPV2ToolProviderConfig {
    name: string;
    transport: "stdio" | "http" | "custom";
    command?: string;
    args?: string[];
    env?: Record<string, string>;
    url?: string;
    headers?: Record<string, string>;
    /** An explicit expected resource URL when sending credentials. */
    audience?: string;
    authProvider?: OAuthClientProvider;
    /** A fresh transport for each connection. The provider owns and closes it. */
    transportFactory?: () => Transport | Promise<Transport>;
    /** Defaults to pinned 2026-07-28. Use auto for an explicit fallback policy. */
    versionNegotiation?: ClientOptions["versionNegotiation"];
    requestTimeoutMs?: number;
    inputRequired?: ClientOptions["inputRequired"];
    /** Modern Tasks extension, negotiated before any task can be accepted. */
    tasks?: boolean;
    maxTaskHandles?: number;
    onToolsChanged?: (tools: readonly ToolDef[], error?: Error) => void;
    /** Host-installed SDK elicitation handlers; no automatic user approval is supplied. */
    configureClient?: (client: Client) => void;
}

/**
 * Detect when registered client credentials need to be re-issued because the
 * resource has been migrated to a new authorization server (SEP-2352). Compare
 * the issuer recorded with the credentials against the issuer of the current
 * resource server's metadata.
 *
 * Returns true when re-registration is required.
 */
export declare function needsReRegistration(recordedIssuer: string | null | undefined, currentIssuer: string | null | undefined): boolean;

/**
 * Pick the `application_type` to send during OpenID Connect Dynamic Client
 * Registration (SEP-837). Servers default unknown clients to `"web"` which
 * rejects localhost redirect URIs on desktop / CLI clients.
 *
 * Returns `"native"` for processes that use localhost redirects (CLIs,
 * background workers, edge functions); `"web"` otherwise.
 */
export declare function pickOidcApplicationType(opts: {
    /** Will the client receive its redirect at a localhost URL? */
    usesLocalhostRedirect?: boolean;
    /** Override - returns this regardless of heuristics. */
    override?: "native" | "web";
}): "native" | "web";

/**
 * Validate the `iss` parameter on an OAuth authorization response per
 * [RFC 9207](https://www.rfc-editor.org/rfc/rfc9207.html) using simple string
 * comparison (RFC 3986 §6.2.1).
 *
 * Per SEP-2468 (MCP 2026-07-28), MCP clients MUST validate `iss` when an
 * authorization server advertises support. Pass the issuer recorded at the
 * start of the flow as `expectedIssuer`.
 *
 * @throws MCPAuthError on mismatch
 */
export declare function validateAuthIssuer(receivedIss: string | undefined, expectedIssuer: string): void;