/**
 * Utility for making authenticated calls to the Amplitude MCP server with
 * automatic Claude agent fallback.
 *
 * When the direct HTTP call fails (tool removed, auth error, parse failure,
 * etc.) the function re-runs the same query via a minimal Claude agent that
 * has only the Amplitude MCP server configured. This insulates callers from
 * MCP API drift without requiring them to write two code paths.
 */
/**
 * Default MCP URL when no zone is known to the caller.
 *
 * Most consumers (`agent-runner`, `agent-interface.buildDefaultAgentConfig`,
 * `addMCPServerToClientsStep`) DO know the zone and should pass `mcpUrl`
 * explicitly via `getMcpUrlFromZone(zone)`. This constant exists for the
 * narrow set of callers that genuinely have no zone context (bootstrap
 * paths, test mocks); falling back to US matches the historical behaviour.
 *
 * Honors the `MCP_URL` env override for tests / dev.
 */
export declare const AMPLITUDE_MCP_URL: string;
/**
 * Drop cached MCP sessions. Pass an `accessToken` to invalidate only
 * that token's entries (e.g. on token refresh); omit to clear every
 * cached session (e.g. on logout). The auth/token-refresh path should
 * call this so the next `callAmplitudeMcp` rehandshakes with the new
 * token instead of failing on a stale `Authorization: Bearer` header.
 */
export declare function invalidateMcpSessionCache(accessToken?: string): void;
/** Test-only: clear the cache between unit-test cases. */
export declare function _clearMcpSessionCacheForTesting(): void;
/**
 * Drop every cached MCP session bound to `accessToken`. Call after
 * silently refreshing the OAuth token so the next `callAmplitudeMcp`
 * doesn't reuse a `callTool` closure carrying the now-expired bearer
 * (which would 401 on the upstream and force the slower agent fallback
 * for ~12s, even though we already have a fresh token in hand).
 *
 * Idempotent — no-op when no entries match.
 */
export declare function invalidateMcpSessionsForToken(accessToken: string): void;
/**
 * Optional progress hook for the agent fallback. Invoked once per `tool_use`
 * block the model emits so callers can surface human-readable status updates
 * (e.g. "Creating chart in Amplitude…") instead of leaving the user staring
 * at a static spinner for the duration of the fallback's timeout budget.
 *
 * Receives:
 *   - `name` — the SDK tool name as the model called it. For MCP tools this is
 *     prefixed `mcp__<server>__<tool>` (e.g. `mcp__amplitude__create_chart`).
 *   - `input` — the raw input the model passed; useful for pulling a chart
 *     title or chart count out, but treat as untrusted (model-generated).
 *
 * Errors thrown by the callback are caught and logged so a buggy hook can
 * never abort the fallback.
 */
export type AgentFallbackToolUseHook = (event: {
    name: string;
    input: unknown;
}) => void;
export type CallToolFn = (id: number, name: string, args: unknown) => Promise<string | null>;
export interface CallAmplitudeMcpOptions<T> {
    accessToken: string;
    mcpUrl?: string;
    /**
     * The direct MCP call path. Receives a `callTool` helper bound to an open
     * session. Return `null` to trigger the agent fallback.
     *
     * When omitted, the MCP session handshake is skipped entirely and the agent
     * fallback runs immediately. Use this when there is no single MCP tool that
     * can satisfy the request and orchestration must be done by the agent.
     */
    direct?: (callTool: CallToolFn) => Promise<T | null>;
    /** Prompt sent to the Claude agent when the direct path returns null or throws. */
    agentPrompt: string;
    /** Extract the result from the agent's collected text output. Return null if unparseable. */
    parseAgent: (text: string) => T | null;
    label?: string;
    agentTimeoutMs?: number;
    /**
     * Optional signal from the caller's AbortController. When aborted, in-flight
     * fetch requests and the agent fallback subprocess are cancelled immediately.
     * The top-level application should wire this to its exit / cleanup handler.
     */
    abortSignal?: AbortSignal;
    /**
     * Optional hook fired once per `tool_use` block emitted by the agent fallback.
     * Use this to translate inner-agent activity into user-visible status updates
     * during long-running fallbacks (e.g. dashboard creation, where a 90s budget
     * with a static spinner is the difference between "wizard is working" and
     * "wizard is hung"). Only fires when the fallback runs — direct-path calls
     * never invoke the hook.
     */
    onAgentToolUse?: AgentFallbackToolUseHook;
}
/**
 * Make an authenticated call to the Amplitude MCP server.
 *
 * 1. Opens an MCP session and calls `opts.direct(callTool)`.
 * 2. If the direct call returns `null` or throws, falls back to a minimal
 *    Claude agent with only the Amplitude MCP configured.
 * 3. Passes the agent's text output to `opts.parseAgent` and returns the result.
 *
 * Returns `null` if both paths fail.
 */
export declare function callAmplitudeMcp<T>(opts: CallAmplitudeMcpOptions<T>): Promise<T | null>;
