@creature-ai/sdk 0.1.2 → 0.1.4

package/dist/server/index.d.ts

@@ -1,6 +1,4 @@
 import { z } from 'zod';
-import { Server } from 'http';
-import { A as AppSessionOptions, W as WidgetState, a as AppSessionState, b as AppSessionListener } from '../types-JBEuUzEi.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 
 /**
@@ -61,6 +59,34 @@ interface ResourceConfig {
         connectDomains?: string[];
         resourceDomains?: string[];
     };
+    /**
+     * Allow multiple instances of this resource.
+     * Default: false (singleton - all tools share one instance per resourceUri)
+     *
+     * - false: Singleton. SDK reuses the same instanceId for all tool calls.
+     * - true: Multi-instance. SDK generates new instanceId each time (unless provided in input).
+     *
+     * Note: multiInstance is only supported on Creature. On ChatGPT, resources always behave as singleton.
+     */
+    multiInstance?: boolean;
+    /**
+     * Enable WebSocket for real-time communication with the UI.
+     * When true, SDK automatically manages WebSocket lifecycle and provides
+     * `context.send()` and `context.onMessage()` in tool handlers.
+     */
+    websocket?: boolean;
+}
+/**
+ * Resource cache configuration.
+ * Controls caching behavior for UI resource HTML content.
+ */
+interface ResourceCacheConfig {
+    /** Maximum number of cached entries (default: 100) */
+    maxSize?: number;
+    /** Time-to-live in milliseconds. 0 = no expiry (default: 0) */
+    ttlMs?: number;
+    /** Whether caching is enabled (default: true) */
+    enabled?: boolean;
 }
 /**
  * Tool configuration.
@@ -78,13 +104,6 @@ interface ToolConfig<TInput extends z.ZodType = z.ZodType> {
     displayModes?: DisplayMode[];
     /** Preferred display mode */
     defaultDisplayMode?: DisplayMode;
-    /**
-     * Whether this tool creates new sessions (multi-instance MCP).
-     * When true, the Host will always create a new pip instead of
-     * reusing an existing one for the same resourceUri.
-     * Use this for tools that spawn independent sessions (e.g., terminal_run).
-     */
-    multiSession?: boolean;
     /** Loading message shown while tool is running (used by ChatGPT) */
     loadingMessage?: string;
     /** Completion message shown when tool finishes (used by ChatGPT) */
@@ -111,21 +130,58 @@ interface ToolResult {
 type ToolHandler<TInput> = (input: TInput, context: ToolContext) => ToolResult | Promise<ToolResult>;
 /**
  * Context passed to tool handlers.
- * Reserved for future use.
+ * Provides access to instanceId, state management, and WebSocket communication.
  */
 interface ToolContext {
+    /**
+     * The instance ID for this tool call.
+     * Generated before handler runs. Use for server-side state keying.
+     * Automatically attached to tool result for UI routing.
+     */
+    instanceId: string;
+    /**
+     * Get server-side state for this instance.
+     * State is NOT sent to UI — use for PIDs, connections, handles.
+     */
+    getState: <T>() => T | undefined;
+    /**
+     * Set server-side state for this instance.
+     * State is NOT sent to UI — use for PIDs, connections, handles.
+     */
+    setState: <T>(state: T) => void;
+    /**
+     * Send a message to the UI via WebSocket.
+     * Only available if the resource has `websocket: true`.
+     * For singleton resources, sends to the single shared WebSocket.
+     * For multi-instance resources, sends to this instance's WebSocket.
+     */
+    send: <T>(message: T) => void;
+    /**
+     * Register a handler for messages from the UI.
+     * Only available if the resource has `websocket: true`.
+     */
+    onMessage: <T>(handler: (message: T) => void) => void;
+    /**
+     * Register a handler called when a UI client connects to the WebSocket.
+     * Useful for sending buffered data when a client connects.
+     * Only available if the resource has `websocket: true`.
+     */
+    onConnect: (handler: () => void) => void;
+    /**
+     * WebSocket URL for the UI to connect to.
+     * Only available if the resource has `websocket: true`.
+     * Automatically included in tool result's structuredContent.
+     */
+    websocketUrl: string | undefined;
 }
 /**
- * Resource cache configuration.
- * Controls caching behavior for UI resource HTML content.
+ * Context passed to onInstanceDestroy callback.
  */
-interface ResourceCacheConfig {
-    /** Maximum number of cached entries (default: 100) */
-    maxSize?: number;
-    /** Time-to-live in milliseconds. 0 = no expiry (default: 0) */
-    ttlMs?: number;
-    /** Whether caching is enabled (default: true) */
-    enabled?: boolean;
+interface InstanceDestroyContext {
+    /** The instanceId being destroyed */
+    instanceId: string;
+    /** Last server-side state for this instance (from setState calls) */
+    state: unknown;
 }
 /**
  * Supported MCP transport types.
@@ -159,7 +215,7 @@ interface AppConfig {
     hmrPort?: number;
     /**
      * Called when a new transport session is created.
-     * Transport sessions are MCP protocol connections (not AppSessions).
+     * Transport sessions are MCP protocol connections (not instances).
      */
     onTransportSessionCreated?: (info: TransportSessionInfo) => void;
     /**
@@ -198,196 +254,114 @@ interface AppConfig {
      */
     resourceCache?: ResourceCacheConfig;
 }
-
 /**
- * WebSocket channel support for real-time bidirectional communication.
+ * WebSocket connection for an instance.
  *
- * Channels provide a type-safe abstraction over WebSockets, allowing MCP Apps
- * to stream data to connected UIs without polling.
+ * Provides real-time bidirectional communication between the server
+ * and all UI clients connected to a particular instance.
  */
-
-/**
- * Handler for incoming client messages.
- */
-type MessageHandler<T> = (message: T) => void;
-/**
- * Configuration for a channel definition.
- */
-interface ChannelConfig<_TServer = unknown, _TClient = unknown> {
-    /** Zod schema for server → client messages (optional, for documentation) */
-    server?: z.ZodType;
-    /** Zod schema for client → server messages (validated on receive) */
-    client?: z.ZodType;
-}
-/**
- * A WebSocket channel instance for a specific AppSession.
- *
- * This provides real-time bidirectional communication between the server
- * and all UI clients connected to a particular AppSession.
- */
-interface AppSessionChannel<TServer = unknown, TClient = unknown> {
-    /** The AppSession ID this channel belongs to */
-    appSessionId: string;
+interface WebSocketConnection<TServer = unknown, TClient = unknown> {
+    /** The instance ID this WebSocket belongs to */
+    instanceId: string;
     /** WebSocket URL for clients to connect */
-    url: string;
+    websocketUrl: string;
     /** Send a message to all connected clients */
     send: (message: TServer) => void;
     /** Register a handler for incoming client messages */
-    onMessage: (handler: MessageHandler<TClient>) => void;
+    onMessage: (handler: (message: TClient) => void) => void;
     /** Register a handler called when a new client connects */
     onConnect: (handler: () => void) => void;
-    /** Close the channel and disconnect all clients */
+    /** Close the WebSocket and disconnect all clients */
     close: () => void;
     /** Number of connected clients */
     readonly clientCount: number;
 }
-/**
- * Manages WebSocket connections and routes messages to AppSession channels.
- */
-declare class ChannelManager {
-    private wss;
-    private channels;
+
+declare class App {
+    private config;
+    private tools;
+    private resources;
+    private transports;
+    private websocketManager;
+    private instanceWebSockets;
+    private httpServer;
+    private isDev;
+    private hmrPort;
+    private hmrConfigChecked;
+    private callerDir;
+    private shutdownRegistered;
+    private isShuttingDown;
+    private resourceCache;
+    private resourceCacheConfig;
+    /** Server-side instance state, keyed by instanceId. */
+    private instanceState;
+    /** Callbacks to invoke when an instance is destroyed. */
+    private instanceDestroyCallbacks;
+    /** Singleton instanceIds per resourceUri (for non-multiInstance resources). */
+    private singletonInstances;
+    /** Whether the connected host supports multiInstance. ChatGPT doesn't, Creature does. */
+    private hostSupportsMultiInstance;
+    constructor(config: AppConfig, callerDir?: string);
+    /**
+     * Define a UI resource.
+     */
+    resource(config: ResourceConfig): this;
+    /**
+     * Define a tool.
+     */
+    tool<TInput extends z.ZodType>(name: string, config: ToolConfig<TInput>, handler: ToolHandler<z.infer<TInput>>): this;
     /**
-     * Attach the WebSocket server to an HTTP server.
+     * Start the MCP server.
      */
-    attach(server: Server): void;
+    start(): Promise<void>;
+    /**
+     * Stop the MCP server gracefully.
+     */
+    stop(): Promise<void>;
     /**
-     * Create a new channel for an AppSession.
+     * Create an instance with optional WebSocket support.
      *
-     * @param channelName - The channel name (e.g., "updates", "terminal")
-     * @param appSessionId - The AppSession ID this channel belongs to
-     * @param config - Channel configuration
-     * @param port - Server port for WebSocket URL
-     * @returns An AppSessionChannel for bidirectional communication
+     * Most tools don't need this — the SDK creates instances automatically.
+     * Only call createInstance() when you need a WebSocket URL for real-time updates.
      */
-    createChannel<TServer, TClient>(channelName: string, appSessionId: string, config: ChannelConfig<TServer, TClient>, port: number): AppSessionChannel<TServer, TClient>;
+    createInstance<TServer = unknown, TClient = unknown>(options?: {
+        websocket?: boolean;
+    }): {
+        instanceId: string;
+        websocketUrl?: string;
+        send?: (msg: TServer) => void;
+        onMessage?: (handler: (msg: TClient) => void) => void;
+        onConnect?: (handler: () => void) => void;
+    };
     /**
-     * Check if a channel exists for an AppSession.
+     * Register a callback to be invoked when an instance is destroyed.
      */
-    hasChannel(channelName: string, appSessionId: string): boolean;
+    onInstanceDestroy(callback: (ctx: InstanceDestroyContext) => void): void;
     /**
-     * Check if any channels exist.
+     * Destroy an instance and clean up its resources.
      */
-    hasAnyChannels(): boolean;
+    destroyInstance(instanceId: string): boolean;
     /**
-     * Close all channels and shut down the WebSocket server.
+     * Check if an instance exists.
      */
-    closeAll(): void;
-}
-/**
- * A channel definition that can create AppSession channel instances.
- */
-declare class ChannelDefinition<TServer = unknown, TClient = unknown> {
-    private manager;
-    private name;
-    private config;
-    private getPort;
-    constructor(manager: ChannelManager, name: string, config: ChannelConfig<TServer, TClient>, getPort: () => number);
+    hasInstance(instanceId: string): boolean;
     /**
-     * Create a channel for a specific AppSession.
-     *
-     * @param appSessionId - The AppSession ID (e.g., from a terminal AppSession)
-     * @returns An AppSessionChannel for bidirectional communication
+     * Get instance state.
      */
-    forAppSession(appSessionId: string): AppSessionChannel<TServer, TClient>;
+    getInstanceState<T>(instanceId: string): T | undefined;
     /**
-     * Check if a channel exists for an AppSession.
+     * Set instance state directly.
      */
-    hasChannel(appSessionId: string): boolean;
+    setInstanceState<T>(instanceId: string, state: T): void;
     /**
-     * Get the channel name.
+     * Create a WebSocket for an existing instance.
+     *
+     * Use this when you need real-time communication for an instance
+     * that was created by a tool handler (which provides instanceId via context).
      */
-    get channelName(): string;
-}
-
-type PartialState<TState extends AppSessionState> = {
-    [K in keyof TState]?: Partial<TState[K]> | TState[K];
-};
-interface ServerAppSessionOptions extends AppSessionOptions {
-    websockets?: boolean;
-}
-/**
- * Server-side AppSession for managing application state.
- *
- * AppSessions are distinct from TransportSessions:
- * - AppSession: Application-level state (internal, backend, ui)
- * - TransportSession: MCP protocol connection (StreamableHTTP session)
- */
-declare class ServerAppSession<TInternal extends Record<string, unknown> = Record<string, unknown>, TBackend extends Record<string, unknown> = Record<string, unknown>, TUi extends WidgetState | null = WidgetState | null> {
-    readonly id: string;
-    private _state;
-    private listeners;
-    private _channel;
-    constructor(initialState?: Partial<AppSessionState<TInternal, TBackend, TUi>>, options?: {
-        id?: string;
-    });
-    private generateId;
-    get state(): AppSessionState<TInternal, TBackend, TUi>;
-    get internal(): TInternal;
-    get backend(): TBackend;
-    get ui(): TUi;
-    get channel(): AppSessionChannel<unknown, unknown> | null;
-    get channelUrl(): string | undefined;
-    setChannel(channel: AppSessionChannel<unknown, unknown>): void;
-    subscribe(listener: AppSessionListener<AppSessionState<TInternal, TBackend, TUi>>): () => void;
-    private notify;
-    setState(partial: PartialState<AppSessionState<TInternal, TBackend, TUi>>): void;
-    setInternal(internal: TInternal | Partial<TInternal>): void;
-    setBackend(backend: TBackend | Partial<TBackend>): void;
-    setUi(ui: TUi): void;
-    updateUi(partial: TUi extends null ? never : Partial<NonNullable<TUi>>): void;
-    injectAppSessionId<T extends Record<string, unknown>>(data: T): T & {
-        appSessionId: string;
-    };
-    close(): void;
-}
-/**
- * Manages ServerAppSession instances.
- *
- * This manages AppSessions (application state), not TransportSessions
- * (MCP protocol connections).
- */
-declare class AppSessionManager {
-    private appSessions;
-    private channelManager;
-    private getPort;
-    private appSessionChannelName;
-    constructor(config: {
-        channelManager?: ChannelManager;
-        getPort: () => number;
-    });
-    setChannelManager(channelManager: ChannelManager): void;
-    create<TInternal extends Record<string, unknown> = Record<string, unknown>, TBackend extends Record<string, unknown> = Record<string, unknown>, TUi extends WidgetState | null = WidgetState | null>(initialState?: Partial<AppSessionState<TInternal, TBackend, TUi>>, options?: ServerAppSessionOptions): ServerAppSession<TInternal, TBackend, TUi>;
-    get(id: string): ServerAppSession | undefined;
-    require(id: string): ServerAppSession;
-    has(id: string): boolean;
-    delete(id: string): boolean;
-    closeAll(): void;
-    get size(): number;
-}
-
-declare class App {
-    private config;
-    private tools;
-    private resources;
-    private transports;
-    private channelManager;
-    private channels;
-    private appSessionManager;
-    private httpServer;
-    private isDev;
-    private hmrPort;
-    private hmrConfigChecked;
-    private callerDir;
-    private shutdownRegistered;
-    private isShuttingDown;
-    private resourceCache;
-    private resourceCacheConfig;
-    constructor(config: AppConfig, callerDir?: string);
+    createWebSocketForInstance<TServer = unknown, TClient = unknown>(instanceId: string): WebSocketConnection<TServer, TClient> | null;
     /**
      * Get list of active transport sessions.
-     * Transport sessions are MCP protocol connections (not AppSessions).
-     * Useful for monitoring and debugging connection state.
      */
     getTransportSessions(): TransportSessionInfo[];
     /**
@@ -396,75 +370,70 @@ declare class App {
     getTransportSessionCount(): number;
     /**
      * Close a specific transport session.
-     *
-     * @param sessionId - The transport session ID to close
-     * @returns true if the session was found and closed
      */
     closeTransportSession(sessionId: string): boolean;
     /**
      * Clear all cached resource content.
-     * Use after updating UI files during development.
      */
     clearResourceCache(): void;
     /**
      * Clear a specific resource from the cache.
-     *
-     * @param uri - The resource URI to clear
-     * @returns true if the resource was in the cache and removed
      */
     clearResourceCacheEntry(uri: string): boolean;
     /**
      * Get resource cache statistics.
-     * Useful for monitoring cache performance.
      */
     getResourceCacheStats(): {
         size: number;
         maxSize: number;
         enabled: boolean;
     };
+    private getPort;
+    private getCallerDir;
+    private getHmrPort;
+    private generateInstanceId;
     /**
-     * Get a cached resource if valid, or null if not cached/expired.
-     */
-    private getCachedResource;
-    /**
-     * Store a resource in the cache with LRU eviction.
-     */
-    private setCachedResource;
-    /**
-     * Get the HMR port, reading from hmr.json lazily if not already set.
-     * This handles the timing issue where Vite may not have written hmr.json
-     * when the server first starts.
+     * Resolve instanceId for a tool call based on resource configuration.
+     *
+     * - Singleton resources (default): Reuse same instanceId per resourceUri
+     * - Multi-instance resources: Generate new instanceId (unless provided in input)
+     *
+     * @param resourceUri The resource URI from tool config
+     * @param inputInstanceId instanceId from tool call input args (if any)
      */
-    private getHmrPort;
-    private getCallerDir;
+    private resolveInstanceId;
     /**
-     * Define a UI resource.
+     * Extract the shape (properties) from a Zod schema.
      */
-    resource(config: ResourceConfig): this;
-    tool<TInput extends z.ZodType>(name: string, config: ToolConfig<TInput>, handler: ToolHandler<z.infer<TInput>>): this;
-    channel<TServer = unknown, TClient = unknown>(name: string, config?: ChannelConfig<TServer, TClient>): ChannelDefinition<TServer, TClient>;
-    private getPort;
-    session<TInternal extends Record<string, unknown> = Record<string, unknown>, TBackend extends Record<string, unknown> = Record<string, unknown>, TUi extends WidgetState | null = WidgetState | null>(initialState?: Partial<AppSessionState<TInternal, TBackend, TUi>>, options?: ServerAppSessionOptions): ServerAppSession<TInternal, TBackend, TUi>;
-    getSession(id: string): ServerAppSession | undefined;
-    requireSession(id: string): ServerAppSession;
-    hasSession(id: string): boolean;
-    closeSession(id: string): boolean;
+    private getSchemaShape;
     /**
-     * Create an MCP server instance with all registered tools and resources.
+     * Check if a field is required in a Zod schema.
      */
+    private isFieldRequired;
+    private getCachedResource;
+    private setCachedResource;
+    private createExpressApp;
+    private handleMcpPost;
+    private handleMcpGet;
+    private handleMcpDelete;
+    private createTransport;
     private createMcpServer;
+    private registerResources;
+    private registerTools;
     /**
-     * Format a tool result into MCP format.
+     * Get or create a WebSocket for an instance.
+     * Used internally by registerTools when resource has websocket: true.
      */
-    private formatToolResult;
-    start(): Promise<void>;
+    private getOrCreateWebSocket;
+    private buildToolMeta;
+    private buildToolDescription;
     /**
-     * Stop the MCP server gracefully.
+     * Format tool result for MCP protocol response.
      *
-     * Calls the onShutdown callback, closes all sessions and channels,
-     * then waits for active transports to close (with timeout).
+     * SDK manages instanceId and websocketUrl automatically.
      */
-    stop(): Promise<void>;
+    private formatToolResult;
+    private registerShutdownHandlers;
 }
 /**
  * Create a new MCP App.
@@ -540,4 +509,4 @@ declare function htmlLoader(filePath: string, basePath?: string): () => string;
  */
 declare function wrapServer<T extends McpServer>(server: T): T;
 
-export { App, type AppConfig, type AppSessionChannel, AppSessionListener, AppSessionManager, AppSessionOptions, AppSessionState, type ChannelConfig, ChannelDefinition, type DisplayMode, type IconConfig, MIME_TYPES, type ResourceCacheConfig, type ResourceConfig, ServerAppSession, type ServerAppSessionOptions, type ToolConfig, type ToolContext, type ToolHandler, type ToolResult, type ToolVisibility, type TransportSessionInfo, type TransportType, createApp, htmlLoader, loadHtml, svgToDataUri, wrapServer };
+export { App, type AppConfig, type DisplayMode, type IconConfig, type InstanceDestroyContext, MIME_TYPES, type ResourceCacheConfig, type ResourceConfig, type ToolConfig, type ToolContext, type ToolHandler, type ToolResult, type ToolVisibility, type TransportSessionInfo, type TransportType, type WebSocketConnection, createApp, htmlLoader, loadHtml, svgToDataUri, wrapServer };