@soederpop/luca 0.0.23 → 0.0.25

package/src/agi/features/assistant.ts

@@ -38,15 +38,26 @@ export const AssistantStateSchema = FeatureStateSchema.extend({
 	docsFolder: z.string().describe('The resolved docs folder'),
 	conversationId: z.string().optional().describe('The active conversation persistence ID'),
 	threadId: z.string().optional().describe('The active thread ID'),
+	systemPrompt: z.string().describe('The loaded system prompt text'),
+	meta: z.record(z.string(), z.any()).describe('Parsed YAML frontmatter from CORE.md'),
+	tools: z.record(z.string(), z.any()).describe('Registered tool implementations'),
+	hooks: z.record(z.string(), z.any()).describe('Loaded event hook functions'),
+	resumeThreadId: z.string().optional().describe('Thread ID override for resume'),
+	pendingPlugins: z.array(z.any()).describe('Pending async plugin promises'),
+	conversation: z.any().nullable().describe('The active Conversation feature instance'),
+	subagents: z.record(z.string(), z.any()).describe('Cached subagent instances'),
 })
 
 export const AssistantOptionsSchema = FeatureOptionsSchema.extend({
-	/** The folder containing the assistant definition (CORE.md, tools.ts, hooks.ts) */
-	folder: z.string().describe('The folder containing the assistant definition'),
+	/** The folder containing the assistant definition (CORE.md, tools.ts, hooks.ts). Optional for runtime-created assistants. */
+	folder: z.string().default('.').describe('The folder containing the assistant definition. Defaults to cwd for runtime-created assistants.'),
 
 	/** If the docs folder is different from folder/docs */
 	docsFolder: z.string().optional().describe('The folder containing the assistant documentation'),
 
+	/** Provide a complete system prompt directly, bypassing CORE.md. Useful for runtime-created assistants. */
+	systemPrompt: z.string().optional().describe('Provide a complete system prompt directly, bypassing CORE.md'),
+
 	/** Text to prepend to the system prompt from CORE.md */
 	prependPrompt: z.string().optional().describe('Text to prepend to the system prompt'),
 
@@ -108,6 +119,14 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 			conversationCount: 0,
 			lastResponse: '',
 			folder: this.resolvedFolder,
+			systemPrompt: '',
+			meta: {},
+			tools: {},
+			hooks: {},
+			resumeThreadId: undefined,
+			pendingPlugins: [],
+			conversation: null,
+			subagents: {},
 		}
 	}
 
@@ -177,15 +196,6 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 		return this.container.feature('contentDb', { rootPath: this.resolvedDocsFolder })
 	}
 
-	private _conversation?: Conversation
-	private _resumeThreadId?: string
-
-	// Using `declare` to prevent class field initializers from overwriting
-	// values set during afterInitialize() (called from the base constructor).
-	declare private _tools: Record<string, ConversationTool>
-	declare private _hooks: Record<string, (...args: any[]) => any>
-	declare private _systemPrompt: string
-	declare private _pendingPlugins: Promise<void>[]
 
 	/**
 	 * Called immediately after the assistant is constructed. Synchronously loads
@@ -193,14 +203,14 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 	 * so every emitted event automatically invokes its corresponding hook.
 	 */
 	override afterInitialize() {
-		this._pendingPlugins = []
+		this.state.set('pendingPlugins', [])
 
 		// Load system prompt synchronously
-		this._systemPrompt = this.loadSystemPrompt()
+		this.state.set('systemPrompt', this.loadSystemPrompt())
 
 		// Load tools and hooks synchronously via vm.performSync
-		this._tools = this.loadTools()
-		this._hooks = this.loadHooks()
+		this.state.set('tools', this.loadTools())
+		this.state.set('hooks', this.loadHooks())
 
 		// Bind hooks to events BEFORE emitting created so the created hook fires
 		this.bindHooksToEvents()
@@ -209,18 +219,25 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 	}
 
 	get conversation(): Conversation {
-		if (!this._conversation) {
-			this._conversation = this.container.feature('conversation', {
-				model: this.options.model || 'gpt-5.2',
+		let conv = this.state.get('conversation') as Conversation | null
+		if (!conv) {
+			conv = this.container.feature('conversation', {
+				model: this.options.model || 'gpt-5.4',
 				local: !!this.options.local,
-				tools: this._tools || this.loadTools(),
+				tools: this.tools,
+				api: 'chat',
 				...(this.options.maxTokens ? { maxTokens: this.options.maxTokens } : {}),
 				history: [
-					{ role: 'system', content: this._systemPrompt || this.loadSystemPrompt() },
+					{ role: 'system', content: this.systemPrompt || this.loadSystemPrompt() },
 				],
 			})
+			this.state.set('conversation', conv)
 		}
-		return this._conversation
+		return conv
+	}
+
+	get availableTools() {
+		return Object.keys(this.tools)
 	}
 
 	get messages() {
@@ -234,32 +251,51 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 
 	/** The current system prompt text. */
 	get systemPrompt(): string {
-		return this._systemPrompt
+		return this.state.get('systemPrompt') || ''
 	}
 
 	/** The tools registered with this assistant. */
 	get tools(): Record<string, ConversationTool> {
-		return this._tools
+		return (this.state.get('tools') || {}) as Record<string, ConversationTool>
 	}
 
 	/**
-	 * Apply a setup function to this assistant. The function receives the
-	 * assistant instance and can configure tools, hooks, event listeners, etc.
+	 * Apply a setup function or a Helper instance to this assistant.
 	 *
-	 * @param fn - Setup function that receives this assistant
+	 * When passed a function, it receives the assistant and can configure
+	 * tools, hooks, event listeners, etc.
+	 *
+	 * When passed a Helper instance that exposes tools via toTools(),
+	 * those tools are automatically added to this assistant.
+	 *
+	 * @param fnOrHelper - Setup function or Helper instance
 	 * @returns this, for chaining
 	 *
 	 * @example
 	 * ```typescript
 	 * assistant
 	 *   .use(setupLogging)
-	 *   .use(addAnalyticsTools)
+	 *   .use(container.feature('git'))
 	 * ```
 	 */
-	use(fn: (assistant: this) => void | Promise<void>): this {
-		const result = fn(this)
-		if (result && typeof (result as any).then === 'function') {
-			this._pendingPlugins.push(result as Promise<void>)
+	use(fnOrHelper: ((assistant: this) => void | Promise<void>) | { toTools: () => { schemas: Record<string, z.ZodType>, handlers: Record<string, Function> } }): this {
+		if (typeof fnOrHelper === 'function') {
+			const result = fnOrHelper(this)
+			if (result && typeof (result as any).then === 'function') {
+				const pending = this.state.get('pendingPlugins') as Promise<void>[]
+				this.state.set('pendingPlugins', [...pending, result as Promise<void>])
+			}
+		} else if (fnOrHelper && typeof fnOrHelper.toTools === 'function') {
+			const { schemas, handlers } = fnOrHelper.toTools()
+			for (const name of Object.keys(schemas)) {
+				if(typeof handlers[name] === 'function') {
+					this.addTool(
+						name,
+						handlers[name] as any,
+						schemas[name],
+					)
+				}
+			}
 		}
 		return this
 	}
@@ -279,29 +315,37 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 	 * }, z.object({ city: z.string() }).describe('Get weather for a city'))
 	 * ```
 	 */
-	addTool(handler: (...args: any[]) => any, schema?: z.ZodType): this {
-		const name = handler.name
+	addTool(name: string, handler: (...args: any[]) => any, schema?: z.ZodType): this {
 		if (!name) throw new Error('addTool handler must be a named function')
 
+		const current = { ...this.tools }
+
 		if (schema) {
 			const jsonSchema = (schema as any).toJSONSchema() as Record<string, any>
-			this._tools[name] = {
+			// OpenAI requires `required` to list ALL property keys — optional params
+			// must still appear in `required` but use a default value in the schema.
+			const properties = jsonSchema.properties || {}
+			const required = Object.keys(properties)
+			current[name] = {
 				handler: handler as ConversationTool['handler'],
 				description: jsonSchema.description || name,
 				parameters: {
 					type: jsonSchema.type || 'object',
-					properties: jsonSchema.properties || {},
-					...(jsonSchema.required ? { required: jsonSchema.required } : {}),
+					properties,
+					required,
 				},
 			}
 		} else {
-			this._tools[name] = {
+			current[name] = {
 				handler: handler as ConversationTool['handler'],
 				description: name,
 				parameters: { type: 'object', properties: {} },
 			}
 		}
 
+		this.state.set('tools', current)
+		this.emit('toolsChanged')
+
 		return this
 	}
 
@@ -312,17 +356,22 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 	 * @returns this, for chaining
 	 */
 	removeTool(nameOrHandler: string | ((...args: any[]) => any)): this {
+		const current = { ...this.tools }
+
 		if (typeof nameOrHandler === 'string') {
-			delete this._tools[nameOrHandler]
+			delete current[nameOrHandler]
 		} else {
-			for (const [name, tool] of Object.entries(this._tools)) {
+			for (const [name, tool] of Object.entries(current)) {
 				if (tool.handler === nameOrHandler) {
-					delete this._tools[name]
+					delete current[name]
 					break
 				}
 			}
 		}
 
+		this.state.set('tools', current)
+		this.emit('toolsChanged')
+
 		return this
 	}
 
@@ -384,17 +433,38 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 		return this
 	}
 
+	/**
+	 * Parsed YAML frontmatter from CORE.md, or empty object if none.
+	 */
+	get meta(): Record<string, any> {
+		return (this.state.get('meta') || {}) as Record<string, any>
+	}
+
 	/**
 	 * Load the system prompt from CORE.md, applying any prepend/append options.
+	 * YAML frontmatter (between --- fences) is stripped from the prompt and
+	 * stored in `_meta`.
 	 *
 	 * @returns {string} The assembled system prompt
 	 */
 	loadSystemPrompt(): string {
 		const { fs } = this.container
 		let prompt = ''
-
-		if (fs.exists(this.corePromptPath)) {
-			prompt = fs.readFile(this.corePromptPath)
+		this.state.set('meta', {})
+
+		if (this.options.systemPrompt) {
+			prompt = this.options.systemPrompt
+		} else if (fs.exists(this.corePromptPath)) {
+			const raw = fs.readFile(this.corePromptPath).toString()
+			const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/)
+
+			if (fmMatch) {
+				const yaml = this.container.feature('yaml')
+				this.state.set('meta', yaml.parse(fmMatch[1]!) ?? {})
+				prompt = raw.slice(fmMatch[0].length)
+			} else {
+				prompt = raw
+			}
 		}
 
 		if (this.options.prependPrompt) {
@@ -426,6 +496,19 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 	 */
 	loadTools(): Record<string, ConversationTool> {
 		const tools: Record<string, ConversationTool> = {}
+
+		// Skip loading if no tools file exists (runtime-created assistants)
+		if (!this.container.fs.exists(this.toolsModulePath)) {
+			return this.mergeOptionTools(tools)
+		}
+
+		// Ensure virtual modules (zod, @soederpop/luca, etc.) are seeded so tools
+		// files outside the project tree can resolve them through the VM
+		if (this.container.features.has('helpers')) {
+			const helpers = this.container.feature('helpers') as any
+			helpers.seedVirtualModules()
+		}
+
 		const vm = this.container.feature('vm')
 
 		let moduleExports: Record<string, any>
@@ -441,7 +524,7 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 			console.error(`Failed to load tools from ${this.toolsModulePath}`)
 			console.error(`There may be a syntax error in this file. Please check it.`)
 			console.error(err.message || err)
-			return tools
+			return this.mergeOptionTools(tools)
 		}
 
 		if (Object.keys(moduleExports).length) {
@@ -472,7 +555,14 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 			}
 		}
 
-		// Merge in option-provided tools and schemas
+		return this.mergeOptionTools(tools)
+	}
+
+	/**
+	 * Merge tools provided via constructor options into the tool map.
+	 * This allows runtime-created assistants to define tools entirely via options.
+	 */
+	private mergeOptionTools(tools: Record<string, ConversationTool>): Record<string, ConversationTool> {
 		if (this.options.tools) {
 			const optionSchemas = this.options.schemas || {}
 
@@ -513,6 +603,12 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 	 */
 	loadHooks(): Record<string, (...args: any[]) => any> {
 		const hooks: Record<string, (...args: any[]) => any> = {}
+
+		// Skip loading if no hooks file exists (runtime-created assistants)
+		if (!this.container.fs.exists(this.hooksModulePath)) {
+			return hooks
+		}
+
 		const vm = this.container.feature('vm')
 
 		let moduleExports: Record<string, any>
@@ -626,7 +722,7 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 	 * @returns this, for chaining
 	 */
 	resumeThread(threadId: string): this {
-		this._resumeThreadId = threadId
+		this.state.set('resumeThreadId', threadId)
 		return this
 	}
 
@@ -659,7 +755,7 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 		const mode = this.options.historyMode || 'lifecycle'
 		if (mode === 'lifecycle') return
 
-		const threadId = this._resumeThreadId || this.buildThreadId(mode)
+		const threadId = (this.state.get('resumeThreadId') as string | undefined) || this.buildThreadId(mode)
 		this.state.set('threadId', threadId)
 
 		const existing = await this.conversationHistory.findByThread(threadId)
@@ -670,7 +766,7 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 
 			// Swap in fresh system prompt if it changed
 			if (messages.length > 0 && (messages[0]!.role === 'system' || messages[0]!.role === 'developer')) {
-				messages[0] = { role: messages[0]!.role, content: this._systemPrompt }
+				messages[0] = { role: messages[0]!.role, content: this.systemPrompt }
 			}
 
 			this.conversation.state.set('id', existing.id)
@@ -699,7 +795,8 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 
 	private bindHooksToEvents() {
 		const assistant = this
-		for (const [eventName, hookFn] of Object.entries(this._hooks)) {
+		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[]) => {
 				this.emit('hookFired', eventName)
@@ -720,17 +817,19 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 		if (this.isStarted) return this
 
 		// Wait for any async .use() plugins to finish before starting
-		if (this._pendingPlugins.length) {
-			await Promise.all(this._pendingPlugins)
-			this._pendingPlugins = []
+		const pending = this.state.get('pendingPlugins') as Promise<void>[]
+		if (pending.length) {
+			await Promise.all(pending)
+			this.state.set('pendingPlugins', [])
 		}
 
 		// Allow hooks.ts to export a formatSystemPrompt(assistant, prompt) => string
 		// that transforms the system prompt before the conversation is created.
-		if (this._hooks.formatSystemPrompt) {
-			const result = await this._hooks.formatSystemPrompt(this, this._systemPrompt)
+		const hooks = (this.state.get('hooks') || {}) as Record<string, (...args: any[]) => any>
+		if (hooks.formatSystemPrompt) {
+			const result = await hooks.formatSystemPrompt(this, this.systemPrompt)
 			if (typeof result === 'string') {
-				this._systemPrompt = result
+				this.state.set('systemPrompt', result)
 			}
 		}
 
@@ -758,6 +857,13 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 		if (mode === 'daily' || mode === 'persistent') {
 			(this.conversation.options as any).autoCompact = true
 		}
+		
+		this.on('toolsChanged', () => {
+			const conv = this.state.get('conversation') as Conversation | null
+			if (conv) {
+				conv.updateTools(this.tools)
+			}
+		})
 
 		this.state.set('started', true)
 		this.emit('started')
@@ -818,6 +924,53 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 
 		return this.conversation.save(opts)
 	}
+
+	// -- Subagent API --
+
+	/**
+	 * Names of assistants available as subagents, discovered via the assistantsManager.
+	 *
+	 * @returns {string[]} Available assistant names
+	 */
+	get availableSubagents(): string[] {
+		try {
+			const manager = this.container.feature('assistantsManager')
+			return manager.available
+		} catch {
+			return []
+		}
+	}
+
+	/**
+	 * Get or create a subagent assistant. Uses the assistantsManager to discover
+	 * and create the assistant, then caches the instance for reuse across tool calls.
+	 *
+	 * @param id - The assistant name (e.g. 'codingAssistant')
+	 * @param options - Additional options to pass to the assistant constructor
+	 * @returns {Promise<Assistant>} The subagent assistant instance, started and ready
+	 *
+	 * @example
+	 * ```typescript
+	 * const researcher = await assistant.subagent('codingAssistant')
+	 * const answer = await researcher.ask('Find all usages of container.feature("fs")')
+	 * ```
+	 */
+	async subagent(id: string, options: Record<string, any> = {}): Promise<Assistant> {
+		const subagents = (this.state.get('subagents') || {}) as Record<string, Assistant>
+		if (subagents[id]) return subagents[id]
+
+		const manager = this.container.feature('assistantsManager')
+
+		if (!manager.state.get('discovered')) {
+			await manager.discover()
+		}
+
+		const instance = manager.create(id, options)
+		await instance.start()
+
+		this.state.set('subagents', { ...subagents, [id]: instance })
+		return instance
+	}
 }
 
 export default Assistant