@soederpop/luca 0.1.2 → 0.1.3

package/src/bootstrap/generated.ts

@@ -1,5 +1,5 @@
 // Auto-generated bootstrap content
-// Generated at: 2026-03-30T06:52:56.930Z
+// Generated at: 2026-04-03T01:24:53.975Z
 // Source: docs/bootstrap/*.md, docs/bootstrap/templates/*, docs/examples/*.md, docs/tutorials/*.md
 //
 // Do not edit manually. Run: luca build-bootstrap
@@ -1253,6 +1253,131 @@ 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.
+`,
+  "entity.md": `---
+title: "Entity"
+tags: [entity, state, events, tools, core]
+lastTested: null
+lastTestPassed: null
+---
+
+# entity
+
+Lightweight, composable objects with observable state, a typed event bus, and an optional tool interface.
+
+## Overview
+
+An entity is a plain object — not a class — created via \`container.entity(id, options?)\`. Same id + options always returns the same underlying state and bus instance. Entities are designed to be extended with methods and getters via \`.extend()\`, and can expose those methods as AI tools via \`.expose()\`.
+
+## Basic Entity with Observable State
+
+Create an entity and read/write state through the observable \`state\` property.
+
+\`\`\`ts
+const counter = container.entity<{ count: number }>('counter')
+counter.setState({ count: 0 })
+
+counter.state.observe((next) => {
+  console.log('count changed to', next.count)
+})
+
+counter.setState(s => ({ count: s.count + 1 }))
+counter.setState(s => ({ count: s.count + 1 }))
+console.log('final count:', counter.state.get('count'))
+\`\`\`
+
+\`setState\` accepts either a partial object or a function that receives the current state. Observers fire synchronously after each change.
+
+## Typed Event Bus
+
+Every entity has a built-in event bus. Declare the event map as the third type parameter.
+
+\`\`\`ts
+type TimerEvents = {
+  tick: [elapsed: number]
+  done: []
+}
+
+const timer = container.entity<{}, {}, TimerEvents>('timer')
+
+timer.on('tick', (elapsed) => {
+  console.log('tick at', elapsed, 'ms')
+})
+
+timer.once('done', () => {
+  console.log('timer finished')
+})
+
+timer.emit('tick', 100)
+timer.emit('tick', 200)
+timer.emit('done')
+\`\`\`
+
+\`once\` auto-detaches after the first fire. \`waitFor\` returns a promise that resolves on the next emit of that event.
+
+## Extending with Methods
+
+Use \`.extend()\` to graft methods and getters onto an entity. All base properties — \`state\`, \`options\`, \`container\`, and the event methods — are available via \`this\`.
+
+\`\`\`ts
+const session = container.entity('session', { userId: '42' })
+  .extend({
+    greet() {
+      return \`Hello user \${this.options.userId}\`
+    },
+    get label() {
+      return \`Session \${this.id} (user \${this.options.userId})\`
+    },
+    bump() {
+      const visits = (this.state.get('visits') ?? 0) + 1
+      this.setState({ visits })
+      this.emit('visited', visits)
+      return visits
+    },
+  })
+
+console.log(session.greet())
+console.log(session.label)
+console.log('visits:', session.bump())
+console.log('visits:', session.bump())
+\`\`\`
+
+Extensions are chained via prototype delegation — each layer can see everything below it.
+
+## Exposing Methods as AI Tools
+
+Use \`.expose(methodName, zodSchema)\` to register methods as tools. \`.toTools()\` returns \`{ schemas, handlers }\` compatible with \`assistant.addTools()\`.
+
+\`\`\`ts
+const search = container.entity('search', {})
+  .extend({
+    async lookup({ query }: { query: string }) {
+      return \`Results for: \${query}\`
+    },
+    async summarize({ text, maxWords }: { text: string; maxWords: number }) {
+      return text.split(' ').slice(0, maxWords).join(' ')
+    },
+  })
+  .expose('lookup', z.object({
+    query: z.string().describe('The search query'),
+  }))
+  .expose('summarize', z.object({
+    text: z.string().describe('Text to summarize'),
+    maxWords: z.number().describe('Maximum words in summary'),
+  }))
+
+const { schemas, handlers } = search.toTools()
+console.log('registered tools:', Object.keys(schemas))
+
+// Pass directly to an assistant
+// assistant.addTools(search)
+\`\`\`
+
+\`.expose()\` is chainable and returns \`this\`, so you can stack as many as you need.
+
+## Summary
+
+Entities give you observable state, a typed event bus, and prototype-safe method extension — all as a plain object with no class overhead. The \`.expose()\` / \`.toTools()\` interface makes it straightforward to surface entity methods as AI tools.
 `,
   "assistant-with-process-manager.md": `---
 title: "Assistant with ProcessManager Tools"

package/src/bus.ts

@@ -1,6 +1,7 @@
 export type EventMap = Record<string, any[]>;
 
 type Listener<Args extends any[] = any[]> = (...args: Args) => void;
+type WildcardListener = (event: string, ...args: any[]) => void;
 
 export interface EventStats {
     event: string;
@@ -12,10 +13,12 @@ export interface EventStats {
 
 export class Bus<T extends EventMap = EventMap> {
     private events: Map<string, Listener[]>;
+    private wildcardListeners: WildcardListener[];
     private stats: Map<string, { fireCount: number; lastFiredAt: number | null; timestamps: number[] }>;
 
     constructor() {
         this.events = new Map();
+        this.wildcardListeners = [];
         this.stats = new Map();
     }
 
@@ -64,12 +67,19 @@ export class Bus<T extends EventMap = EventMap> {
     emit<E extends string & keyof T>(event: E, ...args: T[E]): void {
         this.recordEmit(event);
         const listeners = this.events.get(event);
-        if (!listeners) return;
-
-        listeners.forEach(listener => listener(...args));
+        if (listeners) {
+            listeners.forEach(listener => listener(...args));
+        }
+        this.wildcardListeners.forEach(listener => listener(event, ...args));
     }
 
-    on<E extends string & keyof T>(event: E, listener: (...args: T[E]) => void): void {
+    on(event: '*', listener: WildcardListener): void
+    on<E extends string & keyof T>(event: E, listener: (...args: T[E]) => void): void
+    on<E extends string & keyof T>(event: E | '*', listener: any): void {
+        if (event === '*') {
+            this.wildcardListeners.push(listener);
+            return;
+        }
         const listeners = this.events.get(event) || [];
         listeners.push(listener as Listener);
         this.events.set(event, listeners);
@@ -83,7 +93,19 @@ export class Bus<T extends EventMap = EventMap> {
         this.on(event, onceListener as any);
     }
 
-    off<E extends string & keyof T>(event: E, listener?: (...args: T[E]) => void): void {
+    off(event: '*', listener?: WildcardListener): void
+    off<E extends string & keyof T>(event: E, listener?: (...args: T[E]) => void): void
+    off<E extends string & keyof T>(event: E | '*', listener?: any): void {
+        if (event === '*') {
+            if (!listener) {
+                this.wildcardListeners = [];
+                return;
+            }
+            const index = this.wildcardListeners.indexOf(listener);
+            if (index !== -1) this.wildcardListeners.splice(index, 1);
+            return;
+        }
+
         const listeners = this.events.get(event);
         if (!listeners) return;
 

package/src/cli/build-info.ts

@@ -1,4 +1,4 @@
 // Generated at compile time — do not edit manually
-export const BUILD_SHA = 'e1b45a8'
+export const BUILD_SHA = '2d0d67e'
 export const BUILD_BRANCH = 'main'
-export const BUILD_DATE = '2026-03-30T06:52:57Z'
+export const BUILD_DATE = '2026-04-03T01:24:54Z'

package/src/client.ts

@@ -46,7 +46,7 @@ export class Client<
   static override eventsSchema = ClientEventsSchema
 
   /** Self-register a Client subclass from a static initialization block. */
-  static register: (SubClass: typeof Client, id?: string) => typeof Client
+  static register: (SubClass: abstract new (options: any, context: any) => Client, id?: string) => abstract new (options: any, context: any) => Client
 
   static attach(container: Container & ClientsInterface): any {
     Object.assign(container, {
@@ -141,7 +141,7 @@ export const helperCache = new Map();
  * ```
  */
 Client.register = function registerClient(
-  SubClass: typeof Client,
+  SubClass: abstract new (options: any, context: any) => Client,
   id?: string,
 ) {
   const registryId = id ?? SubClass.name[0]!.toLowerCase() + SubClass.name.slice(1)

package/src/clients/elevenlabs/index.ts

@@ -3,6 +3,7 @@ import { ClientStateSchema, ClientOptionsSchema, ClientEventsSchema } from '@soe
 import { Client } from "@soederpop/luca/client";
 import { RestClient } from "../rest";
 import type { ContainerContext } from "@soederpop/luca/container";
+import type { NodeContainer } from "../../node/container.js";
 import type { AxiosRequestConfig } from 'axios'
 
 declare module "@soederpop/luca/client" {
@@ -92,6 +93,10 @@ export class ElevenLabsClient extends RestClient<ElevenLabsClientState, ElevenLa
     super(options, context)
   }
 
+  override get container(): NodeContainer {
+    return super.container as unknown as NodeContainer
+  }
+
   /** The resolved API key from options or environment. */
   get apiKey(): string {
     return this.options.apiKey || process.env.ELEVENLABS_API_KEY || ''

package/src/commands/bootstrap.ts

@@ -2,6 +2,7 @@ import { z } from 'zod'
 import { commands } from '../command.js'
 import { CommandOptionsSchema } from '../schemas/base.js'
 import type { ContainerContext } from '../container.js'
+import type { NodeContainer } from '../node/container.js'
 import { bootstrapFiles, bootstrapTemplates, bootstrapExamples, bootstrapTutorials } from '../bootstrap/generated.js'
 import { generateScaffold } from '../scaffolds/template.js'
 
@@ -17,7 +18,7 @@ export const argsSchema = CommandOptionsSchema.extend({
 })
 
 async function bootstrap(options: z.infer<typeof argsSchema>, context: ContainerContext) {
-	const { container } = context
+	const container = context.container as unknown as NodeContainer
 	const args = container.argv._ as string[]
 	const fs = container.feature('fs')
 	const ui = container.feature('ui')

package/src/commands/chat.ts

@@ -186,6 +186,7 @@ export default async function chat(options: z.infer<typeof argsSchema>, context:
 		const items = Array.isArray(options.use) ? options.use : [options.use]
 		for (const item of items) {
 			const [namepart, optStr] = item.split(':')
+			if (!namepart) continue
 			const featureOpts: Record<string, any> = { enable: true }
 			if (optStr) {
 				for (const pair of optStr.split(';')) {

package/src/commands/code.ts

@@ -36,7 +36,7 @@ export default async function code(options: z.infer<typeof argsSchema>, context:
 	if (options.prompt) {
 		const resolved = container.paths.resolve(options.prompt)
 		if (fs.exists(resolved)) {
-			systemPrompt = fs.readFile(resolved)
+			systemPrompt = String(fs.readFile(resolved))
 		} else if (!options.prompt.endsWith('.md')) {
 			systemPrompt = options.prompt
 		} else {
@@ -81,6 +81,8 @@ export default async function code(options: z.infer<typeof argsSchema>, context:
 		model: options.model,
 		local: options.local,
 		skills: extraSkills,
+		maxTokens: 2048,
+		autoLoadLucaSkill: true,
 	})
 
 	// ── UI setup ───────────────────────────────────────────────────────────
@@ -319,7 +321,7 @@ export default async function code(options: z.infer<typeof argsSchema>, context:
 
 			const featureContext: Record<string, any> = {}
 			for (const fname of container.features.available) {
-				try { featureContext[fname] = container.feature(fname) } catch {}
+				try { featureContext[fname] = (container as any).feature(fname) } catch {}
 			}
 
 			const replPrompt = ui.colors.magenta('console') + ui.colors.dim(' > ')

package/src/commands/prompt.ts

@@ -257,16 +257,16 @@ async function runParallel(
 
 	function pushLines(idx: number, text: string) {
 		const newLines = text.split('\n')
-		promptStates[idx].lines.push(...newLines)
-		if (promptStates[idx].lines.length > MAX_LINES) {
-			promptStates[idx].lines = promptStates[idx].lines.slice(-MAX_LINES)
+		promptStates[idx]!.lines.push(...newLines)
+		if (promptStates[idx]!.lines.length > MAX_LINES) {
+			promptStates[idx]!.lines = promptStates[idx]!.lines.slice(-MAX_LINES)
 		}
 	}
 
 	function pushToolLine(idx: number, text: string) {
-		promptStates[idx].lines.push(text)
-		if (promptStates[idx].lines.length > MAX_LINES) {
-			promptStates[idx].lines.splice(0, 1)
+		promptStates[idx]!.lines.push(text)
+		if (promptStates[idx]!.lines.length > MAX_LINES) {
+			promptStates[idx]!.lines.splice(0, 1)
 		}
 	}
 
@@ -304,7 +304,7 @@ async function runParallel(
 			if (!Array.isArray(content)) return
 
 			const usage = message?.message?.usage ?? message?.usage
-			if (usage?.output_tokens) promptStates[idx].outputTokens += usage.output_tokens
+			if (usage?.output_tokens) promptStates[idx]!.outputTokens += usage.output_tokens
 
 			for (const block of content) {
 				if (block.type === 'text' && block.text) {
@@ -321,33 +321,33 @@ async function runParallel(
 				const idx = sessionMap.get(sessionId)
 				if (idx === undefined) return
 				if (event.type === 'assistant' || event.type === 'tool_result' || event.type === 'message' || event.type === 'function_call_output') {
-					promptStates[idx].collectedEvents.push(event)
+					promptStates[idx]!.collectedEvents.push(event)
 				}
 			})
 		}
 
 		// Start all sessions — merge per-prompt agentOptions with shared runOptions
 		for (let i = 0; i < prepared.length; i++) {
-			const perPromptOptions = { ...prepared[i].agentOptions, ...runOptions }
+			const perPromptOptions = { ...prepared[i]!.agentOptions, ...runOptions }
 			if (options.model) perPromptOptions.model = options.model
-			const id = await feature.start(prepared[i].promptContent, perPromptOptions)
+			const id = await feature.start(prepared[i]!.promptContent, perPromptOptions)
 			sessionMap.set(id, i)
 		}
 
 		const ids = [...sessionMap.keys()]
 		sessionPromise = Promise.allSettled(ids.map((id) => feature.waitForSession(id))).then((results) => {
 			results.forEach((r, ri) => {
-				const id = ids[ri]
+				const id = ids[ri]!
 				const idx = sessionMap.get(id)!
-				promptStates[idx].durationMs = Date.now() - promptStates[idx].startTime
+				promptStates[idx]!.durationMs = Date.now() - promptStates[idx]!.startTime
 				if (r.status === 'fulfilled' && r.value?.status === 'error') {
-					promptStates[idx].status = 'error'
-					promptStates[idx].error = r.value?.error || 'Session failed'
+					promptStates[idx]!.status = 'error'
+					promptStates[idx]!.error = r.value?.error || 'Session failed'
 				} else if (r.status === 'rejected') {
-					promptStates[idx].status = 'error'
-					promptStates[idx].error = String(r.reason)
+					promptStates[idx]!.status = 'error'
+					promptStates[idx]!.error = String(r.reason)
 				} else {
-					promptStates[idx].status = 'done'
+					promptStates[idx]!.status = 'done'
 				}
 			})
 			allDone = true
@@ -375,16 +375,16 @@ async function runParallel(
 
 			assistant.on('chunk', (text: string) => {
 				lineBuffers[i] += text
-				const parts = lineBuffers[i].split('\n')
+				const parts = lineBuffers[i]!.split('\n')
 				lineBuffers[i] = parts.pop() || ''
 				if (parts.length) {
-					promptStates[i].lines.push(...parts)
-					if (promptStates[i].lines.length > MAX_LINES) {
-						promptStates[i].lines = promptStates[i].lines.slice(-MAX_LINES)
+					promptStates[i]!.lines.push(...parts)
+					if (promptStates[i]!.lines.length > MAX_LINES) {
+						promptStates[i]!.lines = promptStates[i]!.lines.slice(-MAX_LINES)
 					}
 				}
 				if (options['out-file']) {
-					promptStates[i].collectedEvents.push({ type: 'assistant', message: { content: [{ type: 'text', text }] } })
+					promptStates[i]!.collectedEvents.push({ type: 'assistant', message: { content: [{ type: 'text', text }] } })
 				}
 			})
 
@@ -392,7 +392,7 @@ async function runParallel(
 				const argsStr = JSON.stringify(args).slice(0, 80)
 				pushToolLine(i, `  > ${toolName}(${argsStr})`)
 				if (options['out-file']) {
-					promptStates[i].collectedEvents.push({
+					promptStates[i]!.collectedEvents.push({
 						type: 'assistant',
 						message: { content: [{ type: 'tool_use', name: toolName, input: args }] },
 					})
@@ -403,7 +403,7 @@ async function runParallel(
 				const preview = typeof result === 'string' ? result.slice(0, 60) : JSON.stringify(result).slice(0, 60)
 				pushToolLine(i, `  ✓ ${toolName} → ${preview}`)
 				if (options['out-file']) {
-					promptStates[i].collectedEvents.push({
+					promptStates[i]!.collectedEvents.push({
 						type: 'tool_result',
 						content: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
 					})
@@ -418,20 +418,20 @@ async function runParallel(
 			return assistant
 		})
 
-		sessionPromise = Promise.allSettled(assistants.map((a, i) => a.ask(prepared[i].promptContent))).then(
+		sessionPromise = Promise.allSettled(assistants.map((a, i) => a.ask(prepared[i]!.promptContent))).then(
 			(results) => {
 				results.forEach((r, i) => {
-					promptStates[i].durationMs = Date.now() - promptStates[i].startTime
+					promptStates[i]!.durationMs = Date.now() - promptStates[i]!.startTime
 					// Flush remaining line buffer
 					if (lineBuffers[i]) {
-						promptStates[i].lines.push(lineBuffers[i])
+						promptStates[i]!.lines.push(lineBuffers[i]!)
 						lineBuffers[i] = ''
 					}
 					if (r.status === 'rejected') {
-						promptStates[i].status = 'error'
-						promptStates[i].error = String(r.reason)
+						promptStates[i]!.status = 'error'
+						promptStates[i]!.error = String(r.reason)
 					} else {
-						promptStates[i].status = 'done'
+						promptStates[i]!.status = 'done'
 					}
 				})
 				allDone = true
@@ -551,9 +551,9 @@ async function runParallel(
 		const stem = dotIdx > 0 ? base.slice(0, dotIdx) : base
 
 		for (let i = 0; i < promptStates.length; i++) {
-			const ps = promptStates[i]
+			const ps = promptStates[i]!
 			if (!ps.collectedEvents.length) continue
-			const promptBasename = paths.basename(prepared[i].resolvedPath)
+			const promptBasename = paths.basename(prepared[i]!.resolvedPath)
 			const promptStem = promptBasename.lastIndexOf('.') > 0 ? promptBasename.slice(0, promptBasename.lastIndexOf('.')) : promptBasename
 			const outPath = paths.resolve(`${stem}-${promptStem}${ext}`)
 			const markdown = formatSessionMarkdown(ps.collectedEvents, options['include-output'])
@@ -655,7 +655,7 @@ async function resolveInputs(
 
 	// Build wizard questions for missing inputs
 	const questions = missing.map((key) => {
-		const def = inputDefs[key]
+		const def = inputDefs[key]!
 		const q: Record<string, any> = {
 			name: key,
 			message: def.description || key,
@@ -920,7 +920,7 @@ export default async function prompt(options: z.infer<typeof argsSchema>, contex
 	}
 
 	// --- Single prompt mode ---
-	const promptPath = allPaths[0]
+	const promptPath = allPaths[0]!
 	const p = await preparePrompt(promptPath, options, container)
 
 	if (!p) {