@soederpop/luca 0.1.2 → 0.1.3

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

@@ -2,7 +2,7 @@
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
 import { type AvailableFeatures } from '@soederpop/luca/feature'
-import { Feature } from '@soederpop/luca/feature'
+import { Feature } from '../feature.js'
 
 declare module '@soederpop/luca/feature' {
   interface AvailableFeatures {
@@ -1349,6 +1349,170 @@ export class ClaudeCode extends Feature<ClaudeCodeState, ClaudeCodeOptions> {
     }
   }
 
+  /**
+   * List all Claude Code processes currently registered in ~/.claude/sessions/.
+   * Returns each session's metadata along with whether the process is still alive.
+   *
+   * @returns {Promise<Array<{ pid: number; sessionId: string; cwd: string; startedAt: number; kind: string; entrypoint: string; alive: boolean }>>}
+   *
+   * @example
+   * const sessions = await cc.listProcessSessions()
+   * for (const s of sessions) {
+   *   console.log(`[${s.alive ? 'LIVE' : 'dead'}] PID ${s.pid} in ${s.cwd}`)
+   * }
+   */
+  async listProcessSessions(): Promise<Array<{
+    pid: number
+    sessionId: string
+    cwd: string
+    startedAt: number
+    kind: string
+    entrypoint: string
+    alive: boolean
+  }>> {
+    const fs = this.container.feature('fs')
+    const proc = this.container.feature('proc')
+    const home = process.env.HOME ?? '/tmp'
+    const sessionsDir = `${home}/.claude/sessions`
+
+    let files: string[]
+    try {
+      files = await fs.readdir(sessionsDir)
+    } catch {
+      return []
+    }
+
+    const jsonFiles = files.filter((f: string) => f.endsWith('.json'))
+
+    const results = await Promise.all(jsonFiles.map(async (file: string) => {
+      try {
+        const raw = await fs.readFile(`${sessionsDir}/${file}`, 'utf8')
+        const data = JSON.parse(raw)
+        let alive = false
+        try {
+          await proc.exec(`kill -0 ${data.pid}`)
+          alive = true
+        } catch {
+          alive = false
+        }
+        return { ...data, alive }
+      } catch {
+        return null
+      }
+    }))
+
+    return results.filter(Boolean)
+  }
+
+  /**
+   * Read a single process session by PID from ~/.claude/sessions/<pid>.json.
+   *
+   * @param {number} pid - The process ID
+   * @returns {Promise<{ pid: number; sessionId: string; cwd: string; startedAt: number; kind: string; entrypoint: string } | null>}
+   *
+   * @example
+   * const session = await cc.getProcessSession(12345)
+   * console.log(session?.cwd)
+   */
+  async getProcessSession(pid: number): Promise<{
+    pid: number
+    sessionId: string
+    cwd: string
+    startedAt: number
+    kind: string
+    entrypoint: string
+  } | null> {
+    const fs = this.container.feature('fs')
+    const home = process.env.HOME ?? '/tmp'
+    try {
+      const raw = await fs.readFile(`${home}/.claude/sessions/${pid}.json`, 'utf8')
+      return JSON.parse(raw)
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Read the conversation history for a Claude Code session from its JSONL file in
+   * ~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl.
+   *
+   * Returns an array of parsed message objects (user, assistant, tool_use, tool_result).
+   *
+   * @param {string} sessionId - The Claude CLI session ID (from listProcessSessions or getProcessSession)
+   * @param {string} cwd - The working directory of the session (used to locate the project folder)
+   * @returns {Promise<any[]>} Array of parsed JSONL records
+   *
+   * @example
+   * const sessions = await cc.listProcessSessions()
+   * const s = sessions[0]
+   * const history = await cc.getConversationHistory(s.sessionId, s.cwd)
+   * console.log(history.length, 'turns')
+   */
+  async getConversationHistory(sessionId: string, cwd?: string): Promise<any[]> {
+    const fs = this.container.feature('fs')
+    const home = process.env.HOME ?? '/tmp'
+    const resolvedCwd = cwd ?? this.options.cwd ?? (this.container as any).cwd
+    const encodedCwd = resolvedCwd.replace(/\//g, '-').replace(/@/g, '-')
+    const filePath = `${home}/.claude/projects/${encodedCwd}/${sessionId}.jsonl`
+    try {
+      const raw = await fs.readFile(filePath, 'utf8')
+      return raw
+        .split('\n')
+        .filter((line: string) => line.trim())
+        .map((line: string) => JSON.parse(line))
+    } catch {
+      return []
+    }
+  }
+
+  /**
+   * List all conversation sessions stored for a given working directory.
+   * Reads ~/.claude/projects/<encoded-cwd>/ and returns metadata for each .jsonl file.
+   *
+   * @param {string} cwd - The working directory path to look up
+   * @returns {Promise<Array<{ sessionId: string; filePath: string; messageCount: number }>>}
+   *
+   * @example
+   * const sessions = await cc.listSessionsForCwd('/Users/me/my-project')
+   * for (const s of sessions) {
+   *   console.log(s.sessionId, s.messageCount, 'messages')
+   * }
+   */
+  async listSessionsForCwd(cwd?: string): Promise<Array<{
+    sessionId: string
+    filePath: string
+    messageCount: number
+  }>> {
+    const fs = this.container.feature('fs')
+    const home = process.env.HOME ?? '/tmp'
+    const resolvedCwd = cwd ?? this.options.cwd ?? (this.container as any).cwd
+    const encodedCwd = resolvedCwd.replace(/\//g, '-').replace(/@/g, '-')
+    const projectDir = `${home}/.claude/projects/${encodedCwd}`
+
+    let files: string[]
+    try {
+      files = await fs.readdir(projectDir)
+    } catch {
+      return []
+    }
+
+    const jsonlFiles = files.filter((f: string) => f.endsWith('.jsonl'))
+
+    const results = await Promise.all(jsonlFiles.map(async (file: string) => {
+      const sessionId = file.replace(/\.jsonl$/, '')
+      const filePath = `${projectDir}/${file}`
+      try {
+        const raw = await fs.readFile(filePath, 'utf8')
+        const messageCount = raw.split('\n').filter((l: string) => l.trim()).length
+        return { sessionId, filePath, messageCount }
+      } catch {
+        return { sessionId, filePath, messageCount: 0 }
+      }
+    }))
+
+    return results
+  }
+
   /**
    * Clean up any temp MCP config files created during sessions.
    */

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

@@ -1,8 +1,8 @@
 import { z } from 'zod'
 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'
+import { Feature } from '../feature.js'
+import type { DiskCache } from '@soederpop/luca/node/container'
 import type { Message } from './conversation'
 
 declare module '@soederpop/luca/feature' {
@@ -95,10 +95,6 @@ export class ConversationHistory extends Feature<ConversationHistoryState, Conve
 		}
 	}
 
-	/** @returns The parent NodeContainer, narrowed from the base Container type. */
-	override get container() {
-		return super.container as NodeContainer<NodeFeatures, any>
-	}
 
 	/** @returns The diskCache feature instance used for persistence, configured with the optional cachePath. */
 	get diskCache(): DiskCache {

package/src/agi/features/conversation.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
 import { type AvailableFeatures } from '@soederpop/luca/feature'
-import { Feature } from '@soederpop/luca/feature'
+import { Feature } from '../feature.js'
 import type { OpenAIClient } from '../../clients/openai';
 import type OpenAI from 'openai';
 import type { ConversationHistory } from './conversation-history';
@@ -212,9 +212,12 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 	/** 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 > default 512. */
+	/** Registered stubs: matched against user input to short-circuit the API with a canned response. */
+	private _stubs: Array<{ matcher: string | RegExp; response: string | (() => string) }> = []
+
+	/** Resolved max tokens: per-call override > options-level. Undefined means no limit (model default). */
 	private get maxTokens(): number | undefined {
-		return (this.state.get('callMaxTokens') as number | null) ?? this.options.maxTokens ?? 512
+		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. */
@@ -276,6 +279,22 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 		return this
 	}
 
+	/**
+	 * Register a hardcoded stub response that bypasses the API when the user's message matches.
+	 * Streaming is still simulated — chunk/preview events fire word-by-word.
+	 *
+	 * @param matcher - Exact string match, substring, or RegExp tested against user input
+	 * @param response - The text to stream back, or a zero-arg function that returns it
+	 *
+	 * @example
+	 * conversation.stub('hello', 'Hi there!')
+	 * conversation.stub(/weather/i, () => 'Sunny and 72°F.')
+	 */
+	stub(matcher: string | RegExp, response: string | (() => string)): this {
+		this._stubs.push({ matcher, response })
+		return this
+	}
+
 	/** Returns configured remote MCP servers keyed by server label. */
 	get mcpServers(): Record<string, ConversationMCPServer> {
 		return (this.options.mcpServers || {}) as Record<string, ConversationMCPServer>
@@ -286,6 +305,30 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 		return this.state.get('messages') || []
 	}
 
+	/**
+	 * Fork the conversation into a new independent instance.
+	 * The fork inherits the same system prompt, tools, and full message history,
+	 * but has its own identity and state — changes in either direction do not affect the other.
+	 *
+	 * @param overrides - Optional option overrides for the forked conversation (e.g. different model or title)
+	 *
+	 * @example
+	 * ```typescript
+	 * const fork = conversation.fork()
+	 * await fork.ask('What if we took a different approach?')
+	 * // original conversation is unchanged
+	 * ```
+	 */
+	fork(overrides: Partial<ConversationOptions> = {}): Conversation {
+		return this.container.feature('conversation', {
+			...this.options,
+			id: undefined,
+			history: JSON.parse(JSON.stringify(this.messages)),
+			tools: { ...this.tools },
+			...overrides,
+		})
+	}
+
 	/** Returns the OpenAI model name being used for completions. */
 	get model(): string {
 		return this.state.get('model')!
@@ -518,6 +561,11 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 		this.emit('userMessage', content)
 
 		try {
+			const stubText = this._matchStub(typeof content === 'string' ? content : '')
+			if (stubText !== null) {
+				return await this._streamStub(stubText)
+			}
+
 			let raw: string
 
 			if (this.apiMode === 'responses') {
@@ -764,6 +812,50 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 		}
 	}
 
+	/** Check registered stubs against user input. Returns the response text, or null if no match. */
+	private _matchStub(input: string): string | null {
+		for (const { matcher, response } of this._stubs) {
+			const matched = typeof matcher === 'string'
+				? input === matcher || input.includes(matcher)
+				: matcher.test(input)
+			if (matched) {
+				return typeof response === 'function' ? response() : response
+			}
+		}
+		return null
+	}
+
+	/**
+	 * Simulate a streaming response for a hardcoded stub text.
+	 * Emits chunk/preview events word-by-word, yielding between each to keep the event loop alive.
+	 */
+	private async _streamStub(text: string): Promise<string> {
+		this.state.set('streaming', true)
+		this.emit('turnStart', { turn: 1, isFollowUp: false })
+
+		let accumulated = ''
+		const chunks = text.match(/\S+\s*/g) ?? [text]
+
+		try {
+			for (const chunk of chunks) {
+				accumulated += chunk
+				this.emit('chunk', chunk)
+				this.emit('preview', accumulated)
+				await Promise.resolve()
+			}
+		} finally {
+			this.state.set('streaming', false)
+		}
+
+		const trimmed = text
+		this.pushMessage({ role: 'assistant', content: trimmed })
+		this.state.set('lastResponse', trimmed)
+		this.emit('turnEnd', { turn: 1, hasToolCalls: false })
+		this.emit('response', trimmed)
+
+		return trimmed
+	}
+
 	/**
 	 * Runs the streaming Responses API loop. Handles local function calls by
 	 * executing handlers and submitting `function_call_output` items until

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

@@ -1,6 +1,7 @@
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
-import { type AvailableFeatures, Feature } from '@soederpop/luca/feature'
+import { type AvailableFeatures } from '@soederpop/luca/feature'
+import { Feature } from '../feature.js'
 import type { ContentDb } from '@/node.js'
 import type Assistant from './assistant.js'
 

package/src/agi/features/file-tools.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
-import { Feature } from '@soederpop/luca/feature'
+import { Feature } from '../feature.js'
 import type { FS } from '../../node/features/fs.js'
 import type { Grep, GrepMatch } from '../../node/features/grep.js'
 import type { Helper } from '../../helper.js'
@@ -38,7 +38,7 @@ export class FileTools extends Feature {
 
 	static { Feature.register(this, 'fileTools') }
 
-	static tools: Record<string, { schema: z.ZodType; description?: string }> = {
+	static override tools: Record<string, { schema: z.ZodType; description?: string }> = {
 		readFile: {
 			description: 'Read the contents of a file. Returns the text content. Use offset/limit to read portions of large files.',
 			schema: z.object({

package/src/agi/features/luca-coder.ts

@@ -1,7 +1,6 @@
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
-import { Feature } from '@soederpop/luca/feature'
-import type { AGIContainer } from '../container.server.js'
+import { Feature } from '../feature.js'
 import type { Assistant } from './assistant.js'
 import type { ToolCallCtx } from '../lib/interceptor-chain.js'
 
@@ -214,9 +213,6 @@ export class LucaCoder extends Feature<LucaCoderState, LucaCoderOptions> {
 		}
 	}
 
-	override get container(): AGIContainer {
-		return super.container as AGIContainer
-	}
 
 	/** The inner assistant. Throws if not started. */
 	get assistant(): Assistant {

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

@@ -2,7 +2,7 @@
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
 import { type AvailableFeatures } from '@soederpop/luca/feature'
-import { Feature } from '@soederpop/luca/feature'
+import { Feature } from '../feature.js'
 
 declare module '@soederpop/luca/feature' {
   interface AvailableFeatures {

package/src/agi/features/openapi.ts

@@ -1,4 +1,4 @@
-import { Feature } from '../../feature.js'
+import { Feature } from '../feature.js'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
 import { z } from 'zod'
 import { camelCase } from 'lodash-es'
@@ -95,7 +95,7 @@ export interface OpenAIToolDef {
  * api.endpoint('getPetById')
  *
  * // Convert to OpenAI tool definitions
- * api.toTools()
+ * api.toOpenAITools()
  *
  * // Convert a single endpoint to a function definition
  * api.toFunction('getPetById')
@@ -205,7 +205,7 @@ export class OpenAPI extends Feature<OpenAPIState, OpenAPIOptions> {
    * @param {Function} [filter] - Optional predicate to select which endpoints to include
    * @returns {OpenAIToolDef[]} Array of tool definitions ready for the OpenAI tools parameter
    */
-  toTools(filter?: (ep: EndpointInfo) => boolean): OpenAIToolDef[] {
+  toOpenAITools(filter?: (ep: EndpointInfo) => boolean): OpenAIToolDef[] {
     const eps = filter ? this.endpoints.filter(filter) : this.endpoints
     return eps.map((ep) => ({
       type: 'function' as const,

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

@@ -1,9 +1,10 @@
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
-import { type AvailableFeatures, Feature } from '@soederpop/luca/feature'
+import { type AvailableFeatures } from '@soederpop/luca/feature'
+import { Feature } from '../feature.js'
 import { parse } from 'contentbase'
 import type { DocsReader } from './docs-reader.js'
-import type Assistant from './assistant.js'
+import Assistant from './assistant.js'
 
 declare module '@soederpop/luca/feature' {
 	interface AvailableFeatures {
@@ -72,7 +73,7 @@ export class SkillsLibrary extends Feature<SkillsLibraryState, SkillsLibraryOpti
 	static { Feature.register(this, 'skillsLibrary') }
 
 	/** Tools for assistant integration via assistant.use(skillsLibrary). */
-	static tools: Record<string, { schema: z.ZodType; handler?: Function }> = {
+	static override tools: Record<string, { schema: z.ZodType; handler?: Function }> = {
 		searchAvailableSkills: {
 			schema: z.object({
 				query: z.string().optional().describe('Optional search term to filter skills by name or description'),
@@ -102,9 +103,46 @@ export class SkillsLibrary extends Feature<SkillsLibraryState, SkillsLibraryOpti
 		}
 	}
 	
-	override setupToolsConsumer(assistant: Assistant) {
-		console.log('setting up tools consumer', assistant.uuid)
-		assistant.state.set('toolsSetup', true)
+	override setupToolsConsumer(assistant: Feature) {
+		if (!(assistant instanceof Assistant)) {
+			throw new Error('Skills library tools require an Assistant instance (including subclasses).')
+		}
+		
+		const a : Assistant = assistant as Assistant
+		
+		const { container } = a
+		
+		const skillsLibrary = this
+		
+		const preloadSkills : string[] = []
+		if (a.meta.skills) {
+			if (Array.isArray(a.meta.skills)) {
+				preloadSkills.push(...a.meta.skills)
+			} else {
+				preloadSkills.push(a.meta.skills)
+			}
+		}
+
+		async function beforeAskCheckIfWeNeedSkills(ctx: any, next: any) {
+				const { question } = ctx
+				const skills = await skillsLibrary.findRelevantSkillsForAssistant(a, question as string)
+				
+				const allSkillsToLoad : string[] = container.utils.lodash.uniq([
+					...skills,
+					...preloadSkills,
+				])
+				
+				if (allSkillsToLoad.length) {
+					ctx.question = `${ctx.question} \n\n## Required Skills\nYou will need to load the following skills to answer this question: ${skills.join(', ')}`
+				}
+				
+				a.interceptors.beforeAsk.remove(beforeAskCheckIfWeNeedSkills)
+
+				await next()	
+		}
+
+		assistant.intercept('beforeAsk', beforeAskCheckIfWeNeedSkills as any)
+		
 		return assistant
 	}
 
@@ -375,6 +413,49 @@ export class SkillsLibrary extends Feature<SkillsLibraryState, SkillsLibraryOpti
 		const answer = await reader.ask(question)
 		return answer
 	}
+
+	/**
+	 * Fork the given assistant and ask it which skills (if any) are relevant
+	 * to the user's query. Returns an array of skill names that should be loaded
+	 * before the real question is answered.
+	 *
+	 * The fork is ephemeral (historyMode: 'none') and uses structured output so
+	 * the result is always a clean string array — never free text.
+	 *
+	 * @param assistant - The assistant instance to fork
+	 * @param userQuery - The user's original question
+	 * @returns Array of skill names relevant to the query (may be empty)
+	 */
+	async findRelevantSkillsForAssistant(assistant: Assistant, userQuery: string): Promise<string[]> {
+		if (!this.isStarted) await this.start()
+
+		const skills = this.list()
+		if (skills.length === 0) return []
+
+		const responseSchema = z.object({
+			skills: z.array(z.string()).describe('Names of skills relevant to the query. Empty array if none apply.'),
+		})
+	
+		const skillsDescription = Object.entries(this.skillsTable)
+			.map(([title,description]) => `- **${title}**: ${description}`)
+			.join("\n")
+
+		const prompt = this.container.ui.endent(`You are a routing assistant. Given a user query and a list of available skills, determine which skills (if any) should be loaded to help answer the query.
+Available skills:
+-------
+${skillsDescription}
+
+User query: ${userQuery}
+
+Return only the skill names that are directly relevant. Return an empty array if none apply. Do not load skills speculatively — only include ones that would materially help answer this specific query.`)
+			
+			const fork = assistant.conversation.fork()
+			const result = await fork.ask(prompt, { schema: responseSchema }) as unknown as { skills: string[] }
+			
+			console.log('Got a result', result)
+
+			return result.skills.filter(name => this.find(name) !== undefined)
+	}
 }
 
 export default SkillsLibrary

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

@@ -26,6 +26,16 @@ export class InterceptorChain<T> {
 		return this.fns.length
 	}
 
+	clear(): void {
+		this.fns = []
+	}
+
+	clone(): InterceptorChain<T> {
+		const copy = new InterceptorChain<T>()
+		for (const fn of this.fns) copy.add(fn)
+		return copy
+	}
+
 	async run(ctx: T, final: () => Promise<void>): Promise<void> {
 		let index = 0
 		const fns = this.fns

package/src/agi/lib/token-counter.ts

@@ -39,7 +39,7 @@ export function getContextWindow(model: string): number {
 		}
 	}
 
-	return best ? MODEL_CONTEXT_WINDOWS[best] : DEFAULT_CONTEXT_WINDOW
+	return best ? MODEL_CONTEXT_WINDOWS[best] ?? DEFAULT_CONTEXT_WINDOW : DEFAULT_CONTEXT_WINDOW
 }
 
 /** Get a cached tiktoken encoder for a model (falls back to o200k_base). */