@soederpop/luca 0.1.2 → 0.2.1

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,22 +73,22 @@ 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'),
-			}).describe('Search for available skills in the library. Returns matching skill names and descriptions.'),
+				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 name of the skill to load'),
-			}).describe('Load a skill by name and return its full SKILL.md content and metadata.'),
+				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 name of the skill to query'),
-				question: z.string().describe('The question to ask about the skill'),
-			}).describe('Ask a question about a specific skill using AI-assisted document reading.'),
+				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.'),
 		},
 	}
 
@@ -102,9 +103,61 @@ 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
+
+		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
 	}
 
@@ -375,6 +428,51 @@ 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[] }
+
+			const found = result.skills.filter(name => this.find(name) !== undefined)
+			
+			this.emit('foundSkills', found, assistant, userQuery)
+			
+			return found
+	}
 }
 
 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). */

package/src/bootstrap/generated.ts

@@ -1,5 +1,5 @@
 // Auto-generated bootstrap content
-// Generated at: 2026-03-30T06:52:56.930Z
+// Generated at: 2026-04-05T06:58:07.990Z
 // Source: docs/bootstrap/*.md, docs/bootstrap/templates/*, docs/examples/*.md, docs/tutorials/*.md
 //
 // Do not edit manually. Run: luca build-bootstrap
@@ -1253,6 +1253,131 @@ console.log('Running after killAll:', remaining.length)
 ## Summary
 
 This demo covered the \`processManager\` feature: spawning processes that return handles immediately, tracking them by ID or tag, listing all tracked processes, and killing them individually or all at once. It is the right tool for orchestrating background services, dev servers, and any scenario where you need non-blocking process management with lifecycle events.
+`,
+  "entity.md": `---
+title: "Entity"
+tags: [entity, state, events, tools, core]
+lastTested: null
+lastTestPassed: null
+---
+
+# entity
+
+Lightweight, composable objects with observable state, a typed event bus, and an optional tool interface.
+
+## Overview
+
+An entity is a plain object — not a class — created via \`container.entity(id, options?)\`. Same id + options always returns the same underlying state and bus instance. Entities are designed to be extended with methods and getters via \`.extend()\`, and can expose those methods as AI tools via \`.expose()\`.
+
+## Basic Entity with Observable State
+
+Create an entity and read/write state through the observable \`state\` property.
+
+\`\`\`ts
+const counter = container.entity<{ count: number }>('counter')
+counter.setState({ count: 0 })
+
+counter.state.observe((next) => {
+  console.log('count changed to', next.count)
+})
+
+counter.setState(s => ({ count: s.count + 1 }))
+counter.setState(s => ({ count: s.count + 1 }))
+console.log('final count:', counter.state.get('count'))
+\`\`\`
+
+\`setState\` accepts either a partial object or a function that receives the current state. Observers fire synchronously after each change.
+
+## Typed Event Bus
+
+Every entity has a built-in event bus. Declare the event map as the third type parameter.
+
+\`\`\`ts
+type TimerEvents = {
+  tick: [elapsed: number]
+  done: []
+}
+
+const timer = container.entity<{}, {}, TimerEvents>('timer')
+
+timer.on('tick', (elapsed) => {
+  console.log('tick at', elapsed, 'ms')
+})
+
+timer.once('done', () => {
+  console.log('timer finished')
+})
+
+timer.emit('tick', 100)
+timer.emit('tick', 200)
+timer.emit('done')
+\`\`\`
+
+\`once\` auto-detaches after the first fire. \`waitFor\` returns a promise that resolves on the next emit of that event.
+
+## Extending with Methods
+
+Use \`.extend()\` to graft methods and getters onto an entity. All base properties — \`state\`, \`options\`, \`container\`, and the event methods — are available via \`this\`.
+
+\`\`\`ts
+const session = container.entity('session', { userId: '42' })
+  .extend({
+    greet() {
+      return \`Hello user \${this.options.userId}\`
+    },
+    get label() {
+      return \`Session \${this.id} (user \${this.options.userId})\`
+    },
+    bump() {
+      const visits = (this.state.get('visits') ?? 0) + 1
+      this.setState({ visits })
+      this.emit('visited', visits)
+      return visits
+    },
+  })
+
+console.log(session.greet())
+console.log(session.label)
+console.log('visits:', session.bump())
+console.log('visits:', session.bump())
+\`\`\`
+
+Extensions are chained via prototype delegation — each layer can see everything below it.
+
+## Exposing Methods as AI Tools
+
+Use \`.expose(methodName, zodSchema)\` to register methods as tools. \`.toTools()\` returns \`{ schemas, handlers }\` compatible with \`assistant.addTools()\`.
+
+\`\`\`ts
+const search = container.entity('search', {})
+  .extend({
+    async lookup({ query }: { query: string }) {
+      return \`Results for: \${query}\`
+    },
+    async summarize({ text, maxWords }: { text: string; maxWords: number }) {
+      return text.split(' ').slice(0, maxWords).join(' ')
+    },
+  })
+  .expose('lookup', z.object({
+    query: z.string().describe('The search query'),
+  }))
+  .expose('summarize', z.object({
+    text: z.string().describe('Text to summarize'),
+    maxWords: z.number().describe('Maximum words in summary'),
+  }))
+
+const { schemas, handlers } = search.toTools()
+console.log('registered tools:', Object.keys(schemas))
+
+// Pass directly to an assistant
+// assistant.addTools(search)
+\`\`\`
+
+\`.expose()\` is chainable and returns \`this\`, so you can stack as many as you need.
+
+## Summary
+
+Entities give you observable state, a typed event bus, and prototype-safe method extension — all as a plain object with no class overhead. The \`.expose()\` / \`.toTools()\` interface makes it straightforward to surface entity methods as AI tools.
 `,
   "assistant-with-process-manager.md": `---
 title: "Assistant with ProcessManager Tools"

package/src/bus.ts

@@ -1,6 +1,7 @@
 export type EventMap = Record<string, any[]>;
 
 type Listener<Args extends any[] = any[]> = (...args: Args) => void;
+type WildcardListener = (event: string, ...args: any[]) => void;
 
 export interface EventStats {
     event: string;
@@ -12,10 +13,12 @@ export interface EventStats {
 
 export class Bus<T extends EventMap = EventMap> {
     private events: Map<string, Listener[]>;
+    private wildcardListeners: WildcardListener[];
     private stats: Map<string, { fireCount: number; lastFiredAt: number | null; timestamps: number[] }>;
 
     constructor() {
         this.events = new Map();
+        this.wildcardListeners = [];
         this.stats = new Map();
     }
 
@@ -64,12 +67,19 @@ export class Bus<T extends EventMap = EventMap> {
     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));
+        if (listeners) {
+            listeners.forEach(listener => listener(...args));
+        }
+        this.wildcardListeners.forEach(listener => listener(event, ...args));
     }
 
-    on<E extends string & keyof T>(event: E, listener: (...args: T[E]) => void): void {
+    on(event: '*', listener: WildcardListener): void
+    on<E extends string & keyof T>(event: E, listener: (...args: T[E]) => void): void
+    on<E extends string & keyof T>(event: E | '*', listener: any): void {
+        if (event === '*') {
+            this.wildcardListeners.push(listener);
+            return;
+        }
         const listeners = this.events.get(event) || [];
         listeners.push(listener as Listener);
         this.events.set(event, listeners);
@@ -83,7 +93,19 @@ export class Bus<T extends EventMap = EventMap> {
         this.on(event, onceListener as any);
     }
 
-    off<E extends string & keyof T>(event: E, listener?: (...args: T[E]) => void): void {
+    off(event: '*', listener?: WildcardListener): void
+    off<E extends string & keyof T>(event: E, listener?: (...args: T[E]) => void): void
+    off<E extends string & keyof T>(event: E | '*', listener?: any): void {
+        if (event === '*') {
+            if (!listener) {
+                this.wildcardListeners = [];
+                return;
+            }
+            const index = this.wildcardListeners.indexOf(listener);
+            if (index !== -1) this.wildcardListeners.splice(index, 1);
+            return;
+        }
+
         const listeners = this.events.get(event);
         if (!listeners) return;
 

package/src/cli/build-info.ts

@@ -1,4 +1,4 @@
 // Generated at compile time — do not edit manually
-export const BUILD_SHA = 'e1b45a8'
+export const BUILD_SHA = '8323521'
 export const BUILD_BRANCH = 'main'
-export const BUILD_DATE = '2026-03-30T06:52:57Z'
+export const BUILD_DATE = '2026-04-05T06:58:08Z'

package/src/client.ts

@@ -46,7 +46,7 @@ export class Client<
   static override eventsSchema = ClientEventsSchema
 
   /** Self-register a Client subclass from a static initialization block. */
-  static register: (SubClass: typeof Client, id?: string) => typeof Client
+  static register: (SubClass: abstract new (options: any, context: any) => Client, id?: string) => abstract new (options: any, context: any) => Client
 
   static attach(container: Container & ClientsInterface): any {
     Object.assign(container, {
@@ -141,7 +141,7 @@ export const helperCache = new Map();
  * ```
  */
 Client.register = function registerClient(
-  SubClass: typeof Client,
+  SubClass: abstract new (options: any, context: any) => Client,
   id?: string,
 ) {
   const registryId = id ?? SubClass.name[0]!.toLowerCase() + SubClass.name.slice(1)

package/src/clients/elevenlabs/index.ts

@@ -3,6 +3,7 @@ import { ClientStateSchema, ClientOptionsSchema, ClientEventsSchema } from '@soe
 import { Client } from "@soederpop/luca/client";
 import { RestClient } from "../rest";
 import type { ContainerContext } from "@soederpop/luca/container";
+import type { NodeContainer } from "../../node/container.js";
 import type { AxiosRequestConfig } from 'axios'
 
 declare module "@soederpop/luca/client" {
@@ -92,6 +93,10 @@ export class ElevenLabsClient extends RestClient<ElevenLabsClientState, ElevenLa
     super(options, context)
   }
 
+  override get container(): NodeContainer {
+    return super.container as unknown as NodeContainer
+  }
+
   /** The resolved API key from options or environment. */
   get apiKey(): string {
     return this.options.apiKey || process.env.ELEVENLABS_API_KEY || ''