@soederpop/luca 0.0.28 → 0.0.30

package/commands/try-all-challenges.ts

@@ -241,7 +241,7 @@ Be specific and actionable. Reference concrete file paths, APIs, and patterns. T
     '--in-folder', sessionFolder,
     '--out-file', `${sessionFolder}/logs/synthesis-session.md`,
     '--dont-touch-file',
-    '--preserve-frontmatter',
+    '--include-frontmatter',
   ], {
     onOutput: (str: string) => { process.stdout.write(str) },
     onError: (str: string) => { process.stderr.write(str) },

package/docs/TABLE-OF-CONTENTS.md

@@ -57,8 +57,6 @@
 - [ui](./examples/ui.md)
 - [Vault](./examples/vault.md)
 - [vm](./examples/vm.md)
-- [Window Manager](./examples/window-manager.md)
-- [Window Manager Layouts](./examples/window-manager-layouts.md)
 - [YAML](./examples/yaml.md)
 - [YAML Tree](./examples/yaml-tree.md)
 
@@ -159,7 +157,6 @@
 - [UI (features.ui)](./apis/features/node/ui.md)
 - [WebVault (features.vault)](./apis/features/node/vault.md)
 - [VM (features.vm)](./apis/features/node/vm.md)
-- [WindowManager (features.windowManager)](./apis/features/node/window-manager.md)
 - [YAML (features.yaml)](./apis/features/node/yaml.md)
 - [YamlTree (features.yamlTree)](./apis/features/node/yaml-tree.md)
 - [AssetLoader (features.assetLoader)](./apis/features/web/asset-loader.md)

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/tutorials/20-browser-esm.md

@@ -0,0 +1,234 @@
+---
+title: "Browser: Import Luca from esm.sh"
+tags:
+  - browser
+  - esm
+  - web
+  - quickstart
+  - cdn
+---
+# Browser: Import Luca from esm.sh
+
+You can use Luca in any browser environment — no bundler, no build step. Import it from [esm.sh](https://esm.sh) and you get the singleton container on `window.luca`, ready to go. All the same APIs apply.
+
+## Basic Setup
+
+```html
+<script type="module">
+  import "https://esm.sh/@soederpop/luca/web"
+
+  const container = window.luca
+  console.log(container.uuid) // unique container ID
+  console.log(container.features.available) // ['assetLoader', 'voice', 'speech', 'network', 'vault', 'vm', 'esbuild', 'helpers', 'containerLink']
+</script>
+```
+
+The import triggers module evaluation, which creates the `WebContainer` singleton and attaches it to `window.luca`. That's it.
+
+If you prefer a named import:
+
+```html
+<script type="module">
+  import container from "https://esm.sh/@soederpop/luca/web"
+  // container === window.luca
+</script>
+```
+
+## Using Features
+
+Once you have the container, features work exactly like they do on the server — lazy-loaded via `container.feature()`.
+
+```html
+<script type="module">
+  import "https://esm.sh/@soederpop/luca/web"
+  const { luca: container } = window
+
+  // Load a script from a CDN
+  const assetLoader = container.feature('assetLoader')
+  await assetLoader.loadScript('https://cdn.jsdelivr.net/npm/chart.js')
+
+  // Load a stylesheet
+  await assetLoader.loadStylesheet('https://cdn.jsdelivr.net/npm/water.css@2/out/water.css')
+
+  // Text-to-speech
+  const speech = container.feature('speech')
+  speech.speak('Hello from Luca')
+
+  // Voice recognition
+  const voice = container.feature('voice')
+  voice.on('transcript', ({ text }) => console.log('Heard:', text))
+  voice.start()
+</script>
+```
+
+## State and Events
+
+The container is a state machine and event bus. This works identically to the server.
+
+```html
+<script type="module">
+  import container from "https://esm.sh/@soederpop/luca/web"
+
+  // Listen for state changes
+  container.on('stateChanged', ({ changes }) => {
+    console.log('State changed:', changes)
+  })
+
+  // Feature-level state and events
+  const voice = container.feature('voice')
+  voice.on('stateChanged', ({ changes }) => {
+    document.getElementById('status').textContent = changes.listening ? 'Listening...' : 'Idle'
+  })
+</script>
+```
+
+## REST Client
+
+Make HTTP requests with the built-in REST client. Methods return parsed JSON directly.
+
+```html
+<script type="module">
+  import container from "https://esm.sh/@soederpop/luca/web"
+
+  const api = container.client('rest', { baseURL: 'https://jsonplaceholder.typicode.com' })
+  const posts = await api.get('/posts')
+  console.log(posts) // array of post objects, not a Response wrapper
+</script>
+```
+
+## WebSocket Client
+
+Connect to a WebSocket server:
+
+```html
+<script type="module">
+  import container from "https://esm.sh/@soederpop/luca/web"
+
+  const socket = container.client('socket', { url: 'ws://localhost:3000' })
+  socket.on('message', (data) => console.log('Received:', data))
+  socket.send({ type: 'hello' })
+</script>
+```
+
+## Extending: Custom Features
+
+The container exposes the `Feature` class directly, so you can create your own features without any additional imports.
+
+```html
+<script type="module">
+  import container from "https://esm.sh/@soederpop/luca/web"
+
+  const { Feature } = container
+
+  class Theme extends Feature {
+    static shortcut = 'features.theme'
+    static { Feature.register(this, 'theme') }
+
+    get current() {
+      return this.state.get('mode') || 'light'
+    }
+
+    toggle() {
+      const next = this.current === 'light' ? 'dark' : 'light'
+      this.state.set('mode', next)
+      document.documentElement.setAttribute('data-theme', next)
+      this.emit('themeChanged', { mode: next })
+    }
+  }
+
+  const theme = container.feature('theme')
+  theme.on('themeChanged', ({ mode }) => console.log('Theme:', mode))
+  theme.toggle() // => Theme: dark
+</script>
+```
+
+## Utilities
+
+The container's built-in utilities are available in the browser too.
+
+```html
+<script type="module">
+  import container from "https://esm.sh/@soederpop/luca/web"
+
+  // UUID generation
+  const id = container.utils.uuid()
+
+  // Lodash helpers
+  const { groupBy, keyBy, pick } = container.utils.lodash
+
+  // String utilities
+  const { camelCase, kebabCase } = container.utils.stringUtils
+</script>
+```
+
+## Full Example: A Minimal App
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Luca Browser Demo</title>
+</head>
+<body>
+  <h1>Luca Browser Demo</h1>
+  <button id="speak">Speak</button>
+  <button id="theme">Toggle Theme</button>
+  <pre id="output"></pre>
+
+  <script type="module">
+    import container from "https://esm.sh/@soederpop/luca/web"
+
+    const log = (msg) => {
+      document.getElementById('output').textContent += msg + '\n'
+    }
+
+    // Load a stylesheet
+    const assets = container.feature('assetLoader')
+    await assets.loadStylesheet('https://cdn.jsdelivr.net/npm/water.css@2/out/water.css')
+
+    // Custom feature
+    const { Feature } = container
+
+    class Theme extends Feature {
+      static shortcut = 'features.theme'
+      static { Feature.register(this, 'theme') }
+
+      toggle() {
+        const next = (this.state.get('mode') || 'light') === 'light' ? 'dark' : 'light'
+        this.state.set('mode', next)
+        document.documentElement.style.colorScheme = next
+        this.emit('themeChanged', { mode: next })
+      }
+    }
+
+    const theme = container.feature('theme')
+    theme.on('themeChanged', ({ mode }) => log(`Theme: ${mode}`))
+
+    // Speech
+    const speech = container.feature('speech')
+
+    document.getElementById('speak').onclick = () => speech.speak('Hello from Luca')
+    document.getElementById('theme').onclick = () => theme.toggle()
+
+    log(`Container ID: ${container.uuid}`)
+    log(`Features: ${container.features.available.join(', ')}`)
+  </script>
+</body>
+</html>
+```
+
+Save this as an HTML file, open it in a browser, and everything works — no npm, no bundler, no build step.
+
+## Gotchas
+
+- **esm.sh caches aggressively.** Pin a version if you need stability: `https://esm.sh/@soederpop/luca@0.0.29/web`
+- **Browser features only.** The web container doesn't include node-specific features like `fs`, `git`, `proc`, or `docker`. If you need server features, run Luca on the server and connect via the REST or WebSocket clients.
+- **`window.luca` is the singleton.** Don't call `createContainer()` — it just warns and returns the same instance. If you need isolation, use `container.subcontainer()`.
+- **CORS applies.** REST client requests from the browser are subject to browser CORS rules. Your API must send the right headers.
+
+## What's Next
+
+- [State and Events](./05-state-and-events.md) — deep dive into the state machine and event bus (works identically in the browser)
+- [Creating Features](./10-creating-features.md) — full anatomy of a feature with schemas, state, and events
+- [Clients](./09-clients.md) — REST and WebSocket client APIs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soederpop/luca",
-  "version": "0.0.28",
+  "version": "0.0.30",
   "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/container.server.ts

@@ -11,6 +11,7 @@ import { Assistant } from './features/assistant'
 import { AssistantsManager } from './features/assistants-manager'
 import { DocsReader } from './features/docs-reader'
 import { SkillsLibrary } from './features/skills-library'
+import { BrowserUse } from './features/browser-use'
 import { SemanticSearch } from '@soederpop/luca/node/features/semantic-search'
 import { ContentDb } from '@soederpop/luca/node/features/content-db'
 
@@ -26,6 +27,7 @@ export {
 	AssistantsManager,
 	DocsReader,
 	SkillsLibrary,
+	BrowserUse,
 	SemanticSearch,
 	ContentDb,
 	NodeContainer,
@@ -49,6 +51,7 @@ export interface AGIFeatures extends NodeFeatures {
 	assistantsManager: typeof AssistantsManager
 	docsReader: typeof DocsReader
 	skillsLibrary: typeof SkillsLibrary
+	browserUse: typeof BrowserUse
 }
 
 export interface ConversationFactoryOptions {
@@ -121,6 +124,7 @@ const container = new AGIContainer()
 	.use(AssistantsManager)
 	.use(DocsReader)
 	.use(SkillsLibrary)
+	.use(BrowserUse)
 	.use(SemanticSearch)
 
 container.docs = container.feature('contentDb', {

package/src/agi/features/assistant.ts

@@ -7,6 +7,7 @@ import type { AGIContainer } from '../container.server.js'
 import type { ContentDb } from '@soederpop/luca/node'
 import type { ConversationHistory, ConversationMeta } from './conversation-history'
 import hashObject from '../../hash-object.js'
+import { InterceptorChain, type InterceptorFn, type InterceptorPoints, type InterceptorPoint } from '../lib/interceptor-chain.js'
 
 declare module '@soederpop/luca/feature' {
 	interface AvailableFeatures {
@@ -85,6 +86,15 @@ export const AssistantOptionsSchema = FeatureOptionsSchema.extend({
 
 	/** When true, prepend a timestamp to each user message so the assistant can track the passage of time across sessions */
 	injectTimestamps: z.boolean().default(false).describe('Prepend timestamps to user messages so the assistant can perceive time passing between sessions'),
+
+	/** Strict allowlist of tool names to include. Only these tools will be available. Supports "*" glob matching. */
+	allowTools: z.array(z.string()).optional().describe('Strict allowlist of tool name patterns. Only matching tools are available. Supports * glob matching.'),
+
+	/** Denylist of tool names to exclude. Matching tools will be removed. Supports "*" glob matching. */
+	forbidTools: z.array(z.string()).optional().describe('Denylist of tool name patterns to exclude. Supports * glob matching.'),
+
+	/** Convenience alias for allowTools — an explicit list of tool names (exact matches only). */
+	toolNames: z.array(z.string()).optional().describe('Explicit list of tool names to include (exact match). Shorthand for allowTools without glob patterns.'),
 })
 
 export type AssistantState = z.infer<typeof AssistantStateSchema>
@@ -113,6 +123,26 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 
 	static { Feature.register(this, 'assistant') }
 
+	readonly interceptors = {
+		beforeAsk: new InterceptorChain<InterceptorPoints['beforeAsk']>(),
+		beforeTurn: new InterceptorChain<InterceptorPoints['beforeTurn']>(),
+		beforeToolCall: new InterceptorChain<InterceptorPoints['beforeToolCall']>(),
+		afterToolCall: new InterceptorChain<InterceptorPoints['afterToolCall']>(),
+		beforeResponse: new InterceptorChain<InterceptorPoints['beforeResponse']>(),
+	}
+
+	/**
+	 * Register an interceptor at a given point in the pipeline.
+	 *
+	 * @param point - The interception point
+	 * @param fn - Middleware function receiving (ctx, next)
+	 * @returns this, for chaining
+	 */
+	intercept<K extends InterceptorPoint>(point: K, fn: InterceptorFn<InterceptorPoints[K]>): this {
+		this.interceptors[point].add(fn as any)
+		return this
+	}
+
 	/** @returns Default state with the assistant not started, zero conversations, and the resolved folder path. */
 	override get initialState(): AssistantState {
 		return {
@@ -313,7 +343,59 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 
 	/** The tools registered with this assistant. */
 	get tools(): Record<string, ConversationTool> {
-		return (this.state.get('tools') || {}) as Record<string, ConversationTool>
+		const all = (this.state.get('tools') || {}) as Record<string, ConversationTool>
+		return this.applyToolFilters(all)
+	}
+
+	/**
+	 * Apply allowTools, forbidTools, and toolNames filters from options.
+	 * toolNames is treated as an exact-match allowlist. allowTools/forbidTools support "*" glob patterns.
+	 * allowTools is applied first (strict allowlist), then forbidTools removes from whatever remains.
+	 */
+	private applyToolFilters(tools: Record<string, ConversationTool>): Record<string, ConversationTool> {
+		const { allowTools, forbidTools, toolNames } = this.options
+		if (!allowTools && !forbidTools && !toolNames) return tools
+
+		let names = Object.keys(tools)
+
+		// toolNames is a strict exact-match allowlist
+		if (toolNames) {
+			const allowed = new Set(toolNames)
+			names = names.filter(n => allowed.has(n))
+		}
+
+		// allowTools: only keep names matching at least one pattern
+		if (allowTools) {
+			names = names.filter(n => allowTools.some(pattern => this.matchToolPattern(pattern, n)))
+		}
+
+		// forbidTools: remove names matching any pattern
+		if (forbidTools) {
+			names = names.filter(n => !forbidTools.some(pattern => this.matchToolPattern(pattern, n)))
+		}
+
+		const result: Record<string, ConversationTool> = {}
+		for (const n of names) {
+			result[n] = tools[n]
+		}
+		return result
+	}
+
+	/**
+	 * Match a tool name against a pattern that supports "*" as a wildcard.
+	 * - "*" matches everything
+	 * - "prefix*" matches names starting with prefix
+	 * - "*suffix" matches names ending with suffix
+	 * - "pre*suf" matches names starting with pre and ending with suf
+	 * - exact string matches exactly
+	 */
+	private matchToolPattern(pattern: string, name: string): boolean {
+		if (pattern === '*') return true
+		if (!pattern.includes('*')) return pattern === name
+
+		// Convert glob pattern to regex: escape regex chars, replace * with .*
+		const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')
+		return new RegExp(`^${escaped}$`).test(name)
 	}
 
 	/**
@@ -911,6 +993,38 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 		this.conversation.on('toolResult', (name: string, result: any) => this.emit('toolResult', name, result))
 		this.conversation.on('toolError', (name: string, error: any) => this.emit('toolError', name, error))
 
+		// Install interceptor-aware tool executor on the conversation
+		this.conversation.toolExecutor = async (name: string, args: Record<string, any>, handler: (...a: any[]) => Promise<any>) => {
+			const ctx = { name, args, result: undefined as string | undefined, error: undefined, skip: false }
+
+			await this.interceptors.beforeToolCall.run(ctx, async () => {})
+
+			if (ctx.skip) {
+				const result = ctx.result ?? JSON.stringify({ skipped: true })
+				this.emit('toolResult', ctx.name, result)
+				return result
+			}
+
+			try {
+				this.emit('toolCall', ctx.name, ctx.args)
+				const output = await handler(ctx.args)
+				ctx.result = typeof output === 'string' ? output : JSON.stringify(output)
+			} catch (err: any) {
+				ctx.error = err
+				ctx.result = JSON.stringify({ error: err.message || String(err) })
+			}
+
+			await this.interceptors.afterToolCall.run(ctx, async () => {})
+
+			if (ctx.error && !ctx.result?.includes('"error"')) {
+				this.emit('toolError', ctx.name, ctx.error)
+			} else {
+				this.emit('toolResult', ctx.name, ctx.result!)
+			}
+
+			return ctx.result!
+		}
+
 		// Load conversation history for non-lifecycle modes
 		await this.loadConversationHistory()
 
@@ -961,7 +1075,23 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 			question = this.prependTimestamp(question)
 		}
 
-		const result = await this.conversation.ask(question, options)
+		// Run beforeAsk interceptors — they can rewrite the question or short-circuit
+		if (this.interceptors.beforeAsk.hasInterceptors) {
+			const ctx = { question, options } as InterceptorPoints['beforeAsk']
+			await this.interceptors.beforeAsk.run(ctx, async () => {})
+			if (ctx.result !== undefined) return ctx.result
+			question = ctx.question
+			options = ctx.options
+		}
+
+		let result = await this.conversation.ask(question, options)
+
+		// Run beforeResponse interceptors — they can rewrite the final text
+		if (this.interceptors.beforeResponse.hasInterceptors) {
+			const ctx = { text: result }
+			await this.interceptors.beforeResponse.run(ctx, async () => {})
+			result = ctx.text
+		}
 
 		// Auto-save for non-lifecycle modes
 		if (this.options.historyMode !== 'lifecycle' && this.state.get('threadId')) {