@soederpop/luca 0.0.25 → 0.0.28

package/src/scaffolds/generated.ts

@@ -1,5 +1,5 @@
 // Auto-generated scaffold and MCP readme content
-// Generated at: 2026-03-22T06:53:18.105Z
+// Generated at: 2026-03-23T07:45:57.906Z
 // Source: docs/scaffolds/*.md, docs/examples/assistant/, and docs/mcp/readme.md
 //
 // Do not edit manually. Run: luca build-scaffolds

package/src/server.ts

@@ -79,6 +79,44 @@ export class Server<T extends ServerState = ServerState, K extends ServerOptions
         return super.container as NodeContainer
     }
 
+    /** Async functions passed to `.use()` before `start()` — drained in `start()`. */
+    _pendingPlugins: Promise<void>[] = []
+
+    /**
+     * Register a setup function against this server. The function receives the
+     * server instance and can configure it however it likes.
+     *
+     * - If the server hasn't started yet, async return values are queued and
+     *   awaited when `start()` is called.
+     * - If the server is already listening, the function is fire-and-forget.
+     * - Always returns `this` synchronously for chaining.
+     *
+     * @example
+     * ```typescript
+     * server
+     *   .use((s) => s.app.use(cors()))
+     *   .use(async (s) => { await loadRoutes(s) })
+     * await server.start()
+     * ```
+     */
+    use(fn: (server: this) => void | Promise<void>): this {
+      const result = fn(this)
+      if (result && typeof (result as any).then === 'function') {
+        if (!this.isListening) {
+          this._pendingPlugins.push(result as Promise<void>)
+        }
+      }
+      return this
+    }
+
+    /** Drain all pending `.use()` promises. Subclasses should call this at the top of `start()`. */
+    protected async _drainPendingPlugins() {
+      if (this._pendingPlugins.length) {
+        await Promise.all(this._pendingPlugins)
+        this._pendingPlugins = []
+      }
+    }
+
     get isListening() {
       return !!this.state.get('listening')
     }
@@ -117,6 +155,8 @@ export class Server<T extends ServerState = ServerState, K extends ServerOptions
         return this
       }
 
+      await this._drainPendingPlugins()
+
       if (options?.port) {
         this.state.set('port', options.port)
       }

package/src/servers/express.ts

@@ -104,6 +104,8 @@ export class ExpressServer<T extends ServerState = ServerState, K extends Expres
         return this
       }
 
+      await this._drainPendingPlugins()
+
       // Apply runtime port to state so this.port reflects the override
       if (options?.port) {
         this.state.set('port', options.port)

package/src/servers/mcp.ts

@@ -472,6 +472,7 @@ export class MCPServer extends Server<MCPServerState, MCPServerOptions> {
     stdioCompat?: StdioCompatMode
   }) {
     if (this.isListening) return this
+    await this._drainPendingPlugins()
     if (!this.isConfigured) await this.configure()
 
     const transport = options?.transport || this.options.transport || 'stdio'

package/src/servers/socket.ts

@@ -2,6 +2,7 @@ import { z } from 'zod'
 import { ServerStateSchema, ServerOptionsSchema, ServerEventsSchema } from '../schemas/base.js'
 import { type StartOptions, Server, type ServerState } from '../server.js';
 import { WebSocketServer as BaseServer } from 'ws'
+import type { PendingRequest } from '../clients/websocket.js'
 
 declare module '../server' {
   interface AvailableServers {
@@ -29,6 +30,12 @@ export const SocketServerEventsSchema = ServerEventsSchema.extend({
  * 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.
+ *
  * @extends Server
  *
  * @example
@@ -40,6 +47,12 @@ export const SocketServerEventsSchema = ServerEventsSchema.extend({
  *   console.log('Received:', data)
  *   ws.broadcast({ echo: data })
  * })
+ *
+ * // ask/reply: request info from a connected client
+ * ws.on('connection', async (client) => {
+ *   const info = await ws.ask(client, 'identify')
+ *   console.log('Client says:', info)
+ * })
  * ```
  */
 export class WebsocketServer<T extends ServerState = ServerState, K extends SocketServerOptions = SocketServerOptions> extends Server<T,K> {
@@ -63,6 +76,7 @@ export class WebsocketServer<T extends ServerState = ServerState, K extends Sock
     }
 
     connections : Set<any> = new Set()
+    _pending = new Map<string, PendingRequest>()
 
     async broadcast(message: any) {
       for(const ws of this.connections) {
@@ -77,6 +91,66 @@ export class WebsocketServer<T extends ServerState = ServerState, K extends Sock
       return this
     }
 
+    /**
+     * 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.
+     *
+     * @param ws - The WebSocket client to ask
+     * @param type - A string identifying the request type
+     * @param data - Optional payload
+     * @param timeout - How long to wait (default 10 000 ms)
+     * @returns The `data` field of the response
+     *
+     * @example
+     * ```typescript
+     * ws.on('connection', async (client) => {
+     *   const info = await ws.ask(client, 'identify')
+     *   console.log('Client says:', info)
+     * })
+     * ```
+     */
+    async ask<R = any>(ws: any, type: string, data?: any, timeout = 10000): Promise<R> {
+      const requestId = this.container.utils.uuid()
+
+      return new Promise<R>((resolve, reject) => {
+        const timer = setTimeout(() => {
+          this._pending.delete(requestId)
+          reject(new Error(`ask("${type}") timed out after ${timeout}ms`))
+        }, timeout)
+
+        this._pending.set(requestId, { resolve, reject, timer })
+        this.send(ws, { type, data, requestId })
+      })
+    }
+
+    /** @internal Resolve a pending ask() if the incoming message has a replyTo field. Returns true if handled. */
+    _handleReply(message: any): boolean {
+      if (!message || !message.replyTo) return false
+
+      const pending = this._pending.get(message.replyTo)
+      if (!pending) return false
+
+      this._pending.delete(message.replyTo)
+      clearTimeout(pending.timer)
+
+      if (message.error) {
+        pending.reject(new Error(message.error))
+      } else {
+        pending.resolve(message.data)
+      }
+      return true
+    }
+
+    /** @internal Reject all pending ask() calls — used on stop. */
+    _rejectAllPending(reason: string) {
+      for (const [id, pending] of this._pending) {
+        clearTimeout(pending.timer)
+        pending.reject(new Error(reason))
+      }
+      this._pending.clear()
+    }
+
     /**
      * Start the WebSocket server. A runtime `port` overrides the constructor
      * option and is written to state before the underlying `ws.Server` is created,
@@ -89,6 +163,8 @@ export class WebsocketServer<T extends ServerState = ServerState, K extends Sock
         return this
       }
 
+      await this._drainPendingPlugins()
+
       // Apply runtime port to state before configure/wss touches it
       if (options?.port) {
         this.state.set('port', options.port)
@@ -113,6 +189,17 @@ export class WebsocketServer<T extends ServerState = ServerState, K extends Sock
               data = JSON.parse(typeof raw === 'string' ? raw : raw.toString())
             } catch {}
           }
+
+          // Route reply messages to pending ask() calls
+          if (this._handleReply(data)) return
+
+          // If this message is a request (has requestId), provide a reply helper
+          if (data && data.requestId) {
+            const requestId = data.requestId
+            data.reply = (responseData: any) => this.send(ws, { replyTo: requestId, data: responseData })
+            data.replyError = (error: string) => this.send(ws, { replyTo: requestId, error })
+          }
+
           this.emit('message', data, ws)
         })
       })
@@ -127,6 +214,8 @@ export class WebsocketServer<T extends ServerState = ServerState, K extends Sock
         return this
       }
 
+      this._rejectAllPending('WebSocket server stopped')
+
       await Promise.race([
         new Promise<void>((resolve) => {
           if (!this._wss) {

package/src/web/clients/socket.ts

@@ -6,7 +6,10 @@ import { WebSocketClientEventsSchema } from '../../schemas/base.js'
 /**
  * Web-specific WebSocket client implementation using isomorphic-ws.
  * Extends the base WebSocketClient with platform-specific transport and
- * an envelope format that wraps sent data with a unique ID.
+ * an envelope format that wraps sent data with a unique ID. Inherits
+ * ask/reply semantics from the base WebSocketClient — protocol messages
+ * (those with `requestId` or `replyTo`) bypass the envelope wrapper to
+ * maintain compatibility with the Luca WebSocket server's ask/reply flow.
  */
 export class SocketClient<T extends WebSocketClientState = WebSocketClientState, K extends WebSocketClientOptions = WebSocketClientOptions> extends WebSocketClient<T,K> {
   // @ts-expect-error widening ws type for isomorphic-ws compatibility
@@ -20,6 +23,8 @@ export class SocketClient<T extends WebSocketClientState = WebSocketClientState,
   /**
    * Send data over the WebSocket with an ID envelope.
    * Wraps the payload in { id, data } before JSON serialization.
+   * Messages with a `requestId` or `replyTo` are sent as-is to
+   * preserve the ask/reply protocol.
    */
   override async send(data: any) {
     if(!this.isConnected && !this.hasError) {
@@ -30,10 +35,15 @@ export class SocketClient<T extends WebSocketClientState = WebSocketClientState,
       throw new Error(`Missing websocket instance`)
     }
 
-    this.ws.send(JSON.stringify({
-      id: this.container.utils.uuid(),
-      data
-    }))
+    // Protocol messages (ask/reply) bypass the envelope
+    if (data && (data.requestId || data.replyTo)) {
+      this.ws.send(JSON.stringify(data))
+    } else {
+      this.ws.send(JSON.stringify({
+        id: this.container.utils.uuid(),
+        data
+      }))
+    }
   }
 
   /**
@@ -64,7 +74,13 @@ export class SocketClient<T extends WebSocketClientState = WebSocketClientState,
       }
 
       ws.onmessage = (event: any) => {
-        this.emit('message', event)
+        let data = event?.data ?? event
+        try {
+          data = JSON.parse(typeof data === 'string' ? data : data.toString())
+        } catch {}
+        if (!this._handleReply(data)) {
+          this.emit('message', data)
+        }
       }
 
       ws.onclose = (event: any) => {

package/test/websocket-ask.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect, afterAll } from 'bun:test'
+import { NodeContainer } from '../src/node/container'
+
+describe('WebSocket ask/reply protocol', () => {
+  const container = new NodeContainer()
+  const server = container.server('websocket', { json: true })
+  let clientWsOnServer: any
+
+  afterAll(async () => {
+    try { server.connections.forEach((ws: any) => ws.close?.()) } catch {}
+    try { await server.stop() } catch {}
+  })
+
+  it('setup: start server and connect client', async () => {
+    const connPromise = new Promise<any>((resolve) => {
+      server.on('connection', resolve)
+    })
+
+    server.on('message', (data: any) => {
+      if (data.type === 'greet') {
+        data.reply({ greeting: `hello ${data.data.name}` })
+      }
+      if (data.type === 'fail') {
+        data.replyError('something went wrong')
+      }
+    })
+
+    await server.start({ port: 19880 })
+
+    // Use bun's native WebSocket as the client
+    const ws = new WebSocket('ws://localhost:19880')
+    await new Promise<void>((resolve, reject) => {
+      ws.onopen = () => resolve()
+      ws.onerror = (e) => reject(e)
+    })
+
+    clientWsOnServer = await connPromise
+    expect(clientWsOnServer).toBeDefined()
+
+    // Wire up the client to handle server-initiated asks
+    ws.onmessage = (event: any) => {
+      const msg = JSON.parse(event.data)
+      if (msg.requestId && msg.type === 'identify') {
+        ws.send(JSON.stringify({ replyTo: msg.requestId, data: { role: 'worker' } }))
+      }
+    }
+
+    // Stash ws for other tests
+    ;(globalThis as any).__testWs = ws
+  })
+
+  it('client.ask() sends a request and resolves with the server reply', async () => {
+    const ws = (globalThis as any).__testWs as WebSocket
+
+    // Manually implement the client-side ask protocol
+    const requestId = container.utils.uuid()
+    const result = await new Promise<any>((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error('timeout')), 5000)
+      const handler = (event: any) => {
+        const msg = JSON.parse(event.data)
+        if (msg.replyTo === requestId) {
+          clearTimeout(timer)
+          ws.removeEventListener('message', handler)
+          if (msg.error) reject(new Error(msg.error))
+          else resolve(msg.data)
+        }
+      }
+      ws.addEventListener('message', handler)
+      ws.send(JSON.stringify({ type: 'greet', data: { name: 'luca' }, requestId }))
+    })
+
+    expect(result).toEqual({ greeting: 'hello luca' })
+  })
+
+  it('server.ask() sends a request and resolves with the client reply', async () => {
+    const result = await server.ask(clientWsOnServer, 'identify')
+    expect(result).toEqual({ role: 'worker' })
+  })
+
+  it('ask() rejects with error when reply contains error', async () => {
+    const ws = (globalThis as any).__testWs as WebSocket
+
+    const requestId = container.utils.uuid()
+    const promise = new Promise<any>((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error('timeout')), 5000)
+      const handler = (event: any) => {
+        const msg = JSON.parse(event.data)
+        if (msg.replyTo === requestId) {
+          clearTimeout(timer)
+          ws.removeEventListener('message', handler)
+          if (msg.error) reject(new Error(msg.error))
+          else resolve(msg.data)
+        }
+      }
+      ws.addEventListener('message', handler)
+      ws.send(JSON.stringify({ type: 'fail', requestId }))
+    })
+
+    await expect(promise).rejects.toThrow('something went wrong')
+  })
+})