@soederpop/luca 0.0.26 → 0.0.28

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/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.28",
   "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>",

package/src/agi/features/assistant.ts

@@ -28,6 +28,7 @@ export const AssistantEventsSchema = FeatureEventsSchema.extend({
 	toolResult: z.tuple([z.string().describe('Tool name'), z.any().describe('Result value')]).describe('Emitted when a tool returns a result'),
 	toolError: z.tuple([z.string().describe('Tool name'), z.any().describe('Error')]).describe('Emitted when a tool call fails'),
 	hookFired: z.tuple([z.string().describe('Hook/event name')]).describe('Emitted when a hook function is called'),
+	systemPromptExtensionsChanged: z.tuple([]).describe('Emitted when system prompt extensions are added or removed'),
 })
 
 export const AssistantStateSchema = FeatureStateSchema.extend({
@@ -39,6 +40,7 @@ export const AssistantStateSchema = FeatureStateSchema.extend({
 	conversationId: z.string().optional().describe('The active conversation persistence ID'),
 	threadId: z.string().optional().describe('The active thread ID'),
 	systemPrompt: z.string().describe('The loaded system prompt text'),
+	systemPromptExtensions: z.record(z.string(), z.string()).describe('Named extensions appended to the system prompt'),
 	meta: z.record(z.string(), z.any()).describe('Parsed YAML frontmatter from CORE.md'),
 	tools: z.record(z.string(), z.any()).describe('Registered tool implementations'),
 	hooks: z.record(z.string(), z.any()).describe('Loaded event hook functions'),
@@ -120,6 +122,7 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 			lastResponse: '',
 			folder: this.resolvedFolder,
 			systemPrompt: '',
+			systemPromptExtensions: {},
 			meta: {},
 			tools: {},
 			hooks: {},
@@ -228,7 +231,7 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 				api: 'chat',
 				...(this.options.maxTokens ? { maxTokens: this.options.maxTokens } : {}),
 				history: [
-					{ role: 'system', content: this.systemPrompt || this.loadSystemPrompt() },
+					{ role: 'system', content: this.effectiveSystemPrompt },
 				],
 			})
 			this.state.set('conversation', conv)
@@ -254,6 +257,60 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 		return this.state.get('systemPrompt') || ''
 	}
 
+	/** The named extensions appended to the system prompt. */
+	get systemPromptExtensions(): Record<string, string> {
+		return (this.state.get('systemPromptExtensions') || {}) as Record<string, string>
+	}
+
+	/** The system prompt with all extensions appended. This is the value passed to the conversation. */
+	get effectiveSystemPrompt(): string {
+		const base = this.systemPrompt
+		const extensions = Object.values(this.systemPromptExtensions)
+		if (!extensions.length) return base
+		return [base, ...extensions].join('\n\n')
+	}
+
+	/**
+	 * Add or update a named system prompt extension. The value is appended
+	 * to the base system prompt when passed to the conversation.
+	 *
+	 * @param key - A unique identifier for this extension
+	 * @param value - The text to append
+	 * @returns this, for chaining
+	 */
+	addSystemPromptExtension(key: string, value: string): this {
+		this.state.set('systemPromptExtensions', { ...this.systemPromptExtensions, [key]: value })
+		this.syncSystemPromptToConversation()
+		this.emit('systemPromptExtensionsChanged')
+		return this
+	}
+
+	/**
+	 * Remove a named system prompt extension.
+	 *
+	 * @param key - The identifier of the extension to remove
+	 * @returns this, for chaining
+	 */
+	removeSystemPromptExtension(key: string): this {
+		const current = { ...this.systemPromptExtensions }
+		delete current[key]
+		this.state.set('systemPromptExtensions', current)
+		this.syncSystemPromptToConversation()
+		this.emit('systemPromptExtensionsChanged')
+		return this
+	}
+
+	/** Update the conversation's system message to reflect the current effective prompt. */
+	private syncSystemPromptToConversation() {
+		const conv = this.state.get('conversation') as Conversation | null
+		if (!conv) return
+		const messages = [...conv.messages]
+		if (messages.length > 0 && (messages[0]!.role === 'system' || messages[0]!.role === 'developer')) {
+			messages[0] = { ...messages[0]!, content: this.effectiveSystemPrompt }
+			conv.state.set('messages', messages)
+		}
+	}
+
 	/** The tools registered with this assistant. */
 	get tools(): Record<string, ConversationTool> {
 		return (this.state.get('tools') || {}) as Record<string, ConversationTool>
@@ -287,6 +344,9 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 			}
 		} else if (fnOrHelper && typeof (fnOrHelper as any).toTools === 'function') {
 			this._registerTools((fnOrHelper as any).toTools())
+			if (typeof (fnOrHelper as any).setupToolsConsumer === 'function') {
+				(fnOrHelper as any).setupToolsConsumer(this)
+			}
 		} else if (fnOrHelper && 'schemas' in fnOrHelper && 'handlers' in fnOrHelper) {
 			this._registerTools(fnOrHelper as { schemas: Record<string, z.ZodType>, handlers: Record<string, Function> })
 		}
@@ -768,7 +828,7 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 
 			// Swap in fresh system prompt if it changed
 			if (messages.length > 0 && (messages[0]!.role === 'system' || messages[0]!.role === 'developer')) {
-				messages[0] = { role: messages[0]!.role, content: this.systemPrompt }
+				messages[0] = { role: messages[0]!.role, content: this.effectiveSystemPrompt }
 			}
 
 			this.conversation.state.set('id', existing.id)