@soederpop/luca 0.0.30 → 0.0.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soederpop/luca",
-  "version": "0.0.30",
+  "version": "0.0.32",
   "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,69 @@ 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() {
+		if (!this._boundHookListeners) return
+		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:09:11.574Z
 // 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
 }

package/src/introspection/generated.agi.ts

@@ -1,7 +1,7 @@
 import { setBuildTimeData, setContainerBuildTimeData } from './index.js';
 
 // Auto-generated introspection registry data
-// Generated at: 2026-03-24T06:38:35.595Z
+// Generated at: 2026-03-24T09:09:09.989Z
 
 setBuildTimeData('features.googleDocs', {
   "id": "features.googleDocs",
@@ -10426,6 +10426,16 @@ setBuildTimeData('features.helpers', {
         "absPath": {
           "type": "string",
           "description": "Absolute path to the module file"
+        },
+        "options": {
+          "type": "{ cacheBust?: boolean }",
+          "description": "Optional settings",
+          "properties": {
+            "cacheBust": {
+              "type": "any",
+              "description": "When true, appends a timestamp query to bypass the native import cache (useful for hot reload)"
+            }
+          }
         }
       },
       "required": [
@@ -12749,6 +12759,19 @@ setBuildTimeData('servers.express', {
       ],
       "returns": "Promise<this>"
     },
+    "reloadEndpoint": {
+      "description": "Reload a mounted endpoint by its file path. Re-reads the module through the helpers VM loader so the next request picks up the new handlers.",
+      "parameters": {
+        "filePath": {
+          "type": "string",
+          "description": "Absolute path to the endpoint file"
+        }
+      },
+      "required": [
+        "filePath"
+      ],
+      "returns": "Promise<Endpoint | null>"
+    },
     "useEndpointModules": {
       "description": "",
       "parameters": {
@@ -14941,6 +14964,12 @@ setBuildTimeData('features.assistant', {
       "required": [],
       "returns": "Promise<number>"
     },
+    "reload": {
+      "description": "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.",
+      "parameters": {},
+      "required": [],
+      "returns": "this"
+    },
     "start": {
       "description": "Start the assistant by creating the conversation and wiring up events. The system prompt, tools, and hooks are already loaded synchronously during initialization.",
       "parameters": {},
@@ -15128,6 +15157,11 @@ setBuildTimeData('features.assistant', {
       "description": "Event emitted by Assistant",
       "arguments": {}
     },
+    "reloaded": {
+      "name": "reloaded",
+      "description": "Event emitted by Assistant",
+      "arguments": {}
+    },
     "turnStart": {
       "name": "turnStart",
       "description": "Event emitted by Assistant",
@@ -27880,6 +27914,16 @@ export const introspectionData = [
           "absPath": {
             "type": "string",
             "description": "Absolute path to the module file"
+          },
+          "options": {
+            "type": "{ cacheBust?: boolean }",
+            "description": "Optional settings",
+            "properties": {
+              "cacheBust": {
+                "type": "any",
+                "description": "When true, appends a timestamp query to bypass the native import cache (useful for hot reload)"
+              }
+            }
           }
         },
         "required": [
@@ -30192,6 +30236,19 @@ export const introspectionData = [
         ],
         "returns": "Promise<this>"
       },
+      "reloadEndpoint": {
+        "description": "Reload a mounted endpoint by its file path. Re-reads the module through the helpers VM loader so the next request picks up the new handlers.",
+        "parameters": {
+          "filePath": {
+            "type": "string",
+            "description": "Absolute path to the endpoint file"
+          }
+        },
+        "required": [
+          "filePath"
+        ],
+        "returns": "Promise<Endpoint | null>"
+      },
       "useEndpointModules": {
         "description": "",
         "parameters": {
@@ -32376,6 +32433,12 @@ export const introspectionData = [
         "required": [],
         "returns": "Promise<number>"
       },
+      "reload": {
+        "description": "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.",
+        "parameters": {},
+        "required": [],
+        "returns": "this"
+      },
       "start": {
         "description": "Start the assistant by creating the conversation and wiring up events. The system prompt, tools, and hooks are already loaded synchronously during initialization.",
         "parameters": {},
@@ -32563,6 +32626,11 @@ export const introspectionData = [
         "description": "Event emitted by Assistant",
         "arguments": {}
       },
+      "reloaded": {
+        "name": "reloaded",
+        "description": "Event emitted by Assistant",
+        "arguments": {}
+      },
       "turnStart": {
         "name": "turnStart",
         "description": "Event emitted by Assistant",

package/src/introspection/generated.node.ts

@@ -1,7 +1,7 @@
 import { setBuildTimeData, setContainerBuildTimeData } from './index.js';
 
 // Auto-generated introspection registry data
-// Generated at: 2026-03-24T06:38:35.496Z
+// Generated at: 2026-03-24T09:09:09.885Z
 
 setBuildTimeData('features.googleDocs', {
   "id": "features.googleDocs",
@@ -10426,6 +10426,16 @@ setBuildTimeData('features.helpers', {
         "absPath": {
           "type": "string",
           "description": "Absolute path to the module file"
+        },
+        "options": {
+          "type": "{ cacheBust?: boolean }",
+          "description": "Optional settings",
+          "properties": {
+            "cacheBust": {
+              "type": "any",
+              "description": "When true, appends a timestamp query to bypass the native import cache (useful for hot reload)"
+            }
+          }
         }
       },
       "required": [
@@ -12749,6 +12759,19 @@ setBuildTimeData('servers.express', {
       ],
       "returns": "Promise<this>"
     },
+    "reloadEndpoint": {
+      "description": "Reload a mounted endpoint by its file path. Re-reads the module through the helpers VM loader so the next request picks up the new handlers.",
+      "parameters": {
+        "filePath": {
+          "type": "string",
+          "description": "Absolute path to the endpoint file"
+        }
+      },
+      "required": [
+        "filePath"
+      ],
+      "returns": "Promise<Endpoint | null>"
+    },
     "useEndpointModules": {
       "description": "",
       "parameters": {
@@ -23768,6 +23791,16 @@ export const introspectionData = [
           "absPath": {
             "type": "string",
             "description": "Absolute path to the module file"
+          },
+          "options": {
+            "type": "{ cacheBust?: boolean }",
+            "description": "Optional settings",
+            "properties": {
+              "cacheBust": {
+                "type": "any",
+                "description": "When true, appends a timestamp query to bypass the native import cache (useful for hot reload)"
+              }
+            }
           }
         },
         "required": [
@@ -26080,6 +26113,19 @@ export const introspectionData = [
         ],
         "returns": "Promise<this>"
       },
+      "reloadEndpoint": {
+        "description": "Reload a mounted endpoint by its file path. Re-reads the module through the helpers VM loader so the next request picks up the new handlers.",
+        "parameters": {
+          "filePath": {
+            "type": "string",
+            "description": "Absolute path to the endpoint file"
+          }
+        },
+        "required": [
+          "filePath"
+        ],
+        "returns": "Promise<Endpoint | null>"
+      },
       "useEndpointModules": {
         "description": "",
         "parameters": {

package/src/introspection/generated.web.ts

@@ -1,7 +1,7 @@
 import { setBuildTimeData, setContainerBuildTimeData } from './index.js';
 
 // Auto-generated introspection registry data
-// Generated at: 2026-03-24T06:38:35.508Z
+// Generated at: 2026-03-24T09:09:09.897Z
 
 setBuildTimeData('features.containerLink', {
   "id": "features.containerLink",

package/src/node/features/helpers.ts

@@ -408,11 +408,14 @@ export class Helpers extends Feature<HelpersState, HelpersOptions> {
    * Uses the same `useNativeImport` check as discovery to decide the loading strategy.
    *
    * @param absPath - Absolute path to the module file
+   * @param options - Optional settings
+   * @param options.cacheBust - When true, appends a timestamp query to bypass the native import cache (useful for hot reload)
    * @returns The module's exports
    */
-  async loadModuleExports(absPath: string): Promise<Record<string, any>> {
+  async loadModuleExports(absPath: string, options?: { cacheBust?: boolean }): Promise<Record<string, any>> {
     if (this.useNativeImport) {
-      const mod = await import(absPath)
+      const importPath = options?.cacheBust ? `${absPath}?t=${Date.now()}` : absPath
+      const mod = await import(importPath)
       return mod
     }
 

package/src/scaffolds/generated.ts

@@ -1,5 +1,5 @@
 // Auto-generated scaffold and MCP readme content
-// Generated at: 2026-03-24T06:38:36.374Z
+// Generated at: 2026-03-24T09:09:10.786Z
 // Source: docs/scaffolds/*.md, docs/examples/assistant/, and docs/mcp/readme.md
 //
 // Do not edit manually. Run: luca build-scaffolds

package/src/servers/express.ts

@@ -211,6 +211,24 @@ export class ExpressServer<T extends ServerState = ServerState, K extends Expres
       return this
     }
 
+    /**
+     * Reload a mounted endpoint by its file path. Re-reads the module through
+     * the helpers VM loader so the next request picks up the new handlers.
+     *
+     * @param filePath - Absolute path to the endpoint file
+     * @returns The reloaded Endpoint, or null if no mounted endpoint matches
+     */
+    async reloadEndpoint(filePath: string): Promise<Endpoint | null> {
+      const endpoint = this._mountedEndpoints.find(ep => (ep.options as any).filePath === filePath)
+      if (!endpoint) return null
+
+      const helpers = this.container.feature('helpers') as any
+      const mod = await helpers.loadModuleExports(filePath, { cacheBust: true })
+      const endpointModule: EndpointModule = mod.default || mod
+      await endpoint.load(endpointModule)
+      return endpoint
+    }
+
     async useEndpointModules(modules: EndpointModule[]): Promise<this> {
       for (const mod of modules) {
         try {