@soederpop/luca 0.0.26 → 0.0.28

package/src/bootstrap/generated.ts

@@ -1,5 +1,5 @@
 // Auto-generated bootstrap content
-// Generated at: 2026-03-22T20:57:24.866Z
+// Generated at: 2026-03-23T07:45:58.711Z
 // Source: docs/bootstrap/*.md, docs/bootstrap/templates/*, docs/examples/*.md, docs/tutorials/*.md
 //
 // Do not edit manually. Run: luca build-bootstrap
@@ -1167,6 +1167,91 @@ console.log('Running after killAll:', remaining.length)
 ## Summary
 
 This demo covered the \`processManager\` feature: spawning processes that return handles immediately, tracking them by ID or tag, listing all tracked processes, and killing them individually or all at once. It is the right tool for orchestrating background services, dev servers, and any scenario where you need non-blocking process management with lifecycle events.
+`,
+  "assistant-with-process-manager.md": `---
+title: "Assistant with ProcessManager Tools"
+tags: [assistant, processManager, tools, runtime, use]
+lastTested: null
+lastTestPassed: null
+---
+
+# Assistant with ProcessManager Tools
+
+Create an assistant at runtime, give it processManager tools, and watch it orchestrate long-running processes — spawning ping and top, checking their output over time, running a quick command in between, then coming back to report.
+
+## The Demo
+
+\`\`\`ts
+const pm = container.feature('processManager', { enable: true, autoCleanup: true })
+const ui = container.feature('ui')
+
+const assistant = container.feature('assistant', {
+  systemPrompt: [
+    'You are a process management assistant with tools to spawn, monitor, inspect, and kill background processes.',
+    'When asked to check on processes, use getProcessOutput to read their latest output and summarize what you see.',
+    'For ping output, parse the lines and calculate the average response time yourself.',
+    'For top output, summarize CPU and memory usage from the header lines.',
+    'Always be concise — give the data, not a lecture.',
+  ].join('\\n'),
+  model: 'gpt-4.1-mini',
+})
+
+assistant.use(pm)
+await assistant.start()
+
+const tools = Object.keys(assistant.tools)
+console.log(ui.colors.cyan('Tools registered:'), tools.join(', '))
+console.log()
+
+// ── Helper to print assistant responses ──────────────────────────────
+const ask = async (label, question) => {
+  console.log(ui.colors.dim(\`── \${label} ──\`))
+  console.log(ui.colors.yellow('→'), question.split('\\n')[0])
+  const response = await assistant.ask(question)
+  console.log(ui.markdown(response))
+  console.log()
+  return response
+}
+
+// Step 1: Spawn long-running processes
+await ask('SPAWN',
+  'Spawn two background processes:\\n' +
+  '1. Ping google.com with tag "ping-google" (use: ping -c 20 google.com)\\n' +
+  '2. Run top in batch mode with tag "top-monitor" (use: top -l 5 -s 2)\\n' +
+  'Confirm both are running.'
+)
+
+// Step 2: Wait, then check in on their output
+await new Promise(r => setTimeout(r, 4000))
+await ask('CHECK-IN #1',
+  'Check on both processes. For ping-google, read the stdout and tell me how many replies so far and the average response time. For top-monitor, read the stdout and tell me the current CPU usage summary.'
+)
+
+// Step 3: Quick one-shot command while the others keep going
+await ask('QUICK COMMAND',
+  'Run a quick command: "uptime" — tell me the system load averages.'
+)
+
+// Step 4: Second check-in — more data should have accumulated
+await new Promise(r => setTimeout(r, 4000))
+await ask('CHECK-IN #2',
+  'Check on ping-google again. How many replies now vs last time? What is the average response time? Also list all tracked processes and their status.'
+)
+
+// Step 5: Kill everything
+await ask('CLEANUP',
+  'Kill all running processes and confirm they are stopped.'
+)
+
+// Belt and suspenders
+pm.killAll()
+const remaining = pm.list().filter(h => h.status === 'running')
+console.log(ui.colors.green('Running after cleanup:'), remaining.length)
+\`\`\`
+
+## Summary
+
+This example showed a runtime assistant orchestrating real background processes over multiple conversation turns — spawning long-running \`ping\` and \`top\` commands, checking in on their output as it accumulates, running a quick \`uptime\` in between, then coming back for a second check-in before cleaning everything up. The assistant parsed ping times, summarized CPU usage, and managed the full lifecycle without any hardcoded logic — just natural language and processManager tools.
 `,
   "postgres.md": `---
 title: "PostgreSQL"
@@ -2054,6 +2139,135 @@ Attach network volumes to pods via the \`networkVolumeId\` option in \`createPod
 ## Summary
 
 The \`runpod\` feature provides complete GPU cloud management. Create pods from templates, manage lifecycle (start/stop/remove), SSH into running pods, and manage network storage volumes. Supports polling for readiness and file transfer operations. Key methods: \`createPod()\`, \`getpods()\`, \`waitForPod()\`, \`getShell()\`, \`listVolumes()\`, \`createVolume()\`.
+`,
+  "websocket-ask-and-reply-example.md": `---
+title: "websocket-ask-and-reply"
+tags: [websocket, client, server, ask, reply, rpc]
+lastTested: null
+lastTestPassed: null
+---
+
+# websocket-ask-and-reply
+
+Request/response conversations over WebSocket using \`ask()\` and \`reply()\`.
+
+## Overview
+
+The WebSocket client and server both support a request/response protocol on top of the normal fire-and-forget message stream. The client can \`ask()\` the server a question and await the answer. The server can \`ask()\` a connected client the same way. Under the hood it works with correlation IDs — \`requestId\` on the request, \`replyTo\` on the response — but you never have to touch those directly.
+
+## Setup
+
+Declare the shared references that all blocks will use, and wire up the server's message handler. This block is synchronous so the variables persist across subsequent blocks.
+
+\`\`\`ts
+var port = 0
+var server = container.server('websocket', { json: true })
+var client = null
+
+server.on('message', (data, ws) => {
+  if (data.type === 'add') {
+    data.reply({ sum: data.data.a + data.data.b })
+  } else if (data.type === 'divide') {
+    if (data.data.b === 0) {
+      data.replyError('division by zero')
+    } else {
+      data.reply({ result: data.data.a / data.data.b })
+    }
+  }
+})
+console.log('Server and handlers configured')
+\`\`\`
+
+## Start Server and Connect Client
+
+\`\`\`ts
+port = await networking.findOpenPort(19900)
+await server.start({ port })
+console.log('Server listening on port', port)
+
+client = container.client('websocket', { baseURL: \`ws://localhost:\${port}\` })
+await client.connect()
+console.log('Client connected')
+\`\`\`
+
+## Client Asks the Server
+
+\`ask(type, data, timeout?)\` sends a message and returns a promise that resolves with the response payload.
+
+\`\`\`ts
+var sum = await client.ask('add', { a: 3, b: 4 })
+console.log('3 + 4 =', sum.sum)
+
+var quotient = await client.ask('divide', { a: 10, b: 3 })
+console.log('10 / 3 =', quotient.result.toFixed(2))
+\`\`\`
+
+## Handling Errors
+
+When the server calls \`replyError(message)\`, the client's \`ask()\` promise rejects with that message.
+
+\`\`\`ts
+try {
+  await client.ask('divide', { a: 1, b: 0 })
+} catch (err) {
+  console.log('Caught error:', err.message)
+}
+\`\`\`
+
+## Server Asks the Client
+
+The server can also ask a connected client. The client handles incoming requests by listening for messages with a \`requestId\` and sending back a \`replyTo\` response.
+
+\`\`\`ts
+client.on('message', (data) => {
+  if (data.requestId && data.type === 'whoAreYou') {
+    client.send({ replyTo: data.requestId, data: { name: 'luca-client', version: '1.0' } })
+  }
+})
+
+var firstClient = [...server.connections][0]
+var identity = await server.ask(firstClient, 'whoAreYou')
+console.log('Client identified as:', identity.name, identity.version)
+\`\`\`
+
+## Timeouts
+
+If nobody replies, \`ask()\` rejects after the timeout (default 10s, configurable as the third argument).
+
+\`\`\`ts
+try {
+  await client.ask('noop', {}, 500)
+} catch (err) {
+  console.log('Timed out as expected:', err.message)
+}
+\`\`\`
+
+## Regular Messages Still Work
+
+Messages without \`requestId\` flow through the normal \`message\` event as always. The ask/reply protocol is purely additive.
+
+\`\`\`ts
+var received = null
+server.on('message', (data) => {
+  if (data.type === 'ping') received = data
+})
+
+await client.send({ type: 'ping', ts: Date.now() })
+await new Promise(r => setTimeout(r, 50))
+console.log('Regular message received:', received.type, '— no requestId:', received.requestId === undefined)
+\`\`\`
+
+## Cleanup
+
+\`\`\`ts
+await client.disconnect()
+await server.stop()
+console.log('Done')
+\`\`\`
+
+## Summary
+
+The ask/reply protocol gives you awaitable request/response over WebSocket without leaving the Luca helper API. The client calls \`ask(type, data)\` and gets back a promise. The server's message handler gets \`reply()\` and \`replyError()\` injected on any message that carries a \`requestId\`. The server can also \`ask()\` a specific client. Timeouts, error propagation, and cleanup of pending requests on disconnect are all handled automatically.
 `,
   "port-exposer.md": `---
 title: "Port Exposer"

package/src/cli/build-info.ts

@@ -1,4 +1,4 @@
 // Generated at compile time — do not edit manually
-export const BUILD_SHA = '4f7677c'
+export const BUILD_SHA = 'c1e466d'
 export const BUILD_BRANCH = 'main'
-export const BUILD_DATE = '2026-03-22T20:57:24Z'
+export const BUILD_DATE = '2026-03-23T07:45:58Z'

package/src/clients/websocket.ts

@@ -19,6 +19,12 @@ declare module '../client' {
  * providing a clean interface for sending/receiving messages, tracking connection
  * state, and optional auto-reconnection with exponential backoff.
  *
+ * Supports ask/reply semantics when paired with the Luca WebSocket server.
+ * The client can `ask(type, data)` the server and await a typed response.
+ * Incoming messages with a `requestId` are treated as asks from the server
+ * and can be answered with `send({ replyTo: requestId, data })`. Requests
+ * time out if no reply arrives within the configurable window.
+ *
  * Events emitted:
  * - `open` — connection established
  * - `message` — message received (JSON-parsed when possible)
@@ -36,14 +42,24 @@ declare module '../client' {
  * ws.on('message', (data) => console.log('Received:', data))
  * await ws.connect()
  * await ws.send({ type: 'hello' })
+ *
+ * // ask/reply: request data from the server
+ * const result = await ws.ask('getUser', { id: 42 })
  * ```
  */
+export interface PendingRequest<T = any> {
+  resolve: (value: T) => void
+  reject: (reason: any) => void
+  timer: ReturnType<typeof setTimeout>
+}
+
 export class WebSocketClient<
   T extends WebSocketClientState = WebSocketClientState,
   K extends WebSocketClientOptions = WebSocketClientOptions
 > extends Client<T, K> {
   ws!: WebSocket
   _intentionalClose: boolean
+  _pending = new Map<string, PendingRequest>()
 
   static override shortcut = "clients.websocket" as const
   static override stateSchema = WebSocketClientStateSchema
@@ -97,7 +113,9 @@ export class WebSocketClient<
         try {
           data = JSON.parse(data)
         } catch {}
-        this.emit('message', data)
+        if (!this._handleReply(data)) {
+          this.emit('message', data)
+        }
       }
 
       ws.onclose = (event: any) => {
@@ -130,12 +148,69 @@ export class WebSocketClient<
     this.ws.send(JSON.stringify(data))
   }
 
+  /**
+   * 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.
+   *
+   * @param type - A string identifying the request type
+   * @param data - Optional payload to include with the request
+   * @param timeout - How long to wait for a response (default 10 000 ms)
+   * @returns The `data` field of the response message
+   *
+   * @example
+   * ```typescript
+   * const result = await ws.ask('getUser', { id: 42 })
+   * ```
+   */
+  async ask<R = 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({ 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 disconnect. */
+  _rejectAllPending(reason: string) {
+    for (const [id, pending] of this._pending) {
+      clearTimeout(pending.timer)
+      pending.reject(new Error(reason))
+    }
+    this._pending.clear()
+  }
+
   /**
    * Gracefully close the WebSocket connection. Suppresses auto-reconnect
    * and updates connection state to disconnected.
    */
   async disconnect(): Promise<this> {
     this._intentionalClose = true
+    this._rejectAllPending('WebSocket disconnected')
     if (this.ws) {
       this.ws.close()
     }

package/src/helper.ts

@@ -138,9 +138,16 @@ export abstract class Helper<T extends HelperState = HelperState, K extends Help
     this.container.emit('helperInitialized', this)
   }
   
-  /** 
+  /**
+   * The static shortcut identifier for this helper type, e.g. "features.assistant".
+  */
+  get shortcut(): string {
+    return (this.constructor as any).shortcut || ''
+  }
+
+  /**
    * Every helper has a cache key which is computed at the time it is created through the container.
-   * 
+   *
    * This ensures only a single instance of the helper exists for the requested options.
   */
   get cacheKey() {
@@ -189,6 +196,26 @@ export abstract class Helper<T extends HelperState = HelperState, K extends Help
     return this
   }
 
+  /**
+   * Called when another helper (e.g. an assistant) consumes this helper's
+   * tools via `use()`. Override this to detect the consumer type and react —
+   * for example, adding system prompt extensions to an assistant.
+   *
+   * Use `consumer.shortcut` to identify the consumer type:
+   * ```typescript
+   * override setupToolsConsumer(consumer: Helper) {
+   *   if (consumer.shortcut === 'features.assistant') {
+   *     (consumer as any).addSystemPromptExtension('myFeature', 'usage hints here')
+   *   }
+   * }
+   * ```
+   *
+   * The default implementation is a no-op.
+   *
+   * @param consumer - The helper instance that is consuming this helper's tools
+   */
+  setupToolsConsumer(consumer: Helper): void {}
+
   /**
    * Collect all tools from the inheritance chain and instance, returning
    * { schemas, handlers } with matching keys. Walks the prototype chain