open-mcp-app 0.1.0 → 0.1.2

package/dist/core/index.d.ts

@@ -0,0 +1,1171 @@
+import { App } from '@modelcontextprotocol/ext-apps';
+export { applyDocumentTheme, applyHostFonts, applyHostStyleVariables, getDocumentTheme } from '@modelcontextprotocol/ext-apps';
+
+/**
+ * Base Host Client Types
+ *
+ * These types define the spec-compliant interface for MCP Apps and ChatGPT Apps.
+ * Host-specific extensions are defined in their respective adapter modules.
+ */
+/**
+ * Environment types for host detection.
+ */
+type Environment = "chatgpt" | "mcp-apps" | "standalone";
+/**
+ * Display modes for UI resources.
+ * - "inline": Embedded within the conversation flow
+ * - "pip": Picture-in-picture floating panel
+ * - "fullscreen": Full-screen overlay
+ */
+type DisplayMode = "inline" | "pip" | "fullscreen";
+/**
+ * Log severity levels matching MCP protocol LoggingLevel.
+ * These are displayed in the host's DevConsole with appropriate colors.
+ */
+type LogLevel = "debug" | "info" | "notice" | "warning" | "error";
+/**
+ * Structured widget state format (ChatGPT-compatible).
+ * Allows separating model-visible content from private UI state.
+ */
+interface StructuredWidgetState {
+    /** Content visible to the AI model on follow-up turns */
+    modelContent?: string | Record<string, unknown> | null;
+    /** UI-only state, hidden from model */
+    privateContent?: Record<string, unknown> | null;
+    /** File IDs for images the model can see */
+    imageIds?: string[];
+}
+/**
+ * Widget state can be structured (with modelContent/privateContent)
+ * or a simple key-value object.
+ */
+type WidgetState = StructuredWidgetState | Record<string, unknown>;
+/**
+ * Tool call result structure.
+ */
+interface ToolResult<T = Record<string, unknown>> {
+    content?: Array<{
+        type: string;
+        text: string;
+    }>;
+    structuredContent?: T;
+    isError?: boolean;
+    source?: "agent" | "ui";
+}
+/**
+ * Host context sent from MCP Apps host.
+ * Follows MCP Apps spec with extensions via [key: string]: unknown.
+ */
+interface HostContext {
+    theme?: "light" | "dark";
+    styles?: {
+        variables?: Record<string, string>;
+    };
+    displayMode?: DisplayMode;
+    availableDisplayModes?: DisplayMode[];
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    platform?: string;
+    /**
+     * Host application identifier per MCP Apps spec.
+     * Format: "<host>/<version>" (e.g. "creature/1.0.0", "chatgpt/2.0.0").
+     * Use this for spec-compliant host detection after ui/initialize.
+     */
+    userAgent?: string;
+    /**
+     * Widget state restored from previous widget instance.
+     * Supported on both MCP Apps and ChatGPT.
+     */
+    widgetState?: WidgetState;
+    /**
+     * Allow additional host-specific properties.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Configuration for creating a host client.
+ */
+interface HostClientConfig {
+    /** Name of the client (for protocol handshake) */
+    name: string;
+    /** Version of the client */
+    version: string;
+}
+/**
+ * State managed by the host client.
+ */
+interface HostClientState {
+    /** Whether the host connection is ready */
+    isReady: boolean;
+    /** The detected environment */
+    environment: Environment;
+    /** Current widget state */
+    widgetState: WidgetState | null;
+}
+/**
+ * Base event handlers supported by all host clients.
+ * These are spec-compliant events that work across platforms.
+ */
+interface BaseHostClientEvents {
+    /** Called when tool input is received (before execution) */
+    "tool-input": (args: Record<string, unknown>) => void;
+    /** Called when tool result is received */
+    "tool-result": (result: ToolResult) => void;
+    /** Called when widget state changes (restored or updated) */
+    "widget-state-change": (widgetState: WidgetState | null) => void;
+}
+/**
+ * Extended event handlers for MCP Apps hosts.
+ * These are MCP-specific events not available on ChatGPT.
+ */
+interface McpAppsHostClientEvents extends BaseHostClientEvents {
+    /** Called when theme changes (MCP Apps only) */
+    "theme-change": (theme: "light" | "dark") => void;
+    /** Called when host requests teardown (MCP Apps only) */
+    teardown: () => Promise<void> | void;
+}
+/**
+ * Listener for state changes.
+ */
+type StateListener = (state: HostClientState, prevState: HostClientState) => void;
+/**
+ * Base host client interface.
+ * Contains only spec-compliant methods that work across all platforms.
+ */
+interface BaseHostClient {
+    /** Get current state */
+    getState(): HostClientState;
+    /** Subscribe to state changes. Returns unsubscribe function. */
+    subscribe(listener: StateListener): () => void;
+    /** Call a tool on the MCP server */
+    callTool<T = Record<string, unknown>>(toolName: string, args: Record<string, unknown>): Promise<ToolResult<T>>;
+    /** Set widget state */
+    setWidgetState(state: WidgetState | null): void;
+    /**
+     * Request a display mode change from the host.
+     *
+     * The host may refuse or coerce the request (e.g., "pip" → "fullscreen" on mobile).
+     * Always check `availableDisplayModes` in host context before calling, and handle
+     * the returned mode differing from the requested mode.
+     */
+    requestDisplayMode(params: {
+        mode: DisplayMode;
+    }): Promise<{
+        mode: DisplayMode;
+    }>;
+    /**
+     * Send a log message.
+     *
+     * On MCP Apps hosts, logs are sent via the MCP protocol's `notifications/message`
+     * and displayed in the host's unified log viewer alongside server logs.
+     * On ChatGPT, logs go to browser console only.
+     */
+    log(level: LogLevel, message: string, data?: Record<string, unknown>): void;
+    /** Register an event handler. Returns unsubscribe function. */
+    on<K extends keyof BaseHostClientEvents>(event: K, handler: BaseHostClientEvents[K]): () => void;
+    /** Start listening for host messages */
+    connect(): void;
+    /** Stop listening for host messages */
+    disconnect(): void;
+}
+/**
+ * WebSocket connection status.
+ */
+type WebSocketStatus = "disconnected" | "connecting" | "connected" | "error";
+/**
+ * Configuration for creating a WebSocket client.
+ */
+interface WebSocketClientConfig<TReceive = unknown> {
+    /** Called when a message is received */
+    onMessage?: (message: TReceive) => void;
+    /** Called when connection status changes */
+    onStatusChange?: (status: WebSocketStatus, error?: string) => void;
+    /** Whether to auto-reconnect on disconnect (default: true) */
+    reconnect?: boolean;
+    /** Base interval for reconnection attempts in ms (default: 1000) */
+    reconnectInterval?: number;
+}
+/**
+ * WebSocket client interface.
+ */
+interface WebSocketClient<TSend = unknown, TReceive = unknown> {
+    /** Current connection status */
+    readonly status: WebSocketStatus;
+    /** Error message if status is "error" */
+    readonly error: string | undefined;
+    /** Connect to the WebSocket server */
+    connect(): void;
+    /** Disconnect from the WebSocket server */
+    disconnect(): void;
+    /** Send a message to the server */
+    send(message: TSend): void;
+}
+
+/**
+ * Provider Adapter Types
+ *
+ * Defines the interfaces for host-specific adapters that extend
+ * the base host client with additional capabilities.
+ */
+
+/**
+ * All events supported by the unified host client.
+ * Combines base events with MCP-specific events.
+ */
+interface UnifiedHostClientEvents extends BaseHostClientEvents, McpAppsHostClientEvents {
+}
+/**
+ * Unified host client interface.
+ *
+ * This is the primary interface returned by `createHost()`.
+ * It combines the base interface with host-specific extensions,
+ * providing a consistent API across all platforms.
+ */
+interface UnifiedHostClient {
+    /** Get current state */
+    getState(): HostClientState;
+    /** Subscribe to state changes. Returns unsubscribe function. */
+    subscribe(listener: StateListener): () => void;
+    /** Call a tool on the MCP server */
+    callTool<T = Record<string, unknown>>(toolName: string, args: Record<string, unknown>): Promise<ToolResult<T>>;
+    /**
+     * Send a notification to the host.
+     *
+     * MCP Apps only - no-op on ChatGPT.
+     */
+    sendNotification(method: string, params: unknown): void;
+    /** Set widget state */
+    setWidgetState(state: WidgetState | null): void;
+    /**
+     * Set the pip/widget title displayed in the host UI.
+     *
+     * Creature extension - no-op on ChatGPT and generic MCP Apps hosts.
+     */
+    setTitle(title: string): void;
+    /**
+     * Request a display mode change from the host.
+     */
+    requestDisplayMode(params: {
+        mode: DisplayMode;
+    }): Promise<{
+        mode: DisplayMode;
+    }>;
+    /**
+     * Send a log message.
+     */
+    log(level: LogLevel, message: string, data?: Record<string, unknown>): void;
+    /** Register an event handler. Returns unsubscribe function. */
+    on<K extends keyof UnifiedHostClientEvents>(event: K, handler: UnifiedHostClientEvents[K]): () => void;
+    /** Start listening for host messages */
+    connect(): void;
+    /** Stop listening for host messages */
+    disconnect(): void;
+    /**
+     * The detected environment.
+     * Use this to conditionally enable host-specific features.
+     */
+    readonly environment: Environment;
+    /**
+     * The adapter kind currently in use.
+     */
+    readonly adapterKind: AdapterKind;
+    /**
+     * Whether this host is Creature (supports Creature-specific extensions).
+     * Checked via hostContext after connection.
+     */
+    readonly isCreature: boolean;
+    /**
+     * Get the host context received from the host.
+     * Contains theme, styles, userAgent, and host-specific properties.
+     * Returns null before connection is established.
+     */
+    getHostContext(): HostContext | null;
+}
+/**
+ * The kind of adapter in use.
+ */
+type AdapterKind = "mcp-apps" | "creature" | "chatgpt" | "standalone";
+/**
+ * Base adapter interface.
+ * All adapters implement this interface.
+ */
+interface HostAdapter extends UnifiedHostClient {
+    /** The underlying base client */
+    readonly base: BaseHostClient;
+}
+
+/**
+ * Base class for subscribable host clients.
+ * Provides event emitter pattern for state changes and host events.
+ */
+declare abstract class Subscribable {
+    private stateListeners;
+    private eventHandlers;
+    subscribe(listener: StateListener): () => void;
+    on<K extends keyof BaseHostClientEvents>(event: K, handler: BaseHostClientEvents[K]): () => void;
+    protected notifyStateChange(state: HostClientState, prevState: HostClientState): void;
+    protected emit<K extends keyof BaseHostClientEvents>(event: K, ...args: Parameters<BaseHostClientEvents[K]>): void;
+    protected onSubscribe(): void;
+    protected onUnsubscribe(): void;
+}
+/**
+ * Extended subscribable for MCP Apps hosts that support additional events.
+ */
+declare abstract class McpAppsSubscribable extends Subscribable {
+    private mcpEventHandlers;
+    onMcpEvent<K extends "theme-change" | "teardown">(event: K, handler: K extends "theme-change" ? (theme: "light" | "dark") => void : () => Promise<void> | void): () => void;
+    protected emitMcpEvent<K extends "theme-change" | "teardown">(event: K, ...args: K extends "theme-change" ? ["light" | "dark"] : []): void | Promise<void>;
+}
+
+/**
+ * MCP Apps base host client implementation.
+ *
+ * Wraps the official MCP Apps SDK `App` class to provide a spec-compliant interface.
+ * Handles the protocol handshake, tool calls, notifications, and automatic style/theme application.
+ *
+ * This is the base implementation - Creature-specific extensions are added via CreatureAdapter.
+ */
+declare class McpAppsBaseHostClient extends McpAppsSubscribable implements BaseHostClient {
+    private state;
+    protected config: HostClientConfig;
+    protected app: App | null;
+    private connected;
+    private hostContext;
+    constructor(config: HostClientConfig);
+    /**
+     * Get the current client state.
+     */
+    getState(): HostClientState;
+    /**
+     * Get the host context received during initialization.
+     */
+    getHostContext(): HostContext | null;
+    /**
+     * Connect to the MCP Apps host.
+     *
+     * Creates the App instance, registers notification handlers, and initiates
+     * the protocol handshake. The host will receive `ui/initialize` and respond
+     * with host context including theme, styles, and widgetState.
+     */
+    connect(): void;
+    /**
+     * Disconnect from the host.
+     *
+     * Cleans up the App instance and resets state.
+     */
+    disconnect(): void;
+    /**
+     * Call a tool on the MCP server via the host.
+     *
+     * Uses the SDK's callServerTool method which properly routes through
+     * the host to the MCP server.
+     */
+    callTool<T = Record<string, unknown>>(toolName: string, args: Record<string, unknown>): Promise<ToolResult<T>>;
+    /**
+     * Send a notification to the host.
+     *
+     * Sends a notification via the ext-apps SDK transport.
+     */
+    sendNotification(method: string, params: unknown): void;
+    /**
+     * Set widget state and notify the host.
+     *
+     * Widget state is synchronized with the host for persistence across
+     * sessions and visibility to the AI model.
+     */
+    setWidgetState(state: WidgetState | null): void;
+    /**
+     * Request a display mode change from the host.
+     */
+    requestDisplayMode(params: {
+        mode: DisplayMode;
+    }): Promise<{
+        mode: DisplayMode;
+    }>;
+    /**
+     * Send a log message to the host's DevConsole.
+     *
+     * Uses the MCP protocol's `notifications/message` notification to send logs
+     * to the host. Logs appear in the unified DevConsole alongside server logs,
+     * with appropriate color coding based on level.
+     */
+    log(level: LogLevel, message: string, data?: Record<string, unknown>): void;
+    /**
+     * Get the underlying App instance for advanced use cases.
+     */
+    getApp(): App | null;
+    /**
+     * Update internal state and notify listeners.
+     */
+    protected setState(partial: Partial<HostClientState>): void;
+    /**
+     * Set up notification handlers on the App instance.
+     *
+     * Maps the official SDK's callback pattern to our event emitter pattern,
+     * allowing consumers to use `.on("tool-result", ...)` etc.
+     */
+    private setupHandlers;
+    /**
+     * Initiate connection using PostMessageTransport.
+     *
+     * The SDK's App.connect() handles the protocol handshake correctly:
+     * the guest (App) sends `ui/initialize` to the host.
+     */
+    private initiateConnection;
+    /**
+     * Apply theme, styles, and fonts from host context.
+     * Subclasses can override to add additional context handling.
+     */
+    protected applyHostContext(context: {
+        theme?: unknown;
+        styles?: {
+            variables?: unknown;
+            css?: {
+                fonts?: string;
+            };
+        };
+    }): void;
+    /**
+     * Extract text content from SDK result content array.
+     * Filters to only include text items since our ToolResult type expects text.
+     */
+    private extractTextContent;
+}
+
+/**
+ * OpenAI bridge interface exposed by ChatGPT Apps SDK.
+ * Available on `window.openai` when running inside ChatGPT.
+ */
+interface OpenAIBridge {
+    toolOutput?: Record<string, unknown>;
+    widgetState?: WidgetState;
+    setWidgetState?: (state: WidgetState) => void;
+    callTool?: (name: string, args: Record<string, unknown>) => Promise<{
+        structuredContent?: Record<string, unknown>;
+        content?: Array<{
+            type: string;
+            text?: string;
+        }>;
+    }>;
+    requestDisplayMode?: (args: {
+        mode: string;
+    }) => Promise<{
+        mode: string;
+    }>;
+}
+declare global {
+    interface Window {
+        openai?: OpenAIBridge;
+    }
+}
+/**
+ * ChatGPT Apps base host client implementation.
+ *
+ * Bridges the ChatGPT Apps SDK (`window.openai`) to provide a spec-compliant interface.
+ * Handles initial data processing, globals updates, and widget state synchronization.
+ */
+declare class ChatGptBaseHostClient extends Subscribable implements BaseHostClient {
+    private state;
+    protected config: HostClientConfig;
+    private connected;
+    private hasProcessedInitialData;
+    private globalsHandler;
+    private lastToolOutputJson;
+    private lastWidgetStateJson;
+    constructor(config: HostClientConfig);
+    /**
+     * Get the current client state.
+     */
+    getState(): HostClientState;
+    /**
+     * Connect to the ChatGPT host.
+     *
+     * Processes initial data from `window.openai` and sets up a listener
+     * for subsequent `openai:set_globals` events.
+     */
+    connect(): void;
+    /**
+     * Disconnect from the host.
+     *
+     * Removes the globals event listener and cleanup.
+     */
+    disconnect(): void;
+    /**
+     * Call a tool on the MCP server via the ChatGPT bridge.
+     */
+    callTool<T = Record<string, unknown>>(toolName: string, args: Record<string, unknown>): Promise<ToolResult<T>>;
+    /**
+     * Set widget state and sync with the ChatGPT host.
+     */
+    setWidgetState(state: WidgetState | null): void;
+    /**
+     * Log a message to the console.
+     *
+     * ChatGPT doesn't have a DevConsole, so logs go to browser console only.
+     */
+    log(level: LogLevel, message: string, data?: Record<string, unknown>): void;
+    /**
+     * Request a display mode change from the ChatGPT host.
+     */
+    requestDisplayMode(params: {
+        mode: DisplayMode;
+    }): Promise<{
+        mode: DisplayMode;
+    }>;
+    /**
+     * Update internal state and notify listeners.
+     */
+    protected setState(partial: Partial<HostClientState>): void;
+    /**
+     * Process initial data from `window.openai`.
+     *
+     * Called once on connect to handle any tool output or widget state
+     * that was set before the client connected.
+     */
+    private processInitialData;
+    /**
+     * Set up listener for `openai:set_globals` events.
+     *
+     * ChatGPT dispatches this event when tool output or widget state
+     * changes after initial load. Uses JSON comparison to prevent
+     * infinite loops from unchanged data.
+     */
+    private setupGlobalsListener;
+}
+
+/**
+ * Standalone base host client implementation.
+ *
+ * A minimal fallback for when running outside any host environment.
+ * Useful for development and testing scenarios.
+ */
+declare class StandaloneBaseHostClient extends Subscribable implements BaseHostClient {
+    private state;
+    protected config: HostClientConfig;
+    private connected;
+    constructor(config: HostClientConfig);
+    /**
+     * Get the current client state.
+     */
+    getState(): HostClientState;
+    /**
+     * Connect in standalone mode.
+     *
+     * Simply marks the client as ready since there's no host to connect to.
+     */
+    connect(): void;
+    /**
+     * Disconnect in standalone mode.
+     */
+    disconnect(): void;
+    /**
+     * Call a tool - not available in standalone mode.
+     */
+    callTool<T = Record<string, unknown>>(toolName: string, _args: Record<string, unknown>): Promise<ToolResult<T>>;
+    /**
+     * Set widget state locally (no host to sync with).
+     */
+    setWidgetState(state: WidgetState | null): void;
+    /**
+     * Log a message to the console.
+     */
+    log(level: LogLevel, message: string, data?: Record<string, unknown>): void;
+    /**
+     * Request a display mode - returns the requested mode since there's no host to negotiate with.
+     */
+    requestDisplayMode(params: {
+        mode: DisplayMode;
+    }): Promise<{
+        mode: DisplayMode;
+    }>;
+    /**
+     * Update internal state and notify listeners.
+     */
+    protected setState(partial: Partial<HostClientState>): void;
+}
+
+/**
+ * Host Identity Utilities
+ *
+ * Helpers for parsing and working with the `hostContext.userAgent` field.
+ * Per MCP Apps spec, userAgent identifies the host in format "<host>/<version>".
+ */
+
+/**
+ * Parsed host identity from userAgent string.
+ */
+interface HostIdentity {
+    /** Host name (e.g. "creature", "chatgpt") */
+    host: string;
+    /** Host version if provided (e.g. "1.0.0") */
+    version?: string;
+}
+/**
+ * Parse a userAgent string into host and version components.
+ *
+ * Supports formats:
+ * - "<host>/<version>" (e.g. "creature/1.0.0")
+ * - "<host>" (e.g. "creature" - version will be undefined)
+ *
+ * @param userAgent - The userAgent string to parse
+ * @returns Parsed host identity
+ */
+declare function parseHostUserAgent(userAgent: string): HostIdentity;
+/**
+ * Get host identity from a HostContext object.
+ *
+ * Convenience wrapper around parseHostUserAgent that handles null/undefined.
+ *
+ * @param context - The host context (may be null)
+ * @returns Parsed host identity, or empty object if userAgent not available
+ */
+declare function getHostIdentity(context: HostContext | null): Partial<HostIdentity>;
+/**
+ * Check if the host context indicates a specific host.
+ *
+ * @param context - The host context to check
+ * @param hostName - The host name to match (case-insensitive)
+ * @returns true if the context indicates the specified host
+ */
+declare function isHost(context: HostContext | null, hostName: string): boolean;
+/**
+ * Known host identifiers.
+ * Apps can use these constants for reliable host detection.
+ */
+declare const KNOWN_HOSTS: {
+    readonly CREATURE: "creature";
+    readonly CHATGPT: "chatgpt";
+};
+
+/**
+ * MCP Apps Adapter (Base)
+ *
+ * Base adapter for all MCP Apps hosts. This is the foundation that other
+ * host-specific adapters (like CreatureAdapter) extend.
+ *
+ * Works with any MCP Apps-compliant host out of the box.
+ */
+
+/**
+ * MCP Apps adapter implementation.
+ *
+ * This is the base adapter for all MCP Apps hosts. It provides the standard
+ * MCP Apps functionality that works across all compliant hosts.
+ *
+ * Host-specific adapters (like CreatureAdapter) should extend this class
+ * to add their own extensions while maintaining compatibility.
+ */
+declare class McpAppsAdapter implements HostAdapter {
+    readonly base: McpAppsBaseHostClient;
+    readonly adapterKind: AdapterKind;
+    constructor(config: HostClientConfig);
+    /**
+     * Factory method for creating the base client.
+     * Subclasses can override this to use a custom base client.
+     */
+    protected createBaseClient(config: HostClientConfig): McpAppsBaseHostClient;
+    /**
+     * Create an MCP Apps adapter instance.
+     */
+    static create(config: HostClientConfig): McpAppsAdapter;
+    /**
+     * Check if the current environment is MCP Apps (iframe with parent).
+     */
+    static detect(): boolean;
+    get environment(): Environment;
+    /**
+     * Whether this is a Creature host.
+     * Base MCP Apps adapter returns false - CreatureAdapter overrides this.
+     */
+    get isCreature(): boolean;
+    /**
+     * Get the host context received from the host.
+     * Useful for checking host-specific capabilities.
+     */
+    getHostContext(): HostContext | null;
+    getState(): HostClientState;
+    subscribe(listener: StateListener): () => void;
+    callTool<T = Record<string, unknown>>(toolName: string, args: Record<string, unknown>): Promise<ToolResult<T>>;
+    sendNotification(method: string, params: unknown): void;
+    setWidgetState(state: WidgetState | null): void;
+    /**
+     * Set pip/widget title.
+     * Sends a notification - hosts that support it will update the title.
+     */
+    setTitle(title: string): void;
+    requestDisplayMode(params: {
+        mode: DisplayMode;
+    }): Promise<{
+        mode: DisplayMode;
+    }>;
+    log(level: LogLevel, message: string, data?: Record<string, unknown>): void;
+    on<K extends keyof UnifiedHostClientEvents>(event: K, handler: UnifiedHostClientEvents[K]): () => void;
+    connect(): void;
+    disconnect(): void;
+}
+
+/**
+ * Upgrading MCP Apps Client
+ *
+ * A delegating wrapper for MCP Apps environments that determines the
+ * correct adapter type after connection based on hostContext.userAgent.
+ *
+ * This implements the spec-compliant host identification flow:
+ * 1. Start as a generic MCP Apps client
+ * 2. Connect and receive hostContext via ui/initialize
+ * 3. Check hostContext.userAgent to determine if it's Creature
+ * 4. Update adapterKind/isCreature accordingly
+ */
+
+/**
+ * Extended MCP Apps base client that handles Creature-specific hostContext.
+ * Used internally by UpgradingMcpAppsClient.
+ */
+declare class CreatureCapableBaseHostClient extends McpAppsBaseHostClient {
+    private creatureStyles;
+    /**
+     * Get Creature-specific styles from host context.
+     */
+    getCreatureStyles(): Record<string, string | undefined> | null;
+    /**
+     * Check if connected to a Creature host.
+     * Uses hostContext.userAgent (spec-compliant).
+     */
+    isCreatureHost(): boolean;
+    /**
+     * Override to also apply Creature-specific styles.
+     */
+    protected applyHostContext(context: {
+        theme?: unknown;
+        styles?: {
+            variables?: unknown;
+            css?: {
+                fonts?: string;
+            };
+        };
+        creatureStyles?: Record<string, string | undefined>;
+    }): void;
+    /**
+     * Apply Creature-specific CSS variables to the document root.
+     */
+    private applyCreatureStyles;
+}
+/**
+ * Upgrading MCP Apps client that determines the correct adapter type
+ * after connection based on hostContext.userAgent.
+ *
+ * Before connection: adapterKind = "mcp-apps", isCreature = false
+ * After connection: adapterKind and isCreature reflect the actual host
+ */
+declare class UpgradingMcpAppsClient implements HostAdapter {
+    readonly base: CreatureCapableBaseHostClient;
+    constructor(config: HostClientConfig);
+    static create(config: HostClientConfig): UpgradingMcpAppsClient;
+    static detect(): boolean;
+    /**
+     * The adapter kind - determined after connection based on hostContext.userAgent.
+     * Returns "creature" if running in Creature, "mcp-apps" otherwise.
+     */
+    get adapterKind(): AdapterKind;
+    /**
+     * Whether this host is Creature.
+     * Determined via hostContext.userAgent after connection.
+     */
+    get isCreature(): boolean;
+    get environment(): Environment;
+    /**
+     * Get Creature-specific styles if available.
+     * Returns null when not running in Creature.
+     */
+    getCreatureStyles(): Record<string, string | undefined> | null;
+    getHostContext(): HostContext | null;
+    getState(): HostClientState;
+    subscribe(listener: StateListener): () => void;
+    callTool<T = Record<string, unknown>>(toolName: string, args: Record<string, unknown>): Promise<ToolResult<T>>;
+    sendNotification(method: string, params: unknown): void;
+    setWidgetState(state: WidgetState | null): void;
+    /**
+     * Set pip/widget title.
+     * Sends a notification - hosts that support it will update the title.
+     */
+    setTitle(title: string): void;
+    requestDisplayMode(params: {
+        mode: DisplayMode;
+    }): Promise<{
+        mode: DisplayMode;
+    }>;
+    log(level: LogLevel, message: string, data?: Record<string, unknown>): void;
+    on<K extends keyof UnifiedHostClientEvents>(event: K, handler: UnifiedHostClientEvents[K]): () => void;
+    connect(): void;
+    disconnect(): void;
+}
+
+/**
+ * Creature Adapter
+ *
+ * Extends McpAppsAdapter with Creature-specific features:
+ * - isCreature detection via hostContext.userAgent (spec-compliant)
+ * - creatureStyles CSS variables from hostContext
+ * - Creature-specific token authentication (server-side)
+ * - Enhanced logging to DevConsole
+ */
+
+/**
+ * Extended MCP Apps base client that handles Creature-specific hostContext.
+ */
+declare class CreatureBaseHostClient extends McpAppsBaseHostClient {
+    private creatureStyles;
+    /**
+     * Get Creature-specific styles from host context.
+     */
+    getCreatureStyles(): Record<string, string | undefined> | null;
+    /**
+     * Check if connected to a Creature host.
+     *
+     * Detection is done via hostContext.userAgent (spec-compliant approach).
+     */
+    isCreatureHost(): boolean;
+    /**
+     * Override to also apply Creature-specific styles.
+     */
+    protected applyHostContext(context: {
+        theme?: unknown;
+        styles?: {
+            variables?: unknown;
+            css?: {
+                fonts?: string;
+            };
+        };
+        creatureStyles?: Record<string, string | undefined>;
+    }): void;
+    /**
+     * Apply Creature-specific CSS variables to the document root.
+     */
+    private applyCreatureStyles;
+}
+/**
+ * Creature adapter implementation.
+ *
+ * Extends McpAppsAdapter with Creature-specific functionality:
+ * - isCreature property that checks hostContext.userAgent
+ * - getCreatureStyles() for accessing Creature CSS variables
+ * - Full DevConsole logging
+ *
+ * This adapter works with generic MCP Apps hosts -
+ * Creature-specific features simply return null/false when not in Creature.
+ */
+declare class CreatureAdapter extends McpAppsAdapter {
+    readonly adapterKind: AdapterKind;
+    readonly base: CreatureBaseHostClient;
+    constructor(config: HostClientConfig);
+    /**
+     * Override to create the Creature-specific base client.
+     */
+    protected createBaseClient(config: HostClientConfig): CreatureBaseHostClient;
+    /**
+     * Create a Creature adapter instance.
+     */
+    static create(config: HostClientConfig): CreatureAdapter;
+    /**
+     * Whether this host is Creature.
+     * Checked via hostContext.userAgent after connection.
+     */
+    get isCreature(): boolean;
+    /**
+     * Get Creature-specific styles if available.
+     * Returns null when not running in Creature.
+     */
+    getCreatureStyles(): Record<string, string | undefined> | null;
+}
+
+/**
+ * ChatGPT Adapter
+ *
+ * Wraps the ChatGPT base host client with the unified interface.
+ * Provides ChatGPT-specific features via the window.openai bridge.
+ */
+
+/**
+ * ChatGPT adapter implementation.
+ *
+ * Wraps ChatGptBaseHostClient and exposes the unified interface.
+ * MCP-specific features (like notifications and teardown) are no-ops.
+ */
+declare class ChatGptAdapter implements HostAdapter {
+    readonly base: ChatGptBaseHostClient;
+    readonly adapterKind: AdapterKind;
+    constructor(config: HostClientConfig);
+    /**
+     * Create a ChatGPT adapter instance.
+     */
+    static create(config: HostClientConfig): ChatGptAdapter;
+    /**
+     * Check if the current environment is ChatGPT.
+     */
+    static detect(): boolean;
+    get environment(): Environment;
+    get isCreature(): boolean;
+    /**
+     * Get host context - returns null for ChatGPT as it doesn't use MCP Apps protocol.
+     */
+    getHostContext(): HostContext | null;
+    getState(): HostClientState;
+    subscribe(listener: StateListener): () => void;
+    callTool<T = Record<string, unknown>>(toolName: string, args: Record<string, unknown>): Promise<ToolResult<T>>;
+    /**
+     * Send notification - not supported on ChatGPT.
+     */
+    sendNotification(_method: string, _params: unknown): void;
+    setWidgetState(state: WidgetState | null): void;
+    /**
+     * Set pip/widget title - not supported on ChatGPT.
+     */
+    setTitle(_title: string): void;
+    requestDisplayMode(params: {
+        mode: DisplayMode;
+    }): Promise<{
+        mode: DisplayMode;
+    }>;
+    log(level: LogLevel, message: string, data?: Record<string, unknown>): void;
+    on<K extends keyof UnifiedHostClientEvents>(event: K, handler: UnifiedHostClientEvents[K]): () => void;
+    connect(): void;
+    disconnect(): void;
+}
+
+/**
+ * Standalone Adapter
+ *
+ * Wraps the Standalone base host client with the unified interface.
+ * Used when running outside any host environment (development/testing).
+ */
+
+/**
+ * Standalone adapter implementation.
+ *
+ * A minimal fallback for development and testing scenarios.
+ * Host-specific features are no-ops or console-logged.
+ */
+declare class StandaloneAdapter implements HostAdapter {
+    readonly base: StandaloneBaseHostClient;
+    readonly adapterKind: AdapterKind;
+    constructor(config: HostClientConfig);
+    /**
+     * Create a Standalone adapter instance.
+     */
+    static create(config: HostClientConfig): StandaloneAdapter;
+    /**
+     * Check if the current environment is standalone.
+     * Returns true when not in ChatGPT or MCP Apps.
+     */
+    static detect(): boolean;
+    get environment(): Environment;
+    get isCreature(): boolean;
+    /**
+     * Get host context - returns null for standalone mode.
+     */
+    getHostContext(): HostContext | null;
+    getState(): HostClientState;
+    subscribe(listener: StateListener): () => void;
+    callTool<T = Record<string, unknown>>(toolName: string, args: Record<string, unknown>): Promise<ToolResult<T>>;
+    /**
+     * Send notification - logged in standalone mode.
+     */
+    sendNotification(method: string, params: unknown): void;
+    setWidgetState(state: WidgetState | null): void;
+    /**
+     * Set pip/widget title - logged in standalone mode.
+     */
+    setTitle(title: string): void;
+    requestDisplayMode(params: {
+        mode: DisplayMode;
+    }): Promise<{
+        mode: DisplayMode;
+    }>;
+    log(level: LogLevel, message: string, data?: Record<string, unknown>): void;
+    on<K extends keyof UnifiedHostClientEvents>(event: K, handler: UnifiedHostClientEvents[K]): () => void;
+    connect(): void;
+    disconnect(): void;
+}
+
+/**
+ * Environment-Aware Default Styles
+ *
+ * This module provides default CSS variable values for MCP Apps and ChatGPT Apps.
+ * Import `initStyles` early in your app entry point to prevent flash of unstyled content.
+ *
+ * The MCP Apps spec defines CSS variable names (e.g., --color-background-primary).
+ * This module provides environment-specific VALUES for those variables as sensible
+ * defaults until the host injects its own values.
+ *
+ * Flow:
+ * 1. Detect environment (ChatGPT, MCP Apps, or Standalone)
+ * 2. Detect theme (light or dark)
+ * 3. Inject defaults immediately on document.documentElement
+ * 4. When host connects, host variables override these defaults
+ *
+ * IMPORTANT: MCP Apps defaults match Creature's actual values exactly.
+ * The observer only runs for ChatGPT (MCP Apps hosts handle theme changes themselves).
+ */
+
+/**
+ * Theme mode for styling.
+ */
+type Theme = "light" | "dark";
+/**
+ * Options for initializing styles.
+ */
+interface InitStylesOptions {
+    /** Whether to set up a MutationObserver for dynamic theme changes. Default: true for ChatGPT only */
+    observeThemeChanges?: boolean;
+}
+/**
+ * MCP Apps / Creature default values - DARK mode.
+ * These values are extracted directly from Creature's globals.css.
+ * They MUST match exactly what Creature sends via hostContext.styles.variables.
+ */
+declare const MCP_APPS_DARK_DEFAULTS: Record<string, string>;
+/**
+ * MCP Apps / Creature default values - LIGHT mode.
+ * These values are extracted directly from Creature's globals.css.
+ */
+declare const MCP_APPS_LIGHT_DEFAULTS: Record<string, string>;
+/**
+ * Shared MCP Apps / Creature typography and layout tokens (same for light/dark).
+ * These values are extracted directly from Creature's globals.css.
+ */
+declare const MCP_APPS_SHARED_DEFAULTS: Record<string, string>;
+/**
+ * ChatGPT Apps default values - LIGHT mode.
+ * Ported from @openai/apps-sdk-ui design tokens.
+ */
+declare const CHATGPT_LIGHT_DEFAULTS: Record<string, string>;
+/**
+ * ChatGPT Apps default values - DARK mode.
+ */
+declare const CHATGPT_DARK_DEFAULTS: Record<string, string>;
+/**
+ * Shared ChatGPT typography and layout tokens (same for light/dark).
+ */
+declare const CHATGPT_SHARED_DEFAULTS: Record<string, string>;
+/**
+ * Get MCP Apps default styles for the specified theme.
+ * Returns CSS variable names with their default values.
+ * These values match exactly what Creature sends via hostContext.styles.variables.
+ *
+ * @param theme - The theme to get defaults for
+ * @returns Record of CSS variable names to their values
+ */
+declare const getMcpAppDefaultStyles: ({ theme }: {
+    theme: Theme;
+}) => Record<string, string>;
+/**
+ * Get ChatGPT Apps default styles for the specified theme.
+ * Returns CSS variable names with their values matching the @openai/apps-sdk-ui design tokens.
+ *
+ * @param theme - The theme to get defaults for
+ * @returns Record of CSS variable names to their values
+ */
+declare const getChatGptDefaultStyles: ({ theme }: {
+    theme: Theme;
+}) => Record<string, string>;
+/**
+ * Detect the current theme from the document.
+ * Checks data-theme attribute, dark class (Tailwind), and prefers-color-scheme.
+ *
+ * @returns The detected theme
+ */
+declare const detectTheme: () => Theme;
+/**
+ * Apply CSS variables to the document root.
+ *
+ * @param styles - Record of CSS variable names to their values
+ */
+declare const applyStyles: ({ styles }: {
+    styles: Record<string, string>;
+}) => void;
+/**
+ * Initialize default styles based on detected environment and theme.
+ * This should be called early in your app entry point to prevent FOUC.
+ *
+ * For MCP Apps (Creature): Applies defaults once. The host handles theme changes
+ * and sends new styles via hostContext, which override these defaults.
+ *
+ * For ChatGPT: Applies defaults and sets up an observer to handle theme changes,
+ * since ChatGPT may change theme before sending new hostContext.
+ *
+ * @param environment - The detected environment (from detectEnvironment)
+ * @param options - Configuration options
+ */
+declare const initStyles: ({ environment, options, }: {
+    environment: Environment;
+    options?: InitStylesOptions;
+}) => void;
+
+/**
+ * Create a WebSocket client with automatic reconnection.
+ *
+ * @param url - WebSocket server URL
+ * @param config - Client configuration
+ * @returns WebSocket client instance
+ */
+declare function createWebSocket<TSend = unknown, TReceive = unknown>(url: string, config?: WebSocketClientConfig<TReceive>): WebSocketClient<TSend, TReceive>;
+
+/**
+ * Core Host Client Module
+ *
+ * Provides the unified host client factory and all related types.
+ * This is the main entry point for client-side SDK usage.
+ */
+
+/**
+ * Detect the current host environment.
+ *
+ * Used to auto-select the appropriate host client implementation:
+ * - "chatgpt": Running inside ChatGPT's widget system
+ * - "mcp-apps": Running inside an MCP Apps host (iframe with parent)
+ * - "standalone": Running outside any host environment
+ *
+ * @returns The detected environment
+ */
+declare function detectEnvironment(): Environment;
+/**
+ * Create a host client for the detected environment.
+ *
+ * Automatically selects the appropriate adapter based on runtime detection:
+ * - ChatGPT: Uses ChatGptAdapter (detects window.openai)
+ * - MCP Apps: Uses UpgradingMcpAppsClient (determines Creature vs generic after connection)
+ * - Standalone: Uses StandaloneAdapter for development/testing
+ *
+ * For MCP Apps hosts, the returned client uses spec-compliant host identification
+ * via hostContext.userAgent. The adapterKind and isCreature properties will
+ * reflect the actual host after connection.
+ *
+ * @param config - Configuration for the host client
+ * @returns The appropriate host client adapter for the environment
+ */
+declare function createHost(config: HostClientConfig): UnifiedHostClient;
+/**
+ * Create a host client asynchronously, waiting for host identification.
+ *
+ * Unlike createHost(), this function waits for the connection to establish
+ * and hostContext to be received before returning. This guarantees that
+ * adapterKind and isCreature are accurate when the promise resolves.
+ *
+ * Use this when you need to know the exact host type before proceeding.
+ *
+ * @param config - Configuration for the host client
+ * @returns Promise that resolves to the configured host client after connection
+ *
+ * @example
+ * ```typescript
+ * const host = await createHostAsync({ name: "my-app", version: "1.0.0" });
+ * if (host.isCreature) {
+ *   // Creature-specific initialization
+ * }
+ * ```
+ */
+declare function createHostAsync(config: HostClientConfig): Promise<UnifiedHostClient>;
+
+export { type AdapterKind, type BaseHostClient, type BaseHostClientEvents, CHATGPT_DARK_DEFAULTS, CHATGPT_LIGHT_DEFAULTS, CHATGPT_SHARED_DEFAULTS, ChatGptAdapter, ChatGptBaseHostClient, CreatureAdapter, type DisplayMode, type Environment, type HostAdapter, type HostClientConfig, type HostClientState, type HostContext, type HostIdentity, type InitStylesOptions, KNOWN_HOSTS, type LogLevel, MCP_APPS_DARK_DEFAULTS, MCP_APPS_LIGHT_DEFAULTS, MCP_APPS_SHARED_DEFAULTS, McpAppsAdapter, McpAppsBaseHostClient, type McpAppsHostClientEvents, StandaloneAdapter, StandaloneBaseHostClient, type StateListener, type StructuredWidgetState, type Theme, type ToolResult, type UnifiedHostClient, type UnifiedHostClientEvents, UpgradingMcpAppsClient, type WebSocketClient, type WebSocketClientConfig, type WebSocketStatus, type WidgetState, applyStyles, createHost, createHostAsync, createWebSocket, detectEnvironment, detectTheme, getChatGptDefaultStyles, getHostIdentity, getMcpAppDefaultStyles, initStyles, isHost, parseHostUserAgent };