@soederpop/luca 0.0.26 → 0.0.28

package/src/introspection/generated.node.ts

@@ -1,7 +1,7 @@
 import { setBuildTimeData, setContainerBuildTimeData } from './index.js';
 
 // Auto-generated introspection registry data
-// Generated at: 2026-03-22T20:57:23.101Z
+// Generated at: 2026-03-23T07:45:56.976Z
 
 setBuildTimeData('features.googleDocs', {
   "id": "features.googleDocs",
@@ -1525,7 +1525,7 @@ setBuildTimeData('features.downloader', {
 
 setBuildTimeData('features.windowManager', {
   "id": "features.windowManager",
-  "description": "WindowManager Feature — Native window control via LucaVoiceLauncher Acts as an IPC server that the native macOS launcher app connects to. Communicates over a Unix domain socket using NDJSON (newline-delimited JSON). **Protocol:** - Bun listens on a Unix domain socket; the native app connects as a client - Window dispatch commands are sent as NDJSON with a `window` field - The app executes window commands and sends back `windowAck` messages - Any non-windowAck message from the app is emitted as a `message` event - Other features can use `send()` to write arbitrary NDJSON to the app **Capabilities:** - Spawn native browser windows with configurable chrome - Navigate, focus, close, and eval JavaScript in windows - Automatic socket file cleanup and fallback paths",
+  "description": "WindowManager Feature — Native window control via LucaVoiceLauncher Uses a broker/producer architecture so multiple luca processes can trigger window operations without competing for the same Unix socket. **Architecture:** - The first process to call `listen()` becomes the **broker**. It owns the app-facing socket (`ipc-window.sock`) and a control socket (`ipc-window-control.sock`). - Subsequent processes detect the broker and become **producers**. They connect to the control socket and route commands through the broker. - The broker forwards producer commands to the native app and routes acks and lifecycle events back to the originating producer. **Protocol:** - Bun listens on a Unix domain socket; the native app connects as a client - Window dispatch commands are sent as NDJSON with a `window` field - The app executes window commands and sends back `windowAck` messages - Any non-windowAck message from the app is emitted as a `message` event - Other features can use `send()` to write arbitrary NDJSON to the app **Capabilities:** - Spawn native browser windows with configurable chrome - Navigate, focus, close, and eval JavaScript in windows - Multiple luca processes can trigger window operations simultaneously - Automatic broker detection and producer fallback Observable state includes `windows` (open window metadata), `pendingOperations` (in-flight command ids), and `producerCount` (broker). Sockets, promises, and `WindowHandle` instances stay internal. **Producer state:** The broker pushes `windowStateSync` on the control socket when a producer connects and whenever the window roster changes, so every process sees the same `windows` / `windowCount` / `clientConnected` as the broker (not only its own acks).",
   "shortcut": "features.windowManager",
   "className": "WindowManager",
   "methods": {
@@ -1541,7 +1541,18 @@ setBuildTimeData('features.windowManager', {
       "returns": "Promise<this>"
     },
     "listen": {
-      "description": "Start listening on the Unix domain socket for the native app to connect. Fire-and-forget — binds the socket and returns immediately. Sits quietly until the native app connects; does nothing visible if it never does.",
+      "description": "Start the window manager. Automatically detects whether a broker already exists and either becomes the broker or connects as a producer. - If no broker is running: becomes the broker, binds the app socket and a control socket for producers. - If a broker is already running: connects as a producer through the control socket.",
+      "parameters": {
+        "socketPath": {
+          "type": "string",
+          "description": "Override the configured app socket path"
+        }
+      },
+      "required": [],
+      "returns": "Promise<this>"
+    },
+    "cleanupSocket": {
+      "description": "Remove stale socket files without starting or stopping the server. Useful when a previous process crashed and left dead sockets behind. Will not remove sockets that have live listeners.",
       "parameters": {
         "socketPath": {
           "type": "string",
@@ -1549,10 +1560,10 @@ setBuildTimeData('features.windowManager', {
         }
       },
       "required": [],
-      "returns": "this"
+      "returns": "Promise<boolean>"
     },
     "stop": {
-      "description": "Stop the IPC server and clean up all connections. Rejects any pending window operation requests.",
+      "description": "Stop the window manager and clean up all connections. Rejects any pending window operation requests.",
       "parameters": {},
       "required": [],
       "returns": "Promise<this>"
@@ -1825,7 +1836,7 @@ setBuildTimeData('features.windowManager', {
       ]
     },
     "send": {
-      "description": "Write an NDJSON message to the connected app client. Public so other features can send arbitrary protocol messages over the same socket.",
+      "description": "Write an NDJSON message to the connected app client. In producer mode, routes through the broker. Public so other features can send arbitrary protocol messages over the same socket.",
       "parameters": {
         "msg": {
           "type": "Record<string, any>",
@@ -1839,12 +1850,20 @@ setBuildTimeData('features.windowManager', {
     }
   },
   "getters": {
+    "isBroker": {
+      "description": "Whether this instance is acting as the broker.",
+      "returns": "boolean"
+    },
+    "isProducer": {
+      "description": "Whether this instance is acting as a producer.",
+      "returns": "boolean"
+    },
     "isListening": {
-      "description": "Whether the IPC server is currently listening.",
+      "description": "Whether the IPC server is currently listening (broker) or connected to broker (producer).",
       "returns": "boolean"
     },
     "isClientConnected": {
-      "description": "Whether the native app client is currently connected.",
+      "description": "Whether the native app client is currently connected (only meaningful for broker).",
       "returns": "boolean"
     }
   },
@@ -1879,6 +1898,11 @@ setBuildTimeData('features.windowManager', {
       "description": "Event emitted by WindowManager",
       "arguments": {}
     },
+    "windowFocus": {
+      "name": "windowFocus",
+      "description": "Event emitted by WindowManager",
+      "arguments": {}
+    },
     "message": {
       "name": "message",
       "description": "Event emitted by WindowManager",
@@ -6223,7 +6247,7 @@ setBuildTimeData('features.fs', {
 
 setBuildTimeData('features.ipcSocket', {
   "id": "features.ipcSocket",
-  "description": "IpcSocket Feature - Inter-Process Communication via Unix Domain Sockets This feature provides robust IPC (Inter-Process Communication) capabilities using Unix domain sockets. It supports both server and client modes, allowing processes to communicate efficiently through file system-based socket connections. **Key Features:** - Dual-mode operation: server and client functionality - JSON message serialization/deserialization - Multiple client connection support (server mode) - Event-driven message handling - Automatic socket cleanup and management - Broadcast messaging to all connected clients - Lock file management for socket paths **Communication Pattern:** - Messages are automatically JSON-encoded with unique IDs - Both server and client emit 'message' events for incoming data - Server can broadcast to all connected clients - Client maintains single connection to server **Socket Management:** - Automatic cleanup of stale socket files - Connection tracking and management - Graceful shutdown procedures - Lock file protection against conflicts **Usage Examples:** **Server Mode:** ```typescript const ipc = container.feature('ipcSocket'); await ipc.listen('/tmp/myapp.sock', true); // removeLock=true ipc.on('connection', (socket) => { console.log('Client connected'); }); ipc.on('message', (data) => { console.log('Received:', data); ipc.broadcast({ reply: 'ACK', original: data }); }); ``` **Client Mode:** ```typescript const ipc = container.feature('ipcSocket'); await ipc.connect('/tmp/myapp.sock'); ipc.on('message', (data) => { console.log('Server says:', data); }); await ipc.send({ type: 'request', payload: 'hello' }); ```",
+  "description": "IpcSocket Feature - Inter-Process Communication via Unix Domain Sockets This feature provides robust IPC (Inter-Process Communication) capabilities using Unix domain sockets. It supports both server and client modes, allowing processes to communicate efficiently through file system-based socket connections. **Key Features:** - Hub-and-spoke: one server, many named clients with identity tracking - Targeted messaging: sendTo(clientId), broadcast(msg, excludeId) - Request/reply: ask() + reply() with timeout-based correlation - Auto-reconnect: clients reconnect with exponential backoff - Stale socket detection: probeSocket() before listen() - Clean shutdown: stopServer() removes socket file **Server (Hub):** ```typescript const ipc = container.feature('ipcSocket'); await ipc.listen('/tmp/hub.sock', true); ipc.on('connection', (clientId, socket) => { console.log('Client joined:', clientId); }); ipc.on('message', (data, clientId) => { console.log(`From ${clientId}:`, data); // Reply to sender, or ask and wait ipc.sendTo(clientId, { ack: true }); }); ``` **Client (Spoke):** ```typescript const ipc = container.feature('ipcSocket'); await ipc.connect('/tmp/hub.sock', { reconnect: true, name: 'worker-1' }); // Fire and forget await ipc.send({ type: 'status', ready: true }); // Request/reply ipc.on('message', (data) => { if (data.requestId) ipc.reply(data.requestId, { result: 42 }); }); ```",
   "shortcut": "features.ipcSocket",
   "className": "IpcSocket",
   "methods": {
@@ -6263,61 +6287,127 @@ setBuildTimeData('features.ipcSocket', {
       ]
     },
     "broadcast": {
-      "description": "Broadcasts a message to all connected clients (server mode only). This method sends a JSON-encoded message with a unique ID to every client currently connected to the server. Each message is automatically wrapped with metadata including a UUID for tracking. **Message Format:** Messages are automatically wrapped in the format: ```json { \"data\": <your_message>, \"id\": \"<uuid>\" } ```",
+      "description": "Broadcasts a message to all connected clients (server mode only).",
       "parameters": {
         "message": {
           "type": "any",
-          "description": "The message object to broadcast to all clients"
+          "description": "The message object to broadcast"
+        },
+        "exclude": {
+          "type": "string",
+          "description": "Optional client ID to exclude from broadcast"
         }
       },
       "required": [
         "message"
       ],
-      "returns": "void",
-      "examples": [
-        {
-          "language": "ts",
-          "code": "// Broadcast to all connected clients\nipc.broadcast({ \n type: 'notification',\n message: 'Server is shutting down in 30 seconds',\n timestamp: Date.now()\n});\n\n// Chain multiple operations\nipc.broadcast({ status: 'ready' })\n  .broadcast({ time: new Date().toISOString() });"
+      "returns": "void"
+    },
+    "sendTo": {
+      "description": "Sends a message to a specific client by ID (server mode only).",
+      "parameters": {
+        "clientId": {
+          "type": "string",
+          "description": "The target client ID"
+        },
+        "message": {
+          "type": "any",
+          "description": "The message to send"
         }
-      ]
+      },
+      "required": [
+        "clientId",
+        "message"
+      ],
+      "returns": "boolean"
     },
     "send": {
-      "description": "Sends a message to the server (client mode only). This method sends a JSON-encoded message with a unique ID to the connected server. The message is automatically wrapped with metadata for tracking purposes. **Message Format:** Messages are automatically wrapped in the format: ```json { \"data\": <your_message>, \"id\": \"<uuid>\" } ```",
+      "description": "Fire-and-forget: sends a message to the server (client mode only). For server→client, use sendTo() or broadcast().",
       "parameters": {
         "message": {
           "type": "any",
-          "description": "The message object to send to the server"
+          "description": "The message to send"
         }
       },
       "required": [
         "message"
       ],
-      "returns": "void",
-      "examples": [
-        {
-          "language": "ts",
-          "code": "// Send a simple message\nawait ipc.send({ type: 'ping' });\n\n// Send complex data\nawait ipc.send({\n type: 'data_update',\n payload: { users: [...], timestamp: Date.now() }\n});"
+      "returns": "void"
+    },
+    "ask": {
+      "description": "Sends a message and waits for a correlated reply. Works in both client and server mode. The recipient should call `reply(requestId, response)` to respond.",
+      "parameters": {
+        "message": {
+          "type": "any",
+          "description": "The message to send"
+        },
+        "options": {
+          "type": "{ clientId?: string; timeoutMs?: number }",
+          "description": "Optional: clientId (server mode target), timeoutMs"
         }
-      ]
+      },
+      "required": [
+        "message"
+      ],
+      "returns": "Promise<any>"
+    },
+    "reply": {
+      "description": "Sends a reply to a previous ask() call, correlated by requestId.",
+      "parameters": {
+        "requestId": {
+          "type": "string",
+          "description": "The requestId from the incoming message"
+        },
+        "data": {
+          "type": "any",
+          "description": "The reply payload"
+        },
+        "clientId": {
+          "type": "string",
+          "description": "Target client (server mode; for client mode, omit)"
+        }
+      },
+      "required": [
+        "requestId",
+        "data"
+      ],
+      "returns": "void"
     },
     "connect": {
-      "description": "Connects to an IPC server at the specified socket path (client mode). This method establishes a client connection to an existing IPC server. Once connected, the client can send messages to the server and receive responses. The connection is maintained until explicitly closed or the server terminates. **Connection Behavior:** - Sets the socket mode to 'client' - Returns existing connection if already connected - Automatically handles connection events and cleanup - JSON-parses incoming messages and emits 'message' events - Cleans up connection reference when socket closes **Error Handling:** - Throws error if already in server mode - Rejects promise on connection failures - Automatically cleans up on connection close",
+      "description": "Connects to an IPC server at the specified socket path (client mode).",
       "parameters": {
         "socketPath": {
           "type": "string",
-          "description": "The file system path to the server's Unix domain socket"
+          "description": "Path to the server's Unix domain socket"
+        },
+        "options": {
+          "type": "{ reconnect?: boolean; name?: string }",
+          "description": "Optional: reconnect (enable auto-reconnect), name (identify this client)"
         }
       },
       "required": [
         "socketPath"
       ],
-      "returns": "Promise<Socket>",
-      "examples": [
-        {
-          "language": "ts",
-          "code": "// Connect to server\nconst socket = await ipc.connect('/tmp/myapp.sock');\nconsole.log('Connected to IPC server');\n\n// Handle incoming messages\nipc.on('message', (data) => {\n console.log('Server message:', data);\n});\n\n// Send messages\nawait ipc.send({ type: 'hello', client_id: 'client_001' });"
+      "returns": "Promise<Socket>"
+    },
+    "disconnect": {
+      "description": "Disconnects the client and stops any reconnection attempts.",
+      "parameters": {},
+      "required": [],
+      "returns": "void"
+    },
+    "probeSocket": {
+      "description": "Probe an existing socket to see if a live listener is behind it. Attempts a quick connect — if it succeeds, someone is listening.",
+      "parameters": {
+        "socketPath": {
+          "type": "string",
+          "description": "Parameter socketPath"
         }
-      ]
+      },
+      "required": [
+        "socketPath"
+      ],
+      "returns": "Promise<boolean>"
     }
   },
   "getters": {
@@ -6329,12 +6419,25 @@ setBuildTimeData('features.ipcSocket', {
       "description": "Checks if the IPC socket is operating in server mode.",
       "returns": "any"
     },
+    "clientCount": {
+      "description": "Returns the number of currently connected clients (server mode).",
+      "returns": "any"
+    },
+    "connectedClients": {
+      "description": "Returns info about all connected clients (server mode).",
+      "returns": "Array<{ id: string; name?: string; connectedAt: number }>"
+    },
     "connection": {
       "description": "Gets the current client connection socket.",
       "returns": "any"
     }
   },
   "events": {
+    "disconnection": {
+      "name": "disconnection",
+      "description": "Event emitted by IpcSocket",
+      "arguments": {}
+    },
     "connection": {
       "name": "connection",
       "description": "Event emitted by IpcSocket",
@@ -7255,10 +7358,68 @@ setBuildTimeData('features.packageFinder', {
 
 setBuildTimeData('features.processManager', {
   "id": "features.processManager",
-  "description": "Manages long-running child processes with tracking, events, and automatic cleanup. Unlike the `proc` feature whose spawn methods block until the child exits, ProcessManager returns a SpawnHandler immediately — a handle object with its own state, events, and lifecycle methods. The feature tracks all spawned processes, maintains observable state, and can automatically kill them on parent exit.",
+  "description": "Manages long-running child processes with tracking, events, and automatic cleanup. Unlike the `proc` feature whose spawn methods block until the child exits, ProcessManager returns a SpawnHandler immediately — a handle object with its own state, events, and lifecycle methods. The feature tracks all spawned processes, maintains observable state, and can automatically kill them on parent exit. Each handler maintains a memory-efficient output buffer: the first 20 lines (head) and last 50 lines (tail) of stdout/stderr are kept, everything in between is discarded.",
   "shortcut": "features.processManager",
   "className": "ProcessManager",
   "methods": {
+    "spawnProcess": {
+      "description": "Tool handler: spawn a long-running background process.",
+      "parameters": {
+        "args": {
+          "type": "{ command: string; args?: string; tag?: string; cwd?: string }",
+          "description": "Parameter args"
+        }
+      },
+      "required": [
+        "args"
+      ],
+      "returns": "void"
+    },
+    "runCommand": {
+      "description": "Tool handler: run a command to completion and return its output.",
+      "parameters": {
+        "args": {
+          "type": "{ command: string; cwd?: string }",
+          "description": "Parameter args"
+        }
+      },
+      "required": [
+        "args"
+      ],
+      "returns": "void"
+    },
+    "listProcesses": {
+      "description": "Tool handler: list all tracked processes.",
+      "parameters": {},
+      "required": [],
+      "returns": "void"
+    },
+    "getProcessOutput": {
+      "description": "Tool handler: peek at a process's buffered output.",
+      "parameters": {
+        "args": {
+          "type": "{ id?: string; tag?: string; stream?: string }",
+          "description": "Parameter args"
+        }
+      },
+      "required": [
+        "args"
+      ],
+      "returns": "void"
+    },
+    "killProcess": {
+      "description": "Tool handler: kill a process by ID or tag.",
+      "parameters": {
+        "args": {
+          "type": "{ id?: string; tag?: string; signal?: string }",
+          "description": "Parameter args"
+        }
+      },
+      "required": [
+        "args"
+      ],
+      "returns": "void"
+    },
     "spawn": {
       "description": "Spawn a long-running process and return a handle immediately. The returned SpawnHandler provides events for stdout/stderr streaming, exit/crash notifications, and methods to kill or await the process.",
       "parameters": {
@@ -7436,7 +7597,7 @@ setBuildTimeData('features.processManager', {
   "examples": [
     {
       "language": "ts",
-      "code": "const pm = container.feature('processManager', { enable: true })\n\nconst server = pm.spawn('node', ['server.js'], { tag: 'api', cwd: '/app' })\nserver.on('stdout', (data) => console.log('[api]', data))\nserver.on('crash', (code) => console.error('API crashed:', code))\n\n// Kill one\nserver.kill()\n\n// Kill all tracked processes\npm.killAll()\n\n// List and lookup\npm.list()              // SpawnHandler[]\npm.getByTag('api')     // SpawnHandler | undefined"
+      "code": "const pm = container.feature('processManager', { enable: true })\n\nconst server = pm.spawn('node', ['server.js'], { tag: 'api', cwd: '/app' })\nserver.on('stdout', (data) => console.log('[api]', data))\nserver.on('crash', (code) => console.error('API crashed:', code))\n\n// Peek at buffered output\nconst { head, tail } = server.peek()\n\n// Kill one\nserver.kill()\n\n// Kill all tracked processes\npm.killAll()\n\n// List and lookup\npm.list()              // SpawnHandler[]\npm.getByTag('api')     // SpawnHandler | undefined"
     }
   ]
 });
@@ -9805,7 +9966,7 @@ setBuildTimeData('clients.rest', {
 
 setBuildTimeData('clients.websocket', {
   "id": "clients.websocket",
-  "description": "WebSocket client that bridges raw WebSocket events to Luca's Helper event bus, providing a clean interface for sending/receiving messages, tracking connection state, and optional auto-reconnection with exponential backoff. Events emitted: - `open` — connection established - `message` — message received (JSON-parsed when possible) - `close` — connection closed (with code and reason) - `error` — connection error - `reconnecting` — attempting reconnection (with attempt number)",
+  "description": "WebSocketClient helper",
   "shortcut": "clients.websocket",
   "className": "WebSocketClient",
   "methods": {
@@ -9828,6 +9989,59 @@ setBuildTimeData('clients.websocket', {
       ],
       "returns": "Promise<void>"
     },
+    "ask": {
+      "description": "Send a request and wait for a correlated response. The message is sent with a unique `requestId`; the remote side is expected to reply with a message containing `replyTo` set to that same ID.",
+      "parameters": {
+        "type": {
+          "type": "string",
+          "description": "A string identifying the request type"
+        },
+        "data": {
+          "type": "any",
+          "description": "Optional payload to include with the request"
+        },
+        "timeout": {
+          "type": "any",
+          "description": "How long to wait for a response (default 10 000 ms)"
+        }
+      },
+      "required": [
+        "type"
+      ],
+      "returns": "Promise<R>",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "const result = await ws.ask('getUser', { id: 42 })"
+        }
+      ]
+    },
+    "_handleReply": {
+      "description": "",
+      "parameters": {
+        "message": {
+          "type": "any",
+          "description": "Parameter message"
+        }
+      },
+      "required": [
+        "message"
+      ],
+      "returns": "boolean"
+    },
+    "_rejectAllPending": {
+      "description": "",
+      "parameters": {
+        "reason": {
+          "type": "string",
+          "description": "Parameter reason"
+        }
+      },
+      "required": [
+        "reason"
+      ],
+      "returns": "void"
+    },
     "disconnect": {
       "description": "Gracefully close the WebSocket connection. Suppresses auto-reconnect and updates connection state to disconnected.",
       "parameters": {},
@@ -9870,13 +10084,7 @@ setBuildTimeData('clients.websocket', {
   },
   "state": {},
   "options": {},
-  "envVars": [],
-  "examples": [
-    {
-      "language": "ts",
-      "code": "const ws = container.client('websocket', {\n baseURL: 'ws://localhost:8080',\n reconnect: true,\n maxReconnectAttempts: 5\n})\nws.on('message', (data) => console.log('Received:', data))\nawait ws.connect()\nawait ws.send({ type: 'hello' })"
-    }
-  ]
+  "envVars": []
 });
 
 setBuildTimeData('clients.openai', {
@@ -11081,7 +11289,7 @@ setBuildTimeData('servers.express', {
 
 setBuildTimeData('servers.websocket', {
   "id": "servers.websocket",
-  "description": "WebSocket server built on the `ws` library with optional JSON message framing. Manages WebSocket connections, tracks connected clients, and bridges messages to Luca's event bus. When `json` mode is enabled, incoming messages are automatically JSON-parsed (with `.toString()` for Buffer data) and outgoing messages via `send()` / `broadcast()` are JSON-stringified. When `json` mode is disabled, raw message data is emitted as-is and `send()` / `broadcast()` still JSON-stringify for safety.",
+  "description": "WebSocket server built on the `ws` library with optional JSON message framing. Manages WebSocket connections, tracks connected clients, and bridges messages to Luca's event bus. When `json` mode is enabled, incoming messages are automatically JSON-parsed (with `.toString()` for Buffer data) and outgoing messages via `send()` / `broadcast()` are JSON-stringified. When `json` mode is disabled, raw message data is emitted as-is and `send()` / `broadcast()` still JSON-stringify for safety. Supports ask/reply semantics when paired with the Luca WebSocket client. The server can `ask(ws, type, data)` a connected client and await a typed response, or handle incoming asks from clients by listening for messages with a `requestId` and replying via `send(ws, { replyTo, data })`. Requests time out if no reply arrives within the configurable window.",
   "shortcut": "servers.websocket",
   "className": "WebsocketServer",
   "methods": {
@@ -11116,6 +11324,64 @@ setBuildTimeData('servers.websocket', {
       ],
       "returns": "void"
     },
+    "ask": {
+      "description": "Send a request to a specific client and wait for a correlated response. The client is expected to reply with a message whose `replyTo` matches the `requestId` of this message.",
+      "parameters": {
+        "ws": {
+          "type": "any",
+          "description": "The WebSocket client to ask"
+        },
+        "type": {
+          "type": "string",
+          "description": "A string identifying the request type"
+        },
+        "data": {
+          "type": "any",
+          "description": "Optional payload"
+        },
+        "timeout": {
+          "type": "any",
+          "description": "How long to wait (default 10 000 ms)"
+        }
+      },
+      "required": [
+        "ws",
+        "type"
+      ],
+      "returns": "Promise<R>",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "ws.on('connection', async (client) => {\n const info = await ws.ask(client, 'identify')\n console.log('Client says:', info)\n})"
+        }
+      ]
+    },
+    "_handleReply": {
+      "description": "",
+      "parameters": {
+        "message": {
+          "type": "any",
+          "description": "Parameter message"
+        }
+      },
+      "required": [
+        "message"
+      ],
+      "returns": "boolean"
+    },
+    "_rejectAllPending": {
+      "description": "",
+      "parameters": {
+        "reason": {
+          "type": "string",
+          "description": "Parameter reason"
+        }
+      },
+      "required": [
+        "reason"
+      ],
+      "returns": "void"
+    },
     "start": {
       "description": "Start the WebSocket server. A runtime `port` overrides the constructor option and is written to state before the underlying `ws.Server` is created, so the server binds to the correct port.",
       "parameters": {
@@ -11162,7 +11428,7 @@ setBuildTimeData('servers.websocket', {
   "examples": [
     {
       "language": "ts",
-      "code": "const ws = container.server('websocket', { json: true })\nawait ws.start({ port: 8080 })\n\nws.on('message', (data, client) => {\n console.log('Received:', data)\n ws.broadcast({ echo: data })\n})"
+      "code": "const ws = container.server('websocket', { json: true })\nawait ws.start({ port: 8080 })\n\nws.on('message', (data, client) => {\n console.log('Received:', data)\n ws.broadcast({ echo: data })\n})\n\n// ask/reply: request info from a connected client\nws.on('connection', async (client) => {\n const info = await ws.ask(client, 'identify')\n console.log('Client says:', info)\n})"
     }
   ]
 });
@@ -13118,7 +13384,7 @@ export const introspectionData = [
   },
   {
     "id": "features.windowManager",
-    "description": "WindowManager Feature — Native window control via LucaVoiceLauncher Acts as an IPC server that the native macOS launcher app connects to. Communicates over a Unix domain socket using NDJSON (newline-delimited JSON). **Protocol:** - Bun listens on a Unix domain socket; the native app connects as a client - Window dispatch commands are sent as NDJSON with a `window` field - The app executes window commands and sends back `windowAck` messages - Any non-windowAck message from the app is emitted as a `message` event - Other features can use `send()` to write arbitrary NDJSON to the app **Capabilities:** - Spawn native browser windows with configurable chrome - Navigate, focus, close, and eval JavaScript in windows - Automatic socket file cleanup and fallback paths",
+    "description": "WindowManager Feature — Native window control via LucaVoiceLauncher Uses a broker/producer architecture so multiple luca processes can trigger window operations without competing for the same Unix socket. **Architecture:** - The first process to call `listen()` becomes the **broker**. It owns the app-facing socket (`ipc-window.sock`) and a control socket (`ipc-window-control.sock`). - Subsequent processes detect the broker and become **producers**. They connect to the control socket and route commands through the broker. - The broker forwards producer commands to the native app and routes acks and lifecycle events back to the originating producer. **Protocol:** - Bun listens on a Unix domain socket; the native app connects as a client - Window dispatch commands are sent as NDJSON with a `window` field - The app executes window commands and sends back `windowAck` messages - Any non-windowAck message from the app is emitted as a `message` event - Other features can use `send()` to write arbitrary NDJSON to the app **Capabilities:** - Spawn native browser windows with configurable chrome - Navigate, focus, close, and eval JavaScript in windows - Multiple luca processes can trigger window operations simultaneously - Automatic broker detection and producer fallback Observable state includes `windows` (open window metadata), `pendingOperations` (in-flight command ids), and `producerCount` (broker). Sockets, promises, and `WindowHandle` instances stay internal. **Producer state:** The broker pushes `windowStateSync` on the control socket when a producer connects and whenever the window roster changes, so every process sees the same `windows` / `windowCount` / `clientConnected` as the broker (not only its own acks).",
     "shortcut": "features.windowManager",
     "className": "WindowManager",
     "methods": {
@@ -13134,7 +13400,18 @@ export const introspectionData = [
         "returns": "Promise<this>"
       },
       "listen": {
-        "description": "Start listening on the Unix domain socket for the native app to connect. Fire-and-forget — binds the socket and returns immediately. Sits quietly until the native app connects; does nothing visible if it never does.",
+        "description": "Start the window manager. Automatically detects whether a broker already exists and either becomes the broker or connects as a producer. - If no broker is running: becomes the broker, binds the app socket and a control socket for producers. - If a broker is already running: connects as a producer through the control socket.",
+        "parameters": {
+          "socketPath": {
+            "type": "string",
+            "description": "Override the configured app socket path"
+          }
+        },
+        "required": [],
+        "returns": "Promise<this>"
+      },
+      "cleanupSocket": {
+        "description": "Remove stale socket files without starting or stopping the server. Useful when a previous process crashed and left dead sockets behind. Will not remove sockets that have live listeners.",
         "parameters": {
           "socketPath": {
             "type": "string",
@@ -13142,10 +13419,10 @@ export const introspectionData = [
           }
         },
         "required": [],
-        "returns": "this"
+        "returns": "Promise<boolean>"
       },
       "stop": {
-        "description": "Stop the IPC server and clean up all connections. Rejects any pending window operation requests.",
+        "description": "Stop the window manager and clean up all connections. Rejects any pending window operation requests.",
         "parameters": {},
         "required": [],
         "returns": "Promise<this>"
@@ -13418,7 +13695,7 @@ export const introspectionData = [
         ]
       },
       "send": {
-        "description": "Write an NDJSON message to the connected app client. Public so other features can send arbitrary protocol messages over the same socket.",
+        "description": "Write an NDJSON message to the connected app client. In producer mode, routes through the broker. Public so other features can send arbitrary protocol messages over the same socket.",
         "parameters": {
           "msg": {
             "type": "Record<string, any>",
@@ -13432,12 +13709,20 @@ export const introspectionData = [
       }
     },
     "getters": {
+      "isBroker": {
+        "description": "Whether this instance is acting as the broker.",
+        "returns": "boolean"
+      },
+      "isProducer": {
+        "description": "Whether this instance is acting as a producer.",
+        "returns": "boolean"
+      },
       "isListening": {
-        "description": "Whether the IPC server is currently listening.",
+        "description": "Whether the IPC server is currently listening (broker) or connected to broker (producer).",
         "returns": "boolean"
       },
       "isClientConnected": {
-        "description": "Whether the native app client is currently connected.",
+        "description": "Whether the native app client is currently connected (only meaningful for broker).",
         "returns": "boolean"
       }
     },
@@ -13472,6 +13757,11 @@ export const introspectionData = [
         "description": "Event emitted by WindowManager",
         "arguments": {}
       },
+      "windowFocus": {
+        "name": "windowFocus",
+        "description": "Event emitted by WindowManager",
+        "arguments": {}
+      },
       "message": {
         "name": "message",
         "description": "Event emitted by WindowManager",
@@ -17795,7 +18085,7 @@ export const introspectionData = [
   },
   {
     "id": "features.ipcSocket",
-    "description": "IpcSocket Feature - Inter-Process Communication via Unix Domain Sockets This feature provides robust IPC (Inter-Process Communication) capabilities using Unix domain sockets. It supports both server and client modes, allowing processes to communicate efficiently through file system-based socket connections. **Key Features:** - Dual-mode operation: server and client functionality - JSON message serialization/deserialization - Multiple client connection support (server mode) - Event-driven message handling - Automatic socket cleanup and management - Broadcast messaging to all connected clients - Lock file management for socket paths **Communication Pattern:** - Messages are automatically JSON-encoded with unique IDs - Both server and client emit 'message' events for incoming data - Server can broadcast to all connected clients - Client maintains single connection to server **Socket Management:** - Automatic cleanup of stale socket files - Connection tracking and management - Graceful shutdown procedures - Lock file protection against conflicts **Usage Examples:** **Server Mode:** ```typescript const ipc = container.feature('ipcSocket'); await ipc.listen('/tmp/myapp.sock', true); // removeLock=true ipc.on('connection', (socket) => { console.log('Client connected'); }); ipc.on('message', (data) => { console.log('Received:', data); ipc.broadcast({ reply: 'ACK', original: data }); }); ``` **Client Mode:** ```typescript const ipc = container.feature('ipcSocket'); await ipc.connect('/tmp/myapp.sock'); ipc.on('message', (data) => { console.log('Server says:', data); }); await ipc.send({ type: 'request', payload: 'hello' }); ```",
+    "description": "IpcSocket Feature - Inter-Process Communication via Unix Domain Sockets This feature provides robust IPC (Inter-Process Communication) capabilities using Unix domain sockets. It supports both server and client modes, allowing processes to communicate efficiently through file system-based socket connections. **Key Features:** - Hub-and-spoke: one server, many named clients with identity tracking - Targeted messaging: sendTo(clientId), broadcast(msg, excludeId) - Request/reply: ask() + reply() with timeout-based correlation - Auto-reconnect: clients reconnect with exponential backoff - Stale socket detection: probeSocket() before listen() - Clean shutdown: stopServer() removes socket file **Server (Hub):** ```typescript const ipc = container.feature('ipcSocket'); await ipc.listen('/tmp/hub.sock', true); ipc.on('connection', (clientId, socket) => { console.log('Client joined:', clientId); }); ipc.on('message', (data, clientId) => { console.log(`From ${clientId}:`, data); // Reply to sender, or ask and wait ipc.sendTo(clientId, { ack: true }); }); ``` **Client (Spoke):** ```typescript const ipc = container.feature('ipcSocket'); await ipc.connect('/tmp/hub.sock', { reconnect: true, name: 'worker-1' }); // Fire and forget await ipc.send({ type: 'status', ready: true }); // Request/reply ipc.on('message', (data) => { if (data.requestId) ipc.reply(data.requestId, { result: 42 }); }); ```",
     "shortcut": "features.ipcSocket",
     "className": "IpcSocket",
     "methods": {
@@ -17835,61 +18125,127 @@ export const introspectionData = [
         ]
       },
       "broadcast": {
-        "description": "Broadcasts a message to all connected clients (server mode only). This method sends a JSON-encoded message with a unique ID to every client currently connected to the server. Each message is automatically wrapped with metadata including a UUID for tracking. **Message Format:** Messages are automatically wrapped in the format: ```json { \"data\": <your_message>, \"id\": \"<uuid>\" } ```",
+        "description": "Broadcasts a message to all connected clients (server mode only).",
         "parameters": {
           "message": {
             "type": "any",
-            "description": "The message object to broadcast to all clients"
+            "description": "The message object to broadcast"
+          },
+          "exclude": {
+            "type": "string",
+            "description": "Optional client ID to exclude from broadcast"
           }
         },
         "required": [
           "message"
         ],
-        "returns": "void",
-        "examples": [
-          {
-            "language": "ts",
-            "code": "// Broadcast to all connected clients\nipc.broadcast({ \n type: 'notification',\n message: 'Server is shutting down in 30 seconds',\n timestamp: Date.now()\n});\n\n// Chain multiple operations\nipc.broadcast({ status: 'ready' })\n  .broadcast({ time: new Date().toISOString() });"
+        "returns": "void"
+      },
+      "sendTo": {
+        "description": "Sends a message to a specific client by ID (server mode only).",
+        "parameters": {
+          "clientId": {
+            "type": "string",
+            "description": "The target client ID"
+          },
+          "message": {
+            "type": "any",
+            "description": "The message to send"
           }
-        ]
+        },
+        "required": [
+          "clientId",
+          "message"
+        ],
+        "returns": "boolean"
       },
       "send": {
-        "description": "Sends a message to the server (client mode only). This method sends a JSON-encoded message with a unique ID to the connected server. The message is automatically wrapped with metadata for tracking purposes. **Message Format:** Messages are automatically wrapped in the format: ```json { \"data\": <your_message>, \"id\": \"<uuid>\" } ```",
+        "description": "Fire-and-forget: sends a message to the server (client mode only). For server→client, use sendTo() or broadcast().",
         "parameters": {
           "message": {
             "type": "any",
-            "description": "The message object to send to the server"
+            "description": "The message to send"
           }
         },
         "required": [
           "message"
         ],
-        "returns": "void",
-        "examples": [
-          {
-            "language": "ts",
-            "code": "// Send a simple message\nawait ipc.send({ type: 'ping' });\n\n// Send complex data\nawait ipc.send({\n type: 'data_update',\n payload: { users: [...], timestamp: Date.now() }\n});"
+        "returns": "void"
+      },
+      "ask": {
+        "description": "Sends a message and waits for a correlated reply. Works in both client and server mode. The recipient should call `reply(requestId, response)` to respond.",
+        "parameters": {
+          "message": {
+            "type": "any",
+            "description": "The message to send"
+          },
+          "options": {
+            "type": "{ clientId?: string; timeoutMs?: number }",
+            "description": "Optional: clientId (server mode target), timeoutMs"
           }
-        ]
+        },
+        "required": [
+          "message"
+        ],
+        "returns": "Promise<any>"
+      },
+      "reply": {
+        "description": "Sends a reply to a previous ask() call, correlated by requestId.",
+        "parameters": {
+          "requestId": {
+            "type": "string",
+            "description": "The requestId from the incoming message"
+          },
+          "data": {
+            "type": "any",
+            "description": "The reply payload"
+          },
+          "clientId": {
+            "type": "string",
+            "description": "Target client (server mode; for client mode, omit)"
+          }
+        },
+        "required": [
+          "requestId",
+          "data"
+        ],
+        "returns": "void"
       },
       "connect": {
-        "description": "Connects to an IPC server at the specified socket path (client mode). This method establishes a client connection to an existing IPC server. Once connected, the client can send messages to the server and receive responses. The connection is maintained until explicitly closed or the server terminates. **Connection Behavior:** - Sets the socket mode to 'client' - Returns existing connection if already connected - Automatically handles connection events and cleanup - JSON-parses incoming messages and emits 'message' events - Cleans up connection reference when socket closes **Error Handling:** - Throws error if already in server mode - Rejects promise on connection failures - Automatically cleans up on connection close",
+        "description": "Connects to an IPC server at the specified socket path (client mode).",
         "parameters": {
           "socketPath": {
             "type": "string",
-            "description": "The file system path to the server's Unix domain socket"
+            "description": "Path to the server's Unix domain socket"
+          },
+          "options": {
+            "type": "{ reconnect?: boolean; name?: string }",
+            "description": "Optional: reconnect (enable auto-reconnect), name (identify this client)"
           }
         },
         "required": [
           "socketPath"
         ],
-        "returns": "Promise<Socket>",
-        "examples": [
-          {
-            "language": "ts",
-            "code": "// Connect to server\nconst socket = await ipc.connect('/tmp/myapp.sock');\nconsole.log('Connected to IPC server');\n\n// Handle incoming messages\nipc.on('message', (data) => {\n console.log('Server message:', data);\n});\n\n// Send messages\nawait ipc.send({ type: 'hello', client_id: 'client_001' });"
+        "returns": "Promise<Socket>"
+      },
+      "disconnect": {
+        "description": "Disconnects the client and stops any reconnection attempts.",
+        "parameters": {},
+        "required": [],
+        "returns": "void"
+      },
+      "probeSocket": {
+        "description": "Probe an existing socket to see if a live listener is behind it. Attempts a quick connect — if it succeeds, someone is listening.",
+        "parameters": {
+          "socketPath": {
+            "type": "string",
+            "description": "Parameter socketPath"
           }
-        ]
+        },
+        "required": [
+          "socketPath"
+        ],
+        "returns": "Promise<boolean>"
       }
     },
     "getters": {
@@ -17901,12 +18257,25 @@ export const introspectionData = [
         "description": "Checks if the IPC socket is operating in server mode.",
         "returns": "any"
       },
+      "clientCount": {
+        "description": "Returns the number of currently connected clients (server mode).",
+        "returns": "any"
+      },
+      "connectedClients": {
+        "description": "Returns info about all connected clients (server mode).",
+        "returns": "Array<{ id: string; name?: string; connectedAt: number }>"
+      },
       "connection": {
         "description": "Gets the current client connection socket.",
         "returns": "any"
       }
     },
     "events": {
+      "disconnection": {
+        "name": "disconnection",
+        "description": "Event emitted by IpcSocket",
+        "arguments": {}
+      },
       "connection": {
         "name": "connection",
         "description": "Event emitted by IpcSocket",
@@ -18821,10 +19190,68 @@ export const introspectionData = [
   },
   {
     "id": "features.processManager",
-    "description": "Manages long-running child processes with tracking, events, and automatic cleanup. Unlike the `proc` feature whose spawn methods block until the child exits, ProcessManager returns a SpawnHandler immediately — a handle object with its own state, events, and lifecycle methods. The feature tracks all spawned processes, maintains observable state, and can automatically kill them on parent exit.",
+    "description": "Manages long-running child processes with tracking, events, and automatic cleanup. Unlike the `proc` feature whose spawn methods block until the child exits, ProcessManager returns a SpawnHandler immediately — a handle object with its own state, events, and lifecycle methods. The feature tracks all spawned processes, maintains observable state, and can automatically kill them on parent exit. Each handler maintains a memory-efficient output buffer: the first 20 lines (head) and last 50 lines (tail) of stdout/stderr are kept, everything in between is discarded.",
     "shortcut": "features.processManager",
     "className": "ProcessManager",
     "methods": {
+      "spawnProcess": {
+        "description": "Tool handler: spawn a long-running background process.",
+        "parameters": {
+          "args": {
+            "type": "{ command: string; args?: string; tag?: string; cwd?: string }",
+            "description": "Parameter args"
+          }
+        },
+        "required": [
+          "args"
+        ],
+        "returns": "void"
+      },
+      "runCommand": {
+        "description": "Tool handler: run a command to completion and return its output.",
+        "parameters": {
+          "args": {
+            "type": "{ command: string; cwd?: string }",
+            "description": "Parameter args"
+          }
+        },
+        "required": [
+          "args"
+        ],
+        "returns": "void"
+      },
+      "listProcesses": {
+        "description": "Tool handler: list all tracked processes.",
+        "parameters": {},
+        "required": [],
+        "returns": "void"
+      },
+      "getProcessOutput": {
+        "description": "Tool handler: peek at a process's buffered output.",
+        "parameters": {
+          "args": {
+            "type": "{ id?: string; tag?: string; stream?: string }",
+            "description": "Parameter args"
+          }
+        },
+        "required": [
+          "args"
+        ],
+        "returns": "void"
+      },
+      "killProcess": {
+        "description": "Tool handler: kill a process by ID or tag.",
+        "parameters": {
+          "args": {
+            "type": "{ id?: string; tag?: string; signal?: string }",
+            "description": "Parameter args"
+          }
+        },
+        "required": [
+          "args"
+        ],
+        "returns": "void"
+      },
       "spawn": {
         "description": "Spawn a long-running process and return a handle immediately. The returned SpawnHandler provides events for stdout/stderr streaming, exit/crash notifications, and methods to kill or await the process.",
         "parameters": {
@@ -19002,7 +19429,7 @@ export const introspectionData = [
     "examples": [
       {
         "language": "ts",
-        "code": "const pm = container.feature('processManager', { enable: true })\n\nconst server = pm.spawn('node', ['server.js'], { tag: 'api', cwd: '/app' })\nserver.on('stdout', (data) => console.log('[api]', data))\nserver.on('crash', (code) => console.error('API crashed:', code))\n\n// Kill one\nserver.kill()\n\n// Kill all tracked processes\npm.killAll()\n\n// List and lookup\npm.list()              // SpawnHandler[]\npm.getByTag('api')     // SpawnHandler | undefined"
+        "code": "const pm = container.feature('processManager', { enable: true })\n\nconst server = pm.spawn('node', ['server.js'], { tag: 'api', cwd: '/app' })\nserver.on('stdout', (data) => console.log('[api]', data))\nserver.on('crash', (code) => console.error('API crashed:', code))\n\n// Peek at buffered output\nconst { head, tail } = server.peek()\n\n// Kill one\nserver.kill()\n\n// Kill all tracked processes\npm.killAll()\n\n// List and lookup\npm.list()              // SpawnHandler[]\npm.getByTag('api')     // SpawnHandler | undefined"
       }
     ]
   },
@@ -21360,7 +21787,7 @@ export const introspectionData = [
   },
   {
     "id": "clients.websocket",
-    "description": "WebSocket client that bridges raw WebSocket events to Luca's Helper event bus, providing a clean interface for sending/receiving messages, tracking connection state, and optional auto-reconnection with exponential backoff. Events emitted: - `open` — connection established - `message` — message received (JSON-parsed when possible) - `close` — connection closed (with code and reason) - `error` — connection error - `reconnecting` — attempting reconnection (with attempt number)",
+    "description": "WebSocketClient helper",
     "shortcut": "clients.websocket",
     "className": "WebSocketClient",
     "methods": {
@@ -21383,6 +21810,59 @@ export const introspectionData = [
         ],
         "returns": "Promise<void>"
       },
+      "ask": {
+        "description": "Send a request and wait for a correlated response. The message is sent with a unique `requestId`; the remote side is expected to reply with a message containing `replyTo` set to that same ID.",
+        "parameters": {
+          "type": {
+            "type": "string",
+            "description": "A string identifying the request type"
+          },
+          "data": {
+            "type": "any",
+            "description": "Optional payload to include with the request"
+          },
+          "timeout": {
+            "type": "any",
+            "description": "How long to wait for a response (default 10 000 ms)"
+          }
+        },
+        "required": [
+          "type"
+        ],
+        "returns": "Promise<R>",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "const result = await ws.ask('getUser', { id: 42 })"
+          }
+        ]
+      },
+      "_handleReply": {
+        "description": "",
+        "parameters": {
+          "message": {
+            "type": "any",
+            "description": "Parameter message"
+          }
+        },
+        "required": [
+          "message"
+        ],
+        "returns": "boolean"
+      },
+      "_rejectAllPending": {
+        "description": "",
+        "parameters": {
+          "reason": {
+            "type": "string",
+            "description": "Parameter reason"
+          }
+        },
+        "required": [
+          "reason"
+        ],
+        "returns": "void"
+      },
       "disconnect": {
         "description": "Gracefully close the WebSocket connection. Suppresses auto-reconnect and updates connection state to disconnected.",
         "parameters": {},
@@ -21425,13 +21905,7 @@ export const introspectionData = [
     },
     "state": {},
     "options": {},
-    "envVars": [],
-    "examples": [
-      {
-        "language": "ts",
-        "code": "const ws = container.client('websocket', {\n baseURL: 'ws://localhost:8080',\n reconnect: true,\n maxReconnectAttempts: 5\n})\nws.on('message', (data) => console.log('Received:', data))\nawait ws.connect()\nawait ws.send({ type: 'hello' })"
-      }
-    ]
+    "envVars": []
   },
   {
     "id": "clients.openai",
@@ -22629,7 +23103,7 @@ export const introspectionData = [
   },
   {
     "id": "servers.websocket",
-    "description": "WebSocket server built on the `ws` library with optional JSON message framing. Manages WebSocket connections, tracks connected clients, and bridges messages to Luca's event bus. When `json` mode is enabled, incoming messages are automatically JSON-parsed (with `.toString()` for Buffer data) and outgoing messages via `send()` / `broadcast()` are JSON-stringified. When `json` mode is disabled, raw message data is emitted as-is and `send()` / `broadcast()` still JSON-stringify for safety.",
+    "description": "WebSocket server built on the `ws` library with optional JSON message framing. Manages WebSocket connections, tracks connected clients, and bridges messages to Luca's event bus. When `json` mode is enabled, incoming messages are automatically JSON-parsed (with `.toString()` for Buffer data) and outgoing messages via `send()` / `broadcast()` are JSON-stringified. When `json` mode is disabled, raw message data is emitted as-is and `send()` / `broadcast()` still JSON-stringify for safety. Supports ask/reply semantics when paired with the Luca WebSocket client. The server can `ask(ws, type, data)` a connected client and await a typed response, or handle incoming asks from clients by listening for messages with a `requestId` and replying via `send(ws, { replyTo, data })`. Requests time out if no reply arrives within the configurable window.",
     "shortcut": "servers.websocket",
     "className": "WebsocketServer",
     "methods": {
@@ -22664,6 +23138,64 @@ export const introspectionData = [
         ],
         "returns": "void"
       },
+      "ask": {
+        "description": "Send a request to a specific client and wait for a correlated response. The client is expected to reply with a message whose `replyTo` matches the `requestId` of this message.",
+        "parameters": {
+          "ws": {
+            "type": "any",
+            "description": "The WebSocket client to ask"
+          },
+          "type": {
+            "type": "string",
+            "description": "A string identifying the request type"
+          },
+          "data": {
+            "type": "any",
+            "description": "Optional payload"
+          },
+          "timeout": {
+            "type": "any",
+            "description": "How long to wait (default 10 000 ms)"
+          }
+        },
+        "required": [
+          "ws",
+          "type"
+        ],
+        "returns": "Promise<R>",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "ws.on('connection', async (client) => {\n const info = await ws.ask(client, 'identify')\n console.log('Client says:', info)\n})"
+          }
+        ]
+      },
+      "_handleReply": {
+        "description": "",
+        "parameters": {
+          "message": {
+            "type": "any",
+            "description": "Parameter message"
+          }
+        },
+        "required": [
+          "message"
+        ],
+        "returns": "boolean"
+      },
+      "_rejectAllPending": {
+        "description": "",
+        "parameters": {
+          "reason": {
+            "type": "string",
+            "description": "Parameter reason"
+          }
+        },
+        "required": [
+          "reason"
+        ],
+        "returns": "void"
+      },
       "start": {
         "description": "Start the WebSocket server. A runtime `port` overrides the constructor option and is written to state before the underlying `ws.Server` is created, so the server binds to the correct port.",
         "parameters": {
@@ -22710,7 +23242,7 @@ export const introspectionData = [
     "examples": [
       {
         "language": "ts",
-        "code": "const ws = container.server('websocket', { json: true })\nawait ws.start({ port: 8080 })\n\nws.on('message', (data, client) => {\n console.log('Received:', data)\n ws.broadcast({ echo: data })\n})"
+        "code": "const ws = container.server('websocket', { json: true })\nawait ws.start({ port: 8080 })\n\nws.on('message', (data, client) => {\n console.log('Received:', data)\n ws.broadcast({ echo: data })\n})\n\n// ask/reply: request info from a connected client\nws.on('connection', async (client) => {\n const info = await ws.ask(client, 'identify')\n console.log('Client says:', info)\n})"
       }
     ]
   }