@soederpop/luca 0.0.26 → 0.0.29

package/src/agi/features/assistant.ts

@@ -7,6 +7,7 @@ import type { AGIContainer } from '../container.server.js'
 import type { ContentDb } from '@soederpop/luca/node'
 import type { ConversationHistory, ConversationMeta } from './conversation-history'
 import hashObject from '../../hash-object.js'
+import { InterceptorChain, type InterceptorFn, type InterceptorPoints, type InterceptorPoint } from '../lib/interceptor-chain.js'
 
 declare module '@soederpop/luca/feature' {
 	interface AvailableFeatures {
@@ -28,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'),
+	systemPromptExtensionsChanged: z.tuple([]).describe('Emitted when system prompt extensions are added or removed'),
 })
 
 export const AssistantStateSchema = FeatureStateSchema.extend({
@@ -39,6 +41,7 @@ export const AssistantStateSchema = FeatureStateSchema.extend({
 	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'),
+	systemPromptExtensions: z.record(z.string(), z.string()).describe('Named extensions appended to the system prompt'),
 	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'),
@@ -111,6 +114,26 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 
 	static { Feature.register(this, 'assistant') }
 
+	readonly interceptors = {
+		beforeAsk: new InterceptorChain<InterceptorPoints['beforeAsk']>(),
+		beforeTurn: new InterceptorChain<InterceptorPoints['beforeTurn']>(),
+		beforeToolCall: new InterceptorChain<InterceptorPoints['beforeToolCall']>(),
+		afterToolCall: new InterceptorChain<InterceptorPoints['afterToolCall']>(),
+		beforeResponse: new InterceptorChain<InterceptorPoints['beforeResponse']>(),
+	}
+
+	/**
+	 * Register an interceptor at a given point in the pipeline.
+	 *
+	 * @param point - The interception point
+	 * @param fn - Middleware function receiving (ctx, next)
+	 * @returns this, for chaining
+	 */
+	intercept<K extends InterceptorPoint>(point: K, fn: InterceptorFn<InterceptorPoints[K]>): this {
+		this.interceptors[point].add(fn as any)
+		return this
+	}
+
 	/** @returns Default state with the assistant not started, zero conversations, and the resolved folder path. */
 	override get initialState(): AssistantState {
 		return {
@@ -120,6 +143,7 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 			lastResponse: '',
 			folder: this.resolvedFolder,
 			systemPrompt: '',
+			systemPromptExtensions: {},
 			meta: {},
 			tools: {},
 			hooks: {},
@@ -228,7 +252,7 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 				api: 'chat',
 				...(this.options.maxTokens ? { maxTokens: this.options.maxTokens } : {}),
 				history: [
-					{ role: 'system', content: this.systemPrompt || this.loadSystemPrompt() },
+					{ role: 'system', content: this.effectiveSystemPrompt },
 				],
 			})
 			this.state.set('conversation', conv)
@@ -254,6 +278,60 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 		return this.state.get('systemPrompt') || ''
 	}
 
+	/** The named extensions appended to the system prompt. */
+	get systemPromptExtensions(): Record<string, string> {
+		return (this.state.get('systemPromptExtensions') || {}) as Record<string, string>
+	}
+
+	/** The system prompt with all extensions appended. This is the value passed to the conversation. */
+	get effectiveSystemPrompt(): string {
+		const base = this.systemPrompt
+		const extensions = Object.values(this.systemPromptExtensions)
+		if (!extensions.length) return base
+		return [base, ...extensions].join('\n\n')
+	}
+
+	/**
+	 * Add or update a named system prompt extension. The value is appended
+	 * to the base system prompt when passed to the conversation.
+	 *
+	 * @param key - A unique identifier for this extension
+	 * @param value - The text to append
+	 * @returns this, for chaining
+	 */
+	addSystemPromptExtension(key: string, value: string): this {
+		this.state.set('systemPromptExtensions', { ...this.systemPromptExtensions, [key]: value })
+		this.syncSystemPromptToConversation()
+		this.emit('systemPromptExtensionsChanged')
+		return this
+	}
+
+	/**
+	 * Remove a named system prompt extension.
+	 *
+	 * @param key - The identifier of the extension to remove
+	 * @returns this, for chaining
+	 */
+	removeSystemPromptExtension(key: string): this {
+		const current = { ...this.systemPromptExtensions }
+		delete current[key]
+		this.state.set('systemPromptExtensions', current)
+		this.syncSystemPromptToConversation()
+		this.emit('systemPromptExtensionsChanged')
+		return this
+	}
+
+	/** Update the conversation's system message to reflect the current effective prompt. */
+	private syncSystemPromptToConversation() {
+		const conv = this.state.get('conversation') as Conversation | null
+		if (!conv) return
+		const messages = [...conv.messages]
+		if (messages.length > 0 && (messages[0]!.role === 'system' || messages[0]!.role === 'developer')) {
+			messages[0] = { ...messages[0]!, content: this.effectiveSystemPrompt }
+			conv.state.set('messages', messages)
+		}
+	}
+
 	/** The tools registered with this assistant. */
 	get tools(): Record<string, ConversationTool> {
 		return (this.state.get('tools') || {}) as Record<string, ConversationTool>
@@ -287,6 +365,9 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 			}
 		} else if (fnOrHelper && typeof (fnOrHelper as any).toTools === 'function') {
 			this._registerTools((fnOrHelper as any).toTools())
+			if (typeof (fnOrHelper as any).setupToolsConsumer === 'function') {
+				(fnOrHelper as any).setupToolsConsumer(this)
+			}
 		} else if (fnOrHelper && 'schemas' in fnOrHelper && 'handlers' in fnOrHelper) {
 			this._registerTools(fnOrHelper as { schemas: Record<string, z.ZodType>, handlers: Record<string, Function> })
 		}
@@ -768,7 +849,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.effectiveSystemPrompt }
 			}
 
 			this.conversation.state.set('id', existing.id)
@@ -851,6 +932,38 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 		this.conversation.on('toolResult', (name: string, result: any) => this.emit('toolResult', name, result))
 		this.conversation.on('toolError', (name: string, error: any) => this.emit('toolError', name, error))
 
+		// Install interceptor-aware tool executor on the conversation
+		this.conversation.toolExecutor = async (name: string, args: Record<string, any>, handler: (...a: any[]) => Promise<any>) => {
+			const ctx = { name, args, result: undefined as string | undefined, error: undefined, skip: false }
+
+			await this.interceptors.beforeToolCall.run(ctx, async () => {})
+
+			if (ctx.skip) {
+				const result = ctx.result ?? JSON.stringify({ skipped: true })
+				this.emit('toolResult', ctx.name, result)
+				return result
+			}
+
+			try {
+				this.emit('toolCall', ctx.name, ctx.args)
+				const output = await handler(ctx.args)
+				ctx.result = typeof output === 'string' ? output : JSON.stringify(output)
+			} catch (err: any) {
+				ctx.error = err
+				ctx.result = JSON.stringify({ error: err.message || String(err) })
+			}
+
+			await this.interceptors.afterToolCall.run(ctx, async () => {})
+
+			if (ctx.error && !ctx.result?.includes('"error"')) {
+				this.emit('toolError', ctx.name, ctx.error)
+			} else {
+				this.emit('toolResult', ctx.name, ctx.result!)
+			}
+
+			return ctx.result!
+		}
+
 		// Load conversation history for non-lifecycle modes
 		await this.loadConversationHistory()
 
@@ -901,7 +1014,23 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 			question = this.prependTimestamp(question)
 		}
 
-		const result = await this.conversation.ask(question, options)
+		// Run beforeAsk interceptors — they can rewrite the question or short-circuit
+		if (this.interceptors.beforeAsk.hasInterceptors) {
+			const ctx = { question, options } as InterceptorPoints['beforeAsk']
+			await this.interceptors.beforeAsk.run(ctx, async () => {})
+			if (ctx.result !== undefined) return ctx.result
+			question = ctx.question
+			options = ctx.options
+		}
+
+		let result = await this.conversation.ask(question, options)
+
+		// Run beforeResponse interceptors — they can rewrite the final text
+		if (this.interceptors.beforeResponse.hasInterceptors) {
+			const ctx = { text: result }
+			await this.interceptors.beforeResponse.run(ctx, async () => {})
+			result = ctx.text
+		}
 
 		// Auto-save for non-lifecycle modes
 		if (this.options.historyMode !== 'lifecycle' && this.state.get('threadId')) {

package/src/agi/features/conversation.ts

@@ -125,6 +125,44 @@ export type ConversationState = z.infer<typeof ConversationStateSchema>
 
 export type AskOptions = {
 	maxTokens?: number
+	/**
+	 * When provided, enables OpenAI Structured Outputs. The model is constrained
+	 * to return JSON matching this Zod schema. The return value of ask() will be
+	 * the parsed object instead of a raw string.
+	 */
+	schema?: z.ZodType
+}
+
+/**
+ * Recursively set `additionalProperties: false` on every object-type node
+ * in a JSON Schema tree. OpenAI strict mode requires this at every level.
+ * Also ensures every object has a `required` array listing all its property keys.
+ */
+function strictifySchema(schema: Record<string, any>): Record<string, any> {
+	const clone = { ...schema }
+
+	if (clone.type === 'object' && clone.properties) {
+		clone.additionalProperties = false
+		clone.required = Object.keys(clone.properties)
+		const props: Record<string, any> = {}
+		for (const [key, val] of Object.entries(clone.properties)) {
+			props[key] = strictifySchema(val as Record<string, any>)
+		}
+		clone.properties = props
+	}
+
+	if (clone.items) {
+		clone.items = strictifySchema(clone.items)
+	}
+
+	// anyOf / oneOf / allOf
+	for (const combiner of ['anyOf', 'oneOf', 'allOf'] as const) {
+		if (Array.isArray(clone[combiner])) {
+			clone[combiner] = clone[combiner].map((s: Record<string, any>) => strictifySchema(s))
+		}
+	}
+
+	return clone
 }
 
 /**
@@ -151,6 +189,16 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 
 	static { Feature.register(this, 'conversation') }
 
+	/**
+	 * Pluggable tool executor. Called for each tool invocation with the tool
+	 * name, parsed args, and the default handler. Return the serialized result string.
+	 * The Assistant replaces this to wire in beforeToolCall/afterToolCall interceptors.
+	 */
+	toolExecutor: ((name: string, args: Record<string, any>, handler: (...args: any[]) => Promise<any>) => Promise<string>) | null = null
+
+	/** The active structured output schema for the current ask() call, if any. */
+	private _activeSchema: z.ZodType | null = null
+
 	/** Resolved max tokens: per-call override > options-level > undefined (no limit). */
 	private get maxTokens(): number | undefined {
 		return (this.state.get('callMaxTokens') as number | null) ?? this.options.maxTokens ?? undefined
@@ -419,6 +467,7 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 	 */
 	async ask(content: string | ContentPart[], options?: AskOptions): Promise<string> {
 		this.state.set('callMaxTokens', options?.maxTokens ?? null)
+		this._activeSchema = options?.schema ?? null
 
 		// Auto-compact before adding the new message
 		if (this.options.autoCompact) {
@@ -436,6 +485,8 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 		this.emit('userMessage', content)
 
 		try {
+			let raw: string
+
 			if (this.apiMode === 'responses') {
 				const previousResponseId = this.state.get('lastResponseId') || undefined
 				let input: OpenAI.Responses.ResponseInput
@@ -449,17 +500,31 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 					input = this.messagesToResponsesInput()
 				}
 
-				return await this.runResponsesLoop({
+				raw = await this.runResponsesLoop({
 					turn: 1,
 					accumulated: '',
 					input,
 					previousResponseId,
 				})
+			} else {
+				raw = await this.runChatCompletionLoop({ turn: 1, accumulated: '' })
 			}
 
-			return await this.runChatCompletionLoop({ turn: 1, accumulated: '' })
+			// When a structured output schema is active, parse the JSON response
+			if (this._activeSchema) {
+				try {
+					const parsed = JSON.parse(raw)
+					return parsed
+				} catch {
+					// Model returned something that isn't valid JSON — return raw
+					return raw
+				}
+			}
+
+			return raw
 		} finally {
 			this.state.set('callMaxTokens', null)
+			this._activeSchema = null
 		}
 	}
 
@@ -545,6 +610,28 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 		return input
 	}
 
+	/**
+	 * Build the OpenAI response_format / text.format config from the active Zod schema.
+	 * Returns undefined when no schema is active.
+	 */
+	private get structuredOutputConfig(): { name: string; schema: Record<string, any>; strict: true } | undefined {
+		if (!this._activeSchema) return undefined
+
+		const raw = (this._activeSchema as any).toJSONSchema() as Record<string, any>
+		const strict = strictifySchema(raw)
+
+		// Derive a name from the schema description or fall back to a default.
+		// OpenAI requires [a-zA-Z0-9_-] max 64 chars.
+		const desc = raw.description || 'structured_output'
+		const name = desc.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 64)
+
+		return {
+			name,
+			schema: { type: strict.type || 'object', properties: strict.properties, required: strict.required, additionalProperties: false },
+			strict: true,
+		}
+	}
+
 	/** Returns the OpenAI client instance from the container. */
 	get openai() {
 		let baseURL = this.options.clientOptions?.baseURL ? this.options.clientOptions.baseURL : undefined
@@ -603,6 +690,40 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 		})
 	}
 
+	/**
+	 * Execute a single tool call, routing through the pluggable toolExecutor
+	 * if one is set (e.g. by the Assistant's interceptor chain).
+	 */
+	private async executeTool(toolName: string, rawArgs: string): Promise<string> {
+		const tool = this.tools[toolName]
+		const callCount = (this.state.get('toolCalls') || 0) + 1
+		this.state.set('toolCalls', callCount)
+
+		if (!tool) {
+			const result = JSON.stringify({ error: `Unknown tool: ${toolName}` })
+			this.emit('toolError', toolName, result)
+			return result
+		}
+
+		if (this.toolExecutor) {
+			const args = rawArgs ? JSON.parse(rawArgs) : {}
+			return this.toolExecutor(toolName, args, tool.handler)
+		}
+
+		try {
+			const args = rawArgs ? JSON.parse(rawArgs) : {}
+			this.emit('toolCall', toolName, args)
+			const output = await tool.handler(args)
+			const result = typeof output === 'string' ? output : JSON.stringify(output)
+			this.emit('toolResult', toolName, result)
+			return result
+		} catch (err: any) {
+			const result = JSON.stringify({ error: err.message || String(err) })
+			this.emit('toolError', toolName, err)
+			return result
+		}
+	}
+
 	/**
 	 * Runs the streaming Responses API loop. Handles local function calls by
 	 * executing handlers and submitting `function_call_output` items until
@@ -625,6 +746,10 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 		this.state.set('streaming', true)
 		this.emit('turnStart', { turn, isFollowUp: turn > 1 })
 
+		const textFormat = this.structuredOutputConfig
+			? { text: { format: { type: 'json_schema' as const, ...this.structuredOutputConfig } } }
+			: {}
+
 		try {
 			const stream = await this.openai.raw.responses.create({
 				model: this.model as OpenAI.Responses.ResponseCreateParams['model'],
@@ -634,6 +759,7 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 				...(toolsParam ? { tools: toolsParam, tool_choice: 'auto', parallel_tool_calls: true } : {}),
 				...(this.responsesInstructions ? { instructions: this.responsesInstructions } : {}),
 				...(this.maxTokens ? { max_output_tokens: this.maxTokens } : {}),
+				...textFormat,
 			})
 
 			for await (const event of stream) {
@@ -690,27 +816,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 callCount = (this.state.get('toolCalls') || 0) + 1
-				this.state.set('toolCalls', callCount)
-
-				let result: string
-				if (!tool) {
-					result = JSON.stringify({ error: `Unknown tool: ${toolName}` })
-					this.emit('toolError', toolName, result)
-				} else {
-					try {
-						const args = call.arguments ? JSON.parse(call.arguments) : {}
-						this.emit('toolCall', toolName, args)
-						const output = await tool.handler(args)
-						result = typeof output === 'string' ? output : JSON.stringify(output)
-						this.emit('toolResult', toolName, result)
-					} catch (err: any) {
-						result = JSON.stringify({ error: err.message || String(err) })
-						this.emit('toolError', toolName, err)
-					}
-				}
+				const result = await this.executeTool(call.name, call.arguments || '{}')
 
 				this.pushMessage({
 					role: 'tool',
@@ -785,6 +891,10 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 		let turnContent = ''
 		let toolCalls: Array<{ id: string; function: { name: string; arguments: string }; type: 'function' }> = []
 
+		const responseFormat = this.structuredOutputConfig
+			? { response_format: { type: 'json_schema' as const, json_schema: this.structuredOutputConfig } }
+			: {}
+
 		try {
 			const stream = await this.openai.raw.chat.completions.create({
 				model: this.model,
@@ -792,6 +902,7 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 				stream: true,
 				...(toolsParam ? { tools: toolsParam, tool_choice: 'auto' } : {}),
 				...(this.maxTokens ? { max_tokens: this.maxTokens } : {}),
+				...responseFormat,
 			})
 
 			for await (const chunk of stream) {
@@ -850,28 +961,7 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 			this.emit('toolCallsStart', toolCalls)
 
 			for (const tc of toolCalls) {
-				const toolName = tc.function.name
-				const tool = this.tools[toolName]
-				const callCount = (this.state.get('toolCalls') || 0) + 1
-				this.state.set('toolCalls', callCount)
-
-				let result: string
-
-				if (!tool) {
-					result = JSON.stringify({ error: `Unknown tool: ${toolName}` })
-					this.emit('toolError', toolName, result)
-				} else {
-					try {
-						const args = JSON.parse(tc.function.arguments)
-						this.emit('toolCall', toolName, args)
-						const output = await tool.handler(args)
-						result = typeof output === 'string' ? output : JSON.stringify(output)
-						this.emit('toolResult', toolName, result)
-					} catch (err: any) {
-						result = JSON.stringify({ error: err.message || String(err) })
-						this.emit('toolError', toolName, err)
-					}
-				}
+				const result = await this.executeTool(tc.function.name, tc.function.arguments)
 
 				const toolMessage: OpenAI.Chat.Completions.ChatCompletionToolMessageParam = {
 					role: 'tool',

package/src/agi/lib/interceptor-chain.ts

@@ -0,0 +1,79 @@
+/**
+ * A composable middleware chain. Each interceptor receives a mutable
+ * context and a `next` function. Calling `next()` continues the chain;
+ * skipping it short-circuits.
+ */
+
+export type InterceptorFn<T> = (ctx: T, next: () => Promise<void>) => Promise<void>
+
+export class InterceptorChain<T> {
+	private fns: InterceptorFn<T>[] = []
+
+	add(fn: InterceptorFn<T>): void {
+		this.fns.push(fn)
+	}
+
+	remove(fn: InterceptorFn<T>): void {
+		const idx = this.fns.indexOf(fn)
+		if (idx !== -1) this.fns.splice(idx, 1)
+	}
+
+	get hasInterceptors(): boolean {
+		return this.fns.length > 0
+	}
+
+	get size(): number {
+		return this.fns.length
+	}
+
+	async run(ctx: T, final: () => Promise<void>): Promise<void> {
+		let index = 0
+		const fns = this.fns
+
+		const next = async (): Promise<void> => {
+			if (index < fns.length) {
+				const fn = fns[index++]!
+				await fn(ctx, next)
+			} else {
+				await final()
+			}
+		}
+
+		await next()
+	}
+}
+
+export interface BeforeAskCtx {
+	question: string | any[]
+	options?: any
+	result?: string
+}
+
+export interface ToolCallCtx {
+	name: string
+	args: Record<string, any>
+	result?: string
+	error?: any
+	skip?: boolean
+}
+
+export interface BeforeResponseCtx {
+	text: string
+}
+
+export interface BeforeTurnCtx {
+	turn: number
+	isFollowUp: boolean
+	messages: any[]
+	skip?: boolean
+}
+
+export interface InterceptorPoints {
+	beforeAsk: BeforeAskCtx
+	beforeTurn: BeforeTurnCtx
+	beforeToolCall: ToolCallCtx
+	afterToolCall: ToolCallCtx
+	beforeResponse: BeforeResponseCtx
+}
+
+export type InterceptorPoint = keyof InterceptorPoints