@mcpstack/agent-sdk 1.0.0-pr.16.7572c080abaa.13.1

package/dist/react-native/index.d.ts

@@ -0,0 +1,982 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+
+interface ClientToolParameter {
+    type: string;
+    description?: string;
+    required?: boolean;
+    enum?: string[];
+    items?: ClientToolParameter;
+    properties?: Record<string, ClientToolParameter>;
+    additionalProperties?: boolean | ClientToolParameter;
+}
+interface ClientToolDefinition {
+    description: string;
+    parameters: Record<string, ClientToolParameter>;
+    selection?: ClientToolSelection;
+    execute: (params: Record<string, unknown>) => Promise<unknown>;
+}
+type ClientToolsMap$1 = Record<string, ClientToolDefinition>;
+interface ClientToolSelection {
+    categories?: string[];
+    alwaysInclude?: boolean;
+    includeWhen?: string[];
+    risk?: 'low' | 'medium' | 'high' | string;
+    serverPreferred?: boolean;
+}
+interface McpStackEmbeddedAuthIdentity {
+    subject?: string;
+    email?: string;
+    organizationId?: string;
+    displayName?: string;
+    avatarUrl?: string;
+}
+interface McpStackEmbeddedAuthConfig {
+    hostIdentity?: McpStackEmbeddedAuthIdentity;
+    mismatchPolicy: 'block_with_switch';
+}
+interface McpStackAppTokenAuthConfig {
+    mode: 'app-token';
+    appId?: string;
+    getToken: () => Promise<string | undefined> | string | undefined;
+}
+interface McpStackStorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+interface AudioTurnDetectionConfig {
+    /**
+     * Enables SDK-side end-of-speech detection. Defaults to true.
+     * When enabled, the SDK commits microphone input after the user has spoken
+     * and then paused for `silenceDurationMs`.
+     */
+    enabled?: boolean;
+    /**
+     * Whether detected end-of-speech should automatically submit the transcript.
+     * Defaults to true. Set false for push-to-talk/manual-stop experiences.
+     */
+    autoSubmit?: boolean;
+    /**
+     * Trailing silence required before the SDK commits audio, in milliseconds.
+     * Defaults to 850ms.
+     */
+    silenceDurationMs?: number;
+    /**
+     * Minimum detected speech duration before a turn is considered real speech.
+     * Defaults to 180ms to ignore clicks and short bumps.
+     */
+    minSpeechDurationMs?: number;
+    /**
+     * Time to keep listening before speech starts, in milliseconds.
+     * Defaults to 12000ms. Set to 0 to disable.
+     */
+    noSpeechTimeoutMs?: number;
+    /**
+     * Absolute RMS threshold from 0 to 1. Defaults to 0.012.
+     * The SDK also adapts to the ambient noise floor.
+     */
+    speechThreshold?: number;
+    /**
+     * Multiplier applied to the measured ambient noise floor. Defaults to 2.4.
+     */
+    noiseMultiplier?: number;
+}
+interface McpStackAudioInputConfig {
+    /**
+     * SDK-owned turn detection configuration. Consumer apps can tune it, but
+     * they do not need to implement their own microphone VAD.
+     */
+    turnDetection?: AudioTurnDetectionConfig;
+}
+interface McpStackAgentConfig {
+    /** API key for authenticating with the MCP Stack API */
+    apiKey: string;
+    /** Agent ID from the MCP Stack dashboard */
+    agentId: string;
+    /** MCP Stack API URL. Defaults to https://api.mcpstack.com */
+    agentServiceUrl?: string;
+    /**
+     * Callback URL used by the standalone popup OAuth flow.
+     * Defaults to the hosted MCP Stack callback page so downstream auth servers
+     * only need to allow a single redirect URI.
+     */
+    oauthCallbackUrl?: string;
+    /**
+     * Public URL for this client's hosted metadata document when using
+     * Client ID Metadata Documents (CIMD).
+     */
+    oauthClientMetadataUrl?: string;
+    /**
+     * Callback to get the auth token for MCP Stack API requests.
+     * If provided, called before each chat API request.
+     * Use this when your session token may expire and needs refresh (e.g., dashboard playground).
+     * If not provided, uses the static `apiKey` value.
+     */
+    getAuthToken?: () => Promise<string | undefined>;
+    /**
+     * Host app auth-session boundary for persisted MCP auth state.
+     * Use the current app session id so logging out forces MCP reconnect,
+     * even when the same browser later signs back in as the same user.
+     */
+    authSessionKey?: string | null;
+    /**
+     * Embedded popup auth settings.
+     * Use this to tell MCP Stack which host-app user is currently signed in so
+     * the built-in popup flow can prefer the same downstream account.
+     */
+    embeddedAuth?: McpStackEmbeddedAuthConfig;
+    /**
+     * App-owned MCP auth for embedded products.
+     * Use this when your app already authenticated the user and can return a
+     * short-lived app access token. The SDK exchanges that token at Gateway for
+     * an MCP-facing token without opening a second sign-in window.
+     */
+    auth?: McpStackAppTokenAuthConfig;
+    /**
+     * If true, MCP server calls include cookies (for cookie-based auth).
+     * Default: false
+     */
+    useCookies?: boolean;
+    /**
+     * Called when an MCP server requires authentication and the built-in
+     * popup flow is not being used. The SDK will invoke this so the
+     * integrator can trigger a custom login flow.
+     *
+     * Return the token response on success, or undefined to cancel.
+     * The SDK stores the token and handles refresh automatically.
+     */
+    onAuthRequired?: (mcpServerUrl: string, authConfig: McpServerAuthConfig) => Promise<OAuthTokenResponse | undefined>;
+    /** Optional: external user ID to associate with conversations */
+    externalUserId?: string;
+    /** Optional: additional context sent with each message */
+    context?: Record<string, unknown>;
+    /** Optional: microphone input behavior. */
+    audioInput?: McpStackAudioInputConfig;
+    /**
+     * Optional: resume an existing server-side conversation on init.
+     * Use this with persisted conversation ids in the host app.
+     */
+    initialConversationId?: string | null;
+    /**
+     * Page size for conversation replay bootstrap and older-message loading.
+     * Default: 50
+     */
+    conversationHistoryPageSize?: number;
+    /**
+     * Client tools — execute locally in browser, exposed to LLM.
+     * The agent can call these to interact with the host app (e.g. fill forms, read page state).
+     */
+    clientTools?: ClientToolsMap$1;
+    /**
+     * Optional persistent storage override used for MCP auth/session artifacts.
+     * If omitted, the runtime falls back to `localStorage` when available.
+     */
+    storage?: McpStackStorageLike | null;
+}
+interface ChatMessage {
+    id: string;
+    role: 'user' | 'assistant' | 'tool_call' | 'tool_result' | 'error';
+    content: string;
+    toolName?: string;
+    toolLabel?: string;
+    toolCallId?: string;
+    timestamp: Date;
+    toolCallStatus?: 'calling' | 'completed' | 'error';
+    toolCallStartTime?: number;
+    toolCallDuration?: number;
+    toolResult?: string;
+    toolError?: string;
+    errorCode?: string;
+    metadataJson?: string | null;
+}
+interface ConversationReplayMessage {
+    id: string;
+    sequenceNumber: number;
+    role: ChatMessage['role'];
+    content?: string | null;
+    createdAt: string;
+    toolName?: string | null;
+    toolLabel?: string | null;
+    toolCallId?: string | null;
+    toolCallStatus?: 'calling' | 'completed' | 'error' | null;
+    toolCallDurationMs?: number | null;
+    toolArgumentsJson?: string | null;
+    toolResultJson?: string | null;
+    toolError?: string | null;
+    errorCode?: string | null;
+    metadataJson?: string | null;
+}
+interface ConversationMessagesPage {
+    conversationId: string;
+    messages: ConversationReplayMessage[];
+    pageSize: number;
+    nextCursor?: string | null;
+    hasNextPage: boolean;
+}
+type ConversationFeedbackSentiment = 'up' | 'down';
+interface SubmitConversationFeedbackRequest {
+    sentiment: ConversationFeedbackSentiment;
+    comment?: string;
+    source?: string;
+    toolCallId?: string;
+    conversationMessageId?: string;
+    metadata?: Record<string, unknown>;
+}
+interface ConversationFeedback {
+    id: string;
+    conversationId: string;
+    sentiment: ConversationFeedbackSentiment;
+    comment?: string | null;
+    source: string;
+    toolCallId?: string | null;
+    conversationMessageId?: string | null;
+    metadataJson?: string | null;
+    createdAt: string;
+}
+interface McpServerAuthConfig {
+    authType: 'none' | 'apiKey' | 'bearer' | 'oauth2';
+    issuer?: string;
+    authorizationServerUrl?: string;
+    authorizationServerMetadataUrl?: string;
+    authorizationEndpoint?: string;
+    loginUrl?: string;
+    tokenEndpoint?: string;
+    tokenUrl?: string;
+    registrationEndpoint?: string;
+    clientId?: string;
+    scopes?: string[];
+    resource?: string;
+    callbackUrl?: string;
+    protectedResourceMetadataUrl?: string;
+    clientIdMetadataDocumentSupported?: boolean;
+    resourceParameterSupported?: boolean;
+    registrationPreference?: McpClientRegistrationPreference;
+    clientMode?: McpResolvedClientMode;
+    authRecipe?: McpAuthRecipe;
+    manualOverrides?: string[];
+    discovered?: boolean;
+}
+type McpAuthRecipe = 'sqlos' | 'auth0' | 'entra' | 'workos' | 'manual';
+type McpClientRegistrationPreference = 'auto' | 'preregistered' | 'cimd' | 'dcr' | 'manual';
+type McpResolvedClientMode = 'preregistered' | 'cimd' | 'dcr' | 'manual';
+/** OAuth token response from token endpoint */
+interface OAuthTokenResponse {
+    accessToken: string;
+    refreshToken?: string;
+    expiresIn?: number;
+    tokenType?: string;
+    resolvedAuthConfig?: McpServerAuthConfig;
+}
+interface McpServerInfo {
+    id: string;
+    name: string;
+    url: string;
+    authStatus: 'connected' | 'needs_auth';
+    authConfig?: McpServerAuthConfig | null;
+}
+interface AgentConfigResponse {
+    agentId: string;
+    name: string;
+    conversationResumeVersion: string;
+    /** @deprecated Use mcpServers instead */
+    mcpServerUrl?: string;
+    mcpServers: McpServerInfo[];
+    widgetConfig?: WidgetConfig | null;
+    modelConfig?: AgentPublicModelConfig | null;
+    audio?: AgentPublicAudioConfig | null;
+}
+interface AgentModelCapabilities {
+    textInput?: boolean;
+    textOutput?: boolean;
+    audioInput?: boolean;
+    audioOutput?: boolean;
+    realtime?: boolean;
+    toolCalls?: boolean;
+    text?: boolean;
+    realtimeAudioInput?: boolean;
+    realtimeAudioOutput?: boolean;
+    transcription?: boolean;
+    translation?: boolean;
+}
+interface AgentPublicModelConfig {
+    id: string;
+    provider: string;
+    displayName: string;
+    capabilities: AgentModelCapabilities;
+}
+interface AgentPublicAudioConfig {
+    inputEnabled: boolean;
+    outputEnabled: boolean;
+    maxSessionSeconds: number;
+    transcriptionModel?: string | null;
+}
+interface WidgetConfig {
+    theme?: string;
+    position?: string;
+    title?: string;
+    placeholder?: string;
+    welcomeMessage?: string;
+}
+interface SseContentDelta {
+    text: string;
+}
+interface SseToolCall {
+    toolCallId: string;
+    toolName: string;
+    toolLabel?: string;
+    arguments: Record<string, unknown>;
+    mcpServerUrl?: string;
+    mcpServerName?: string;
+    /** When 'client', execute locally via clientTools; when 'mcp' or absent with mcpServerUrl, use MCP */
+    source?: 'client' | 'mcp';
+}
+interface SseMessageEnd {
+    inputTokens: number;
+    outputTokens: number;
+    toolCalls: number;
+}
+interface AgentBudgetSnapshot {
+    enabled: boolean;
+    currency: string;
+    identityType: 'identified' | 'anonymous' | string;
+    externalUserId: string;
+    displayName: string;
+    budgetSource: 'explicit' | 'default_user' | 'anonymous' | 'none' | string;
+    windowStartUtc: string;
+    windowEndUtc: string;
+    agentMonthlyBudgetUsd?: number | null;
+    agentCurrentMonthSpendUsd: number;
+    agentRemainingBudgetUsd?: number | null;
+    userMonthlyBudgetUsd?: number | null;
+    userCurrentMonthSpendUsd: number;
+    userRemainingBudgetUsd?: number | null;
+    organizationCreditsRemainingUsd?: number | null;
+    effectiveRemainingUsd?: number | null;
+    status: 'healthy' | 'warning' | 'blocked' | 'disabled' | string;
+}
+interface SseError {
+    code: string;
+    message: string;
+    budget?: AgentBudgetSnapshot | null;
+}
+type AudioInputStatus = 'idle' | 'requesting_permission' | 'connecting' | 'listening' | 'transcribing' | 'sending' | 'error';
+interface AudioInputState {
+    status: AudioInputStatus;
+    isSupported: boolean;
+    isEnabled: boolean;
+    transcript: string;
+    partialTranscript: string;
+    error: SseError | null;
+    sessionId?: string | null;
+    conversationId?: string | null;
+    maxSessionSeconds?: number | null;
+    inputLevel?: number;
+    isSpeaking?: boolean;
+    speechMs?: number;
+    silenceMs?: number;
+    autoSubmitEnabled?: boolean;
+}
+interface AudioTranscriptDeltaEvent {
+    text: string;
+    transcript: string;
+    isFinal: false;
+}
+interface AudioTranscriptFinalEvent {
+    text: string;
+    transcript: string;
+    conversationId: string;
+}
+interface AudioActivityEvent {
+    inputLevel: number;
+    noiseFloor: number;
+    isSpeaking: boolean;
+    speechMs: number;
+    silenceMs: number;
+}
+interface McpAuthStatusEvent {
+    mcpServerUrl: string;
+    mcpServerName: string;
+    authStatus: 'connected' | 'needs_auth';
+}
+type McpStackAgentEventMap = {
+    message: ChatMessage;
+    content_delta: SseContentDelta;
+    tool_call: SseToolCall;
+    tool_result: {
+        toolCallId: string;
+        result: unknown;
+        duration: number;
+    };
+    tool_error: {
+        toolCallId: string;
+        error: string;
+        duration: number;
+    };
+    message_end: SseMessageEnd;
+    budget_snapshot: AgentBudgetSnapshot;
+    error: SseError;
+    loading: boolean;
+    thinking: boolean;
+    mcp_auth_status: McpAuthStatusEvent;
+    audio_state: AudioInputState;
+    audio_activity: AudioActivityEvent;
+    audio_transcript_delta: AudioTranscriptDeltaEvent;
+    audio_transcript_final: AudioTranscriptFinalEvent;
+};
+type McpStackAgentEvent = keyof McpStackAgentEventMap;
+
+type ClientToolsMap = ClientToolsMap$1;
+type AppAgentUserIdentity = McpStackEmbeddedAuthIdentity;
+interface KeyValueStore {
+    getItem(key: string): Promise<string | null> | string | null;
+    setItem(key: string, value: string): Promise<void> | void;
+    removeItem(key: string): Promise<void> | void;
+}
+interface OAuthSessionRequest {
+    authorizeUrl: string;
+    redirectUri: string;
+    preferEphemeralSession?: boolean;
+}
+type OAuthSessionResult = {
+    type: 'success';
+    url: string;
+} | {
+    type: 'cancel' | 'dismiss';
+} | {
+    type: 'error';
+    message?: string;
+};
+interface AppAgentPlatform {
+    storage?: {
+        durable: KeyValueStore;
+        secure?: KeyValueStore;
+    };
+    auth?: {
+        openOAuthSession(request: OAuthSessionRequest): Promise<OAuthSessionResult>;
+        dismissOAuthSession?(): Promise<void> | void;
+    };
+    lifecycle?: {
+        onForegroundChange?(listener: (isForeground: boolean) => void): () => void;
+        onConnectivityChange?(listener: (isOnline: boolean) => void): () => void;
+    };
+}
+interface AppAgentApproval {
+    id: string;
+    title: string;
+    rationale?: string;
+    steps: string[];
+    toolCallId?: string | null;
+    confirmLabel?: string;
+    cancelLabel?: string;
+}
+interface AppAgentInputOption {
+    label: string;
+    value: string;
+}
+interface AppAgentInputField {
+    key: string;
+    label: string;
+    kind: 'text' | 'textarea' | 'number' | 'select' | 'boolean';
+    required?: boolean;
+    placeholder?: string;
+    options?: AppAgentInputOption[];
+}
+interface AppAgentInputRequest {
+    id: string;
+    title: string;
+    prompt?: string;
+    fields: AppAgentInputField[];
+    toolCallId?: string | null;
+    submitLabel?: string;
+    cancelLabel?: string;
+}
+interface AppAgentIssue {
+    code: 'stale_conversation' | 'runtime_error' | 'config_error';
+    message: string;
+    recoverable: boolean;
+}
+interface AppAgentFeedbackState {
+    isSubmitting: boolean;
+    error: string | null;
+    lastSubmittedAt: string | null;
+    lastFeedback: ConversationFeedback | null;
+}
+interface AppAgentConnection {
+    url: string;
+    name: string;
+    authStatus: 'connected' | 'needs_auth';
+    canSignOut: boolean;
+}
+interface AppAgentConfig {
+    apiKey: string;
+    agentId: string;
+    serviceUrl?: string;
+    initialConnections?: AppAgentConnection[];
+    oauthCallbackUrl?: string;
+    oauthClientMetadataUrl?: string;
+    getAuthToken?: () => Promise<string | undefined>;
+    appSessionKey?: string | null;
+    userIdentity?: AppAgentUserIdentity;
+    auth?: McpStackAppTokenAuthConfig;
+    useCookies?: boolean;
+    externalUserId?: string;
+    appContext?: Record<string, unknown>;
+    clientTools?: ClientToolsMap;
+    platform?: AppAgentPlatform;
+    onAuthRequired?: (mcpServerUrl: string, authConfig: McpServerAuthConfig) => Promise<OAuthTokenResponse | undefined>;
+    conversation?: {
+        namespace?: string;
+        historyPageSize?: number;
+    };
+    feedbackSource?: string;
+    storage?: McpStackStorageLike | null;
+}
+interface AppAgentLifecycleState {
+    isReady: boolean;
+    isLoading: boolean;
+    isLoadingHistory: boolean;
+    isThinking: boolean;
+    hasOlderMessages: boolean;
+    error: SseError | null;
+    issue: AppAgentIssue | null;
+}
+interface AppAgentSnapshotBase {
+    runtime: {
+        agent: unknown;
+        agentConfig: AgentConfigResponse | null;
+    };
+    conversation: AppAgentLifecycleState & {
+        id: string | null;
+        messages: ChatMessage[];
+        streamingContent: string;
+        statusLabel: string;
+        resumeKey: string | null;
+    };
+    connections: {
+        items: AppAgentConnection[];
+        needsAttention: boolean;
+    };
+    approvals: {
+        pending: AppAgentApproval[];
+    };
+    requests: {
+        pending: AppAgentInputRequest[];
+    };
+    feedback: AppAgentFeedbackState;
+    budget: AgentBudgetSnapshot | null;
+    voice: AudioInputState;
+}
+
+type EventHandler<T> = (data: T) => void;
+/**
+ * Core orchestration class for the MCP Stack Agent SDK.
+ * Framework-agnostic — works in any JavaScript environment.
+ *
+ * Handles:
+ * - Communication with the MCP Stack chat API (SSE streaming)
+ * - Tool execution via MCP server (browser-side, with user's auth token)
+ * - Conversation state management
+ * - Event emission for UI updates
+ */
+declare class McpStackAgent {
+    private config;
+    private agentConfig;
+    private budgetSnapshot;
+    private conversationId;
+    private messages;
+    private historyCursor;
+    private hasOlderMessages;
+    private isLoadingHistory;
+    private abortController;
+    private isLoading;
+    private listeners;
+    /** Per-server MCP session tracking */
+    private mcpSessions;
+    /** OAuth tokens per MCP server URL (standalone mode only) */
+    private oauthTokens;
+    /** Servers explicitly disconnected by the user and awaiting manual re-auth */
+    private manuallySignedOutServers;
+    private audioState;
+    private audioStream;
+    private audioContext;
+    private audioSource;
+    private audioProcessor;
+    private audioSilentGain;
+    private audioSocket;
+    private audioSessionTimer;
+    private audioSessionStopRequested;
+    private audioFinalTranscript;
+    private audioTurnState;
+    constructor(config: McpStackAgentConfig);
+    private resolveAuthToken;
+    /** Initialize: fetch agent config (tools, widget settings, MCP servers) */
+    init(): Promise<AgentConfigResponse>;
+    /** Get current MCP server auth statuses */
+    getMcpServers(): Array<{
+        url: string;
+        name: string;
+        authStatus: 'connected' | 'needs_auth';
+        canSignOut: boolean;
+    }>;
+    /** Send a message and process the full orchestration loop (including tool calls) */
+    sendMessage(message: string): Promise<void>;
+    /** Start a new conversation */
+    newConversation(): void;
+    /** Cancel the current in-flight request */
+    cancel(): void;
+    /** Get all messages in the current conversation */
+    getMessages(): ChatMessage[];
+    /** Get the current conversation ID */
+    getConversationId(): string | null;
+    getHasOlderMessages(): boolean;
+    getIsLoadingHistory(): boolean;
+    /** Get the loaded agent config */
+    getAgentConfig(): AgentConfigResponse | null;
+    getAudioInputState(): AudioInputState;
+    startVoiceInput(): Promise<void>;
+    stopVoiceInput(): Promise<void>;
+    cancelVoiceInput(): void;
+    loadConversation(conversationId: string, pageSize?: number): Promise<ConversationMessagesPage>;
+    loadOlderMessages(pageSize?: number): Promise<ConversationMessagesPage | null>;
+    submitFeedback(input: SubmitConversationFeedbackRequest): Promise<ConversationFeedback>;
+    /** Convert client tools to the API schema format. */
+    private clientToolsToSchemas;
+    private resolveExternalUserId;
+    private buildExternalUserContext;
+    /** Latest runtime budget snapshot for the current SDK identity. */
+    getBudgetSnapshot(): AgentBudgetSnapshot | null;
+    /** Refresh the current SDK identity's budget snapshot from the API. */
+    refreshBudgetSnapshot(): Promise<AgentBudgetSnapshot | null>;
+    /** Whether a request is currently in flight */
+    getIsLoading(): boolean;
+    /** Update the per-turn app context sent with each chat request. */
+    setAppContext(context: Record<string, unknown> | undefined): void;
+    /** Update the client tools exposed to the agent without recreating the session. */
+    setClientTools(clientTools: ClientToolsMap$1 | undefined): void;
+    /**
+     * Proactively authenticate with an MCP server before sending a message.
+     * If a token response is provided directly, it is stored immediately.
+     * Otherwise, this uses the configured OAuth flow and verifies via MCP init.
+     *
+     * @param mcpServerUrl - The MCP server URL to authenticate with
+     * @param tokenResponse - Optional: provide token response directly (from OAuth popup)
+     */
+    authenticate(mcpServerUrl: string, tokenResponse?: OAuthTokenResponse): Promise<boolean>;
+    /** Disconnect from an MCP server and require explicit re-authentication before reuse. */
+    signOutMcpServer(mcpServerUrl: string): Promise<void>;
+    /** Get the auth config for an MCP server (from agent config) */
+    getServerAuthConfig(mcpServerUrl: string): McpServerAuthConfig | null;
+    getOAuthCallbackUrl(): string;
+    getOAuthClientMetadataUrl(): string;
+    private getDefaultAuthRequiredHandler;
+    setOnAuthRequired(onAuthRequired: McpStackAgentConfig['onAuthRequired']): void;
+    private isAudioInputSupported;
+    private isAudioInputEnabled;
+    private isAudioAutoSubmitEnabled;
+    private getAudioTurnDetectionConfig;
+    private clampNumber;
+    private buildAudioState;
+    private setAudioState;
+    private getAudioContextConstructor;
+    private createRealtimeTranscriptionSession;
+    private buildApiError;
+    private openAudioSocket;
+    private normalizeAudioSocketUrl;
+    private bindAudioSocket;
+    private handleAudioSocketMessage;
+    private commitVoiceInput;
+    private stopVoiceInputWithoutTranscript;
+    private createAudioTurnState;
+    private analyzeAudioFrame;
+    private processAudioTurnActivity;
+    private updateNoiseFloor;
+    private emitAudioActivity;
+    private startAudioCapture;
+    private resampleToPcm16;
+    private floatToPcm16;
+    private pcm16ToBase64;
+    private cleanupAudioCapture;
+    private clearAudioSessionTimer;
+    private extractErrorCode;
+    private getPersistentStorage;
+    private resolveOAuthClientRegistration;
+    /** Subscribe to events */
+    on<K extends McpStackAgentEvent>(event: K, handler: EventHandler<McpStackAgentEventMap[K]>): void;
+    /** Unsubscribe from events */
+    off<K extends McpStackAgentEvent>(event: K, handler: EventHandler<McpStackAgentEventMap[K]>): void;
+    private buildProtectedResourceMetadataCandidates;
+    private hasSameOrigin;
+    private extractQuotedHeaderValue;
+    private buildAuthorizationServerMetadataCandidates;
+    private hasExplicitManualOverride;
+    private pickAuthConfigValue;
+    private pickAuthConfigArrayValue;
+    private mergeAuthConfigs;
+    private discoverAuthConfig;
+    private resolveServerAuthConfig;
+    private ensureServerAuthConfig;
+    private updateServerAuthConfig;
+    private emit;
+    /** Generate the legacy token cache suffix used before auth-aware keying. */
+    private hashUrl;
+    private getLegacyTokenStorageKey;
+    private getAuthSessionKey;
+    private getTokenStorageKey;
+    private getTokenStorageCandidates;
+    /** Load OAuth token from memory/persistent storage using auth-aware cache keying. */
+    private loadOAuthToken;
+    /** Check if we have a valid (non-expired) OAuth token */
+    private hasValidOAuthToken;
+    /** Store OAuth token to memory and persistent storage */
+    private storeOAuthToken;
+    /** Clear OAuth token from memory and persistent storage */
+    private clearOAuthToken;
+    /** Refresh OAuth token using refresh token */
+    private refreshOAuthToken;
+    /**
+     * Resolve the auth token for an MCP server.
+     * - OAuth mode: Checks stored token, refreshes if expired, triggers auth if needed
+     */
+    private resolveToken;
+    /**
+     * The core orchestration loop:
+     * 1. Send message to chat API
+     * 2. Stream response
+     * 3. If tool_call → execute tool via MCP → send result → continue
+     * 4. If message_end → done
+     */
+    private runChatLoop;
+    private callChatApi;
+    private fetchConversationMessages;
+    private applyConversationPage;
+    private mapReplayMessage;
+    /**
+     * Process an SSE stream from the chat API.
+     * Returns when the stream ends (either message_end or tool_call).
+     */
+    private processSseStream;
+    /** Build headers for MCP server requests */
+    private getMcpHeaders;
+    /** Best-effort MCP session teardown so reconnect starts cleanly after sign-out. */
+    private closeMcpSession;
+    /** Initialize the MCP session for a specific server (required before tools/call) */
+    private initMcpSession;
+    /** Update auth status for an MCP server and emit event */
+    private updateMcpAuthStatus;
+    /** Parse a JSON-RPC response from either JSON or SSE format */
+    private parseMcpResponse;
+    private executeTool;
+}
+
+type AppAgentToolCallMessage = ChatMessage & {
+    role: 'tool_call';
+};
+type AppAgentAssistantMessage = ChatMessage & {
+    role: 'assistant';
+};
+type AppAgentUserMessage = ChatMessage & {
+    role: 'user';
+};
+type AppAgentErrorMessage = ChatMessage & {
+    role: 'error';
+};
+type AppAgentConversationMessage = AppAgentAssistantMessage | AppAgentUserMessage | AppAgentErrorMessage;
+type AppAgentVisibleMessage = AppAgentConversationMessage | AppAgentToolCallMessage;
+type AppAgentLastTurnSummary = {
+    prompt: string;
+    toolsUsed: number;
+    durationMs: number | null;
+};
+type AppAgentRenderedNode = {
+    kind: 'user';
+    id: string;
+    content: string;
+} | {
+    kind: 'assistant';
+    id: string;
+    content: string;
+} | {
+    kind: 'tools';
+    id: string;
+    tools: AppAgentToolCallMessage[];
+};
+type AppAgentInlinePendingTurnState = {
+    prompt: string;
+    baselineAssistantId: string | null;
+    baselineToolCount: number;
+};
+type AppAgentInlineFeedState = {
+    isActive: boolean;
+    pendingPrompt: string | null;
+    recentTools: AppAgentToolCallMessage[];
+    previewText: string | null;
+    waitingForActivity: boolean;
+};
+declare function deriveVisibleMessages(messages: ChatMessage[]): AppAgentVisibleMessage[];
+declare function deriveConversationMessages(messages: ChatMessage[]): AppAgentConversationMessage[];
+declare function deriveToolMessages(messages: ChatMessage[]): AppAgentToolCallMessage[];
+declare function getLatestAssistantMessage(messages: ChatMessage[]): AppAgentAssistantMessage | null;
+declare function getLatestUserMessage(messages: ChatMessage[]): AppAgentUserMessage | null;
+declare function getLatestToolMessage(messages: ChatMessage[]): AppAgentToolCallMessage | null;
+declare function createInlinePendingTurnState(prompt: string, messages: ChatMessage[]): AppAgentInlinePendingTurnState;
+declare function buildRenderedNodes(messages: ChatMessage[]): AppAgentRenderedNode[];
+declare function deriveLastTurnSummary(messages: ChatMessage[]): AppAgentLastTurnSummary | null;
+declare function deriveInlineFeedState(options: {
+    pendingTurn: AppAgentInlinePendingTurnState | null;
+    toolMessages: AppAgentToolCallMessage[];
+    latestAssistantMessage?: {
+        id: string;
+        content: string;
+    } | null;
+    streamingContent?: string;
+    isLoading: boolean;
+    isThinking: boolean;
+    maxRecentTools?: number;
+}): AppAgentInlineFeedState;
+
+type Listener = () => void;
+type AppAgentSnapshot = AppAgentSnapshotBase & {
+    runtime: AppAgentSnapshotBase['runtime'] & {
+        agent: McpStackAgent;
+    };
+    conversation: AppAgentSnapshotBase['conversation'] & {
+        visibleMessages: ReturnType<typeof deriveVisibleMessages>;
+        conversationMessages: ReturnType<typeof deriveConversationMessages>;
+        toolMessages: ReturnType<typeof deriveToolMessages>;
+        renderedNodes: ReturnType<typeof buildRenderedNodes>;
+        latestAssistantMessage: ReturnType<typeof getLatestAssistantMessage>;
+        latestToolMessage: ReturnType<typeof getLatestToolMessage>;
+        latestUserMessage: ReturnType<typeof getLatestUserMessage>;
+        lastTurn: ReturnType<typeof deriveLastTurnSummary>;
+        pendingTurn: ReturnType<typeof createInlinePendingTurnState> | null;
+        inlineFeed: ReturnType<typeof deriveInlineFeedState>;
+    };
+};
+declare class AppAgentController {
+    private config;
+    private readonly listeners;
+    private readonly agent;
+    private readonly platform;
+    private readonly recoveredConversationIds;
+    private readonly approvalResolvers;
+    private readonly inputResolvers;
+    private readonly pendingToolCallsByAction;
+    private readonly lifecycleUnsubscribers;
+    private readonly userMessageDisplayOverrides;
+    private state;
+    private snapshot;
+    private started;
+    private disposed;
+    private initializationPromise;
+    private pendingDisplayText;
+    constructor(config: AppAgentConfig);
+    getAgent(): McpStackAgent;
+    getSnapshot: () => AppAgentSnapshot;
+    private buildSnapshot;
+    subscribe(listener: Listener): () => void;
+    start(): void;
+    dispose(): void;
+    updateDynamicConfig(config: Pick<AppAgentConfig, 'appContext' | 'clientTools' | 'feedbackSource'>): void;
+    setAuthRequiredHandler(onAuthRequired: ((mcpServerUrl: string, authConfig: McpServerAuthConfig) => Promise<OAuthTokenResponse | undefined>) | undefined): void;
+    send(prompt: string, options?: {
+        displayText?: string;
+    }): Promise<void>;
+    cancel(): void;
+    startVoiceInput(): Promise<void>;
+    stopVoiceInput(): Promise<void>;
+    cancelVoiceInput(): void;
+    loadMore(): Promise<void>;
+    resetConversation(): Promise<void>;
+    connect(serverUrl: string): Promise<boolean>;
+    disconnect(serverUrl: string): Promise<void>;
+    submitFeedback(input: Omit<SubmitConversationFeedbackRequest, 'source'>): Promise<ConversationFeedback>;
+    resolveApproval(id: string, approved: boolean): void;
+    submitRequest(id: string, values?: Record<string, unknown>): void;
+    cancelRequest(id: string): void;
+    private initialize;
+    private ensureInitialized;
+    private bindRuntimeEvents;
+    private readonly handleMessage;
+    private readonly handleContentDelta;
+    private readonly handleToolCall;
+    private readonly handleToolResult;
+    private readonly handleToolError;
+    private readonly handleThinking;
+    private readonly handleLoading;
+    private readonly handleError;
+    private readonly handleBudgetSnapshot;
+    private readonly handleMcpAuthStatus;
+    private readonly handleAudioState;
+    private handleStaleConversation;
+    private bindLifecycleSignals;
+    private buildClientTools;
+    private shiftPendingToolCallId;
+    private syncFromRuntime;
+    private finalizePendingTurnIfSettled;
+    private getResumeStorageKey;
+    private readResumeRecord;
+    private persistResumeRecord;
+    private clearResumeRecord;
+    private setState;
+    private recomputeDerivedState;
+    private emit;
+}
+
+interface OAuthPopupState {
+    serverName: string;
+    serverUrl: string;
+    phase: 'prompt' | 'preparing' | 'waiting' | 'exchanging' | 'blocked' | 'canceled' | 'error';
+    statusMessage?: string | null;
+    errorMessage?: string | null;
+    hostIdentityLabel?: string | null;
+}
+interface UseAppAgentOptions {
+    enabled?: boolean;
+}
+interface UseAppAgentReturn {
+    controller: AppAgentController;
+    runtime: AppAgentSnapshot['runtime'];
+    conversation: AppAgentSnapshot['conversation'] & {
+        loadMore: () => Promise<void>;
+        reset: () => Promise<void>;
+    };
+    composer: {
+        send: (prompt: string, options?: {
+            displayText?: string;
+        }) => Promise<void>;
+        cancel: () => void;
+    };
+    connections: AppAgentSnapshot['connections'] & {
+        connect: (serverUrl: string) => Promise<boolean>;
+        disconnect: (serverUrl: string) => Promise<void>;
+    };
+    approvals: AppAgentSnapshot['approvals'] & {
+        resolve: (id: string, approved: boolean) => void;
+    };
+    requests: AppAgentSnapshot['requests'] & {
+        submit: (id: string, values?: Record<string, unknown>) => void;
+        cancel: (id: string) => void;
+    };
+    feedback: AppAgentSnapshot['feedback'] & {
+        submit: (input: Omit<SubmitConversationFeedbackRequest, 'source'>) => Promise<unknown>;
+    };
+    budget: AppAgentSnapshot['budget'];
+    voice: AppAgentSnapshot['voice'] & {
+        start: () => Promise<void>;
+        stop: () => Promise<void>;
+        cancel: () => void;
+    };
+    popupAuthState: OAuthPopupState | null;
+    startOrRetryPopupAuth: () => void;
+    cancelPopupAuth: () => void;
+}
+
+interface AppAgentProviderProps extends AppAgentConfig {
+    children: React.ReactNode;
+}
+declare function useAppAgent(config: AppAgentConfig, options?: UseAppAgentOptions): UseAppAgentReturn;
+declare function AppAgentProvider({ children, ...config }: AppAgentProviderProps): react_jsx_runtime.JSX.Element;
+declare function useAppAgentContext(): UseAppAgentReturn;
+
+export { AppAgentProvider, type AppAgentProviderProps, type UseAppAgentOptions, type UseAppAgentReturn, useAppAgent, useAppAgentContext };