@soederpop/luca 0.0.23 → 0.0.25

package/src/agi/features/assistants-manager.ts

@@ -35,27 +35,29 @@ export const AssistantsManagerEventsSchema = FeatureEventsSchema.extend({
 		z.string().describe('The assistant name'),
 		z.any().describe('The assistant instance'),
 	]).describe('Emitted when a new assistant instance is created'),
+	assistantRegistered: z.tuple([
+		z.string().describe('The assistant id'),
+	]).describe('Emitted when an assistant factory is registered at runtime'),
 })
 
 export const AssistantsManagerStateSchema = FeatureStateSchema.extend({
 	discovered: z.boolean().describe('Whether discovery has been run'),
 	assistantCount: z.number().describe('Number of discovered assistant definitions'),
 	activeCount: z.number().describe('Number of currently instantiated assistants'),
+	entries: z.record(z.string(), z.any()).describe('Discovered assistant entries keyed by name'),
+	instances: z.record(z.string(), z.any()).describe('Active assistant instances keyed by name'),
+	factories: z.record(z.string(), z.any()).describe('Registered factory functions keyed by name'),
 })
 
-export const AssistantsManagerOptionsSchema = FeatureOptionsSchema.extend({
-	/** Whether to automatically run discovery after initialization. */
-	autoDiscover: z.boolean().default(false).describe('Automatically discover assistants on init'),
-})
+export const AssistantsManagerOptionsSchema = FeatureOptionsSchema.extend({})
 
 export type AssistantsManagerState = z.infer<typeof AssistantsManagerStateSchema>
 export type AssistantsManagerOptions = z.infer<typeof AssistantsManagerOptionsSchema>
 
 /**
- * Discovers and manages assistant definitions by finding all CORE.md files
- * in the project using the fileManager. Each directory containing a CORE.md
- * is treated as an assistant definition that can also contain tools.ts,
- * hooks.ts, voice.yaml, and a docs/ folder.
+ * Discovers and manages assistant definitions by looking for subdirectories
+ * in two locations: ~/.luca/assistants/ and cwd/assistants/. Each subdirectory
+ * containing a CORE.md is treated as an assistant definition.
  *
  * Use `discover()` to scan for available assistants, `list()` to enumerate them,
  * and `create(name)` to instantiate one as a running Assistant feature.
@@ -66,8 +68,8 @@ export type AssistantsManagerOptions = z.infer<typeof AssistantsManagerOptionsSc
  * ```typescript
  * const manager = container.feature('assistantsManager')
  * manager.discover()
- * console.log(manager.list()) // [{ name: 'assistants/chief-of-staff', folder: '...', ... }]
- * const assistant = manager.create('assistants/chief-of-staff')
+ * console.log(manager.list()) // [{ name: 'chief-of-staff', folder: '...', ... }]
+ * const assistant = manager.create('chief-of-staff')
  * const answer = await assistant.ask('Hello!')
  * ```
  */
@@ -86,6 +88,9 @@ export class AssistantsManager extends Feature<AssistantsManagerState, Assistant
 			discovered: false,
 			assistantCount: 0,
 			activeCount: 0,
+			entries: {},
+			instances: {},
+			factories: {},
 		}
 	}
 
@@ -93,57 +98,102 @@ export class AssistantsManager extends Feature<AssistantsManagerState, Assistant
 		return super.container as AGIContainer
 	}
 
-	private _entries: Map<string, AssistantEntry> = new Map()
-	private _instances: Map<string, Assistant> = new Map()
+	/** Discovered assistant entries keyed by name. */
+	get entries(): Record<string, AssistantEntry> {
+		return (this.state.get('entries') || {}) as Record<string, AssistantEntry>
+	}
 
-	override async afterInitialize() {
-		if (this.options.autoDiscover) {
-			await this.discover()
-		}
+	/** Active assistant instances keyed by name. */
+	get instances(): Record<string, Assistant> {
+		return (this.state.get('instances') || {}) as Record<string, Assistant>
+	}
+
+	/** Registered factory functions keyed by name. */
+	get factories(): Record<string, (options: Record<string, any>) => Assistant> {
+		return (this.state.get('factories') || {}) as Record<string, (options: Record<string, any>) => Assistant>
 	}
 
 	/**
-	 * Discovers assistants by finding all CORE.md files in the project
-	 * using the fileManager. Each directory containing a CORE.md is
-	 * treated as an assistant definition.
+	 * Discovers assistants by listing subdirectories in ~/.luca/assistants/
+	 * and cwd/assistants/. Each subdirectory containing a CORE.md is an assistant.
 	 *
 	 * @returns {Promise<this>} This instance, for chaining
 	 */
 	async discover(): Promise<this> {
-		const { fs, paths } = this.container
-		const fileManager = this.container.feature('fileManager') as any
-
-		await fileManager.start()
-
-		this._entries.clear()
-
-		const coreFiles = fileManager.matchFiles('**/CORE.md')
-
-		for (const file of coreFiles) {
-			const dir = file.dirname
-			const name = file.relativeDirname
-
-			this._entries.set(name, {
-				name,
-				folder: dir,
-				hasCorePrompt: true,
-				hasTools: fs.exists(paths.resolve(dir, 'tools.ts')),
-				hasHooks: fs.exists(paths.resolve(dir, 'hooks.ts')),
-				hasVoice: fs.exists(paths.resolve(dir, 'voice.yaml')),
-			})
+		const { fs, paths, os } = this.container
+
+		const discovered: Record<string, AssistantEntry> = {}
+
+		const locations = [
+			`${os.homedir}/.luca/assistants`,
+			paths.resolve('assistants'),
+		]
+
+		for (const location of locations) {
+			if (!fs.exists(location)) continue
+
+			const dirEntries = fs.readdirSync(location)
+
+			for (const entry of dirEntries) {
+				const folder = `${location}/${entry}`
+				if (!fs.isDirectory(folder)) continue
+
+				const hasCorePrompt = fs.exists(`${folder}/CORE.md`)
+				if (!hasCorePrompt) continue
+
+				// Don't overwrite earlier entries (home takes precedence for same name)
+				if (!discovered[entry]) {
+					discovered[entry] = {
+						name: entry,
+						folder,
+						hasCorePrompt: true,
+						hasTools: fs.exists(`${folder}/tools.ts`),
+						hasHooks: fs.exists(`${folder}/hooks.ts`),
+						hasVoice: fs.exists(`${folder}/voice.yaml`),
+					}
+				}
+			}
 		}
 
 		this.state.setState({
+			entries: discovered,
 			discovered: true,
-			assistantCount: this._entries.size,
+			assistantCount: Object.keys(discovered).length,
 		})
 
 		this.emit('discovered')
 		return this
 	}
 
+	/**
+	 * Downloads the core assistants that ship with luca from GitHub
+	 * into ~/.luca/assistants.
+	 *
+	 * @returns {Promise<{ files: string[] }>} The files extracted
+	 *
+	 * @example
+	 * ```typescript
+	 * const manager = container.feature('assistantsManager')
+	 * await manager.downloadLucaCoreAssistants()
+	 * await manager.discover()
+	 * console.log(manager.available)
+	 * ```
+	 */
+	async downloadLucaCoreAssistants() {
+		const { os, paths } = this.container
+		const dest = `${os.homedir}/.luca/assistants`
+		const git = this.container.feature('git') as any
+
+		return await git.extractFolder({
+			source: 'soederpop/luca/assistants',
+			destination: dest,
+		})
+	}
+
 	get available() {
-		return Array.from(this._entries.keys()) 
+		const entryKeys = Object.keys(this.entries)
+		const factoryKeys = Object.keys(this.factories)
+		return [...new Set([...entryKeys, ...factoryKeys])]
 	}
 
 	/**
@@ -152,55 +202,77 @@ export class AssistantsManager extends Feature<AssistantsManagerState, Assistant
 	 * @returns {AssistantEntry[]} All discovered entries
 	 */
 	list(): AssistantEntry[] {
-		return Array.from(this._entries.values())
+		return Object.values(this.entries)
 	}
 
 	/**
 	 * Looks up a single assistant entry by name.
 	 *
-	 * @param {string} name - The assistant name (e.g. 'assistants/chief-of-staff')
+	 * @param {string} name - The assistant name (e.g. 'chief-of-staff')
 	 * @returns {AssistantEntry | undefined} The entry, or undefined if not found
 	 */
 	get(name: string): AssistantEntry | undefined {
-		const found = this._entries.get(name)
-
-		if (found) {
-			return found
-		}
-
-		const aliases = this.available.filter(key => key === name || key.endsWith(`/${name}`))
-
-		if (aliases.length === 1) {
-			return this._entries.get(aliases[0]!)
-		} else if (aliases.length > 1) {
-			throw new Error(`Ambiguous assistant name "${name}", matches: ${aliases.join(', ')}`)
-		}
+		return this.entries[name]
+	}
 
-		return undefined
+	/**
+	 * Registers a factory function that creates an assistant at runtime.
+	 * Registered factories take precedence over discovered entries when
+	 * calling `create()`.
+	 *
+	 * @param {string} id - The assistant identifier
+	 * @param {(options: Record<string, any>) => Assistant} factory - Factory function that receives create options and returns an Assistant
+	 * @returns {this} This instance, for chaining
+	 *
+	 * @example
+	 * ```typescript
+	 * manager.register('custom-bot', (options) => {
+	 *   return container.feature('assistant', {
+	 *     systemPrompt: 'You are a custom bot.',
+	 *     ...options,
+	 *   })
+	 * })
+	 * const bot = manager.create('custom-bot')
+	 * ```
+	 */
+	register(id: string, factory: (options: Record<string, any>) => Assistant): this {
+		this.state.set('factories', { ...this.factories, [id]: factory })
+		this.emit('assistantRegistered', id)
+		return this
 	}
 
 	/**
 	 * Creates and returns a new Assistant feature instance for the given name.
+	 * Checks runtime-registered factories first, then falls back to discovered entries.
 	 * The assistant is configured with the discovered folder path. Any additional
 	 * options are merged in.
 	 *
-	 * @param {string} name - The assistant name (must match a discovered entry)
+	 * @param {string} name - The assistant name (must match a registered factory or discovered entry)
 	 * @param {Record<string, any>} options - Additional options to pass to the Assistant constructor
 	 * @returns {Assistant} The created assistant instance
-	 * @throws {Error} If the name is not found among discovered assistants
+	 * @throws {Error} If the name is not found among registered factories or discovered assistants
 	 *
 	 * @example
 	 * ```typescript
-	 * const assistant = manager.create('assistants/chief-of-staff', { model: 'gpt-4.1' })
+	 * const assistant = manager.create('chief-of-staff', { model: 'gpt-4.1' })
 	 * ```
 	 */
 	create(name: string, options: Record<string, any> = {}): Assistant {
+		// Check registered factories first
+		const factory = this.factories[name]
+		if (factory) {
+			const instance = factory(options)
+			const updated = { ...this.instances, [name]: instance }
+			this.state.setState({ instances: updated, activeCount: Object.keys(updated).length })
+			this.emit('assistantCreated', name, instance)
+			return instance
+		}
+
 		const entry = this.get(name)
 
 		if (!entry) {
-			const available = Array.from(this._entries.keys())
 			throw new Error(
-				`Assistant "${name}" not found. Available assistants: ${available.join(', ') || '(none — run discover() first)'}`
+				`Assistant "${name}" not found. Available assistants: ${this.available.join(', ') || '(none — run discover() first)'}`
 			)
 		}
 
@@ -209,8 +281,8 @@ export class AssistantsManager extends Feature<AssistantsManagerState, Assistant
 			...options,
 		})
 
-		this._instances.set(name, instance)
-		this.state.set('activeCount', this._instances.size)
+		const updated = { ...this.instances, [name]: instance }
+		this.state.setState({ instances: updated, activeCount: Object.keys(updated).length })
 		this.emit('assistantCreated', name, instance)
 
 		return instance
@@ -223,7 +295,7 @@ export class AssistantsManager extends Feature<AssistantsManagerState, Assistant
 	 * @returns {Assistant | undefined} The instance, or undefined if not yet created
 	 */
 	getInstance(name: string): Assistant | undefined {
-		return this._instances.get(name)
+		return this.instances[name]
 	}
 
 	/**

package/src/agi/features/conversation.ts

@@ -94,6 +94,8 @@ export const ConversationStateSchema = FeatureStateSchema.extend({
 	estimatedInputTokens: z.number().describe('Estimated input token count for the current messages array'),
 	compactionCount: z.number().describe('Number of times compact() has been called'),
 	contextWindow: z.number().describe('The context window size for the current model'),
+	tools: z.record(z.string(), z.any()).describe('Active tools map including any runtime overrides'),
+	callMaxTokens: z.number().nullable().describe('Per-call max tokens override, cleared after each ask()'),
 })
 
 export const ConversationEventsSchema = FeatureEventsSchema.extend({
@@ -149,15 +151,9 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 
 	static { Feature.register(this, 'conversation') }
 
-	private _callMaxTokens: number | undefined = undefined
-
 	/** Resolved max tokens: per-call override > options-level > undefined (no limit). */
 	private get maxTokens(): number | undefined {
-		return this._callMaxTokens ?? this.options.maxTokens ?? undefined
-	}
-
-	private get _tools(): Record<string, ConversationTool> {
-		return this.options.tools || {}
+		return (this.state.get('callMaxTokens') as number | null) ?? this.options.maxTokens ?? undefined
 	}
 
 	/** @returns Default state seeded from options: id, thread, model, initial history, and zero token usage. */
@@ -177,12 +173,46 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 			estimatedInputTokens: 0,
 			compactionCount: 0,
 			contextWindow: this.options.contextWindow || getContextWindow(this.options.model || 'gpt-5'),
+			tools: (this.options.tools || {}) as Record<string, ConversationTool>,
+			callMaxTokens: null,
 		}
 	}
 
 	/** Returns the registered tools available for the model to call. */
-	get tools() : Record<string, any> {
-		return this.options.tools || {}
+	get tools() : Record<string, ConversationTool> {
+		return (this.state.get('tools') || {}) as Record<string, ConversationTool>
+	}
+	
+	get availableTools() {
+		return Object.keys(this.tools)
+	}
+
+	/**
+	 * Add or replace a single tool by name.
+	 * Uses the same format as tools passed at construction time.
+	 */
+	addTool(name: string, tool: ConversationTool): this {
+		this.state.set('tools', { ...this.tools, [name]: tool })
+		return this
+	}
+
+	/**
+	 * Remove a tool by name.
+	 */
+	removeTool(name: string): this {
+		const current = { ...this.tools }
+		delete current[name]
+		this.state.set('tools', current)
+		return this
+	}
+
+	/**
+	 * Merge new tools into the conversation, replacing any with the same name.
+	 * Accepts the same Record<string, ConversationTool> format used at construction time.
+	 */
+	updateTools(tools: Record<string, ConversationTool>): this {
+		this.state.set('tools', { ...this.tools, ...tools })
+		return this
 	}
 
 	/** Returns configured remote MCP servers keyed by server label. */
@@ -388,7 +418,7 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 	 * ])
 	 */
 	async ask(content: string | ContentPart[], options?: AskOptions): Promise<string> {
-		this._callMaxTokens = options?.maxTokens
+		this.state.set('callMaxTokens', options?.maxTokens ?? null)
 
 		// Auto-compact before adding the new message
 		if (this.options.autoCompact) {
@@ -429,7 +459,7 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 
 			return await this.runChatCompletionLoop({ turn: 1, accumulated: '' })
 		} finally {
-			this._callMaxTokens = undefined
+			this.state.set('callMaxTokens', null)
 		}
 	}
 
@@ -584,6 +614,7 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 		input: OpenAI.Responses.ResponseInput
 		previousResponseId?: string
 	}): Promise<string> {
+
 		const { turn } = context
 		let accumulated = context.accumulated
 		let turnContent = ''
@@ -660,7 +691,7 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 			const functionOutputs: OpenAI.Responses.ResponseInputItem.FunctionCallOutput[] = []
 			for (const call of functionCalls) {
 				const toolName = call.name
-				const tool = this._tools[toolName]
+				const tool = this.tools[toolName]
 				const callCount = (this.state.get('toolCalls') || 0) + 1
 				this.state.set('toolCalls', callCount)
 
@@ -741,10 +772,11 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 	 * @returns {Promise<string>} The final assistant text response (accumulated across all turns)
 	 */
 	private async runChatCompletionLoop(context: { turn: number; accumulated: string } = { turn: 1, accumulated: '' }): Promise<string> {
+		
 		const { turn } = context
 		let accumulated = context.accumulated
 
-		const hasTools = Object.keys(this._tools || {}).length > 0
+		const hasTools = Object.keys(this.tools).length > 0
 		const toolsParam = hasTools ? this.openaiTools : undefined
 
 		this.state.set('streaming', true)
@@ -819,7 +851,7 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 
 			for (const tc of toolCalls) {
 				const toolName = tc.function.name
-				const tool = this._tools[toolName]
+				const tool = this.tools[toolName]
 				const callCount = (this.state.get('toolCalls') || 0) + 1
 				this.state.set('toolCalls', callCount)
 

package/src/agi/features/docs-reader.ts

@@ -0,0 +1,142 @@
+import { z } from 'zod'
+import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
+import { type AvailableFeatures, Feature } from '@soederpop/luca/feature'
+import type { ContentDb } from '@/node.js'
+import type Assistant from './assistant.js'
+
+declare module '@soederpop/luca/feature' {
+	interface AvailableFeatures {
+		docsReader: typeof DocsReader
+	}
+}
+
+export const DocsReaderStateSchema = FeatureStateSchema.extend({
+	started: z.boolean().describe('Whether the docs reader has been started'),
+})
+
+export const DocsReaderOptionsSchema = FeatureOptionsSchema.extend({
+	contentDb: z.union([
+		z.string(),
+		z.any()
+	]).describe('Either the contentDb instance or the path to the contentDb you want to load'),
+	model: z.string().describe('The model to use for the conversation').default("gpt-5.4"),
+	local: z.boolean().default(false).describe('Whether to use a local model for the conversation')
+}).loose()
+
+export const DocsReaderEventsSchema = FeatureEventsSchema.extend({
+	loaded: z.tuple([]).describe('Fired after the docs reader has been started'),
+}).describe('DocsReader events')
+
+export type DocsReaderState = z.infer<typeof DocsReaderStateSchema>
+export type DocsReaderOptions = z.infer<typeof DocsReaderOptionsSchema>
+
+/**
+ * The DocsReader feature is an AI Assisted wrapper around a ContentDB feature.
+ *
+ * You can ask it questions about the content, and it will use the ContentDB to find the answers
+ * from the documents.
+*/
+export class DocsReader extends Feature<DocsReaderState, DocsReaderOptions> {
+	static override stateSchema = DocsReaderStateSchema
+	static override optionsSchema = DocsReaderOptionsSchema
+	static override eventsSchema = DocsReaderEventsSchema
+	static override shortcut = 'features.docsReader' as const
+
+	static { Feature.register(this, 'docsReader') }
+
+	/** @returns Default state with started=false. */
+	override get initialState(): DocsReaderState {
+		return {
+			...super.initialState,
+			started: false,
+		}
+	}
+
+	/** Whether the docs reader has been started. */
+	get isStarted(): boolean {
+		return !!this.state.get('started')
+	}
+
+	calculateCacheKeyForQuestion(question: string) {
+		return this.container.utils.hashObject({
+			question,
+			sha: this.container.git?.sha,
+		})
+	}
+
+	get answerCache() {
+		return this.container.feature('diskCache')
+	}
+
+	get contentDb() : ContentDb {
+		return typeof this.options.contentDb === 'object' ?
+			this.options.contentDb as ContentDb :
+			this.container.feature('contentDb', { rootPath: this.options.contentDb })
+	}
+
+	async ask(question: string) {
+		if (!this.isStarted) {
+			await this.start()
+		}
+
+		if (!this.assistant) {
+			throw new Error('DocsReader not started')
+		}
+
+		return this.assistant.ask(question)
+	}
+
+	async askCached(question: string) {
+		if (!this.isStarted) {
+			await this.start()
+		}
+
+		if (!this.assistant) {
+			throw new Error('DocsReader not started')
+		}
+
+		const cacheKey = this.calculateCacheKeyForQuestion(question)
+		const cached = await this.answerCache.get(cacheKey)
+		if (cached) {
+			return cached
+		}
+
+		const answer = await this.assistant.ask(question)
+		await this.answerCache.set(cacheKey, answer)
+		return answer
+	}
+
+	assistant?: Assistant
+
+	/** Start the docs reader by loading the contentDb and wiring its tools into an assistant. */
+	async start(): Promise<DocsReader> {
+		if (this.isStarted) return this
+
+		const contentDb = this.contentDb
+		if (!contentDb.isLoaded) await contentDb.load()
+
+		this.assistant = this.container.feature('assistant', {
+			systemPrompt: CONTENT_DB_SYSTEM_PROMPT,
+			model: this.options.model,
+			local: this.options.local,
+		}).use(contentDb)
+
+
+		this.state.set('started', true)
+		this.emit('started')
+
+		return this
+	}
+}
+
+export default DocsReader
+
+export const CONTENT_DB_SYSTEM_PROMPT = `You answer questions using a collection of structured documents. Follow this workflow:
+
+1. Start with getCollectionOverview to understand the collection structure, available models, and document counts
+2. Use listDocuments or queryDocuments to find relevant documents by model, glob pattern, or metadata filters
+3. Use searchContent for text/regex search or semanticSearch for natural language queries
+4. Use readDocument to read specific documents — use include/exclude to focus on relevant sections and avoid loading unnecessary content
+5. Synthesize your answer from the documents you've read
+
+Be precise: read only what you need, use section filtering to stay focused, and cite document IDs in your answers.`

package/src/agi/features/openapi.ts

@@ -161,7 +161,7 @@ export class OpenAPI extends Feature<OpenAPIState, OpenAPIOptions> {
       endpointCount: this._endpoints.size,
     })
 
-    this.emit('loaded', this._spec)
+    this.emit('started', this._spec)
     return this
   }