luca 2.0.0 → 3.0.0

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

@@ -0,0 +1,478 @@
+import { z } from 'zod'
+import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
+import { type AvailableFeatures } from '@soederpop/luca/feature'
+import { Feature } from '../feature.js'
+import { parse } from 'contentbase'
+import type { DocsReader } from './docs-reader.js'
+import Assistant from './assistant.js'
+
+declare module '@soederpop/luca/feature' {
+	interface AvailableFeatures {
+		skillsLibrary: typeof SkillsLibrary
+	}
+}
+
+export interface SkillInfo {
+	/** Skill name derived from folder name or frontmatter */
+	name: string
+	/** Description from frontmatter */
+	description: string
+	/** Absolute path to the skill folder (dirname of SKILL.md) */
+	path: string
+	/** Absolute path to SKILL.md */
+	skillFilePath: string
+	/** Which location this skill was found in */
+	locationPath: string
+	/** All frontmatter metadata */
+	meta: Record<string, unknown>
+}
+
+export const SkillsLibraryStateSchema = FeatureStateSchema.extend({
+	loaded: z.boolean().describe('Whether skill locations have been scanned'),
+	locations: z.array(z.string()).describe('Tracked skill location folder paths'),
+	skillCount: z.number().describe('Total number of discovered skills'),
+	skills: z.record(z.string(), z.any()).describe('Discovered skills keyed by name'),
+})
+
+export const SkillsLibraryOptionsSchema = FeatureOptionsSchema.extend({
+	configPath: z.string().optional().describe('Override path for skills.json (defaults to ~/.luca/skills.json)'),
+})
+
+export const SkillsLibraryEventsSchema = FeatureEventsSchema.extend({
+	started: z.tuple([]).describe('Fired after all skill locations have been scanned'),
+	locationAdded: z.tuple([z.string().describe('The absolute path of the added location')]).describe('Fired when a new skill location is registered'),
+	skillDiscovered: z.tuple([z.any().describe('The SkillInfo object')]).describe('Fired when a skill is discovered during scanning'),
+}).describe('SkillsLibrary events')
+
+export type SkillsLibraryState = z.infer<typeof SkillsLibraryStateSchema>
+export type SkillsLibraryOptions = z.infer<typeof SkillsLibraryOptionsSchema>
+
+/**
+ * Manages a registry of skill locations — folders containing SKILL.md files.
+ *
+ * Persists known locations to ~/.luca/skills.json and scans them on start.
+ * Each skill folder can be opened as a DocsReader for AI-assisted Q&A.
+ * Exposes tools for assistant integration via assistant.use(skillsLibrary).
+ *
+ * @extends Feature
+ * @example
+ * ```typescript
+ * const lib = container.feature('skillsLibrary')
+ * await lib.start()
+ * await lib.addLocation('~/.claude/skills')
+ * lib.list() // => SkillInfo[]
+ * const reader = lib.createSkillReader('my-skill')
+ * ```
+ */
+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') }
+
+	/** Tools for assistant integration via assistant.use(skillsLibrary). */
+	static override tools: Record<string, { schema: z.ZodType; handler?: Function }> = {
+		searchAvailableSkills: {
+			schema: z.object({
+				query: z.string().optional().describe('A keyword or phrase to filter skills by name or description. Omit to list all available skills.'),
+			}).describe('Discover what skills are available. Call this first when you need specialized knowledge — skills are curated guides and reference material for specific domains (frameworks, tools, patterns). Returns skill names and descriptions so you can decide which to load.'),
+		},
+		loadSkill: {
+			schema: z.object({
+				skillName: z.string().describe('The exact skill name as returned by searchAvailableSkills'),
+			}).describe('Load a skill\'s full reference content (SKILL.md). This gives you detailed guidance, examples, and best practices for that domain. Load a skill before attempting work in an unfamiliar area — the content is curated to prevent common mistakes.'),
+		},
+		askSkillBasedQuestion: {
+			schema: z.object({
+				skillName: z.string().describe('The exact skill name to query'),
+				question: z.string().describe('A specific question about the skill\'s domain. Be precise — "how do I add a new feature to the container?" is better than "tell me about features".'),
+			}).describe('Ask a focused question about a skill\'s domain using AI-assisted document reading. Use this when you need a specific answer from a skill rather than reading the whole thing. More efficient than loadSkill for targeted lookups.'),
+		},
+	}
+
+	/** @returns Default state. */
+	override get initialState(): SkillsLibraryState {
+		return {
+			...super.initialState,
+			started: false,
+			locations: [],
+			skillCount: 0,
+			skills: {},
+		}
+	}
+	
+	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
+
+		a.addSystemPromptExtension('skillsLibrary', [
+			'## Skills Library',
+			'',
+			'You have access to a library of curated skills — domain-specific reference guides with examples, patterns, and best practices.',
+			'',
+			'**When to use skills:**',
+			'- When working in an unfamiliar domain or framework — load the skill before writing code',
+			'- When the user asks about a topic that might have a matching skill — search first',
+			'- When you see "Required Skills" in a message — load those skills immediately with `loadSkill` before answering',
+			'',
+			'**Workflow:** `searchAvailableSkills` → find relevant skill → `loadSkill` to get the full guide → follow its patterns. Use `askSkillBasedQuestion` for targeted lookups when you don\'t need the whole guide.',
+			'',
+			'**Skills are authoritative.** When a loaded skill contradicts your general knowledge, follow the skill — it reflects project-specific conventions and decisions.',
+		].join('\n'))
+		
+		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
+	}
+
+	/** Discovered skills keyed by name. */
+	get skills(): Record<string, SkillInfo> {
+		return (this.state.get('skills') || {}) as Record<string, SkillInfo>
+	}
+	
+	get availableSkills() {
+		return Object.keys(this.skills)
+	}
+	
+	get skillsTable() : Record<string, string> {
+		const skills = this.skills
+
+		return Object.fromEntries(
+			Object.keys(skills).map((name) => [name, this.skills[name]!.description])
+		)
+	}
+
+	/** Resolved path to the skills.json config file. */
+	get configPath(): string {
+		if (this.options.configPath) return this.options.configPath
+		const { os, paths } = this.container
+		return paths.resolve(os.homedir, '.luca', 'skills.json')
+	}
+
+	/** Whether the library has been loaded. */
+	get isStarted(): boolean {
+		return !!this.state.get('started')
+	}
+	
+	/** Expand ~ to home directory in a path. */
+	private expandHome(p: string): string {
+		return p.replace(/^\~/, this.container.os.homedir)
+	}
+
+	/** Read the persisted config, creating it if it doesn't exist. */
+	private readConfig(): { locations: string[] } {
+		const { fs } = this.container
+
+		if (!fs.exists(this.configPath)) {
+			const defaultConfig = { locations: [] as string[] }
+			this.writeConfig(defaultConfig)
+			return defaultConfig
+		}
+
+		return fs.readJson(this.configPath)
+	}
+
+	/** Write the config back to disk. */
+	private writeConfig(config: { locations: string[] }): void {
+		const { fs, os, paths } = this.container
+		fs.mkdirp(paths.resolve(os.homedir, '.luca'))
+		fs.writeJson(this.configPath, config, 2)
+	}
+
+	/**
+	 * Start the skills library: read config, scan all locations.
+	 *
+	 * @returns This instance for chaining
+	 */
+	async start(): Promise<SkillsLibrary> {
+		if (this.isStarted) return this
+
+	  const { uniq } = this.container.utils.lodash
+		const config = this.readConfig()
+		const configLocations = config.locations.map(l => this.expandHome(l))
+		const allLocations = uniq([
+			...configLocations,
+			(this.container as any).paths.resolve((this.container as any).os.homedir, '.claude', 'skills'),
+			(this.container as any).paths.resolve((this.container as any).cwd, '.claude', 'skills')
+		]).filter(Boolean).filter(l => (this.container as any).fs.exists(l))
+		this.state.set('locations', allLocations)
+
+		for (const loc of allLocations) {
+			await this.scanLocation(loc)
+		}
+
+		this.state.set('started', true)
+		this.state.set('skillCount', Object.keys(this.skills).length)
+		this.emit('started')
+
+		return this
+	}
+
+	/**
+	 * Add a new skill location folder and scan it for skills.
+	 *
+	 * @param locationPath - Path to a directory containing skill subfolders with SKILL.md
+	 */
+	async addLocation(locationPath: string): Promise<void> {
+		const resolved = this.expandHome(locationPath)
+		const current = this.state.get('locations') as string[]
+
+		if (current.includes(resolved)) return
+
+		const updated = [...current, resolved]
+		this.state.set('locations', updated)
+
+		// Persist — store the original (unexpanded) path for portability
+		const config = this.readConfig()
+		if (!config.locations.includes(locationPath)) {
+			config.locations.push(locationPath)
+			this.writeConfig(config)
+		}
+
+		await this.scanLocation(resolved)
+		this.state.set('skillCount', Object.keys(this.skills).length)
+		this.emit('locationAdded', resolved)
+	}
+
+	/**
+	 * Remove a skill location and its skills from the library.
+	 *
+	 * @param locationPath - The location path to remove
+	 */
+	async removeLocation(locationPath: string): Promise<void> {
+		const resolved = this.expandHome(locationPath)
+		const current = this.state.get('locations') as string[]
+		this.state.set('locations', current.filter(l => l !== resolved))
+
+		// Remove skills from this location
+		const remaining: Record<string, SkillInfo> = {}
+		for (const [name, info] of Object.entries(this.skills)) {
+			if (info.locationPath !== resolved) {
+				remaining[name] = info
+			}
+		}
+		this.state.set('skills', remaining)
+		this.state.set('skillCount', Object.keys(remaining).length)
+
+		// Persist
+		const config = this.readConfig()
+		config.locations = config.locations.filter(l => this.expandHome(l) !== resolved)
+		this.writeConfig(config)
+	}
+
+	/**
+	 * Scan a location folder for skill subfolders containing SKILL.md.
+	 *
+	 * @param locationPath - Absolute path to scan
+	 */
+	async scanLocation(locationPath: string): Promise<void> {
+		const { fs, paths } = this.container
+		if (!fs.exists(locationPath)) return
+
+		const entries = fs.readdirSync(locationPath)
+
+		for (const entry of entries) {
+			const skillDir = paths.resolve(locationPath, entry)
+			const skillFile = paths.resolve(skillDir, 'SKILL.md')
+
+			if (!fs.exists(skillFile)) continue
+
+			try {
+				const parsed = await parse(skillFile)
+				const meta = (parsed.meta || {}) as Record<string, unknown>
+				const name = entry
+
+				const info: SkillInfo = {
+					name,
+					description: (meta.description as string) || '',
+					path: skillDir,
+					skillFilePath: skillFile,
+					locationPath,
+					meta,
+				}
+
+				this.state.set('skills', { ...this.skills, [name]: info })
+				this.emit('skillDiscovered', info)
+			} catch {
+				// Skip unparseable skill files
+			}
+		}
+	}
+
+	/** Return all discovered skills. */
+	list(): SkillInfo[] {
+		return Object.values(this.skills)
+	}
+
+	/** Find a skill by name. */
+	find(skillName: string): SkillInfo | undefined {
+		return this.skills[skillName]
+	}
+
+	/**
+	 * Create a DocsReader for a skill's folder, enabling AI-assisted Q&A.
+	 *
+	 * @param skillName - Name of the skill to create a reader for
+	 * @returns A DocsReader instance rooted at the skill's folder
+	 */
+	createSkillReader(skillName: string): DocsReader {
+		const skill = this.find(skillName)
+		if (!skill) throw new Error(`Skill "${skillName}" not found in the library`)
+
+		return this.container.feature('docsReader', { contentDb: skill.path })
+	}
+
+	/**
+	 * Create a tmp directory containing symlinked/copied skill folders by name,
+	 * suitable for passing to claude --add-dir.
+	 *
+	 * @param skillNames - Array of skill names to include
+	 * @returns Absolute path to the created directory
+	 */
+	ensureFolderCreatedWithSkillsByName(skillNames: string[]): string {
+		const { fs, paths, os } = this.container
+		const hash = this.container.utils.hashObject(skillNames.sort())
+		const dir = paths.resolve(os.tmpdir, 'luca-skills', hash)
+
+		if (fs.exists(dir)) return dir
+
+		fs.mkdirp(dir)
+
+		for (const name of skillNames) {
+			const skill = this.find(name)
+			if (!skill) throw new Error(`Skill "${name}" not found in the library`)
+
+			const dest = paths.resolve(dir, name)
+			if (!fs.exists(dest)) {
+				fs.copy(skill.path, dest)
+			}
+		}
+
+		return dir
+	}
+
+	// --- Tool handlers for assistant.use(skillsLibrary) ---
+
+	/** Search available skills, optionally filtered by a query string. */
+	async searchAvailableSkills({ query }: { query?: string } = {}): Promise<string> {
+		if (!this.isStarted) await this.start()
+
+		let skills = this.list()
+
+		if (query) {
+			const q = query.toLowerCase()
+			skills = skills.filter(s =>
+				s.name.toLowerCase().includes(q) ||
+				s.description.toLowerCase().includes(q)
+			)
+		}
+
+		if (skills.length === 0) return 'No skills found.'
+
+		return skills.map(s => `- **${s.name}**: ${s.description || '(no description)'}\n  Path: ${s.path}`).join('\n')
+	}
+
+	/** Load a skill's full SKILL.md content and metadata. */
+	async loadSkill({ skillName }: { skillName: string }): Promise<string> {
+		if (!this.isStarted) await this.start()
+
+		const skill = this.find(skillName)
+		if (!skill) return `Skill "${skillName}" not found.`
+
+		const content = this.container.fs.readFile(skill.skillFilePath)
+
+		return `# Skill: ${skill.name}\n\n**Description:** ${skill.description}\n**Path:** ${skill.path}\n\n---\n\n${content}`
+	}
+
+	/** Ask a question about a specific skill using a DocsReader. */
+	async askSkillBasedQuestion({ skillName, question }: { skillName: string; question: string }): Promise<string> {
+		if (!this.isStarted) await this.start()
+
+		const reader = this.createSkillReader(skillName)
+		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[] }
+
+			const found = result.skills.filter(name => this.find(name) !== undefined)
+			
+			this.emit('foundSkills', found, assistant, userQuery)
+			
+			return found
+	}
+}
+
+export default SkillsLibrary

package/src/agi/index.ts

@@ -0,0 +1,6 @@
+import container from './container.server'
+import type { AGIContainer } from './container.server'
+
+export * from './container.server'
+
+export default container as AGIContainer

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

@@ -0,0 +1,89 @@
+/**
+ * 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
+	}
+
+	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
+
+		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

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

@@ -0,0 +1,122 @@
+import { encodingForModel, getEncoding } from 'js-tiktoken'
+import type { Tiktoken } from 'js-tiktoken'
+
+/**
+ * Known model context window sizes. Prefix-matched for dated variants
+ * (e.g. "gpt-4o-2024-08-06" matches "gpt-4o").
+ */
+const MODEL_CONTEXT_WINDOWS: Record<string, number> = {
+	'gpt-4.1': 1_000_000,
+	'gpt-4.1-mini': 1_000_000,
+	'gpt-4.1-nano': 1_000_000,
+	'gpt-4o': 128_000,
+	'gpt-4o-mini': 128_000,
+	'gpt-4-turbo': 128_000,
+	'gpt-4': 8_192,
+	'gpt-3.5-turbo': 16_385,
+	'o1': 200_000,
+	'o1-mini': 128_000,
+	'o1-pro': 200_000,
+	'o3': 200_000,
+	'o3-mini': 200_000,
+	'o4-mini': 200_000,
+	'gpt-5': 1_000_000,
+}
+
+const DEFAULT_CONTEXT_WINDOW = 128_000
+
+const encoderCache = new Map<string, Tiktoken>()
+
+/** Look up the context window size for a model name (exact then prefix match). */
+export function getContextWindow(model: string): number {
+	if (MODEL_CONTEXT_WINDOWS[model]) return MODEL_CONTEXT_WINDOWS[model]
+
+	// Prefix match — longest prefix wins (e.g. "gpt-4o-mini" before "gpt-4o")
+	let best = ''
+	for (const key of Object.keys(MODEL_CONTEXT_WINDOWS)) {
+		if (model.startsWith(key) && key.length > best.length) {
+			best = key
+		}
+	}
+
+	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). */
+export function getEncoder(model: string): Tiktoken {
+	if (encoderCache.has(model)) return encoderCache.get(model)!
+
+	let enc: Tiktoken
+	try {
+		enc = encodingForModel(model as any)
+	} catch {
+		enc = getEncoding('o200k_base')
+	}
+
+	encoderCache.set(model, enc)
+	return enc
+}
+
+/** Count tokens in a plain string. */
+export function countTokens(text: string, model: string): number {
+	return getEncoder(model).encode(text).length
+}
+
+/**
+ * Estimate the total input token count for a messages array.
+ * Follows the OpenAI token counting recipe with per-message overhead.
+ */
+export function countMessageTokens(messages: any[], model: string): number {
+	const enc = getEncoder(model)
+	const TOKENS_PER_MESSAGE = 3 // <|start|>role\ncontent<|end|>
+	const REPLY_PRIMING = 3
+
+	let total = 0
+
+	for (const msg of messages) {
+		total += TOKENS_PER_MESSAGE
+
+		// Role
+		if (msg.role) {
+			total += enc.encode(msg.role).length
+		}
+
+		// Content
+		if (typeof msg.content === 'string') {
+			total += enc.encode(msg.content).length
+		} else if (Array.isArray(msg.content)) {
+			for (const part of msg.content) {
+				if (part.type === 'text' && part.text) {
+					total += enc.encode(part.text).length
+				} else if (part.type === 'image_url') {
+					// Rough image token estimates
+					const detail = part.image_url?.detail || 'auto'
+					total += detail === 'low' ? 85 : 170
+				} else if (part.type === 'input_audio' || part.type === 'input_file') {
+					total += 50 // rough placeholder for non-text parts
+				}
+			}
+		}
+
+		// Tool calls on assistant messages
+		if (msg.tool_calls && Array.isArray(msg.tool_calls)) {
+			for (const tc of msg.tool_calls) {
+				total += 3 // tool call overhead
+				if (tc.function?.name) {
+					total += enc.encode(tc.function.name).length
+				}
+				if (tc.function?.arguments) {
+					total += enc.encode(tc.function.arguments).length
+				}
+			}
+		}
+
+		// Name field (used on some message types)
+		if (msg.name) {
+			total += enc.encode(msg.name).length + 1
+		}
+	}
+
+	total += REPLY_PRIMING
+	return total
+}