@soederpop/luca 0.0.29 → 0.0.31

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/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.29",
+  "version": "0.0.31",
   "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

@@ -29,6 +29,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'),
+	reloaded: z.tuple([]).describe('Emitted after tools, hooks, and system prompt are reloaded from disk'),
 	systemPromptExtensionsChanged: z.tuple([]).describe('Emitted when system prompt extensions are added or removed'),
 })
 
@@ -86,6 +87,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>
@@ -334,7 +344,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)
 	}
 
 	/**
@@ -400,6 +462,8 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 	 */
 	addTool(name: string, handler: (...args: any[]) => any, schema?: z.ZodType): this {
 		if (!name) throw new Error('addTool handler must be a named function')
+		if (!this._runtimeToolNames) this._runtimeToolNames = new Set()
+		this._runtimeToolNames.add(name)
 
 		const current = { ...this.tools }
 
@@ -443,10 +507,12 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 
 		if (typeof nameOrHandler === 'string') {
 			delete current[nameOrHandler]
+			this._runtimeToolNames?.delete(nameOrHandler)
 		} else {
 			for (const [name, tool] of Object.entries(current)) {
 				if (tool.handler === nameOrHandler) {
 					delete current[name]
+					this._runtimeToolNames?.delete(name)
 					break
 				}
 			}
@@ -875,17 +941,68 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 	 */
 	/** Hook names that are called directly during lifecycle, not bound as event listeners. */
 	private static lifecycleHooks = new Set(['formatSystemPrompt'])
+	/** Stored references to bound hook listeners so they can be unbound on reload. Lazily initialized because afterInitialize runs before field initializers. */
+	private _boundHookListeners!: Array<{ event: string; listener: (...args: any[]) => void }>
+	/** Tool names added at runtime via addTool()/use(), so reload() can preserve them. */
+	private _runtimeToolNames!: Set<string>
 
 	private bindHooksToEvents() {
+		if (!this._boundHookListeners) this._boundHookListeners = []
 		const assistant = this
 		const hooks = (this.state.get('hooks') || {}) as Record<string, (...args: any[]) => any>
 		for (const [eventName, hookFn] of Object.entries(hooks)) {
 			if (Assistant.lifecycleHooks.has(eventName)) continue
-			this.on(eventName as any, (...args: any[]) => {
+			const listener = (...args: any[]) => {
 				this.emit('hookFired', eventName)
 				hookFn(assistant, ...args)
-			})
+			}
+			this._boundHookListeners.push({ event: eventName, listener })
+			this.on(eventName as any, listener)
+		}
+	}
+
+	private unbindHooksFromEvents() {
+		for (const { event, listener } of this._boundHookListeners) {
+			this.off(event as any, listener)
+		}
+		this._boundHookListeners = []
+	}
+
+	/**
+	 * Reload tools, hooks, and system prompt from disk. Useful during development
+	 * or when tool/hook files have been modified and you want the assistant to
+	 * pick up changes without restarting.
+	 *
+	 * @returns this, for chaining
+	 */
+	reload(): this {
+		// Unbind existing hook listeners
+		this.unbindHooksFromEvents()
+
+		// Snapshot runtime-added tools before reloading from disk
+		const runtimeTools: Record<string, ConversationTool> = {}
+		if (this._runtimeToolNames?.size) {
+			const current = this.tools
+			for (const name of this._runtimeToolNames) {
+				if (current[name]) runtimeTools[name] = current[name]
+			}
 		}
+
+		// Reload system prompt from disk
+		this.state.set('systemPrompt', this.loadSystemPrompt())
+
+		// Reload tools from disk (merges with option tools), then restore runtime tools
+		const diskTools = this.loadTools()
+		this.state.set('tools', { ...diskTools, ...runtimeTools })
+		this.emit('toolsChanged')
+
+		// Reload hooks from disk and rebind
+		this.state.set('hooks', this.loadHooks())
+		this.bindHooksToEvents()
+
+		this.emit('reloaded')
+
+		return this
 	}
 
 	/**