@creature-ai/sdk 0.1.2 → 0.1.4

package/dist/server/index.js

@@ -93,12 +93,12 @@ var require_code = __commonJS({
     exports._ = _;
     var plus = new _Code("+");
     function str(strs, ...args) {
-      const expr = [safeStringify2(strs[0])];
+      const expr = [safeStringify(strs[0])];
       let i = 0;
       while (i < args.length) {
         expr.push(plus);
         addCodeArg(expr, args[i]);
-        expr.push(plus, safeStringify2(strs[++i]));
+        expr.push(plus, safeStringify(strs[++i]));
       }
       optimize(expr);
       return new _Code(expr);
@@ -150,16 +150,16 @@ var require_code = __commonJS({
     }
     exports.strConcat = strConcat;
     function interpolate(x) {
-      return typeof x == "number" || typeof x == "boolean" || x === null ? x : safeStringify2(Array.isArray(x) ? x.join(",") : x);
+      return typeof x == "number" || typeof x == "boolean" || x === null ? x : safeStringify(Array.isArray(x) ? x.join(",") : x);
     }
     function stringify(x) {
-      return new _Code(safeStringify2(x));
+      return new _Code(safeStringify(x));
     }
     exports.stringify = stringify;
-    function safeStringify2(x) {
+    function safeStringify(x) {
       return JSON.stringify(x).replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
     }
-    exports.safeStringify = safeStringify2;
+    exports.safeStringify = safeStringify;
     function getProperty(key) {
       return typeof key == "string" && exports.IDENTIFIER.test(key) ? new _Code(`.${key}`) : _`[${key}]`;
     }
@@ -13563,9 +13563,9 @@ function isInitializeRequest2(body) {
   return msg.method === "initialize" && msg.jsonrpc === "2.0";
 }
 
-// src/server/channel.ts
+// src/server/websocket.ts
 import { WebSocketServer, WebSocket } from "ws";
-var AppSessionChannelInternal = class {
+var WebSocketConnectionInternal = class {
   constructor(id, config) {
     this.id = id;
     this.clientSchema = config.client;
@@ -13596,7 +13596,7 @@ var AppSessionChannelInternal = class {
       const message = this.clientSchema ? this.clientSchema.parse(raw) : raw;
       this.handler(message);
     } catch (error) {
-      console.error(`[Channel ${this.id}] Invalid message:`, error);
+      console.error(`[WebSocket ${this.id}] Invalid message:`, error);
     }
   }
   broadcast(message) {
@@ -13610,22 +13610,31 @@ var AppSessionChannelInternal = class {
   }
   closeAll() {
     for (const client of this.clients) {
-      client.close(1e3, "Channel closed");
+      client.close(1e3, "WebSocket closed");
     }
     this.clients.clear();
   }
 };
-var ChannelManager = class {
+var WebSocketManager = class {
   wss = null;
-  channels = /* @__PURE__ */ new Map();
+  httpServer = null;
+  isAttached = false;
+  connections = /* @__PURE__ */ new Map();
+  /**
+   * Store the HTTP server reference for lazy WebSocket attachment.
+   */
+  setServer(server) {
+    this.httpServer = server;
+  }
   /**
-   * Attach the WebSocket server to an HTTP server.
+   * Lazily attach the WebSocket server when first needed.
    */
-  attach(server) {
+  ensureAttached() {
+    if (this.isAttached || !this.httpServer) return;
     this.wss = new WebSocketServer({ noServer: true });
-    server.on("upgrade", (request, socket, head) => {
+    this.httpServer.on("upgrade", (request, socket, head) => {
       const url = request.url || "";
-      if (!url.startsWith("/channels/")) {
+      if (!url.startsWith("/ws/")) {
         socket.destroy();
         return;
       }
@@ -13634,62 +13643,63 @@ var ChannelManager = class {
       });
     });
     this.wss.on("connection", (ws, req) => {
-      const match = req.url?.match(/^\/channels\/([^/]+)\/(.+)$/);
+      const match = req.url?.match(/^\/ws\/(.+)$/);
       if (!match) {
-        ws.close(4e3, "Invalid channel URL");
+        ws.close(4e3, "Invalid WebSocket URL");
         return;
       }
-      const [, channelName, appSessionId] = match;
-      const fullId = `${channelName}/${appSessionId}`;
-      const channel = this.channels.get(fullId);
-      if (!channel) {
-        ws.close(4004, "Channel not found");
+      const [, instanceId] = match;
+      const connection = this.connections.get(instanceId);
+      if (!connection) {
+        ws.close(4004, "Instance not found");
         return;
       }
-      channel.addClient(ws);
+      connection.addClient(ws);
       ws.on("message", (data) => {
         try {
           const message = JSON.parse(data.toString());
-          channel.handleMessage(message);
+          connection.handleMessage(message);
         } catch (e) {
-          console.error(`[Channel] Failed to parse message:`, e);
+          console.error(`[WebSocket] Failed to parse message:`, e);
         }
       });
       ws.on("close", () => {
-        channel.removeClient(ws);
+        connection.removeClient(ws);
       });
       ws.on("error", (error) => {
-        console.error(`[Channel ${fullId}] WebSocket error:`, error);
-        channel.removeClient(ws);
+        console.error(`[WebSocket ${instanceId}] Error:`, error);
+        connection.removeClient(ws);
       });
     });
+    this.isAttached = true;
+    console.log(`WebSocket available at ws://localhost:${this.httpServer.address()?.port || "?"}/ws`);
   }
   /**
-   * Create a new channel for an AppSession.
+   * Create a WebSocket connection for an instance.
+   * Lazily initializes the WebSocket server on first call.
    *
-   * @param channelName - The channel name (e.g., "updates", "terminal")
-   * @param appSessionId - The AppSession ID this channel belongs to
-   * @param config - Channel configuration
+   * @param instanceId - The instance ID
+   * @param config - WebSocket configuration
    * @param port - Server port for WebSocket URL
-   * @returns An AppSessionChannel for bidirectional communication
+   * @returns A WebSocketConnection for bidirectional communication
    */
-  createChannel(channelName, appSessionId, config, port) {
-    const fullId = `${channelName}/${appSessionId}`;
-    const existing = this.channels.get(fullId);
+  createWebSocket(instanceId, config, port) {
+    this.ensureAttached();
+    const existing = this.connections.get(instanceId);
     if (existing) {
       existing.closeAll();
     }
-    const internal = new AppSessionChannelInternal(fullId, config);
-    this.channels.set(fullId, internal);
+    const internal = new WebSocketConnectionInternal(instanceId, config);
+    this.connections.set(instanceId, internal);
     return {
-      appSessionId,
-      url: `ws://localhost:${port}/channels/${channelName}/${appSessionId}`,
+      instanceId,
+      websocketUrl: `ws://localhost:${port}/ws/${instanceId}`,
       send: (msg) => internal.broadcast(msg),
       onMessage: (handler) => internal.setHandler(handler),
       onConnect: (handler) => internal.setConnectHandler(handler),
       close: () => {
         internal.closeAll();
-        this.channels.delete(fullId);
+        this.connections.delete(instanceId);
       },
       get clientCount() {
         return internal.clientCount;
@@ -13697,228 +13707,50 @@ var ChannelManager = class {
     };
   }
   /**
-   * Check if a channel exists for an AppSession.
+   * Check if a WebSocket exists for an instance.
    */
-  hasChannel(channelName, appSessionId) {
-    return this.channels.has(`${channelName}/${appSessionId}`);
+  hasWebSocket(instanceId) {
+    return this.connections.has(instanceId);
   }
   /**
-   * Check if any channels exist.
+   * Close a specific instance's WebSocket.
    */
-  hasAnyChannels() {
-    return this.channels.size > 0;
+  closeWebSocket(instanceId) {
+    const connection = this.connections.get(instanceId);
+    if (connection) {
+      connection.closeAll();
+      this.connections.delete(instanceId);
+      return true;
+    }
+    return false;
   }
   /**
-   * Close all channels and shut down the WebSocket server.
+   * Close all WebSocket connections and shut down the server.
    */
   closeAll() {
-    for (const channel of this.channels.values()) {
-      channel.closeAll();
+    for (const connection of this.connections.values()) {
+      connection.closeAll();
     }
-    this.channels.clear();
+    this.connections.clear();
     if (this.wss) {
       this.wss.close();
       this.wss = null;
     }
-  }
-};
-var ChannelDefinition = class {
-  constructor(manager, name, config, getPort) {
-    this.manager = manager;
-    this.name = name;
-    this.config = config;
-    this.getPort = getPort;
-  }
-  /**
-   * Create a channel for a specific AppSession.
-   *
-   * @param appSessionId - The AppSession ID (e.g., from a terminal AppSession)
-   * @returns An AppSessionChannel for bidirectional communication
-   */
-  forAppSession(appSessionId) {
-    return this.manager.createChannel(this.name, appSessionId, this.config, this.getPort());
-  }
-  /**
-   * Check if a channel exists for an AppSession.
-   */
-  hasChannel(appSessionId) {
-    return this.manager.hasChannel(this.name, appSessionId);
-  }
-  /**
-   * Get the channel name.
-   */
-  get channelName() {
-    return this.name;
-  }
-};
-
-// src/server/appSession.ts
-var ServerAppSession = class {
-  id;
-  _state;
-  listeners = /* @__PURE__ */ new Set();
-  _channel = null;
-  constructor(initialState = {}, options = {}) {
-    this.id = options.id ?? this.generateId();
-    this._state = {
-      internal: initialState.internal ?? {},
-      backend: initialState.backend ?? {},
-      ui: initialState.ui ?? null
-    };
-    console.log(`[AppSession] Created: ${this.id}`);
-  }
-  generateId() {
-    return `appSession_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
-  }
-  get state() {
-    return this._state;
-  }
-  get internal() {
-    return this._state.internal;
-  }
-  get backend() {
-    return this._state.backend;
-  }
-  get ui() {
-    return this._state.ui;
-  }
-  get channel() {
-    return this._channel;
-  }
-  get channelUrl() {
-    return this._channel?.url;
-  }
-  setChannel(channel) {
-    console.log(`[AppSession:${this.id}] Channel attached: ${channel.url}`);
-    this._channel = channel;
-  }
-  subscribe(listener) {
-    this.listeners.add(listener);
-    return () => {
-      this.listeners.delete(listener);
-    };
-  }
-  notify(prevState) {
-    this.listeners.forEach((listener) => listener(this._state, prevState));
-  }
-  setState(partial) {
-    const prev = this._state;
-    this._state = {
-      internal: partial.internal !== void 0 ? { ...prev.internal, ...partial.internal } : prev.internal,
-      backend: partial.backend !== void 0 ? { ...prev.backend, ...partial.backend } : prev.backend,
-      ui: partial.ui !== void 0 ? partial.ui : prev.ui
-    };
-    this.notify(prev);
-  }
-  setInternal(internal) {
-    const prev = this._state;
-    this._state = {
-      ...prev,
-      internal: { ...prev.internal, ...internal }
-    };
-    this.notify(prev);
-  }
-  setBackend(backend) {
-    const prev = this._state;
-    this._state = {
-      ...prev,
-      backend: { ...prev.backend, ...backend }
-    };
-    this.notify(prev);
-  }
-  setUi(ui) {
-    const prev = this._state;
-    this._state = { ...prev, ui };
-    this.notify(prev);
-  }
-  updateUi(partial) {
-    const prev = this._state;
-    const newUi = prev.ui !== null ? { ...prev.ui, ...partial } : partial;
-    this._state = { ...prev, ui: newUi };
-    this.notify(prev);
-  }
-  injectAppSessionId(data) {
-    return { ...data, appSessionId: this.id };
-  }
-  close() {
-    console.log(`[AppSession:${this.id}] Closing`);
-    this._channel?.close();
-    this._channel = null;
-    this.listeners.clear();
-  }
-};
-var AppSessionManager = class {
-  appSessions = /* @__PURE__ */ new Map();
-  channelManager = null;
-  getPort;
-  appSessionChannelName = "app-session";
-  constructor(config) {
-    this.channelManager = config.channelManager ?? null;
-    this.getPort = config.getPort;
-  }
-  setChannelManager(channelManager) {
-    this.channelManager = channelManager;
-  }
-  create(initialState = {}, options = {}) {
-    console.log(`[AppSessionManager] Creating AppSession`, { websockets: options.websockets ?? false });
-    const appSession = new ServerAppSession(initialState, { id: options.id });
-    if (options.websockets && this.channelManager) {
-      const channel = this.channelManager.createChannel(
-        this.appSessionChannelName,
-        appSession.id,
-        {},
-        this.getPort()
-      );
-      appSession.setChannel(channel);
-    }
-    this.appSessions.set(appSession.id, appSession);
-    console.log(`[AppSessionManager] AppSession registered: ${appSession.id} (total: ${this.appSessions.size})`);
-    return appSession;
-  }
-  get(id) {
-    return this.appSessions.get(id);
-  }
-  require(id) {
-    const appSession = this.appSessions.get(id);
-    if (!appSession) {
-      throw new Error(`AppSession not found: ${id}`);
-    }
-    return appSession;
-  }
-  has(id) {
-    return this.appSessions.has(id);
-  }
-  delete(id) {
-    const appSession = this.appSessions.get(id);
-    if (appSession) {
-      console.log(`[AppSessionManager] Deleting AppSession: ${id}`);
-      appSession.close();
-      this.appSessions.delete(id);
-      return true;
-    }
-    console.log(`[AppSessionManager] AppSession not found for deletion: ${id}`);
-    return false;
-  }
-  closeAll() {
-    for (const appSession of this.appSessions.values()) {
-      appSession.close();
-    }
-    this.appSessions.clear();
-  }
-  get size() {
-    return this.appSessions.size;
+    this.isAttached = false;
   }
 };
 
 // src/server/app.ts
 var App = class {
+  // ==========================================================================
+  // Private Properties
+  // ==========================================================================
   config;
   tools = /* @__PURE__ */ new Map();
   resources = /* @__PURE__ */ new Map();
   transports = /* @__PURE__ */ new Map();
-  channelManager = new ChannelManager();
-  channels = /* @__PURE__ */ new Map();
-  appSessionManager;
+  websocketManager = new WebSocketManager();
+  instanceWebSockets = /* @__PURE__ */ new Map();
   httpServer = null;
   isDev;
   hmrPort = null;
@@ -13928,32 +13760,210 @@ var App = class {
   isShuttingDown = false;
   resourceCache = /* @__PURE__ */ new Map();
   resourceCacheConfig;
+  /** Server-side instance state, keyed by instanceId. */
+  instanceState = /* @__PURE__ */ new Map();
+  /** Callbacks to invoke when an instance is destroyed. */
+  instanceDestroyCallbacks = [];
+  /** Singleton instanceIds per resourceUri (for non-multiInstance resources). */
+  singletonInstances = /* @__PURE__ */ new Map();
+  /** Whether the connected host supports multiInstance. ChatGPT doesn't, Creature does. */
+  hostSupportsMultiInstance = false;
+  // ==========================================================================
+  // Constructor
+  // ==========================================================================
   constructor(config, callerDir) {
     this.callerDir = callerDir || process.cwd();
     this.config = config;
     this.isDev = config.dev ?? process.env.NODE_ENV === "development";
-    this.appSessionManager = new AppSessionManager({
-      channelManager: this.channelManager,
-      getPort: () => this.getPort()
-    });
     this.resourceCacheConfig = {
       maxSize: config.resourceCache?.maxSize ?? 100,
       ttlMs: config.resourceCache?.ttlMs ?? 0,
       enabled: config.resourceCache?.enabled ?? true
     };
-    if (this.isDev) {
-      if (config.hmrPort) {
-        this.hmrPort = config.hmrPort;
+    if (this.isDev && config.hmrPort) {
+      this.hmrPort = config.hmrPort;
+    }
+  }
+  // ==========================================================================
+  // Public API: Registration
+  // ==========================================================================
+  /**
+   * Define a UI resource.
+   */
+  resource(config) {
+    if (!config.uri.startsWith("ui://")) {
+      throw new Error(`Resource URI must start with "ui://": ${config.uri}`);
+    }
+    const normalizedConfig = {
+      ...config,
+      html: typeof config.html === "string" ? htmlLoader(config.html, this.getCallerDir()) : config.html
+    };
+    this.resources.set(config.uri, { config: normalizedConfig });
+    return this;
+  }
+  /**
+   * Define a tool.
+   */
+  tool(name, config, handler) {
+    this.tools.set(name, {
+      config,
+      handler
+    });
+    return this;
+  }
+  // ==========================================================================
+  // Public API: Server Lifecycle
+  // ==========================================================================
+  /**
+   * Start the MCP server.
+   */
+  async start() {
+    const port = this.getPort();
+    const expressApp = this.createExpressApp();
+    this.httpServer = expressApp.listen(port, () => {
+      console.log(`MCP server ready on port ${port}`);
+    });
+    this.websocketManager.setServer(this.httpServer);
+    this.registerShutdownHandlers();
+  }
+  /**
+   * Stop the MCP server gracefully.
+   */
+  async stop() {
+    const gracefulTimeout = this.config.gracefulShutdownTimeout ?? 5e3;
+    const keepAliveTimeout = this.config.keepAliveTimeout ?? 5e3;
+    try {
+      await this.config.onShutdown?.();
+    } catch (error) {
+      console.error("[MCP] Error in onShutdown callback:", error);
+    }
+    for (const instanceId of this.instanceState.keys()) {
+      this.destroyInstance(instanceId);
+    }
+    this.websocketManager.closeAll();
+    const transportClosePromises = [...this.transports.values()].map(
+      (transport) => transport.close().catch(() => {
+      })
+    );
+    await Promise.race([
+      Promise.all(transportClosePromises),
+      new Promise((resolve2) => setTimeout(resolve2, gracefulTimeout))
+    ]);
+    this.transports.clear();
+    if (this.httpServer) {
+      this.httpServer.keepAliveTimeout = keepAliveTimeout;
+      await new Promise((resolve2) => {
+        const forceClose = setTimeout(resolve2, gracefulTimeout);
+        this.httpServer?.close(() => {
+          clearTimeout(forceClose);
+          resolve2();
+        });
+      });
+      this.httpServer = null;
+    }
+    console.log("[MCP] Shutdown complete");
+  }
+  // ==========================================================================
+  // Public API: Instance Lifecycle
+  // ==========================================================================
+  /**
+   * Create an instance with optional WebSocket support.
+   * 
+   * Most tools don't need this — the SDK creates instances automatically.
+   * Only call createInstance() when you need a WebSocket URL for real-time updates.
+   */
+  createInstance(options = {}) {
+    const instanceId = this.generateInstanceId();
+    if (options.websocket) {
+      const ws = this.websocketManager.createWebSocket(
+        instanceId,
+        {},
+        this.getPort()
+      );
+      this.instanceWebSockets.set(instanceId, ws);
+      return {
+        instanceId,
+        websocketUrl: ws.websocketUrl,
+        send: ws.send,
+        onMessage: ws.onMessage,
+        onConnect: ws.onConnect
+      };
+    }
+    return { instanceId };
+  }
+  /**
+   * Register a callback to be invoked when an instance is destroyed.
+   */
+  onInstanceDestroy(callback) {
+    this.instanceDestroyCallbacks.push(callback);
+  }
+  /**
+   * Destroy an instance and clean up its resources.
+   */
+  destroyInstance(instanceId) {
+    const state = this.instanceState.get(instanceId);
+    const hasState = state !== void 0 || this.instanceState.has(instanceId);
+    const hasWebSocket = this.instanceWebSockets.has(instanceId);
+    if (hasState || hasWebSocket) {
+      for (const callback of this.instanceDestroyCallbacks) {
+        try {
+          callback({ instanceId, state });
+        } catch (error) {
+          console.error(`[MCP] onInstanceDestroy callback error for ${instanceId}:`, error);
+        }
+      }
+      const ws = this.instanceWebSockets.get(instanceId);
+      if (ws) {
+        ws.close();
+        this.instanceWebSockets.delete(instanceId);
       }
+      this.instanceState.delete(instanceId);
+      console.log(`[MCP] Instance destroyed: ${instanceId}`);
+      return true;
     }
+    return false;
+  }
+  /**
+   * Check if an instance exists.
+   */
+  hasInstance(instanceId) {
+    return this.instanceState.has(instanceId);
+  }
+  /**
+   * Get instance state.
+   */
+  getInstanceState(instanceId) {
+    return this.instanceState.get(instanceId);
   }
-  // ============================================================================
-  // Public API: Transport Session Lifecycle
-  // ============================================================================
+  /**
+   * Set instance state directly.
+   */
+  setInstanceState(instanceId, state) {
+    this.instanceState.set(instanceId, state);
+  }
+  /**
+   * 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).
+   */
+  createWebSocketForInstance(instanceId) {
+    if (this.instanceWebSockets.has(instanceId)) {
+      return this.instanceWebSockets.get(instanceId);
+    }
+    const ws = this.websocketManager.createWebSocket(
+      instanceId,
+      {},
+      this.getPort()
+    );
+    this.instanceWebSockets.set(instanceId, ws);
+    return ws;
+  }
+  // ==========================================================================
+  // Public API: Transport Sessions
+  // ==========================================================================
   /**
    * Get list of active transport sessions.
-   * Transport sessions are MCP protocol connections (not AppSessions).
-   * Useful for monitoring and debugging connection state.
    */
   getTransportSessions() {
     return [...this.transports.keys()].map((id) => ({
@@ -13969,9 +13979,6 @@ var App = class {
   }
   /**
    * Close a specific transport session.
-   *
-   * @param sessionId - The transport session ID to close
-   * @returns true if the session was found and closed
    */
   closeTransportSession(sessionId) {
     const transport = this.transports.get(sessionId);
@@ -13983,28 +13990,23 @@ var App = class {
     }
     return false;
   }
-  // ============================================================================
-  // Public API: Resource Cache Management
-  // ============================================================================
+  // ==========================================================================
+  // Public API: Resource Cache
+  // ==========================================================================
   /**
    * Clear all cached resource content.
-   * Use after updating UI files during development.
    */
   clearResourceCache() {
     this.resourceCache.clear();
   }
   /**
    * 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) {
     return this.resourceCache.delete(uri);
   }
   /**
    * Get resource cache statistics.
-   * Useful for monitoring cache performance.
    */
   getResourceCacheStats() {
     return {
@@ -14013,9 +14015,84 @@ var App = class {
       enabled: this.resourceCacheConfig.enabled
     };
   }
+  // ==========================================================================
+  // Private: Configuration Helpers
+  // ==========================================================================
+  getPort() {
+    return this.config.port || parseInt(process.env.MCP_PORT || process.env.PORT || "3000", 10);
+  }
+  getCallerDir() {
+    return this.callerDir;
+  }
+  getHmrPort() {
+    if (!this.isDev) return null;
+    if (this.hmrPort !== null) return this.hmrPort;
+    const hmrConfig = readHmrConfig();
+    if (hmrConfig) {
+      this.hmrPort = hmrConfig.port;
+    }
+    this.hmrConfigChecked = true;
+    return this.hmrPort;
+  }
+  // ==========================================================================
+  // Private: Instance Helpers
+  // ==========================================================================
+  generateInstanceId() {
+    return `inst_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+  }
+  /**
+   * 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)
+   */
+  resolveInstanceId(resourceUri, inputInstanceId) {
+    if (typeof inputInstanceId === "string") {
+      return inputInstanceId;
+    }
+    const resource = this.resources.get(resourceUri);
+    const isMultiInstance = resource?.config.multiInstance && this.hostSupportsMultiInstance;
+    if (isMultiInstance) {
+      return this.generateInstanceId();
+    }
+    let instanceId = this.singletonInstances.get(resourceUri);
+    if (!instanceId) {
+      instanceId = this.generateInstanceId();
+      this.singletonInstances.set(resourceUri, instanceId);
+      console.log(`[MCP] Singleton instance created for ${resourceUri}: ${instanceId}`);
+    }
+    return instanceId;
+  }
+  // ==========================================================================
+  // Private: Schema Introspection
+  // ==========================================================================
+  /**
+   * Extract the shape (properties) from a Zod schema.
+   */
+  getSchemaShape(schema) {
+    if ("_def" in schema && typeof schema._def?.shape === "function") {
+      return schema._def.shape();
+    }
+    return void 0;
+  }
   /**
-   * Get a cached resource if valid, or null if not cached/expired.
+   * Check if a field is required in a Zod schema.
    */
+  isFieldRequired(schema, fieldName) {
+    const shape = this.getSchemaShape(schema);
+    if (!shape || !(fieldName in shape)) return false;
+    const field = shape[fieldName];
+    if ("_def" in field && field._def?.typeName === "ZodOptional") {
+      return false;
+    }
+    return true;
+  }
+  // ==========================================================================
+  // Private: Resource Cache
+  // ==========================================================================
   getCachedResource(uri) {
     if (!this.resourceCacheConfig.enabled) return null;
     const cached = this.resourceCache.get(uri);
@@ -14027,9 +14104,6 @@ var App = class {
     }
     return cached.html;
   }
-  /**
-   * Store a resource in the cache with LRU eviction.
-   */
   setCachedResource(uri, html) {
     if (!this.resourceCacheConfig.enabled) return;
     const { maxSize } = this.resourceCacheConfig;
@@ -14041,81 +14115,136 @@ var App = class {
     }
     this.resourceCache.set(uri, { html, timestamp: Date.now() });
   }
-  /**
-   * 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.
-   */
-  getHmrPort() {
-    if (!this.isDev) return null;
-    if (this.hmrPort !== null) return this.hmrPort;
-    const hmrConfig = readHmrConfig();
-    if (hmrConfig) {
-      this.hmrPort = hmrConfig.port;
-    }
-    this.hmrConfigChecked = true;
-    return this.hmrPort;
+  // ==========================================================================
+  // Private: Express Server
+  // ==========================================================================
+  createExpressApp() {
+    const app = express();
+    app.use(express.json());
+    app.use((req, res, next) => {
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+      res.setHeader("Access-Control-Allow-Headers", "Content-Type, Accept, Mcp-Session-Id");
+      res.setHeader("Access-Control-Expose-Headers", "Mcp-Session-Id");
+      if (req.method === "OPTIONS") {
+        res.status(204).end();
+        return;
+      }
+      next();
+    });
+    app.get("/health", (_req, res) => {
+      res.json({
+        status: "ok",
+        server: this.config.name,
+        version: this.config.version,
+        activeSessions: this.transports.size,
+        websockets: this.instanceWebSockets.size
+      });
+    });
+    app.post("/mcp", (req, res) => this.handleMcpPost(req, res));
+    app.get("/mcp", (req, res) => this.handleMcpGet(req, res));
+    app.delete("/mcp", (req, res) => this.handleMcpDelete(req, res));
+    return app;
   }
-  getCallerDir() {
-    return this.callerDir;
+  async handleMcpPost(req, res) {
+    const transportSessionId = req.headers["mcp-session-id"];
+    try {
+      let transport;
+      if (transportSessionId && this.transports.has(transportSessionId)) {
+        transport = this.transports.get(transportSessionId);
+      } else if (!transportSessionId && isInitializeRequest2(req.body)) {
+        const clientName = req.body?.params?.clientInfo?.name;
+        this.hostSupportsMultiInstance = clientName === "creature";
+        console.log(`[MCP] Client: ${clientName}, multiInstance support: ${this.hostSupportsMultiInstance}`);
+        transport = this.createTransport();
+        const server = this.createMcpServer();
+        await server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+        return;
+      } else {
+        res.status(400).json({
+          jsonrpc: "2.0",
+          error: { code: -32e3, message: "Bad Request: No valid transport session ID" },
+          id: null
+        });
+        return;
+      }
+      await transport.handleRequest(req, res, req.body);
+    } catch (error) {
+      console.error("Error:", error);
+      if (!res.headersSent) {
+        res.status(500).json({
+          jsonrpc: "2.0",
+          error: { code: -32603, message: "Internal server error" },
+          id: null
+        });
+      }
+    }
   }
-  /**
-   * Define a UI resource.
-   */
-  resource(config) {
-    if (!config.uri.startsWith("ui://")) {
-      throw new Error(`Resource URI must start with "ui://": ${config.uri}`);
+  async handleMcpGet(req, res) {
+    const transportSessionId = req.headers["mcp-session-id"];
+    if (!transportSessionId || !this.transports.has(transportSessionId)) {
+      res.status(400).send("Invalid or missing transport session ID");
+      return;
     }
-    const normalizedConfig = {
-      ...config,
-      html: typeof config.html === "string" ? htmlLoader(config.html, this.getCallerDir()) : config.html
-    };
-    this.resources.set(config.uri, { config: normalizedConfig });
-    return this;
+    const transport = this.transports.get(transportSessionId);
+    await transport.handleRequest(req, res);
   }
-  tool(name, config, handler) {
-    this.tools.set(name, {
-      config,
-      handler
+  async handleMcpDelete(req, res) {
+    const transportSessionId = req.headers["mcp-session-id"];
+    if (!transportSessionId || !this.transports.has(transportSessionId)) {
+      res.status(400).send("Invalid or missing transport session ID");
+      return;
+    }
+    const transport = this.transports.get(transportSessionId);
+    await transport.handleRequest(req, res);
+  }
+  // ==========================================================================
+  // Private: MCP Server & Transport
+  // ==========================================================================
+  createTransport() {
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID(),
+      onsessioninitialized: (newSessionId) => {
+        this.transports.set(newSessionId, transport);
+        console.log(`[MCP] Transport session created: ${newSessionId}`);
+        this.config.onTransportSessionCreated?.({
+          id: newSessionId,
+          transport: "streamable-http"
+        });
+      }
     });
-    return this;
-  }
-  channel(name, config = {}) {
-    const definition = new ChannelDefinition(
-      this.channelManager,
-      name,
-      config,
-      () => this.getPort()
-    );
-    this.channels.set(name, definition);
-    return definition;
-  }
-  getPort() {
-    return this.config.port || parseInt(process.env.MCP_PORT || process.env.PORT || "3000", 10);
-  }
-  session(initialState = {}, options = {}) {
-    return this.appSessionManager.create(initialState, options);
-  }
-  getSession(id) {
-    return this.appSessionManager.get(id);
-  }
-  requireSession(id) {
-    return this.appSessionManager.require(id);
-  }
-  hasSession(id) {
-    return this.appSessionManager.has(id);
-  }
-  closeSession(id) {
-    return this.appSessionManager.delete(id);
+    transport.onerror = (error) => {
+      const sid = transport.sessionId || "unknown";
+      console.error(`[MCP] Transport session error for ${sid}:`, error.message);
+      this.config.onTransportSessionError?.(
+        { id: sid, transport: "streamable-http" },
+        error
+      );
+    };
+    transport.onclose = () => {
+      const sid = transport.sessionId;
+      if (sid) {
+        console.log(`[MCP] Transport session closed: ${sid}. Client should re-initialize to continue.`);
+        this.transports.delete(sid);
+        this.config.onTransportSessionClosed?.({
+          id: sid,
+          transport: "streamable-http"
+        });
+      }
+    };
+    return transport;
   }
-  /**
-   * Create an MCP server instance with all registered tools and resources.
-   */
   createMcpServer() {
     const server = new McpServer(
       { name: this.config.name, version: this.config.version },
       { capabilities: { logging: {} } }
     );
+    this.registerResources(server);
+    this.registerTools(server);
+    return server;
+  }
+  registerResources(server) {
     for (const [uri, { config }] of this.resources) {
       server.registerResource(
         config.name,
@@ -14131,7 +14260,6 @@ var App = class {
             html = injectHmrClient(html, hmrPort);
           }
           const mcpAppsMeta = {
-            // MCP Apps Extension metadata
             ui: {
               displayModes: config.displayModes,
               ...config.icon && {
@@ -14142,7 +14270,6 @@ var App = class {
               },
               ...config.csp && { csp: config.csp }
             },
-            // ChatGPT Apps SDK metadata (also included in MCP Apps format)
             "openai/widgetPrefersBorder": true
           };
           const chatgptMeta = {
@@ -14150,14 +14277,12 @@ var App = class {
           };
           return {
             contents: [
-              // MCP Apps format (with both MCP and ChatGPT metadata)
               {
                 uri,
                 mimeType: MIME_TYPES.MCP_APPS,
                 text: html,
                 _meta: mcpAppsMeta
               },
-              // ChatGPT format (skybridge MIME type)
               {
                 uri,
                 mimeType: MIME_TYPES.CHATGPT,
@@ -14169,39 +14294,62 @@ var App = class {
         }
       );
     }
+  }
+  registerTools(server) {
     for (const [name, { config, handler }] of this.tools) {
-      const toolMeta = {};
-      if (config.ui) {
-        toolMeta.ui = {
-          resourceUri: config.ui,
-          visibility: config.visibility || ["model", "app"],
-          ...config.displayModes && { displayModes: config.displayModes },
-          ...config.defaultDisplayMode && {
-            defaultDisplayMode: config.defaultDisplayMode
-          },
-          ...config.multiSession && { multiSession: config.multiSession }
-        };
-        toolMeta["openai/outputTemplate"] = config.ui;
-      }
-      if (config.loadingMessage) {
-        toolMeta["openai/toolInvocation/invoking"] = config.loadingMessage;
-      }
-      if (config.completedMessage) {
-        toolMeta["openai/toolInvocation/invoked"] = config.completedMessage;
-      }
+      const toolMeta = this.buildToolMeta(config);
       const inputSchema = config.input || z2.object({});
+      const description = this.buildToolDescription(config, inputSchema);
+      const hasUi = !!config.ui;
       server.registerTool(
         name,
         {
-          description: config.description,
+          description,
           inputSchema,
           ...Object.keys(toolMeta).length > 0 && { _meta: toolMeta }
         },
         async (args) => {
           try {
             const input = config.input ? config.input.parse(args) : args;
-            const result = await handler(input, {});
-            return this.formatToolResult(result);
+            let instanceId;
+            if (hasUi && config.ui) {
+              instanceId = this.resolveInstanceId(config.ui, args.instanceId);
+            }
+            const resource = config.ui ? this.resources.get(config.ui) : void 0;
+            const hasWebSocket = resource?.config.websocket === true;
+            let ws;
+            let websocketUrl;
+            if (hasWebSocket && instanceId) {
+              ws = this.getOrCreateWebSocket(instanceId);
+              websocketUrl = ws?.websocketUrl;
+            }
+            const context = {
+              instanceId: instanceId || "",
+              getState: () => instanceId ? this.instanceState.get(instanceId) : void 0,
+              setState: (state) => {
+                if (instanceId) {
+                  this.instanceState.set(instanceId, state);
+                }
+              },
+              send: (message) => {
+                if (ws) {
+                  ws.send(message);
+                }
+              },
+              onMessage: (messageHandler) => {
+                if (ws) {
+                  ws.onMessage(messageHandler);
+                }
+              },
+              onConnect: (connectHandler) => {
+                if (ws) {
+                  ws.onConnect(connectHandler);
+                }
+              },
+              websocketUrl
+            };
+            const result = await handler(input, context);
+            return this.formatToolResult(result, instanceId, websocketUrl);
           } catch (error) {
             const err = error instanceof Error ? error : new Error(String(error));
             console.error(`[MCP] Tool "${name}" failed:`, err.message);
@@ -14214,182 +14362,96 @@ var App = class {
         }
       );
     }
-    return server;
   }
   /**
-   * Format a tool result into MCP format.
+   * Get or create a WebSocket for an instance.
+   * Used internally by registerTools when resource has websocket: true.
    */
-  formatToolResult(result) {
+  getOrCreateWebSocket(instanceId) {
+    const existing = this.instanceWebSockets.get(instanceId);
+    if (existing) {
+      return existing;
+    }
+    const ws = this.websocketManager.createWebSocket(instanceId, {}, this.getPort());
+    this.instanceWebSockets.set(instanceId, ws);
+    console.log(`[MCP] WebSocket created for instance ${instanceId}`);
+    return ws;
+  }
+  buildToolMeta(config) {
+    const toolMeta = {};
+    if (config.ui) {
+      toolMeta.ui = {
+        resourceUri: config.ui,
+        visibility: config.visibility || ["model", "app"],
+        ...config.displayModes && { displayModes: config.displayModes },
+        ...config.defaultDisplayMode && { defaultDisplayMode: config.defaultDisplayMode }
+      };
+      toolMeta["openai/outputTemplate"] = config.ui;
+    }
+    if (config.loadingMessage) {
+      toolMeta["openai/toolInvocation/invoking"] = config.loadingMessage;
+    }
+    if (config.completedMessage) {
+      toolMeta["openai/toolInvocation/invoked"] = config.completedMessage;
+    }
+    return toolMeta;
+  }
+  buildToolDescription(config, inputSchema) {
+    let description = config.description;
+    if (config.ui) {
+      const schemaShape = this.getSchemaShape(inputSchema);
+      const hasInstanceIdInSchema = schemaShape && "instanceId" in schemaShape;
+      const isInstanceIdRequired = this.isFieldRequired(inputSchema, "instanceId");
+      if (isInstanceIdRequired) {
+        description += " Requires instanceId from a previous tool response.";
+      } else if (hasInstanceIdInSchema) {
+        description += " Returns instanceId. Pass it in subsequent calls to target the same widget.";
+      } else {
+        description += " Returns instanceId for the new widget.";
+      }
+    }
+    return description;
+  }
+  /**
+   * Format tool result for MCP protocol response.
+   * 
+   * SDK manages instanceId and websocketUrl automatically.
+   */
+  formatToolResult(result, instanceId, websocketUrl) {
     const text = result.text || JSON.stringify(result.data || {});
     const structuredContent = {
       ...result.data,
       ...result.title && { title: result.title },
-      ...result.inlineHeight && { inlineHeight: result.inlineHeight }
+      ...result.inlineHeight && { inlineHeight: result.inlineHeight },
+      ...instanceId && { instanceId },
+      ...websocketUrl && { websocketUrl }
     };
+    const meta = {};
+    if (instanceId) {
+      meta["openai/widgetSessionId"] = instanceId;
+    }
     return {
       content: [{ type: "text", text }],
       ...Object.keys(structuredContent).length > 0 && { structuredContent },
+      ...Object.keys(meta).length > 0 && { _meta: meta },
       ...result.isError && { isError: true }
     };
   }
-  async start() {
-    const port = this.getPort();
-    const expressApp = express();
-    expressApp.use(express.json());
-    expressApp.use((req, res, next) => {
-      res.setHeader("Access-Control-Allow-Origin", "*");
-      res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
-      res.setHeader("Access-Control-Allow-Headers", "Content-Type, Accept, Mcp-Session-Id");
-      res.setHeader("Access-Control-Expose-Headers", "Mcp-Session-Id");
-      if (req.method === "OPTIONS") {
-        res.status(204).end();
-        return;
-      }
-      next();
-    });
-    expressApp.get("/health", (_req, res) => {
-      res.json({
-        status: "ok",
-        server: this.config.name,
-        version: this.config.version,
-        activeSessions: this.transports.size,
-        channels: this.channels.size
-      });
-    });
-    expressApp.post("/mcp", async (req, res) => {
-      const transportSessionId = req.headers["mcp-session-id"];
-      try {
-        let transport;
-        if (transportSessionId && this.transports.has(transportSessionId)) {
-          transport = this.transports.get(transportSessionId);
-        } else if (!transportSessionId && isInitializeRequest2(req.body)) {
-          transport = new StreamableHTTPServerTransport({
-            sessionIdGenerator: () => randomUUID(),
-            onsessioninitialized: (newSessionId) => {
-              this.transports.set(newSessionId, transport);
-              console.log(`[MCP] Transport session created: ${newSessionId}`);
-              this.config.onTransportSessionCreated?.({
-                id: newSessionId,
-                transport: "streamable-http"
-              });
-            }
-          });
-          transport.onerror = (error) => {
-            const sid = transport.sessionId || "unknown";
-            console.error(`[MCP] Transport session error for ${sid}:`, error.message);
-            this.config.onTransportSessionError?.(
-              { id: sid, transport: "streamable-http" },
-              error
-            );
-          };
-          transport.onclose = () => {
-            const sid = transport.sessionId;
-            if (sid) {
-              console.log(`[MCP] Transport session closed: ${sid}. Client should re-initialize to continue.`);
-              this.transports.delete(sid);
-              this.config.onTransportSessionClosed?.({
-                id: sid,
-                transport: "streamable-http"
-              });
-            }
-          };
-          const server = this.createMcpServer();
-          await server.connect(transport);
-          await transport.handleRequest(req, res, req.body);
-          return;
-        } else {
-          res.status(400).json({
-            jsonrpc: "2.0",
-            error: { code: -32e3, message: "Bad Request: No valid transport session ID" },
-            id: null
-          });
-          return;
-        }
-        await transport.handleRequest(req, res, req.body);
-      } catch (error) {
-        console.error("Error:", error);
-        if (!res.headersSent) {
-          res.status(500).json({
-            jsonrpc: "2.0",
-            error: { code: -32603, message: "Internal server error" },
-            id: null
-          });
-        }
-      }
-    });
-    expressApp.get("/mcp", async (req, res) => {
-      const transportSessionId = req.headers["mcp-session-id"];
-      if (!transportSessionId || !this.transports.has(transportSessionId)) {
-        res.status(400).send("Invalid or missing transport session ID");
-        return;
-      }
-      const transport = this.transports.get(transportSessionId);
-      await transport.handleRequest(req, res);
-    });
-    expressApp.delete("/mcp", async (req, res) => {
-      const transportSessionId = req.headers["mcp-session-id"];
-      if (!transportSessionId || !this.transports.has(transportSessionId)) {
-        res.status(400).send("Invalid or missing transport session ID");
-        return;
-      }
-      const transport = this.transports.get(transportSessionId);
-      await transport.handleRequest(req, res);
-    });
-    this.httpServer = expressApp.listen(port, () => {
-      console.log(`MCP server ready on port ${port}`);
-    });
-    this.channelManager.attach(this.httpServer);
-    console.log(`WebSocket channels available at ws://localhost:${port}/channels`);
-    if (!this.shutdownRegistered) {
-      this.shutdownRegistered = true;
-      const handleShutdown = async (signal) => {
-        if (this.isShuttingDown) return;
-        this.isShuttingDown = true;
-        console.log(`[MCP] ${signal} received, shutting down gracefully...`);
-        await this.stop();
-        process.exit(0);
-      };
-      process.on("SIGINT", () => handleShutdown("SIGINT"));
-      process.on("SIGTERM", () => handleShutdown("SIGTERM"));
-    }
-  }
-  /**
-   * Stop the MCP server gracefully.
-   *
-   * Calls the onShutdown callback, closes all sessions and channels,
-   * then waits for active transports to close (with timeout).
-   */
-  async stop() {
-    const gracefulTimeout = this.config.gracefulShutdownTimeout ?? 5e3;
-    const keepAliveTimeout = this.config.keepAliveTimeout ?? 5e3;
-    try {
-      await this.config.onShutdown?.();
-    } catch (error) {
-      console.error("[MCP] Error in onShutdown callback:", error);
-    }
-    this.appSessionManager.closeAll();
-    this.channelManager.closeAll();
-    const transportClosePromises = [...this.transports.values()].map(
-      (transport) => transport.close().catch(() => {
-      })
-    );
-    await Promise.race([
-      Promise.all(transportClosePromises),
-      new Promise((resolve2) => setTimeout(resolve2, gracefulTimeout))
-    ]);
-    this.transports.clear();
-    if (this.httpServer) {
-      this.httpServer.keepAliveTimeout = keepAliveTimeout;
-      await new Promise((resolve2) => {
-        const forceClose = setTimeout(resolve2, gracefulTimeout);
-        this.httpServer?.close(() => {
-          clearTimeout(forceClose);
-          resolve2();
-        });
-      });
-      this.httpServer = null;
-    }
-    console.log("[MCP] Shutdown complete");
+  // ==========================================================================
+  // Private: Shutdown
+  // ==========================================================================
+  registerShutdownHandlers() {
+    if (this.shutdownRegistered) return;
+    this.shutdownRegistered = true;
+    const handleShutdown = async (signal) => {
+      if (this.isShuttingDown) return;
+      this.isShuttingDown = true;
+      console.log(`[MCP] ${signal} received, shutting down gracefully...`);
+      await this.stop();
+      process.exit(0);
+    };
+    process.on("SIGINT", () => handleShutdown("SIGINT"));
+    process.on("SIGTERM", () => handleShutdown("SIGTERM"));
   }
 };
 function isSDKPath(filename) {
@@ -14477,10 +14539,7 @@ function wrapServer(server) {
 }
 export {
   App,
-  AppSessionManager,
-  ChannelDefinition,
   MIME_TYPES,
-  ServerAppSession,
   createApp,
   htmlLoader,
   loadHtml,