@soederpop/luca 0.0.2

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

@@ -0,0 +1,425 @@
+import { z } from 'zod'
+import path from 'path'
+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 type { Container } from '@soederpop/luca/container'
+import { type AvailableFeatures, features, Feature } from '@soederpop/luca/feature'
+import { Collection, defineModel } from 'contentbase'
+import type { ConversationTool } from './conversation'
+
+declare module '@soederpop/luca/feature' {
+	interface AvailableFeatures {
+		skillsLibrary: typeof SkillsLibrary
+	}
+}
+
+export interface SkillEntry {
+	/** Skill name from frontmatter */
+	name: string
+	/** Skill description from frontmatter */
+	description: string
+	/** Markdown body (instructions) */
+	body: string
+	/** Raw content including frontmatter */
+	raw: string
+	/** Which collection this came from */
+	source: 'project' | 'user'
+	/** Directory/path id within its collection */
+	pathId: string
+	/** All frontmatter metadata */
+	meta: Record<string, unknown>
+}
+
+const SkillMetaSchema = z.object({
+	name: z.string().describe('Unique name identifier for the skill'),
+	description: z.string().describe('What the skill does and when to use it'),
+	version: z.string().optional().describe('Skill version'),
+	tags: z.array(z.string()).optional().describe('Tags for categorization'),
+	author: z.string().optional().describe('Skill author'),
+	license: z.string().optional().describe('Skill license'),
+})
+
+const SkillModel = defineModel('Skill', {
+	meta: SkillMetaSchema as any,
+	match: (doc: { id: string; meta: Record<string, unknown> }) =>
+		doc.id.endsWith('/SKILL') || doc.id === 'SKILL',
+})
+
+export const SkillsLibraryStateSchema = FeatureStateSchema.extend({
+	loaded: z.boolean().describe('Whether both collections have been loaded'),
+	projectSkillCount: z.number().describe('Number of skills in the project collection'),
+	userSkillCount: z.number().describe('Number of skills in the user-level collection'),
+	totalSkillCount: z.number().describe('Total number of skills across both collections'),
+})
+
+export const SkillsLibraryOptionsSchema = FeatureOptionsSchema.extend({
+	/** Path to project-level skills directory. Defaults to .claude/skills relative to container cwd. */
+	projectSkillsPath: z.string().optional().describe('Path to project-level skills directory'),
+	/** Path to user-level skills directory. Defaults to ~/.luca/skills. */
+	userSkillsPath: z.string().optional().describe('Path to user-level global skills directory'),
+})
+
+export type SkillsLibraryState = z.infer<typeof SkillsLibraryStateSchema>
+export type SkillsLibraryOptions = z.infer<typeof SkillsLibraryOptionsSchema>
+
+/**
+ * Manages two contentbase collections of skills following the Claude Code SKILL.md format.
+ * Project-level skills live in .claude/skills/ and user-level skills live in ~/.luca/skills/.
+ * Skills can be discovered, searched, created, updated, and removed at runtime.
+ *
+ * @extends Feature
+ *
+ * @example
+ * ```typescript
+ * const skills = container.feature('skillsLibrary')
+ * await skills.load()
+ *
+ * // List and search
+ * const allSkills = skills.list()
+ * const matches = skills.search('code review')
+ *
+ * // Create a new skill
+ * await skills.create({
+ *   name: 'summarize',
+ *   description: 'Summarize a document',
+ *   body: '## Instructions\nRead the document and produce a concise summary.'
+ * })
+ * ```
+ */
+export class SkillsLibrary extends Feature<SkillsLibraryState, SkillsLibraryOptions> {
+	static override stateSchema = SkillsLibraryStateSchema
+	static override optionsSchema = SkillsLibraryOptionsSchema
+	static override shortcut = 'features.skillsLibrary' as const
+
+	private _projectCollection?: Collection
+	private _userCollection?: Collection
+
+	static attach(container: Container<AvailableFeatures, any>) {
+		features.register('skillsLibrary', SkillsLibrary)
+		return container
+	}
+
+	/** @returns Default state with loaded=false and zero skill counts across both collections. */
+	override get initialState(): SkillsLibraryState {
+		return {
+			...super.initialState,
+			loaded: false,
+			projectSkillCount: 0,
+			userSkillCount: 0,
+			totalSkillCount: 0,
+		}
+	}
+
+	/** Returns the project-level contentbase Collection, lazily initialized. */
+	get projectCollection(): Collection {
+		if (this._projectCollection) return this._projectCollection
+		const rootPath =
+			this.options.projectSkillsPath ||
+			(this.container as any).paths.resolve('.claude', 'skills')
+		this._projectCollection = new Collection({ rootPath, extensions: ['md'] })
+		this._projectCollection.register(SkillModel)
+		return this._projectCollection
+	}
+
+	/** Returns the user-level contentbase Collection, lazily initialized. */
+	get userCollection(): Collection {
+		if (this._userCollection) return this._userCollection
+		const rootPath =
+			this.options.userSkillsPath || path.resolve(os.homedir(), '.luca', 'skills')
+		this._userCollection = new Collection({ rootPath, extensions: ['md'] })
+		this._userCollection.register(SkillModel)
+		return this._userCollection
+	}
+
+	/** Whether the skills library has been loaded. */
+	get isLoaded(): boolean {
+		return !!this.state.get('loaded')
+	}
+
+	/** Array of all skill names across both collections. */
+	get skillNames(): string[] {
+		return this.list().map((s) => s.name)
+	}
+
+	/**
+	 * Loads both project and user skill collections from disk.
+	 * Gracefully handles missing directories.
+	 *
+	 * @returns {Promise<SkillsLibrary>} This instance
+	 */
+	async load(): Promise<SkillsLibrary> {
+		if (this.isLoaded) return this
+
+		try {
+			await this.projectCollection.load()
+		} catch {
+			// Directory doesn't exist yet - zero project skills
+		}
+
+		try {
+			await this.userCollection.load()
+		} catch {
+			// Directory doesn't exist yet - zero user skills
+		}
+
+		this.updateCounts()
+		this.state.set('loaded', true)
+		this.emit('loaded')
+		return this
+	}
+
+	/**
+	 * Lists all skills from both collections. Project skills come first.
+	 *
+	 * @returns {SkillEntry[]} All available skills
+	 */
+	list(): SkillEntry[] {
+		const projectSkills = this.listFromCollection(this.projectCollection, 'project')
+		const userSkills = this.listFromCollection(this.userCollection, 'user')
+		return [...projectSkills, ...userSkills]
+	}
+
+	/**
+	 * Finds a skill by name. Project skills take precedence over user skills.
+	 *
+	 * @param {string} name - The skill name to find (case-insensitive)
+	 * @returns {SkillEntry | undefined} The skill entry, or undefined if not found
+	 */
+	find(name: string): SkillEntry | undefined {
+		const lower = name.toLowerCase()
+		return this.list().find((s) => s.name.toLowerCase() === lower)
+	}
+
+	/**
+	 * Searches skills by substring match against name and description.
+	 *
+	 * @param {string} query - The search query
+	 * @returns {SkillEntry[]} Matching skills
+	 */
+	search(query: string): SkillEntry[] {
+		const q = query.toLowerCase()
+		return this.list().filter(
+			(s) =>
+				s.name.toLowerCase().includes(q) || s.description.toLowerCase().includes(q)
+		)
+	}
+
+	/**
+	 * Gets a skill by name. Alias for find().
+	 *
+	 * @param {string} name - The skill name
+	 * @returns {SkillEntry | undefined} The skill entry
+	 */
+	getSkill(name: string): SkillEntry | undefined {
+		return this.find(name)
+	}
+
+	/**
+	 * Creates a new SKILL.md file in the specified collection.
+	 * Maintains the directory-per-skill structure (skill-name/SKILL.md).
+	 *
+	 * @param {object} skill - The skill to create
+	 * @param {'project' | 'user'} target - Which collection to write to (default: 'project')
+	 * @returns {Promise<SkillEntry>} The created skill entry
+	 */
+	async create(
+		skill: {
+			name: string
+			description: string
+			body: string
+			meta?: Record<string, unknown>
+		},
+		target: 'project' | 'user' = 'project'
+	): Promise<SkillEntry> {
+		const collection =
+			target === 'project' ? this.projectCollection : this.userCollection
+
+		const frontmatter = (yaml.dump({
+			name: skill.name,
+			description: skill.description,
+			...skill.meta,
+		}) as string).trim()
+
+		const content = `---\n${frontmatter}\n---\n\n${skill.body}`
+		const dirName = kebabCase(skill.name)
+		const pathId = `${dirName}/SKILL`
+
+		await fs.mkdir((collection as any).rootPath, { recursive: true })
+		await collection.saveItem(pathId, { content, extension: '.md' })
+		await collection.load({ refresh: true })
+		this.updateCounts()
+
+		const entry: SkillEntry = {
+			name: skill.name,
+			description: skill.description,
+			body: skill.body,
+			raw: content,
+			source: target,
+			pathId,
+			meta: { name: skill.name, description: skill.description, ...skill.meta },
+		}
+
+		this.emit('skillCreated', entry)
+		return entry
+	}
+
+	/**
+	 * Updates an existing skill's content or metadata.
+	 *
+	 * @param {string} name - The skill name to update
+	 * @param {object} updates - Fields to update
+	 * @returns {Promise<SkillEntry>} The updated skill entry
+	 */
+	async update(
+		name: string,
+		updates: {
+			description?: string
+			body?: string
+			meta?: Record<string, unknown>
+		}
+	): Promise<SkillEntry> {
+		const existing = this.find(name)
+		if (!existing) throw new Error(`Skill "${name}" not found`)
+
+		const collection =
+			existing.source === 'project' ? this.projectCollection : this.userCollection
+
+		const newMeta = { ...existing.meta, ...updates.meta }
+		if (updates.description) newMeta.description = updates.description
+
+		const frontmatter = (yaml.dump(newMeta) as string).trim()
+		const body = updates.body ?? existing.body
+		const content = `---\n${frontmatter}\n---\n\n${body}`
+
+		await collection.saveItem(existing.pathId, { content, extension: '.md' })
+		await collection.load({ refresh: true })
+		this.updateCounts()
+
+		const entry: SkillEntry = {
+			name: existing.name,
+			description: updates.description ?? existing.description,
+			body,
+			raw: content,
+			source: existing.source,
+			pathId: existing.pathId,
+			meta: newMeta,
+		}
+
+		this.emit('skillUpdated', entry)
+		return entry
+	}
+
+	/**
+	 * Removes a skill by name, deleting its SKILL.md and cleaning up the directory.
+	 *
+	 * @param {string} name - The skill name to remove
+	 * @returns {Promise<boolean>} Whether the skill was found and removed
+	 */
+	async remove(name: string): Promise<boolean> {
+		const existing = this.find(name)
+		if (!existing) return false
+
+		const collection =
+			existing.source === 'project' ? this.projectCollection : this.userCollection
+
+		await collection.deleteItem(existing.pathId)
+
+		const skillDir = path.resolve(
+			(collection as any).rootPath,
+			existing.pathId.split('/')[0]!
+		)
+		try {
+			await fs.rm(skillDir, { recursive: true })
+		} catch {
+			// directory might have other files or already be gone
+		}
+
+		await collection.load({ refresh: true })
+		this.updateCounts()
+		this.emit('skillRemoved', existing.name)
+		return true
+	}
+
+	/**
+	 * Converts all skills into ConversationTool format for use with Conversation.
+	 * Each skill becomes a tool that returns its instruction body when invoked.
+	 *
+	 * @returns {Record<string, ConversationTool>} Tools keyed by sanitized skill name
+	 */
+	toConversationTools(): Record<string, ConversationTool> {
+		const tools: Record<string, ConversationTool> = {}
+
+		for (const skill of this.list()) {
+			const toolName = `skill_${skill.name.replace(/[^a-zA-Z0-9_]/g, '_')}`
+			tools[toolName] = {
+				handler: async () => skill.body,
+				description: skill.description,
+				parameters: {
+					type: 'object',
+					properties: {},
+				},
+			}
+		}
+
+		return tools
+	}
+
+	/**
+	 * Generates a markdown block listing all available skills with names and descriptions.
+	 * Suitable for injecting into a system prompt.
+	 *
+	 * @returns {string} Markdown listing, or empty string if no skills
+	 */
+	toSystemPromptBlock(): string {
+		const skills = this.list()
+		if (skills.length === 0) return ''
+
+		const lines = skills.map((s) => `- **${s.name}**: ${s.description}`)
+		return `## Available Skills\n\n${lines.join('\n')}`
+	}
+
+	// --- Private ---
+
+	private listFromCollection(
+		collection: Collection,
+		source: 'project' | 'user'
+	): SkillEntry[] {
+		if (!(collection as any).loaded) return []
+
+		const entries: SkillEntry[] = []
+		for (const pathId of collection.available) {
+			if (!pathId.endsWith('/SKILL') && pathId !== 'SKILL') continue
+
+			const item = collection.items.get(pathId)!
+			entries.push({
+				name: (item.meta.name as string) || pathId.split('/')[0] || pathId,
+				description: (item.meta.description as string) || '',
+				body: item.content,
+				raw: item.raw,
+				source,
+				pathId,
+				meta: item.meta,
+			})
+		}
+
+		return entries
+	}
+
+	private updateCounts(): void {
+		const projectCount = this.listFromCollection(
+			this.projectCollection,
+			'project'
+		).length
+		const userCount = this.listFromCollection(this.userCollection, 'user').length
+		this.state.setState({
+			projectSkillCount: projectCount,
+			userSkillCount: userCount,
+			totalSkillCount: projectCount + userCount,
+		})
+	}
+}
+
+export default features.register('skillsLibrary', 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/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
+}
+
+/** 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
+}

package/src/browser.ts

@@ -0,0 +1,25 @@
+export * from './web/container.js'
+import { WebContainer } from './web/container.js'
+import './introspection/generated.web.js'
+
+const container = new WebContainer({})
+
+if (typeof window !== 'undefined') {
+  ;(window as any).luca = container
+}
+
+export default container
+
+/**
+ * Returns the singleton container instance.
+ * LLMs love to hallucinate this function — so we provide it, but warn.
+ * If you need a separate container, use `container.subcontainer()`.
+ */
+export function createContainer() {
+  console.warn(
+    '[luca] createContainer() is unnecessary — import the default export instead.\n' +
+    '       `import container from "@soederpop/luca"`\n' +
+    '       For a separate instance, use container.subcontainer().'
+  )
+  return container
+}

package/src/bus.ts

@@ -0,0 +1,100 @@
+export type EventMap = Record<string, any[]>;
+
+type Listener<Args extends any[] = any[]> = (...args: Args) => void;
+
+export interface EventStats {
+    event: string;
+    fireCount: number;
+    lastFiredAt: number | null;
+    timestamps: number[];
+    firesPerMinute: number;
+}
+
+export class Bus<T extends EventMap = EventMap> {
+    private events: Map<string, Listener[]>;
+    private stats: Map<string, { fireCount: number; lastFiredAt: number | null; timestamps: number[] }>;
+
+    constructor() {
+        this.events = new Map();
+        this.stats = new Map();
+    }
+
+    private recordEmit(event: string): void {
+        const now = Date.now();
+        const existing = this.stats.get(event) || { fireCount: 0, lastFiredAt: null, timestamps: [] };
+        existing.fireCount++;
+        existing.lastFiredAt = now;
+        existing.timestamps.push(now);
+        this.stats.set(event, existing);
+    }
+
+    private computeFiresPerMinute(timestamps: number[]): number {
+        if (timestamps.length < 2) return 0;
+        const now = Date.now();
+        const oneMinuteAgo = now - 60_000;
+        const recent = timestamps.filter(t => t >= oneMinuteAgo);
+        return recent.length;
+    }
+
+    getEventStats<E extends string & keyof T>(event: E): EventStats {
+        const raw = this.stats.get(event) || { fireCount: 0, lastFiredAt: null, timestamps: [] };
+        return {
+            event,
+            fireCount: raw.fireCount,
+            lastFiredAt: raw.lastFiredAt,
+            timestamps: raw.timestamps,
+            firesPerMinute: this.computeFiresPerMinute(raw.timestamps),
+        };
+    }
+
+    get history(): EventStats[] {
+        return Array.from(this.stats.keys()).map(event => this.getEventStats(event as any));
+    }
+
+    get firedEvents(): string[] {
+        return Array.from(this.stats.keys());
+    }
+
+    async waitFor<E extends string & keyof T>(event: E): Promise<T[E]> {
+        return new Promise(resolve => {
+            this.once(event, resolve as any);
+        });
+    }
+
+    emit<E extends string & keyof T>(event: E, ...args: T[E]): void {
+        this.recordEmit(event);
+        const listeners = this.events.get(event);
+        if (!listeners) return;
+
+        listeners.forEach(listener => listener(...args));
+    }
+
+    on<E extends string & keyof T>(event: E, listener: (...args: T[E]) => void): void {
+        const listeners = this.events.get(event) || [];
+        listeners.push(listener as Listener);
+        this.events.set(event, listeners);
+    }
+
+    once<E extends string & keyof T>(event: E, listener: (...args: T[E]) => void): void {
+        const onceListener: Listener = (...args: any[]) => {
+            (listener as Listener)(...args);
+            this.off(event, onceListener as any);
+        };
+        this.on(event, onceListener as any);
+    }
+
+    off<E extends string & keyof T>(event: E, listener?: (...args: T[E]) => void): void {
+        const listeners = this.events.get(event);
+        if (!listeners) return;
+
+        if (!listener) {
+            this.events.delete(event);
+            return;
+        }
+
+        const index = listeners.indexOf(listener as Listener);
+        if (index !== -1) {
+            listeners.splice(index, 1);
+        }
+    }
+}