@soederpop/luca 0.0.26 → 0.0.29

package/docs/examples/assistant-with-process-manager.md

@@ -0,0 +1,84 @@
+---
+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.

package/docs/examples/structured-output-with-assistants.md

@@ -0,0 +1,144 @@
+---
+title: "Structured Output with Assistants"
+tags: [assistant, conversation, structured-output, zod, openai]
+lastTested: null
+lastTestPassed: null
+---
+
+# Structured Output with Assistants
+
+Get typed, schema-validated JSON responses from OpenAI instead of raw text strings.
+
+## Overview
+
+OpenAI's Structured Outputs feature constrains the model to return JSON that exactly matches a schema you provide. Combined with Zod, this means `ask()` can return parsed objects instead of strings — no regex parsing, no "please respond in JSON", no malformed output.
+
+Pass a `schema` option to `ask()` and the response comes back as a parsed object guaranteed to match your schema.
+
+## Basic: Extract Structured Data
+
+The simplest use case — ask a question and get structured data back.
+
+```ts
+const { z } = container
+const conversation = container.feature('conversation', {
+  model: 'gpt-4.1-mini',
+  history: [{ role: 'system', content: 'You are a helpful data extraction assistant.' }]
+})
+
+const result = await conversation.ask('The founders of Apple are Steve Jobs, Steve Wozniak, and Ronald Wayne. They started it in 1976 in Los Altos, California.', {
+  schema: z.object({
+    company: z.string(),
+    foundedYear: z.number(),
+    location: z.string(),
+    founders: z.array(z.string()),
+  }).describe('CompanyInfo')
+})
+
+console.log('Company:', result.company)
+console.log('Founded:', result.foundedYear)
+console.log('Location:', result.location)
+console.log('Founders:', result.founders)
+```
+
+The `.describe()` on the schema gives OpenAI the schema name — keep it short and descriptive.
+
+## Enums and Categorization
+
+Structured outputs work great for classification tasks where you want the model to pick from a fixed set of values.
+
+```ts
+const { z } = container
+const conversation = container.feature('conversation', {
+  model: 'gpt-4.1-mini',
+  history: [{ role: 'system', content: 'You are a helpful assistant.' }]
+})
+
+const sentiment = await conversation.ask('I absolutely love this product, it changed my life!', {
+  schema: z.object({
+    sentiment: z.enum(['positive', 'negative', 'neutral', 'mixed']),
+    confidence: z.number(),
+    reasoning: z.string(),
+  }).describe('SentimentAnalysis')
+})
+
+console.log('Sentiment:', sentiment.sentiment)
+console.log('Confidence:', sentiment.confidence)
+console.log('Reasoning:', sentiment.reasoning)
+```
+
+Because the model is constrained by the schema, `sentiment` will always be one of the four allowed values.
+
+## Nested Objects and Arrays
+
+Schemas can be as complex as you need. Here we extract a structured analysis with nested objects.
+
+```ts
+const { z } = container
+const conversation = container.feature('conversation', {
+  model: 'gpt-4.1-mini',
+  history: [{ role: 'system', content: 'You are a technical analyst.' }]
+})
+
+const analysis = await conversation.ask(
+  'TypeScript 5.5 introduced inferred type predicates, which automatically narrow types in filter callbacks. It also added isolated declarations for faster builds in monorepos, and a new regex syntax checking feature.',
+  {
+    schema: z.object({
+      subject: z.string(),
+      version: z.string(),
+      features: z.array(z.object({
+        name: z.string(),
+        category: z.enum(['type-system', 'performance', 'developer-experience', 'syntax', 'other']),
+        summary: z.string(),
+      })),
+      featureCount: z.number(),
+    }).describe('ReleaseAnalysis')
+  }
+)
+
+console.log('Subject:', analysis.subject, analysis.version)
+console.log('Features:')
+for (const f of analysis.features) {
+  console.log(`  [${f.category}] ${f.name}: ${f.summary}`)
+}
+console.log('Total features:', analysis.featureCount)
+```
+
+Every level of nesting is validated — the model cannot return a feature without a category or skip required fields.
+
+## With an Assistant
+
+Structured outputs work the same way through the assistant API. The schema passes straight through to the underlying conversation.
+
+```ts
+const { z } = container
+const assistant = container.feature('assistant', {
+  systemPrompt: 'You are a code review assistant. You analyze code snippets and provide structured feedback.',
+  model: 'gpt-4.1-mini',
+})
+
+const review = await assistant.ask(
+  'Review this: function add(a, b) { return a + b }',
+  {
+    schema: z.object({
+      issues: z.array(z.object({
+        severity: z.enum(['info', 'warning', 'error']),
+        message: z.string(),
+      })),
+      suggestion: z.string(),
+      score: z.number(),
+    }).describe('CodeReview')
+  }
+)
+
+console.log('Score:', review.score)
+console.log('Suggestion:', review.suggestion)
+console.log('Issues:')
+for (const issue of review.issues) {
+  console.log(`  [${issue.severity}] ${issue.message}`)
+}
+```
+
+## Summary
+
+This demo covered extracting structured data, classification with enums, nested schema validation, and using structured outputs through both the conversation and assistant APIs. The key is passing a Zod schema via `{ schema }` in the options to `ask()` — OpenAI guarantees the response matches, and you get a parsed object back.

package/docs/examples/websocket-ask-and-reply-example.md

@@ -0,0 +1,128 @@
+---
+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.

package/docs/window-manager-fix.md

@@ -0,0 +1,249 @@
+# Window Manager Fix
+
+## Problem
+
+The current `windowManager` design allows any Luca process to call `listen()` on the same well-known Unix socket:
+
+- `~/Library/Application Support/LucaVoiceLauncher/ipc-window.sock`
+
+That means unrelated commands can compete for ownership of the app-facing socket. The current implementation makes this worse by doing the following on startup:
+
+1. If the socket path exists, `unlinkSync(socketPath)`.
+2. Bind a new server at the same path.
+
+This creates a race where one Luca process can steal the socket from another. The native `LucaVoiceLauncher` app then disconnects from the old server and reconnects to whichever process currently owns the path. If that process exits, the app falls into reconnect loops.
+
+This is the root cause of the observed behavior where:
+
+- the launcher sometimes connects successfully
+- the connection then drops unexpectedly
+- repeated `ipc connect failed` messages appear in the launcher log
+
+## Design Goal
+
+We want:
+
+- one stable owner of the app-facing socket
+- many independent Luca commands able to trigger window actions
+- optional failover if the main owner dies
+- support for multiple launcher app clients over time, and optionally at once
+
+The key design rule is:
+
+> Many clients is fine. Many servers competing for the same well-known socket is not.
+
+## Recommended Architecture
+
+### 1. Single broker for the app socket
+
+Only one broker process may own:
+
+- `ipc-window.sock`
+
+The broker is responsible for:
+
+- accepting native launcher app connections
+- tracking connected app clients
+- routing window commands to the selected app client
+- receiving `windowAck`, `windowClosed`, and `terminalExited`
+- routing responses and lifecycle events back to the original requester
+
+### 2. Separate control channel for Luca commands
+
+Luca commands should not bind the app-facing socket directly.
+
+Instead, they should talk to the broker over a separate channel, for example:
+
+- `~/Library/Application Support/LucaVoiceLauncher/ipc-window-control.sock`
+
+This control channel is for producers:
+
+- `luca main`
+- `luca workflow run ...`
+- `luca present`
+- scripts
+- background jobs
+
+These producers send requests to the broker, and the broker fans them out to the connected app client.
+
+### 3. Broker supports multiple app clients
+
+The broker should replace the current single `_client` field with a registry:
+
+```ts
+Map<string, ClientConnection>
+```
+
+Each client should have:
+
+- `clientId`
+- `socket`
+- `buffer`
+- metadata if useful later, such as display, role, labels, or lastSeenAt
+
+This allows:
+
+- multiple launcher app instances
+- reconnect without confusing request ownership
+- future routing by target client
+
+## Routing Model
+
+### Producer -> broker
+
+Producer sends a request like:
+
+```json
+{
+  "type": "windowRequest",
+  "requestId": "uuid",
+  "originId": "uuid",
+  "targetClientId": "optional",
+  "window": {
+    "action": "open",
+    "url": "https://example.com"
+  }
+}
+```
+
+### Broker -> app client
+
+Broker forwards the request to the chosen app client, preserving `requestId`.
+
+### App client -> broker
+
+App replies with:
+
+- `windowAck`
+- `windowClosed`
+- `terminalExited`
+
+### Broker -> producer
+
+Broker routes:
+
+- the `windowAck` back to the producer that originated the request
+- lifecycle events either to the originating producer, or to any subscribed producer
+
+## Client Selection Policy
+
+The simplest policy is:
+
+- use the most recently connected healthy app client
+
+Later policies can support:
+
+- explicit `targetClientId`
+- labels like `role=presenter`
+- display-aware routing
+- sticky routing based on `windowId -> clientId`
+
+## Leader Election / Failover
+
+If we want multiple `windowManager` instances to exist, they must not all behave as brokers.
+
+Instead:
+
+1. Try connecting to the broker control socket.
+2. If broker exists, act as a producer client.
+3. If broker does not exist, try to acquire a broker lock.
+4. If lock succeeds, become broker and bind both sockets.
+5. If lock fails, retry broker connection and act as producer.
+
+Possible lock mechanisms:
+
+- lock file with `flock`
+- lock directory with atomic `mkdir`
+- local TCP/Unix registration endpoint
+
+The important constraint is:
+
+- only the elected broker binds `ipc-window.sock`
+
+All other instances must route through it.
+
+## Why not let many processes bind the same socket?
+
+Because Unix domain socket paths are singular ownership points. A path is not a shared bus.
+
+If multiple processes all call `listen()` against the same path and delete stale files optimistically, they will:
+
+- steal the path from each other
+- disconnect the app unexpectedly
+- lose in-flight requests
+- create non-deterministic routing
+
+This is fundamentally the wrong abstraction.
+
+## Backward-Compatible Migration
+
+We can migrate without breaking the public `windowManager.spawn()` API.
+
+### Phase 1
+
+- Introduce a broker mode internally.
+- Add `ipc-window-control.sock`.
+- Keep the existing app protocol unchanged.
+- Make `windowManager.spawn()` talk to the broker when possible.
+
+### Phase 2
+
+- Prevent non-broker processes from binding `ipc-window.sock`.
+- Replace blind `unlinkSync(socketPath)` with active listener detection.
+- Add broker election and failover.
+
+### Phase 3
+
+- Add multi-client routing.
+- Add subscriptions for lifecycle events.
+- Add explicit target selection if needed.
+
+## Minimal Fix if We Need Something Fast
+
+If we do not implement the full broker immediately, we should at least stop destroying active listeners.
+
+`listen()` should:
+
+1. Attempt to connect to the existing socket.
+2. If a listener is alive, do not unlink or rebind.
+3. If the socket is dead, clean it up and bind.
+
+This does not solve multi-producer routing, but it prevents random Luca commands from stealing the app socket from a healthy broker.
+
+## Proposed Internal Refactor
+
+Current state:
+
+- one process tries to be both broker and producer
+- one `_client`
+- one app-facing socket
+
+Target state:
+
+- broker owns app-facing socket
+- producers use control socket
+- broker stores:
+  - `clients: Map<clientId, ClientConnection>`
+  - `pendingRequests: Map<requestId, PendingRequest>`
+  - `requestOrigins: Map<requestId, originConnection>`
+  - `windowOwners: Map<windowId, clientId>`
+
+That separation gives us:
+
+- stable app connectivity
+- multi-command triggering
+- failover
+- room for multi-client routing
+
+## Summary
+
+The right fix is not “allow many `listen()` calls on the same socket.”
+
+The right fix is:
+
+- one elected broker owns the app socket
+- many Luca processes talk to the broker
+- many app clients may connect to the broker
+- failover is implemented through broker election, not socket contention
+
+That preserves a stable connection for the launcher app while still allowing multiple people, commands, or workflows to trigger window operations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soederpop/luca",
-  "version": "0.0.26",
+  "version": "0.0.29",
   "website": "https://luca.soederpop.com",
   "description": "lightweight universal conversational architecture AKA Le Ultimate Component Architecture AKA Last Universal Common Ancestor, part AI part Human",
   "author": "jon soeder aka the people's champ <jon@soederpop.com>",