import { CredentialsPort } from '@ai-matrx/data';
import { MatrxTransport } from '@ai-matrx/api';
import { JsonValue, PortableAgentBundle } from './index.js';

/**
 * `@ai-matrx/agents/portable/mcp` — an agent's server tools as an MCP server.
 *
 * `createAgentToolsMcpHandler` answers MCP JSON-RPC (`initialize`,
 * `tools/list`, `tools/call`, `ping`) for ONE agent. `tools/list` is the
 * bundle's server tools (resolved by the realtime-tools funnel on the server);
 * `tools/call` runs the tool through `POST /ai/tools/execute`, which
 * re-resolves the agent's set and refuses anything outside it, and writes the
 * same `cx_tool_call` row a turn-based call writes.
 *
 * Every call reads the credential FRESH from the `CredentialsPort` and carries
 * `X-Organization-Id` — nothing is cached, and the token never leaves this
 * process (the CLI only ever sees a URL). Signed out, a call answers one plain
 * sentence instead of failing obscurely.
 *
 * Transport-neutral: the host feeds it the parsed JSON body of each HTTP POST
 * (MCP "streamable HTTP") and writes back what it returns. Pure: no Node, no
 * React, no I/O at import.
 */

/** The MCP protocol revisions this handler speaks, newest first. */
declare const AGENT_TOOLS_MCP_PROTOCOL_VERSIONS: readonly ["2025-06-18", "2025-03-26", "2024-11-05"];
/** The server name the CLIs see (`mcp__matrx-agent__<tool>` in Claude Code). */
declare const AGENT_TOOLS_MCP_SERVER_NAME = "matrx-agent";
/** What a signed-out tool call answers. */
declare const SIGNED_OUT_TOOL_MESSAGE = "Sign in to AI Matrx to use this tool.";
/** What a call with no organization answers. */
declare const NO_ORGANIZATION_TOOL_MESSAGE = "Pick an organization in AI Matrx to use this tool.";
interface AgentToolsMcpOptions {
    /** The bundle the session loaded — its `tools`, agent/version identity and `surface`. */
    bundle: Pick<PortableAgentBundle, "agent_id" | "version_id" | "name" | "tools" | "surface">;
    /** The credential source, read fresh per call. `null`/absent = signed out. */
    credentials?: CredentialsPort | null;
    /** The organization every call runs in (value, or a per-call getter that may be async). */
    organizationId?: string | null | (() => string | null | undefined | Promise<string | null | undefined>);
    /** AI Matrx server base URL, no trailing slash. */
    baseUrl: string;
    /**
     * One conversation id for the whole coding session, so its tool calls group
     * under one `cx_conversation`. Default: a fresh id per handler.
     */
    conversationId?: string;
    /** Test seam: replaces the transport built from the options above. */
    transport?: MatrxTransport;
    /** Every tool call's outcome, for the host's transcript or logs. */
    onToolCall?: (event: {
        name: string;
        ok: boolean;
        callId: string;
    }) => void;
}
/** A JSON-RPC message, structurally. */
interface McpJsonRpcMessage {
    jsonrpc?: string;
    id?: string | number | null;
    method?: string;
    params?: unknown;
}
/** What the host writes back: HTTP status, plus a JSON body when there is one. */
interface McpHttpReply {
    status: number;
    body?: unknown;
}
interface AgentToolsMcpHandler {
    /** Handle one parsed HTTP POST body (a message or a batch). */
    handle(body: unknown): Promise<McpHttpReply>;
    /** The tools `tools/list` returns, in MCP shape. */
    listTools(): McpToolDescriptor[];
}
interface McpToolDescriptor {
    name: string;
    description: string;
    inputSchema: Record<string, JsonValue>;
}
declare function createAgentToolsMcpHandler(options: AgentToolsMcpOptions): AgentToolsMcpHandler;

export { AGENT_TOOLS_MCP_PROTOCOL_VERSIONS, AGENT_TOOLS_MCP_SERVER_NAME, NO_ORGANIZATION_TOOL_MESSAGE, SIGNED_OUT_TOOL_MESSAGE, createAgentToolsMcpHandler };
export type { AgentToolsMcpHandler, AgentToolsMcpOptions, McpHttpReply, McpJsonRpcMessage, McpToolDescriptor };