@soederpop/luca 0.0.30 → 0.0.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soederpop/luca",
-  "version": "0.0.30",
+  "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/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'),
 })
 
@@ -461,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 }
 
@@ -504,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
 				}
 			}
@@ -936,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
 	}
 
 	/**

package/src/bootstrap/generated.ts

@@ -1,5 +1,5 @@
 // Auto-generated bootstrap content
-// Generated at: 2026-03-24T06:38:37.146Z
+// Generated at: 2026-03-24T09:08:07.564Z
 // Source: docs/bootstrap/*.md, docs/bootstrap/templates/*, docs/examples/*.md, docs/tutorials/*.md
 //
 // Do not edit manually. Run: luca build-bootstrap

package/src/cli/build-info.ts

@@ -1,4 +1,4 @@
 // Generated at compile time — do not edit manually
-export const BUILD_SHA = 'd0653ac'
+export const BUILD_SHA = 'ff23ed7'
 export const BUILD_BRANCH = 'main'
-export const BUILD_DATE = '2026-03-24T06:38:37Z'
+export const BUILD_DATE = '2026-03-24T09:08:07Z'

package/src/command.ts

@@ -109,7 +109,26 @@ export class Command<
 		const named = this._normalizeInput(raw, dispatchSource)
 
 		// Validate against argsSchema
-		const parsed = Cls.argsSchema.parse(named)
+		let parsed: any
+		try {
+			parsed = Cls.argsSchema.parse(named)
+		} catch (err: any) {
+			if (err?.name === 'ZodError' && dispatchSource === 'cli') {
+				const ui = (this.container as any).feature('ui')
+				const cmdName = Cls.shortcut?.replace('commands.', '') || 'unknown'
+				const issues = err.issues || []
+
+				ui.print.red(`\n  Error: Invalid options for "${cmdName}"\n`)
+				for (const issue of issues) {
+					const path = issue.path?.length ? issue.path.join('.') : 'input'
+					ui.print(`  ${ui.colors.yellow('→')} ${ui.colors.bold(path)}: ${issue.message}`)
+				}
+				ui.print('')
+				ui.print.dim(`  Run ${ui.colors.cyan(`luca ${cmdName} --help`)} for usage info.\n`)
+				process.exit(1)
+			}
+			throw err
+		}
 
 		// For headless dispatch, capture stdout/stderr
 		if (dispatchSource !== 'cli') {

package/src/commands/serve.ts

@@ -19,6 +19,7 @@ export const argsSchema = CommandOptionsSchema.extend({
 	force: z.boolean().default(false).describe('Kill any process currently using the target port'),
 	anyPort: z.boolean().default(false).describe('Find an available port starting above 3000'),
 	open: z.boolean().default(true).describe('Open the server URL in Google Chrome'),
+	watch: z.boolean().default(false).describe('Watch endpoint files and hot-reload handlers on change'),
 })
 
 export default async function serve(options: z.infer<typeof argsSchema>, context: ContainerContext) {
@@ -157,6 +158,32 @@ export default async function serve(options: z.infer<typeof argsSchema>, context
 		}
 	}
 
+	if (options.watch && endpointsDir) {
+		const fm = container.feature('fileManager')
+		await fm.watch({ paths: [endpointsDir] })
+
+		fm.on('file:change', async ({ type, path: filePath }: { type: string; path: string }) => {
+			if (!filePath.endsWith('.ts')) return
+
+			if (type === 'change') {
+				try {
+					const ep = await expressServer.reloadEndpoint(filePath)
+					if (ep) {
+						console.log(`[watch] Reloaded ${ep.methods.map((m: string) => m.toUpperCase()).join(',')} ${ep.path}`)
+					}
+				} catch (err: any) {
+					console.error(`[watch] Failed to reload ${filePath}: ${err.message}`)
+				}
+			} else if (type === 'add') {
+				console.log(`[watch] New file detected: ${filePath} (restart to mount)`)
+			} else if (type === 'delete') {
+				console.log(`[watch] File deleted: ${filePath} (restart to unmount)`)
+			}
+		})
+
+		console.log(`\n[watch] Watching ${endpointsDir} for changes`)
+	}
+
 	console.log()
 }
 

package/src/endpoint.ts

@@ -197,6 +197,12 @@ export class Endpoint<
 
   async reload(): Promise<this> {
     this._module = null
+    if (this.options.filePath) {
+      const helpers = this.container.feature('helpers') as any
+      const mod = await helpers.loadModuleExports(this.options.filePath, { cacheBust: true })
+      const endpointModule: EndpointModule = mod.default || mod
+      return this.load(endpointModule)
+    }
     return this.load()
   }
 

package/src/helper.ts

@@ -704,16 +704,42 @@ function presentIntrospectionAsTypeScript(introspection: HelperIntrospection, se
     }
   }
 
-  // State
+  // State — render as the observable State<T> object, not just currentState
   if (shouldRender('state') && introspection.state && Object.keys(introspection.state).length > 0) {
     if (members.length > 0) members.push('')
     const stateMembers = Object.entries(introspection.state)
       .map(([name, info]) => {
-        const comment = info.description ? `    /** ${info.description} */\n` : ''
-        return `${comment}    ${name}: ${normalizeTypeString(info.type || 'any')};`
+        const comment = info.description ? `      /** ${info.description} */\n` : ''
+        return `${comment}      ${name}: ${normalizeTypeString(info.type || 'any')};`
       })
       .join('\n')
-    members.push(`  state: {\n${stateMembers}\n  };`)
+    const stateShape = `{\n${stateMembers}\n    }`
+    members.push(`  state: {`)
+    members.push(`    /** The current version number, incremented on each change */`)
+    members.push(`    readonly version: number;`)
+    members.push(`    /** Get the value of a state key */`)
+    members.push(`    get<K extends keyof T>(key: K): T[K] | undefined;`)
+    members.push(`    /** Set a state key to a new value, notifying observers */`)
+    members.push(`    set<K extends keyof T>(key: K, value: T[K]): this;`)
+    members.push(`    /** Delete a state key, notifying observers */`)
+    members.push(`    delete<K extends keyof T>(key: K): this;`)
+    members.push(`    /** Check if a state key exists */`)
+    members.push(`    has<K extends keyof T>(key: K): boolean;`)
+    members.push(`    /** Get all state keys */`)
+    members.push(`    keys(): string[];`)
+    members.push(`    /** Get the current state snapshot */`)
+    members.push(`    readonly current: ${stateShape};`)
+    members.push(`    /** Get all entries as [key, value] pairs */`)
+    members.push(`    entries(): [string, any][];`)
+    members.push(`    /** Get all state values */`)
+    members.push(`    values(): any[];`)
+    members.push(`    /** Register an observer callback for state changes. Returns an unsubscribe function. */`)
+    members.push(`    observe(callback: (changeType: 'add' | 'update' | 'delete', key: string, value?: any) => void): () => void;`)
+    members.push(`    /** Merge partial state, notifying observers for each changed key */`)
+    members.push(`    setState(value: Partial<${stateShape}> | ((current: ${stateShape}, state: this) => Partial<${stateShape}>)): void;`)
+    members.push(`    /** Clear all state, notifying observers */`)
+    members.push(`    clear(): void;`)
+    members.push(`  };`)
   }
 
   // Options
@@ -804,5 +830,16 @@ function isGenericObjectType(type: string): boolean {
 function normalizeTypeString(type: string): string {
   if (!type) return 'any'
   // The AST scanner sometimes wraps types in quotes
-  return type.replace(/^["']|["']$/g, '')
+  type = type.replace(/^["']|["']$/g, '')
+  // Convert internal ReturnType<typeof this.container.feature<'name'>> to a clean import reference
+  // e.g. ReturnType<typeof this.container.feature<'proc'>> → import('luca').Proc
+  type = type.replace(
+    /ReturnType<typeof this\.container\.(feature|client|server)<'([^']+)'>>/g,
+    (_match, _kind, name) => {
+      // Convert shortcut name to PascalCase class name
+      const className = name.replace(/(^|[-_])(\w)/g, (_: string, _sep: string, ch: string) => ch.toUpperCase())
+      return `import('@soederpop/luca').${className}`
+    }
+  )
+  return type
 }