@soederpop/luca 0.0.6 → 0.0.8

package/scripts/examples/using-ollama.ts

@@ -2,7 +2,8 @@ import container from '@soederpop/luca/agi'
 
 const conversation = container.feature('conversation', {
 	local: true,
-	model: "qwen2.5:7b"
+	model: "qwen/qwen3-coder-30b",
+	api: "responses"
 })
 
 const response = await conversation.ask('What model am I using?')

package/scripts/update-introspection-data.ts

@@ -14,7 +14,7 @@ import { NodeContainer } from '../src/node/container.js';
 const targets = [
   {
     name: 'node',
-    src: ['src/node/features', 'src/servers', 'src/container.ts', 'src/node/container.ts'],
+    src: ['src/node/features', 'src/clients', 'src/servers', 'src/container.ts', 'src/node/container.ts'],
     outputPath: 'src/introspection/generated.node.ts',
   },
   {
@@ -24,7 +24,7 @@ const targets = [
   },
   {
     name: 'agi',
-    src: ['src/node/features', 'src/servers', 'src/agi/features', 'src/container.ts', 'src/node/container.ts', 'src/agi/container.server.ts'],
+    src: ['src/node/features', 'src/clients', 'src/servers', 'src/agi/features', 'src/container.ts', 'src/node/container.ts', 'src/agi/container.server.ts'],
     outputPath: 'src/introspection/generated.agi.ts',
   },
 ];

package/src/agi/endpoints/experts.ts

@@ -19,7 +19,7 @@ export async function get(_parameters: any, ctx: EndpointContext) {
 
   for (const relativePath of promptFiles) {
     const name = relativePath.split('/')[1]
-    const prompt = (await fs.readFileAsync(container.paths.resolve(relativePath))).toString()
+    const prompt = await fs.readFileAsync(container.paths.resolve(relativePath))
     const lines = prompt.split('\n').filter((l: string) => l.trim())
     const title = lines[0]?.replace(/^#+\s*/, '') || name
     const description = lines[1] || ''

package/src/agi/features/assistant.ts

@@ -65,6 +65,8 @@ export const AssistantOptionsSchema = FeatureOptionsSchema.extend({
 
 	maxTokens: z.number().optional().describe('Maximum number of output tokens per completion'),
 
+	local: z.boolean().default(false).describe('Whether to use our local models for this'),
+
 	/** History persistence mode: lifecycle (ephemeral), daily (auto-resume per day), persistent (single long-running thread), session (unique per run, resumable) */
 	historyMode: z.enum(['lifecycle', 'daily', 'persistent', 'session']).optional().describe('Conversation history persistence mode'),
 })
@@ -110,6 +112,10 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 		return super.container as AGIContainer
 	}
 
+	get name() {
+		return this.resolvedFolder.split('/').pop()
+	}
+
 	/** The absolute resolved path to the assistant folder. */
 	get resolvedFolder(): string {
 		return this.container.paths.resolve(this.options.folder)
@@ -203,6 +209,7 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 		if (!this._conversation) {
 			this._conversation = this.container.feature('conversation', {
 				model: this.options.model || 'gpt-5.2',
+				local: !!this.options.local,
 				tools: this._tools || this.loadTools(),
 				...(this.options.maxTokens ? { maxTokens: this.options.maxTokens } : {}),
 				history: [

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

@@ -96,9 +96,9 @@ export class AssistantsManager extends Feature<AssistantsManagerState, Assistant
 	private _entries: Map<string, AssistantEntry> = new Map()
 	private _instances: Map<string, Assistant> = new Map()
 
-	override afterInitialize() {
+	override async afterInitialize() {
 		if (this.options.autoDiscover) {
-			this.discover()
+			await this.discover()
 		}
 	}
 
@@ -107,13 +107,13 @@ export class AssistantsManager extends Feature<AssistantsManagerState, Assistant
 	 * using the fileManager. Each directory containing a CORE.md is
 	 * treated as an assistant definition.
 	 *
-	 * @returns {this} This instance, for chaining
+	 * @returns {Promise<this>} This instance, for chaining
 	 */
-	discover(): this {
+	async discover(): Promise<this> {
 		const { fs, paths } = this.container
 		const fileManager = this.container.feature('fileManager') as any
 
-		fileManager.start()
+		await fileManager.start()
 
 		this._entries.clear()
 

package/src/agi/features/claude-code.ts

@@ -1,6 +1,6 @@
 // @ts-nocheck
 import { z } from 'zod'
-import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
+import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
 import { type AvailableFeatures } from '@soederpop/luca/feature'
 import { Feature } from '@soederpop/luca/feature'
 
@@ -136,6 +136,8 @@ export const FileLogLevelSchema = z.enum(['verbose', 'normal', 'minimal']).descr
 export type FileLogLevel = z.infer<typeof FileLogLevelSchema>
 
 export const ClaudeCodeOptionsSchema = FeatureOptionsSchema.extend({
+  /** Claude CLI session ID to resume by default. When set, subsequent run()/start() calls will resume this session unless overridden. */
+  session: z.string().optional().describe('Claude CLI session ID to resume by default'),
   /** Path to the claude CLI binary. Defaults to 'claude'. */
   claudePath: z.string().optional().describe('Path to the claude CLI binary'),
   /** Default model to use for sessions. */
@@ -182,6 +184,21 @@ export const ClaudeCodeOptionsSchema = FeatureOptionsSchema.extend({
   skillsFolders: z.array(z.string()).optional().describe('Directories containing Claude Code skills to load into sessions'),
 })
 
+export const ClaudeCodeEventsSchema = FeatureEventsSchema.extend({
+  'session:start': z.tuple([z.object({ sessionId: z.string(), prompt: z.string() })]).describe('Fired when a new Claude Code session is spawned'),
+  'session:init': z.tuple([z.object({ sessionId: z.string(), init: z.any() })]).describe('Fired when the CLI emits its init system event'),
+  'session:event': z.tuple([z.object({ sessionId: z.string(), event: z.any() })]).describe('Fired for every parsed JSON event from the CLI stream'),
+  'session:stream': z.tuple([z.object({ sessionId: z.string(), streamEvent: z.any() })]).describe('Fired for stream_event type events from the CLI'),
+  'session:delta': z.tuple([z.object({ sessionId: z.string(), text: z.string(), role: z.string() })]).describe('Fired for each text delta from an assistant message'),
+  'session:message': z.tuple([z.object({ sessionId: z.string(), message: z.any() })]).describe('Fired when a complete assistant message is received'),
+  'session:result': z.tuple([z.object({ sessionId: z.string(), result: z.string() })]).describe('Fired when a session completes with a final result'),
+  'session:error': z.tuple([z.object({ sessionId: z.string(), error: z.any(), exitCode: z.number().optional() })]).describe('Fired when a session encounters an error'),
+  'session:abort': z.tuple([z.object({ sessionId: z.string() })]).describe('Fired when a session is aborted by the user'),
+  'session:warning': z.tuple([z.object({ sessionId: z.string(), message: z.string() })]).describe('Fired when the log reader encounters a warning'),
+  'session:log-error': z.tuple([z.object({ sessionId: z.string(), error: z.any() })]).describe('Fired when the log reader encounters an error'),
+  'session:parse-error': z.tuple([z.object({ sessionId: z.string(), line: z.string() })]).describe('Fired when a JSON line from the CLI cannot be parsed'),
+}).describe('ClaudeCode events')
+
 export type ClaudeCodeState = z.infer<typeof ClaudeCodeStateSchema>
 export type ClaudeCodeOptions = z.infer<typeof ClaudeCodeOptionsSchema>
 
@@ -277,6 +294,7 @@ export interface RunOptions {
 export class ClaudeCode extends Feature<ClaudeCodeState, ClaudeCodeOptions> {
   static override stateSchema = ClaudeCodeStateSchema
   static override optionsSchema = ClaudeCodeOptionsSchema
+  static override eventsSchema = ClaudeCodeEventsSchema
   static override shortcut = 'features.claudeCode' as const
   static override envVars = ['TMPDIR']
 
@@ -296,8 +314,17 @@ export class ClaudeCode extends Feature<ClaudeCodeState, ClaudeCodeOptions> {
    *
    * @returns {string} The path to the claude binary
    */
+  private _resolvedClaudePath: string | null = null
+
   get claudePath(): string {
-    return this.options.claudePath || 'claude'
+    if (this.options.claudePath) return this.options.claudePath
+    if (this._resolvedClaudePath) return this._resolvedClaudePath
+    try {
+      this._resolvedClaudePath = this.container.feature('proc').resolveRealPath('claude')
+    } catch {
+      this._resolvedClaudePath = 'claude'
+    }
+    return this._resolvedClaudePath
   }
 
   /**
@@ -511,7 +538,8 @@ export class ClaudeCode extends Feature<ClaudeCodeState, ClaudeCodeOptions> {
 
     if (configPaths.length) args.push('--mcp-config', ...configPaths)
 
-    if (options.resumeSessionId) args.push('--resume', options.resumeSessionId)
+    const resumeSessionId = options.resumeSessionId ?? (options.sessionId ? undefined : this.options.session)
+    if (resumeSessionId) args.push('--resume', resumeSessionId)
     if (options.continue) args.push('--continue')
     if (options.dangerouslySkipPermissions) args.push('--dangerously-skip-permissions')
 
@@ -1082,6 +1110,238 @@ export class ClaudeCode extends Feature<ClaudeCodeState, ClaudeCodeOptions> {
     }
   }
 
+  /**
+   * The Claude CLI session ID of the most recently initialized session,
+   * or the session set via the `session` option. Useful for resuming later.
+   *
+   * @returns {string | undefined} The Claude CLI session ID
+   *
+   * @example
+   * ```typescript
+   * const cc = container.feature('claudeCode')
+   * await cc.run('Do something')
+   * console.log(cc.sessionId) // the Claude CLI session ID
+   * ```
+   */
+  get sessionId(): string | undefined {
+    // Check if a default session was set via options
+    if (this.options.session) return this.options.session
+
+    // Find the most recently created session that has a Claude CLI sessionId
+    const sessions = Object.values(this.state.current.sessions) as ClaudeSession[]
+    if (sessions.length === 0) return undefined
+
+    // Return the last session's Claude CLI session ID
+    const last = sessions[sessions.length - 1]
+    return last?.sessionId
+  }
+
+  /**
+   * Export session history as a readable markdown document.
+   * Reads from a raw JSONL file (Claude CLI session log or this feature's NDJSON log)
+   * so it works independently of in-memory state.
+   *
+   * Can also accept a local session ID to export from in-memory state as a fallback.
+   *
+   * @param {string} [source] - Path to a JSONL file, a local session ID, or omit for the most recent session
+   * @returns {Promise<string>} Markdown-formatted session history
+   *
+   * @example
+   * ```typescript
+   * // From a JSONL file (works without any prior state)
+   * const md = await cc.sessionHistoryToMarkdown('/path/to/session.jsonl')
+   *
+   * // From the most recent in-memory session
+   * const md = await cc.sessionHistoryToMarkdown()
+   *
+   * // From a specific local session ID
+   * const md = await cc.sessionHistoryToMarkdown(localSessionId)
+   * ```
+   */
+  async sessionHistoryToMarkdown(source?: string): Promise<string> {
+    // If source looks like a file path, read JSONL from disk
+    if (source && (source.includes('/') || source.endsWith('.jsonl'))) {
+      return this.jsonlToMarkdown(source)
+    }
+
+    // Otherwise try to resolve from in-memory state
+    const sessionId = source || this.findLastSessionId()
+    if (!sessionId) throw new Error('No session found. Pass a JSONL file path or run a session first.')
+
+    const session = this.state.current.sessions[sessionId] as ClaudeSession | undefined
+    if (!session) throw new Error(`Session ${sessionId} not found in state. Pass a JSONL file path instead.`)
+
+    return this.sessionToMarkdown(session)
+  }
+
+  /**
+   * Find the local ID of the most recent session.
+   */
+  private findLastSessionId(): string | undefined {
+    const ids = Object.keys(this.state.current.sessions)
+    return ids.length > 0 ? ids[ids.length - 1] : undefined
+  }
+
+  /**
+   * Parse a JSONL file and convert its events to markdown.
+   */
+  private async jsonlToMarkdown(filePath: string): Promise<string> {
+    const fs = this.container.feature('fs')
+    const content = await fs.readFileAsync(filePath, 'utf-8')
+    const lines = content.split('\n').filter((l: string) => l.trim())
+
+    const events: ClaudeEvent[] = []
+    for (const line of lines) {
+      try {
+        const parsed = JSON.parse(line)
+        // Support both raw Claude events and our wrapper format (which has a .data field)
+        events.push(parsed.data ?? parsed)
+      } catch {
+        // skip malformed lines
+      }
+    }
+
+    return this.eventsToMarkdown(events, filePath)
+  }
+
+  /**
+   * Convert a ClaudeSession (from state) to markdown.
+   */
+  private sessionToMarkdown(session: ClaudeSession): string {
+    const lines: string[] = []
+
+    lines.push(`# Session: ${session.id}`)
+    if (session.sessionId) lines.push(`**Claude Session ID:** \`${session.sessionId}\``)
+    lines.push(`**Status:** ${session.status}`)
+    if (session.costUsd) lines.push(`**Cost:** $${session.costUsd.toFixed(4)}`)
+    if (session.turns) lines.push(`**Turns:** ${session.turns}`)
+    lines.push('')
+
+    lines.push(`## Prompt`)
+    lines.push('')
+    lines.push(session.prompt)
+    lines.push('')
+
+    if (session.messages.length > 0) {
+      lines.push(`## Conversation`)
+      lines.push('')
+
+      for (const msg of session.messages) {
+        this.renderAssistantMessage(lines, msg)
+      }
+    }
+
+    if (session.result) {
+      lines.push(`## Result`)
+      lines.push('')
+      lines.push(session.result)
+      lines.push('')
+    }
+
+    if (session.error) {
+      lines.push(`## Error`)
+      lines.push('')
+      lines.push(`\`\`\`\n${session.error}\n\`\`\``)
+      lines.push('')
+    }
+
+    return lines.join('\n')
+  }
+
+  /**
+   * Convert raw Claude events to markdown.
+   */
+  private eventsToMarkdown(events: ClaudeEvent[], source: string): string {
+    const lines: string[] = []
+    let sessionId: string | undefined
+    let model: string | undefined
+    let prompt: string | undefined
+    let costUsd: number | undefined
+    let turns: number | undefined
+    let durationMs: number | undefined
+
+    // Extract metadata from init and result events
+    for (const event of events) {
+      if (event.type === 'system' && (event as any).subtype === 'init') {
+        const init = event as ClaudeInitEvent
+        sessionId = init.session_id
+        model = init.model
+      }
+      if (event.type === 'result') {
+        const result = event as ClaudeResultEvent
+        costUsd = result.total_cost_usd
+        turns = result.num_turns
+        durationMs = result.duration_ms
+      }
+    }
+
+    lines.push(`# Session History`)
+    lines.push(`**Source:** \`${source}\``)
+    if (sessionId) lines.push(`**Session ID:** \`${sessionId}\``)
+    if (model) lines.push(`**Model:** ${model}`)
+    if (costUsd != null) lines.push(`**Cost:** $${costUsd.toFixed(4)}`)
+    if (turns != null) lines.push(`**Turns:** ${turns}`)
+    if (durationMs != null) lines.push(`**Duration:** ${(durationMs / 1000).toFixed(1)}s`)
+    lines.push('')
+
+    lines.push(`## Conversation`)
+    lines.push('')
+
+    for (const event of events) {
+      if (event.type === 'assistant') {
+        this.renderAssistantMessage(lines, event as ClaudeAssistantMessage)
+      } else if (event.type === 'tool_result') {
+        const tr = event as ClaudeToolResult
+        lines.push(`<details>`)
+        lines.push(`<summary>Tool Result (${tr.tool_use_id})</summary>`)
+        lines.push('')
+        lines.push('```')
+        lines.push(tr.content.length > 2000 ? tr.content.slice(0, 2000) + '\n... (truncated)' : tr.content)
+        lines.push('```')
+        lines.push(`</details>`)
+        lines.push('')
+      } else if (event.type === 'result') {
+        const result = event as ClaudeResultEvent
+        lines.push(`## Result`)
+        lines.push('')
+        if (result.is_error) {
+          lines.push(`**Error:**`)
+          lines.push(`\`\`\`\n${result.result}\n\`\`\``)
+        } else {
+          lines.push(result.result)
+        }
+        lines.push('')
+      }
+    }
+
+    return lines.join('\n')
+  }
+
+  /**
+   * Render a single assistant message to markdown lines.
+   */
+  private renderAssistantMessage(lines: string[], msg: ClaudeAssistantMessage): void {
+    lines.push(`### Assistant`)
+    if (msg.message?.usage) {
+      const u = msg.message.usage
+      lines.push(`*${u.input_tokens} in / ${u.output_tokens} out tokens*`)
+    }
+    lines.push('')
+
+    for (const block of msg.message?.content || []) {
+      if (block.type === 'text') {
+        lines.push(block.text)
+        lines.push('')
+      } else if (block.type === 'tool_use') {
+        lines.push(`**Tool Use:** \`${block.name}\``)
+        lines.push('```json')
+        lines.push(JSON.stringify(block.input, null, 2))
+        lines.push('```')
+        lines.push('')
+      }
+    }
+  }
+
   /**
    * Clean up any temp MCP config files created during sessions.
    */

package/src/agi/features/conversation-history.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod'
-import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
+import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
 import { type AvailableFeatures } from '@soederpop/luca/feature'
 import { Feature } from '@soederpop/luca/feature'
 import { NodeContainer, type DiskCache, type NodeFeatures } from '@soederpop/luca/node/container'
@@ -48,6 +48,11 @@ export const ConversationHistoryStateSchema = FeatureStateSchema.extend({
 	lastSaved: z.string().optional().describe('ISO timestamp of the last save operation'),
 })
 
+export const ConversationHistoryEventsSchema = FeatureEventsSchema.extend({
+	saved: z.tuple([z.string().describe('The conversation ID that was saved')]).describe('Fired after a conversation record is persisted'),
+	deleted: z.tuple([z.string().describe('The conversation ID that was deleted')]).describe('Fired after a conversation record is deleted'),
+}).describe('ConversationHistory events')
+
 export type ConversationHistoryOptions = z.infer<typeof ConversationHistoryOptionsSchema>
 export type ConversationHistoryState = z.infer<typeof ConversationHistoryStateSchema>
 
@@ -76,6 +81,7 @@ export type ConversationHistoryState = z.infer<typeof ConversationHistoryStateSc
 export class ConversationHistory extends Feature<ConversationHistoryState, ConversationHistoryOptions> {
 	static override stateSchema = ConversationHistoryStateSchema
 	static override optionsSchema = ConversationHistoryOptionsSchema
+	static override eventsSchema = ConversationHistoryEventsSchema
 	static override shortcut = 'features.conversationHistory' as const
 
 	static { Feature.register(this, 'conversationHistory') }

package/src/agi/features/conversation.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod'
-import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
+import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
 import { type AvailableFeatures } from '@soederpop/luca/feature'
 import { Feature } from '@soederpop/luca/feature'
 import type { OpenAIClient } from '../../clients/openai';
@@ -96,6 +96,28 @@ export const ConversationStateSchema = FeatureStateSchema.extend({
 	contextWindow: z.number().describe('The context window size for the current model'),
 })
 
+export const ConversationEventsSchema = FeatureEventsSchema.extend({
+	userMessage: z.tuple([z.any().describe('The user message content (string or ContentPart[])')]).describe('Fired when a user message is added to the conversation'),
+	turnStart: z.tuple([z.object({ turn: z.number(), isFollowUp: z.boolean() })]).describe('Fired at the start of each completion turn'),
+	turnEnd: z.tuple([z.object({ turn: z.number(), hasToolCalls: z.boolean() })]).describe('Fired at the end of each completion turn'),
+	toolCallsStart: z.tuple([z.any().describe('Array of tool call objects from the model')]).describe('Fired when the model begins a batch of tool calls'),
+	toolCall: z.tuple([z.string().describe('Tool name'), z.any().describe('Parsed arguments object')]).describe('Fired before invoking a single tool handler'),
+	toolResult: z.tuple([z.string().describe('Tool name'), z.string().describe('Serialized result')]).describe('Fired after a tool handler returns successfully'),
+	toolError: z.tuple([z.string().describe('Tool name'), z.any().describe('Error object or message')]).describe('Fired when a tool handler throws or the tool is unknown'),
+	toolCallsEnd: z.tuple([]).describe('Fired after all tool calls in a turn have been executed'),
+	chunk: z.tuple([z.string().describe('Text delta from the stream')]).describe('Fired for each streaming text delta'),
+	preview: z.tuple([z.string().describe('Accumulated text so far')]).describe('Fired after each chunk with the full accumulated text'),
+	response: z.tuple([z.string().describe('Final accumulated response text')]).describe('Fired when the final text response is produced'),
+	responseCompleted: z.tuple([z.any().describe('The completed OpenAI Response object')]).describe('Fired when the Responses API stream completes'),
+	rawEvent: z.tuple([z.any().describe('Raw stream event from the API')]).describe('Fired for every raw event from the Responses API stream'),
+	mcpEvent: z.tuple([z.any().describe('MCP-related stream event')]).describe('Fired for MCP-related events from the Responses API'),
+	summarizeStart: z.tuple([]).describe('Fired before generating a conversation summary'),
+	summarizeEnd: z.tuple([z.string().describe('The generated summary text')]).describe('Fired after the summary is generated'),
+	compactStart: z.tuple([z.object({ messageCount: z.number(), keepRecent: z.number() })]).describe('Fired before compacting the conversation history'),
+	compactEnd: z.tuple([z.object({ summary: z.string(), removedCount: z.number(), estimatedTokens: z.number(), compactionCount: z.number() })]).describe('Fired after compaction completes'),
+	autoCompactTriggered: z.tuple([z.object({ estimated: z.number(), limit: z.number(), contextWindow: z.number() })]).describe('Fired when auto-compact kicks in because tokens exceeded the threshold'),
+}).describe('Conversation events')
+
 export type ConversationOptions = z.infer<typeof ConversationOptionsSchema>
 export type ConversationState = z.infer<typeof ConversationStateSchema>
 
@@ -122,6 +144,7 @@ export type AskOptions = {
 export class Conversation extends Feature<ConversationState, ConversationOptions> {
 	static override stateSchema = ConversationStateSchema
 	static override optionsSchema = ConversationOptionsSchema
+	static override eventsSchema = ConversationEventsSchema
 	static override shortcut = 'features.conversation' as const
 
 	static { Feature.register(this, 'conversation') }
@@ -438,11 +461,11 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 		let baseURL = this.options.clientOptions?.baseURL ? this.options.clientOptions.baseURL : undefined
 
 		if (this.options.local) {
-			baseURL = "http://localhost:11434/v1" 
+			baseURL = "http://localhost:1234/v1" 
 		}
 
 		return (this.container as any).client('openai', {
-			defaultModel: this.options.model || (this.options.local ? "qwen2.5:7b" : "gpt-4o"),
+			defaultModel: this.options.model || (this.options.local ? this.options.model || "qwen/qwen3-coder-30b" : "gpt-5"),
 			...this.options.clientOptions,
 			...(baseURL ? { baseURL } : {}),
 		}) as OpenAIClient

package/src/agi/features/openai-codex.ts

@@ -1,6 +1,6 @@
 // @ts-nocheck
 import { z } from 'zod'
-import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
+import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
 import { type AvailableFeatures } from '@soederpop/luca/feature'
 import { Feature } from '@soederpop/luca/feature'
 
@@ -96,6 +96,20 @@ export const OpenAICodexOptionsSchema = FeatureOptionsSchema.extend({
   fullStdout: z.boolean().optional().describe('Do not truncate stdout/stderr from command outputs'),
 })
 
+export const OpenAICodexEventsSchema = FeatureEventsSchema.extend({
+  'session:start': z.tuple([z.object({ sessionId: z.string(), prompt: z.string() })]).describe('Fired when a new Codex session is spawned'),
+  'session:event': z.tuple([z.object({ sessionId: z.string(), event: z.any() })]).describe('Fired for every parsed JSON event from the Codex CLI stream'),
+  'session:delta': z.tuple([z.object({ sessionId: z.string(), text: z.string(), role: z.string() })]).describe('Fired for each text delta from an agent message'),
+  'session:message': z.tuple([z.object({ sessionId: z.string(), message: z.any() })]).describe('Fired when a complete agent message is received'),
+  'session:exec': z.tuple([z.object({ sessionId: z.string(), exec: z.any() })]).describe('Fired when a command execution item completes'),
+  'session:exec-start': z.tuple([z.object({ sessionId: z.string(), command: z.string() })]).describe('Fired when a command execution item starts'),
+  'session:reasoning': z.tuple([z.object({ sessionId: z.string(), text: z.string() })]).describe('Fired when a reasoning item is received'),
+  'session:result': z.tuple([z.object({ sessionId: z.string(), result: z.string() })]).describe('Fired when a session completes with a final result'),
+  'session:error': z.tuple([z.object({ sessionId: z.string(), error: z.any(), exitCode: z.number().optional() })]).describe('Fired when a session encounters an error'),
+  'session:abort': z.tuple([z.object({ sessionId: z.string() })]).describe('Fired when a session is aborted by the user'),
+  'session:parse-error': z.tuple([z.object({ sessionId: z.string(), line: z.string() })]).describe('Fired when a JSON line from the CLI cannot be parsed'),
+}).describe('OpenAICodex events')
+
 export type OpenAICodexState = z.infer<typeof OpenAICodexStateSchema>
 export type OpenAICodexOptions = z.infer<typeof OpenAICodexOptionsSchema>
 
@@ -146,6 +160,7 @@ export interface CodexRunOptions {
 export class OpenAICodex extends Feature<OpenAICodexState, OpenAICodexOptions> {
   static override stateSchema = OpenAICodexStateSchema
   static override optionsSchema = OpenAICodexOptionsSchema
+  static override eventsSchema = OpenAICodexEventsSchema
   static override shortcut = 'features.openaiCodex' as const
 
   static { Feature.register(this, 'openaiCodex') }
@@ -159,9 +174,18 @@ export class OpenAICodex extends Feature<OpenAICodexState, OpenAICodexOptions> {
     }
   }
 
+  private _resolvedCodexPath: string | null = null
+
   /** @returns The path to the codex CLI binary, falling back to 'codex' on the PATH. */
   get codexPath(): string {
-    return this.options.codexPath || 'codex'
+    if (this.options.codexPath) return this.options.codexPath
+    if (this._resolvedCodexPath) return this._resolvedCodexPath
+    try {
+      this._resolvedCodexPath = this.container.feature('proc').resolveRealPath('codex')
+    } catch {
+      this._resolvedCodexPath = 'codex'
+    }
+    return this._resolvedCodexPath
   }
 
   /**

package/src/agi/features/openapi.ts

@@ -1,5 +1,5 @@
 import { Feature } from '../../feature.js'
-import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
+import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
 import { z } from 'zod'
 import { camelCase } from 'lodash-es'
 
@@ -20,6 +20,10 @@ export const OpenAPIOptionsSchema = FeatureOptionsSchema.extend({
   url: z.string().optional().describe('URL to the OpenAPI/Swagger spec or the API server base URL')
 })
 
+export const OpenAPIEventsSchema = FeatureEventsSchema.extend({
+	loaded: z.tuple([z.any().describe('The parsed OpenAPI spec object')]).describe('Fired after the spec is fetched and parsed'),
+}).describe('OpenAPI events')
+
 export type OpenAPIOptions = z.infer<typeof OpenAPIOptionsSchema>
 export type OpenAPIState = z.infer<typeof OpenAPIStateSchema>
 
@@ -102,6 +106,7 @@ export class OpenAPI extends Feature<OpenAPIState, OpenAPIOptions> {
   static override description = 'Load and inspect OpenAPI specs, convert endpoints to OpenAI tool/function definitions'
   static override stateSchema = OpenAPIStateSchema
   static override optionsSchema = OpenAPIOptionsSchema
+  static override eventsSchema = OpenAPIEventsSchema
 
   static { Feature.register(this, 'openapi') }
 

package/src/agi/features/skills-library.ts

@@ -4,7 +4,7 @@ import os from 'os'
 import fs from 'fs/promises'
 import yaml from 'js-yaml'
 import { kebabCase } from 'lodash-es'
-import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
+import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
 import { type AvailableFeatures, Feature } from '@soederpop/luca/feature'
 import { Collection, defineModel } from 'contentbase'
 import type { ConversationTool } from './conversation'
@@ -61,6 +61,13 @@ export const SkillsLibraryOptionsSchema = FeatureOptionsSchema.extend({
 	userSkillsPath: z.string().optional().describe('Path to user-level global skills directory'),
 })
 
+export const SkillsLibraryEventsSchema = FeatureEventsSchema.extend({
+	loaded: z.tuple([]).describe('Fired after both project and user skill collections are loaded'),
+	skillCreated: z.tuple([z.any().describe('The created SkillEntry object')]).describe('Fired after a new skill is written to disk'),
+	skillUpdated: z.tuple([z.any().describe('The updated SkillEntry object')]).describe('Fired after an existing skill is updated'),
+	skillRemoved: z.tuple([z.string().describe('The name of the removed skill')]).describe('Fired after a skill is deleted'),
+}).describe('SkillsLibrary events')
+
 export type SkillsLibraryState = z.infer<typeof SkillsLibraryStateSchema>
 export type SkillsLibraryOptions = z.infer<typeof SkillsLibraryOptionsSchema>
 
@@ -91,6 +98,7 @@ export type SkillsLibraryOptions = z.infer<typeof SkillsLibraryOptionsSchema>
 export class SkillsLibrary extends Feature<SkillsLibraryState, SkillsLibraryOptions> {
 	static override stateSchema = SkillsLibraryStateSchema
 	static override optionsSchema = SkillsLibraryOptionsSchema
+	static override eventsSchema = SkillsLibraryEventsSchema
 	static override shortcut = 'features.skillsLibrary' as const
 
 	static { Feature.register(this, 'skillsLibrary') }