luca 3.0.0 → 3.1.0

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

@@ -1,12 +1,12 @@
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
-import { type AvailableFeatures } from '@soederpop/luca/feature'
+import { type AvailableFeatures } from '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' {
+declare module 'luca/feature' {
 	interface AvailableFeatures {
 		skillsLibrary: typeof SkillsLibrary
 	}
@@ -36,6 +36,9 @@ export const SkillsLibraryStateSchema = FeatureStateSchema.extend({
 
 export const SkillsLibraryOptionsSchema = FeatureOptionsSchema.extend({
 	configPath: z.string().optional().describe('Override path for skills.json (defaults to ~/.luca/skills.json)'),
+	only: z.array(z.string()).optional().describe('Glob patterns to filter which skills are exposed. When set, only matching skills are available. Supports * wildcards (e.g. "luca-*", "react-ink").'),
+	locations: z.array(z.string()).optional().describe('Additional skill location directories to scan for this instance only. Not persisted to skills.json — other consumers will not see these.'),
+	useAgentsFolders: z.boolean().optional().default(false).describe('When true, automatically scan conventional agent skill folders: .claude/skills and .agents/skills in both the home directory and project cwd.'),
 })
 
 export const SkillsLibraryEventsSchema = FeatureEventsSchema.extend({
@@ -54,14 +57,21 @@ export type SkillsLibraryOptions = z.infer<typeof SkillsLibraryOptionsSchema>
  * Each skill folder can be opened as a DocsReader for AI-assisted Q&A.
  * Exposes tools for assistant integration via assistant.use(skillsLibrary).
  *
+ * No paths are scanned by default — callers must explicitly provide locations
+ * via the `locations` option or `addLocation()`. Set `useAgentsFolders: true`
+ * to automatically scan conventional agent skill folders (.claude/skills and
+ * .agents/skills in both $HOME and cwd).
+ *
  * @extends Feature
  * @example
  * ```typescript
- * const lib = container.feature('skillsLibrary')
+ * const lib = container.feature('skillsLibrary', { locations: ['./my-skills'] })
  * await lib.start()
- * await lib.addLocation('~/.claude/skills')
  * lib.list() // => SkillInfo[]
- * const reader = lib.createSkillReader('my-skill')
+ *
+ * // Or opt in to conventional agent folders:
+ * const lib2 = container.feature('skillsLibrary', { useAgentsFolders: true })
+ * await lib2.start()
  * ```
  */
 export class SkillsLibrary extends Feature<SkillsLibraryState, SkillsLibraryOptions> {
@@ -109,26 +119,55 @@ export class SkillsLibrary extends Feature<SkillsLibraryState, SkillsLibraryOpti
 		}
 
 		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 skillCount = Object.keys(this.filteredSkills).length
+		const isSmallSet = skillCount <= 10
+
+		if (!isSmallSet && !this.options.only) {
+			if (!process.env.LUCA_SKILLS_NO_WARN) {
+				container.feature('ui').print.yellow(`SkillsLibrary: ${skillCount} skills loaded with no \`only\` filter. Use container.feature('skillsLibrary', { only: ['pattern*'] }) to limit, or set LUCA_SKILLS_NO_WARN=1 to silence.`)
+			}
+		}
+
+		if (isSmallSet) {
+			const table = Object.entries(this.skillsTable)
+				.map(([name, desc]) => `- **${name}**: ${desc}`)
+				.join('\n')
+
+			a.addSystemPromptExtension('skillsLibrary', [
+				'## Skills Library',
+				'',
+				'You have access to the following curated skills — domain-specific reference guides with examples, patterns, and best practices.',
+				'',
+				'**Available skills:**',
+				table,
+				'',
+				'**When to use skills:**',
+				'- When working in an unfamiliar domain or framework — load the skill before writing code',
+				'- When you see "Required Skills" in a message — load those skills immediately with `loadSkill` before answering',
+				'',
+				'**Workflow:** Choose a skill from the list above → `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'))
+		} else {
+			a.addSystemPromptExtension('skillsLibrary', [
+				'## Skills Library',
+				'',
+				`You have access to a large library of ${skillCount} curated skills — domain-specific reference guides with examples, patterns, and best practices.`,
+				'',
+				'**When to use skills:**',
+				'- When working in an unfamiliar domain or framework — search for a 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 preloadSkills : string[] = []
 		if (a.meta.skills) {
 			if (Array.isArray(a.meta.skills)) {
@@ -138,46 +177,72 @@ export class SkillsLibrary extends Feature<SkillsLibraryState, SkillsLibraryOpti
 			}
 		}
 
-		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)
+		// Only use the fork-based auto-detection for small skill sets
+		if (isSmallSet) {
+			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: ${allSkillsToLoad.join(', ')}`
+					}
+
+					a.interceptors.beforeAsk.remove(beforeAskCheckIfWeNeedSkills)
+
+					await next()
+			}
 
-				await next()	
+			assistant.intercept('beforeAsk', beforeAskCheckIfWeNeedSkills as any)
 		}
 
-		assistant.intercept('beforeAsk', beforeAskCheckIfWeNeedSkills as any)
-		
 		return assistant
 	}
 
-	/** Discovered skills keyed by name. */
+	/** Discovered skills keyed by name (unfiltered). */
 	get skills(): Record<string, SkillInfo> {
 		return (this.state.get('skills') || {}) as Record<string, SkillInfo>
 	}
-	
+
+	/** Skills filtered by the `only` option when set. */
+	get filteredSkills(): Record<string, SkillInfo> {
+		const all = this.skills
+		const only = this.options.only
+		if (!only || only.length === 0) return all
+
+		const result: Record<string, SkillInfo> = {}
+		for (const [name, info] of Object.entries(all)) {
+			if (only.some(pattern => this.matchPattern(pattern, name))) {
+				result[name] = info
+			}
+		}
+		return result
+	}
+
 	get availableSkills() {
-		return Object.keys(this.skills)
+		return Object.keys(this.filteredSkills)
 	}
-	
+
 	get skillsTable() : Record<string, string> {
-		const skills = this.skills
+		const skills = this.filteredSkills
 
 		return Object.fromEntries(
-			Object.keys(skills).map((name) => [name, this.skills[name]!.description])
+			Object.keys(skills).map((name) => [name, skills[name]!.description])
 		)
 	}
 
+	/** Match a name against a glob pattern (* wildcards). */
+	private matchPattern(pattern: string, name: string): boolean {
+		if (pattern === '*') return true
+		if (!pattern.includes('*')) return pattern === name
+		const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')
+		return new RegExp(`^${escaped}$`).test(name)
+	}
+
 	/** Resolved path to the skills.json config file. */
 	get configPath(): string {
 		if (this.options.configPath) return this.options.configPath
@@ -226,10 +291,24 @@ export class SkillsLibrary extends Feature<SkillsLibraryState, SkillsLibraryOpti
 	  const { uniq } = this.container.utils.lodash
 		const config = this.readConfig()
 		const configLocations = config.locations.map(l => this.expandHome(l))
+		const instanceLocations = (this.options.locations || []).map(l => this.expandHome(l))
+		const agentsFolders: string[] = []
+		if (this.options.useAgentsFolders) {
+			const { paths, os, cwd } = this.container as any
+			// Check conventional agent skill locations (home + project cwd)
+			const candidates = [
+				paths.resolve(os.homedir, '.claude', 'skills'),
+				paths.resolve(os.homedir, '.agents', 'skills'),
+				paths.resolve(cwd, '.claude', 'skills'),
+				paths.resolve(cwd, '.agents', 'skills'),
+			]
+			agentsFolders.push(...candidates)
+		}
+
 		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')
+			...instanceLocations,
+			...agentsFolders,
 		]).filter(Boolean).filter(l => (this.container as any).fs.exists(l))
 		this.state.set('locations', allLocations)
 
@@ -335,9 +414,9 @@ export class SkillsLibrary extends Feature<SkillsLibraryState, SkillsLibraryOpti
 		}
 	}
 
-	/** Return all discovered skills. */
+	/** Return all discovered skills (respects the `only` filter). */
 	list(): SkillInfo[] {
-		return Object.values(this.skills)
+		return Object.values(this.filteredSkills)
 	}
 
 	/** Find a skill by name. */
@@ -389,11 +468,11 @@ export class SkillsLibrary extends Feature<SkillsLibraryState, SkillsLibraryOpti
 
 	// --- Tool handlers for assistant.use(skillsLibrary) ---
 
-	/** Search available skills, optionally filtered by a query string. */
+	/** Search available skills, optionally filtered by a query string. Respects the `only` filter. */
 	async searchAvailableSkills({ query }: { query?: string } = {}): Promise<string> {
 		if (!this.isStarted) await this.start()
 
-		let skills = this.list()
+		let skills = Object.values(this.filteredSkills)
 
 		if (query) {
 			const q = query.toLowerCase()

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

@@ -25,6 +25,86 @@ const MODEL_CONTEXT_WINDOWS: Record<string, number> = {
 
 const DEFAULT_CONTEXT_WINDOW = 128_000
 
+/**
+ * Model pricing in dollars per 1M tokens: [inputPer1M, outputPer1M].
+ * Prefix-matched for dated variants just like context windows.
+ */
+const MODEL_PRICING: Record<string, [input: number, output: number]> = {
+	'gpt-5.5-pro': [30.00, 180.00],
+	'gpt-5.5': [5.00, 30.00],
+	'gpt-5.4-pro': [30.00, 180.00],
+	'gpt-5.4-nano': [0.20, 1.25],
+	'gpt-5.4-mini': [0.75, 4.50],
+	'gpt-5.4': [2.50, 15.00],
+	'gpt-5': [1.25, 10.00],
+	'gpt-4.1-nano': [0.10, 0.40],
+	'gpt-4.1-mini': [0.40, 1.60],
+	'gpt-4.1': [2.00, 8.00],
+	'gpt-4o-mini': [0.15, 0.60],
+	'gpt-4o': [2.50, 10.00],
+	'gpt-4-turbo': [10.00, 30.00],
+	'gpt-4': [30.00, 60.00],
+	'gpt-3.5-turbo': [0.50, 1.50],
+	'o4-mini': [1.10, 4.40],
+	'o3-mini': [1.10, 4.40],
+	'o3': [2.00, 8.00],
+	'o1-pro': [150.00, 600.00],
+	'o1-mini': [1.10, 4.40],
+	'o1': [15.00, 60.00],
+}
+
+export interface CostBreakdown {
+	inputCost: number
+	outputCost: number
+	totalCost: number
+	model: string
+	inputTokens: number
+	outputTokens: number
+	cachedTokens?: number
+	reasoningTokens?: number
+}
+
+/** Look up the per-1M-token pricing for a model (exact then prefix match). Returns [inputPer1M, outputPer1M] or null if unknown. */
+export function getModelPricing(model: string): [input: number, output: number] | null {
+	if (MODEL_PRICING[model]) return MODEL_PRICING[model]
+
+	let best = ''
+	for (const key of Object.keys(MODEL_PRICING)) {
+		if (model.startsWith(key) && key.length > best.length) {
+			best = key
+		}
+	}
+
+	return best ? MODEL_PRICING[best] ?? null : null
+}
+
+/**
+ * Calculate cost in dollars from token usage and model name.
+ * When cachedTokens is provided, those tokens are billed at 50% of the input rate.
+ */
+export function calculateCost(model: string, inputTokens: number, outputTokens: number, opts?: { cachedTokens?: number; reasoningTokens?: number }): CostBreakdown {
+	const pricing = getModelPricing(model)
+	const cachedTokens = opts?.cachedTokens || 0
+
+	let inputCost = 0
+	if (pricing) {
+		const fullPriceInputTokens = inputTokens - cachedTokens
+		inputCost = (fullPriceInputTokens / 1_000_000) * pricing[0] + (cachedTokens / 1_000_000) * pricing[0] * 0.5
+	}
+	const outputCost = pricing ? (outputTokens / 1_000_000) * pricing[1] : 0
+
+	return {
+		inputCost,
+		outputCost,
+		totalCost: inputCost + outputCost,
+		model,
+		inputTokens,
+		outputTokens,
+		cachedTokens: cachedTokens || undefined,
+		reasoningTokens: opts?.reasoningTokens || undefined,
+	}
+}
+
 const encoderCache = new Map<string, Tiktoken>()
 
 /** Look up the context window size for a model name (exact then prefix match). */