@soederpop/luca 0.1.1 → 0.1.3

package/src/node/features/redis.ts

@@ -400,7 +400,7 @@ export class RedisFeature extends Feature<RedisState, RedisOptions> {
     )
 
     if (existing) {
-      if (existing.state !== 'running') {
+      if (existing.status !== 'running') {
         await docker.startContainer(name)
       }
       return existing.id

package/src/node/features/repl.ts

@@ -101,7 +101,7 @@ export class Repl<
 
     // Load existing history
     try {
-      const content = fs.readFile(this._historyPath, 'utf-8')
+      const content = this.container.fs.readFile(this._historyPath, 'utf-8') as string
       this._history = content.split('\n').filter(Boolean).reverse()
     } catch {}
 
@@ -204,7 +204,7 @@ export class Repl<
   private _saveHistory(line: string) {
     if (!this._historyPath || !line.trim()) return
     try {
-      fs.appendFileSync(this._historyPath, line + '\n')
+      this.container.fs.appendFile(this._historyPath, line + '\n')
     } catch {}
   }
 }

package/src/node/features/transpiler.ts

@@ -18,7 +18,9 @@ export interface TransformResult {
  * so the code can run in a vm context that provides `require`.
  */
 function esmToCjs(code: string): string {
-  return code
+  const exportedNames: string[] = []
+
+  let result = code
     // import Foo, { bar, baz } from 'x' → const Foo = require('x').default ?? require('x'); const { bar, baz } = require('x')
     .replace(/^import\s+(\w+)\s*,\s*\{([^}]+)\}\s+from\s+(['"][^'"]+['"])\s*;?$/gm,
       'const $1 = require($3).default ?? require($3); const {$2} = require($3);')
@@ -39,14 +41,37 @@ function esmToCjs(code: string): string {
     // export { a, b } from 'x' → Object.assign(module.exports, require('x'))  (re-exports)
     .replace(/^export\s+\{[^}]*\}\s+from\s+(['"][^'"]+['"])\s*;?$/gm,
       'Object.assign(module.exports, require($1));')
-    // export { ... } → strip (vars already in scope)
-    .replace(/^export\s+\{[^}]*\}\s*;?$/gm, '')
-    // export const/let/var → const/let/var
-    .replace(/^export\s+(const|let|var)\s+/gm, '$1 ')
-    // export function → function (keep declaration, strip export keyword)
-    .replace(/^export\s+(function|class)\s+/gm, '$1 ')
-    // export async function → async function
-    .replace(/^export\s+(async\s+function)\s+/gm, '$1 ')
+    // export { a, b as c } → exports.a = a; exports.c = b;
+    .replace(/^export\s+\{([^}]*)\}\s*;?$/gm, (_match, body: string) => {
+      return body.split(',').map(s => {
+        const parts = s.trim().split(/\s+as\s+/)
+        const local = (parts[0] ?? '').trim()
+        const exported = (parts[1] ?? parts[0] ?? '').trim()
+        return local ? `exports['${exported}'] = ${local};` : ''
+      }).filter(Boolean).join(' ')
+    })
+    // export const/let/var NAME → const/let/var NAME (track for deferred export)
+    .replace(/^export\s+(const|let|var)\s+(\w+)/gm, (_match, decl: string, name: string) => {
+      exportedNames.push(name)
+      return `${decl} ${name}`
+    })
+    // export function NAME / export class NAME → function/class NAME (track for deferred export)
+    .replace(/^export\s+(function|class)\s+(\w+)/gm, (_match, type: string, name: string) => {
+      exportedNames.push(name)
+      return `${type} ${name}`
+    })
+    // export async function NAME → async function NAME (track for deferred export)
+    .replace(/^export\s+(async\s+function)\s+(\w+)/gm, (_match, type: string, name: string) => {
+      exportedNames.push(name)
+      return `${type} ${name}`
+    })
+
+  // Append exports for all tracked named exports
+  if (exportedNames.length > 0) {
+    result += '\n' + exportedNames.map(n => `exports['${n}'] = ${n};`).join('\n')
+  }
+
+  return result
 }
 
 /**

package/src/node/features/ui.ts

@@ -2,7 +2,7 @@ import { z } from 'zod'
 import { FeatureStateSchema } from '../../schemas/base.js'
 import { Feature } from "../feature.js";
 import colors from "chalk";
-import type { Fonts } from "figlet";
+import type { FontName as Fonts } from "figlet";
 import { figlet, fontNames } from "./figlet-fonts.js";
 import inquirer from "inquirer";
 import { marked } from 'marked';

package/src/node/features/vm.ts

@@ -219,9 +219,9 @@ export class VM<
 
     // Find the last non-empty line
     let lastIdx = lines.length - 1
-    while (lastIdx > 0 && !lines[lastIdx].trim()) lastIdx--
+    while (lastIdx > 0 && !(lines[lastIdx] ?? '').trim()) lastIdx--
 
-    let lastLine = lines[lastIdx]!
+    let lastLine = lines[lastIdx] ?? ''
 
     // For single-line code with semicolons (e.g. CLI eval), split the last line
     // into statements and only try to return the final statement.
@@ -390,12 +390,13 @@ export class VM<
     if (!fs.exists(filePath)) return {}
 
     const raw = fs.readFile(filePath)
-    const { code } = this.container.feature('transpiler').transformSync(raw, { format: 'cjs' })
+    const { code } = this.container.feature('transpiler').transformSync(String(raw), { format: 'cjs' })
 
+    const sharedExports = {}
     const { context } = this.performSync(code, {
       require: this.createRequireFor(filePath),
-      exports: {},
-      module: { exports: {} },
+      exports: sharedExports,
+      module: { exports: sharedExports },
       console,
       setTimeout,
       setInterval,

package/src/node/features/yaml-tree.ts

@@ -113,7 +113,7 @@ export class YamlTree<T extends YamlTreeState = YamlTreeState> extends Feature<T
     for (const file of yamlFiles.filter(Boolean)) {
       if(file?.relativePath) {
         const fileContent = fileSystem.readFile(file.relativePath);
-        const fileData = yamlFeature.parse(fileContent);
+        const fileData = yamlFeature.parse(String(fileContent));
         const path = file.relativePath.replace(/\.ya?ml$/, "").replace(basePath + "/", "").split("/").filter(v => v?.length).map(p => camelCase(p));
         set(tree, path, fileData)
       }

package/src/node.ts

@@ -65,6 +65,7 @@ export type { AvailableFeatures, FeatureOptions, FeatureState } from './feature'
 export type { NodeContainer, NodeFeatures } from './node/container'
 export type { AvailableServers, StartOptions, ServersInterface } from './server'
 export type { HelperState, HelperOptions } from './helper'
+export type { Entity } from './entity'
 export type { EventMap } from './bus'
 export type { SetStateValue, StateChangeType } from './state'
 

package/src/python/generated.ts

@@ -1,5 +1,5 @@
 // Auto-generated Python bridge script
-// Generated at: 2026-03-28T06:19:50.936Z
+// Generated at: 2026-04-03T01:24:54.795Z
 // Source: src/python/bridge.py
 //
 // Do not edit manually. Run: luca build-python-bridge

package/src/scaffolds/generated.ts

@@ -1,5 +1,5 @@
 // Auto-generated scaffold and MCP readme content
-// Generated at: 2026-03-28T06:19:49.219Z
+// Generated at: 2026-04-03T01:24:53.146Z
 // Source: docs/scaffolds/*.md, docs/examples/assistant/, and docs/mcp/readme.md
 //
 // Do not edit manually. Run: luca build-scaffolds

package/src/selector.ts

@@ -135,17 +135,17 @@ export class Selector<
 		}
 
 		// Run the selector
-		this.state.set('running' as any, true)
+		this.state.set('running' as any, true as any)
 		this.emit('started' as any)
 
 		let data: any
 		try {
 			data = await this.run(parsed, this.context)
-			this.state.set('running' as any, false)
-			this.state.set('lastRanAt' as any, Date.now())
+			this.state.set('running' as any, false as any)
+			this.state.set('lastRanAt' as any, Date.now() as any)
 			this.emit('completed' as any, data)
 		} catch (err: any) {
-			this.state.set('running' as any, false)
+			this.state.set('running' as any, false as any)
 			this.emit('failed' as any, err)
 			throw err
 		}
@@ -197,6 +197,76 @@ export class SelectorsRegistry extends Registry<Selector<any>> {
 	override scope = 'selectors'
 	override baseClass = Selector as any
 
+	/**
+	 * Convert all registered selectors into a `{ schemas, handlers }` object
+	 * compatible with `assistant.use()`.
+	 *
+	 * Each selector becomes a tool whose parameters come from the selector's
+	 * `argsSchema` (with internal fields stripped) and whose handler dispatches
+	 * the selector and returns the data directly (cache metadata is not exposed).
+	 *
+	 * @param container - The container used to instantiate and run selectors
+	 * @param options - Optional filter/transform options
+	 * @param options.include - Only include these selector names (default: all)
+	 * @param options.exclude - Exclude these selector names (default: none)
+	 * @param options.prefix - Prefix tool names (e.g. 'sel_' → 'sel_packageInfo')
+	 */
+	toTools(
+		container: Container<any> & SelectorsInterface,
+		options?: { include?: string[], exclude?: string[], prefix?: string },
+	): { schemas: Record<string, z.ZodType>, handlers: Record<string, Function> } {
+		const schemas: Record<string, z.ZodType> = {}
+		const handlers: Record<string, Function> = {}
+		const prefix = options?.prefix ?? ''
+		const includeSet = options?.include ? new Set(options.include) : null
+		const excludeSet = new Set(options?.exclude ?? [])
+
+		// Internal fields from HelperOptionsSchema and SelectorOptionsSchema
+		const internalFields = ['name', '_cacheKey', 'dispatchSource']
+
+		for (const name of this.available) {
+			if (excludeSet.has(name)) continue
+			if (includeSet && !includeSet.has(name)) continue
+
+			const Sel = this.lookup(name) as typeof Selector
+			const rawSchema = Sel.argsSchema
+			const description = Sel.selectorDescription || Sel.description || name
+
+			let toolSchema: z.ZodType
+			try {
+				const shape = typeof (rawSchema as any)?._def?.shape === 'function'
+					? (rawSchema as any)._def.shape()
+					: (rawSchema as any)?._def?.shape
+
+				if (shape) {
+					const cleanShape: Record<string, z.ZodType> = {}
+					for (const [key, val] of Object.entries(shape)) {
+						if (internalFields.includes(key)) continue
+						cleanShape[key] = val as z.ZodType
+					}
+
+					toolSchema = Object.keys(cleanShape).length > 0
+						? z.object(cleanShape).describe(description)
+						: z.object({}).describe(description)
+				} else {
+					toolSchema = z.object({}).describe(description)
+				}
+			} catch {
+				toolSchema = z.object({}).describe(description)
+			}
+
+			const toolName = `${prefix}${name}`
+			schemas[toolName] = toolSchema
+			handlers[toolName] = async (args: Record<string, any>) => {
+				const sel = (container.select as any)(name)
+				const result = await sel.select(args ?? {})
+				return result.data
+			}
+		}
+
+		return { schemas, handlers }
+	}
+
 	/**
 	 * Discover and register selectors from a directory.
 	 * Detection order:

package/src/server.ts

@@ -30,7 +30,7 @@ export class Server<T extends ServerState = ServerState, K extends ServerOptions
     static override eventsSchema = ServerEventsSchema
 
     /** Self-register a Server subclass from a static initialization block. */
-    static register: (SubClass: typeof Server, id?: string) => typeof Server
+    static register: (SubClass: abstract new (options: any, context: any) => Server, id?: string) => abstract new (options: any, context: any) => Server
 
     override get initialState() : T {
       return ({
@@ -203,7 +203,7 @@ export const helperCache = new Map()
  * ```
  */
 Server.register = function registerServer(
-  SubClass: typeof Server,
+  SubClass: abstract new (options: any, context: any) => Server,
   id?: string,
 ) {
   const registryId = id ?? SubClass.name[0]!.toLowerCase() + SubClass.name.slice(1)

package/src/servers/mcp.ts

@@ -33,9 +33,9 @@ export type MCPContext = {
 export interface RegisteredTool {
   name: string
   description?: string
-  schema?: z.ZodObject<any>
+  schema?: z.ZodType
   jsonSchema?: Record<string, any>
-  handler: (args: any, ctx: MCPContext) => any
+  handler: Function
 }
 
 /** A registered MCP resource with its URI, metadata, and handler. */
@@ -61,9 +61,9 @@ export type PromptMessage = {
 }
 
 type ToolRegistrationOptions = {
-  schema?: z.ZodObject<any>
+  schema?: z.ZodType
   description?: string
-  handler: (args: any, ctx: MCPContext) => any
+  handler?: Function | ((args: any, ctx: any) => any)
 }
 
 type ResourceRegistrationOptions = {
@@ -340,7 +340,7 @@ export class MCPServer extends Server<MCPServerState, MCPServerOptions> {
    * @param name - Unique tool name
    * @param options - Tool schema, description, and handler
    */
-  tool(name: string, options: ToolRegistrationOptions): this {
+  override tool(name: string, options: ToolRegistrationOptions): this {
     let jsonSchema: Record<string, any> | undefined
 
     if (options.schema) {
@@ -357,7 +357,7 @@ export class MCPServer extends Server<MCPServerState, MCPServerOptions> {
       description: options.description,
       schema: options.schema,
       jsonSchema,
-      handler: options.handler,
+      handler: options.handler ?? (() => {}),
     }
 
     this._tools.set(name, registered)

package/src/web/features/helpers.ts

@@ -136,7 +136,7 @@ export class Helpers extends Feature<HelpersState, HelpersOptions> {
         return {}
       }
 
-      const manifest: Manifest = await response.json()
+      const manifest = await response.json() as Manifest
       this._manifest = manifest
       this.state.set('manifestLoaded', true)
       this.emit('manifestLoaded' as any, manifest)

package/src/web/features/network.ts

@@ -1,3 +1,4 @@
+/// <reference lib="dom" />
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
 import { Feature } from "../feature.js";

package/test/assistant.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect, beforeEach } from 'bun:test'
+import { AGIContainer } from '../src/agi/container.server'
+
+describe('Assistant', () => {
+	let container: AGIContainer
+
+	beforeEach(() => {
+		container = new AGIContainer()
+	})
+
+	describe('codingAssistant', () => {
+		it('loads a non-empty system prompt from CORE.md', () => {
+			const assistant = container.feature('assistant', { folder: 'assistants/codingAssistant' })
+			expect(assistant.systemPrompt.length).toBeGreaterThan(0)
+			expect(assistant.systemPrompt).toContain('coding assistant')
+		})
+
+		it('loads tools from tools.ts via the VM', () => {
+			const assistant = container.feature('assistant', { folder: 'assistants/codingAssistant' })
+			const tools = assistant.availableTools
+			expect(tools).toContain('rg')
+			expect(tools).toContain('ls')
+			expect(tools).toContain('cat')
+			expect(tools).toContain('pwd')
+			expect(tools.length).toBeGreaterThan(0)
+		})
+
+		it('tools have descriptions and parameter schemas', () => {
+			const assistant = container.feature('assistant', { folder: 'assistants/codingAssistant' })
+			const { rg, ls, cat } = assistant.tools
+			expect(rg.description.length).toBeGreaterThan(0)
+			expect(rg.parameters.type).toBe('object')
+			expect(rg.parameters.properties).toHaveProperty('args')
+			expect(ls.parameters.properties).toHaveProperty('args')
+			expect(cat.parameters.properties).toHaveProperty('args')
+		})
+
+		it('loads hooks from hooks.ts via the VM', () => {
+			const assistant = container.feature('assistant', { folder: 'assistants/codingAssistant' })
+			const hooks = assistant.state.get('hooks') as Record<string, Function>
+			expect(hooks).toBeDefined()
+			expect(typeof hooks.started).toBe('function')
+		})
+
+		it('hooks fire when the assistant starts', async () => {
+			const assistant = container.feature('assistant', {
+				folder: 'assistants/codingAssistant',
+				local: true,
+				model: 'qwen/qwen3-8b',
+			})
+
+			// bindHooksToEvents emits 'hookFired' with the event name each time a hook runs
+			const fired: string[] = []
+			assistant.on('hookFired', (eventName: string) => { fired.push(eventName) })
+
+			await assistant.start()
+			expect(fired).toContain('started')
+		})
+
+		it('tools are wired into the conversation after start', async () => {
+			const assistant = container.feature('assistant', {
+				folder: 'assistants/codingAssistant',
+				local: true,
+				model: 'qwen/qwen3-8b',
+			})
+			await assistant.start()
+			const convTools = assistant.conversation.tools
+			expect(Object.keys(convTools)).toContain('rg')
+			expect(Object.keys(convTools)).toContain('ls')
+		})
+	})
+})

package/test/conversation.test.ts

@@ -0,0 +1,220 @@
+import { describe, it, expect, beforeEach } from 'bun:test'
+import { AGIContainer } from '../src/agi/container.server'
+import type { Conversation } from '../src/agi/features/conversation'
+
+function makeConversation(opts: Record<string, any> = {}): Conversation {
+	const container = new AGIContainer()
+	return container.feature('conversation', { model: 'gpt-5', ...opts }) as Conversation
+}
+
+describe('Conversation', () => {
+	describe('state', () => {
+		it('initializes with empty messages when no history provided', () => {
+			const conv = makeConversation()
+			expect(conv.messages).toEqual([])
+		})
+
+		it('seeds message history from options', () => {
+			const history = [{ role: 'system', content: 'You are helpful.' }]
+			const conv = makeConversation({ history })
+			expect(conv.messages).toHaveLength(1)
+			expect(conv.messages[0]).toEqual(history[0])
+		})
+
+		it('uses provided model', () => {
+			const conv = makeConversation({ model: 'gpt-4.1' })
+			expect(conv.model).toBe('gpt-4.1')
+		})
+
+		it('isStreaming is false initially', () => {
+			const conv = makeConversation()
+			expect(conv.isStreaming).toBe(false)
+		})
+	})
+
+	describe('pushMessage', () => {
+		it('appends to messages', () => {
+			const conv = makeConversation()
+			conv.pushMessage({ role: 'user', content: 'hello' })
+			expect(conv.messages).toHaveLength(1)
+			expect(conv.messages[0]!.role).toBe('user')
+		})
+
+		it('does not mutate prior messages array', () => {
+			const conv = makeConversation()
+			const before = conv.messages
+			conv.pushMessage({ role: 'user', content: 'hi' })
+			expect(conv.messages).not.toBe(before)
+		})
+	})
+
+	describe('tools', () => {
+		it('starts with no tools', () => {
+			const conv = makeConversation()
+			expect(conv.availableTools).toHaveLength(0)
+		})
+
+		it('addTool registers a tool', () => {
+			const conv = makeConversation()
+			conv.addTool('greet', {
+				description: 'Says hello',
+				parameters: { type: 'object', properties: {} },
+				handler: async () => 'hello',
+			})
+			expect(conv.availableTools).toContain('greet')
+		})
+
+		it('removeTool deregisters a tool', () => {
+			const conv = makeConversation()
+			conv.addTool('greet', {
+				description: 'Says hello',
+				parameters: { type: 'object', properties: {} },
+				handler: async () => 'hello',
+			})
+			conv.removeTool('greet')
+			expect(conv.availableTools).not.toContain('greet')
+		})
+
+		it('updateTools merges without replacing unrelated tools', () => {
+			const conv = makeConversation()
+			conv.addTool('a', { description: 'A', parameters: { type: 'object', properties: {} }, handler: async () => 'a' })
+			conv.updateTools({ b: { description: 'B', parameters: { type: 'object', properties: {} }, handler: async () => 'b' } })
+			expect(conv.availableTools).toContain('a')
+			expect(conv.availableTools).toContain('b')
+		})
+
+		it('construction-time tools are available immediately', () => {
+			const conv = makeConversation({
+				tools: {
+					ping: { description: 'Ping', parameters: { type: 'object', properties: {} }, handler: async () => 'pong' }
+				}
+			})
+			expect(conv.availableTools).toContain('ping')
+		})
+	})
+
+	describe('estimateTokens', () => {
+		it('returns a near-zero baseline for empty messages', () => {
+			const conv = makeConversation()
+			expect(conv.estimateTokens()).toBeLessThan(10)
+		})
+
+		it('returns a positive number when messages exist', () => {
+			const conv = makeConversation({
+				history: [{ role: 'user', content: 'What is the capital of France?' }]
+			})
+			expect(conv.estimateTokens()).toBeGreaterThan(0)
+		})
+
+		it('increases as more messages are added', () => {
+			const conv = makeConversation()
+			conv.pushMessage({ role: 'user', content: 'Hello' })
+			const first = conv.estimateTokens()
+			conv.pushMessage({ role: 'assistant', content: 'Hi there, how can I help you today?' })
+			const second = conv.estimateTokens()
+			expect(second).toBeGreaterThan(first)
+		})
+	})
+
+	describe('stub()', () => {
+		it('exact string match returns the stub response', async () => {
+			const conv = makeConversation()
+			conv.stub('ping', 'pong')
+			const result = await conv.ask('ping')
+			expect(result).toBe('pong')
+		})
+
+		it('substring match triggers the stub', async () => {
+			const conv = makeConversation()
+			conv.stub('weather', 'Sunny and 72°F.')
+			const result = await conv.ask('what is the weather today?')
+			expect(result).toBe('Sunny and 72°F.')
+		})
+
+		it('regex match triggers the stub', async () => {
+			const conv = makeConversation()
+			conv.stub(/hello/i, 'Hey there!')
+			const result = await conv.ask('HELLO')
+			expect(result).toBe('Hey there!')
+		})
+
+		it('function response is called on each match', async () => {
+			const conv = makeConversation()
+			let callCount = 0
+			conv.stub('count', () => `call ${++callCount}`)
+			expect(await conv.ask('count')).toBe('call 1')
+			expect(await conv.ask('count')).toBe('call 2')
+		})
+
+		it('first matching stub wins', async () => {
+			const conv = makeConversation()
+			conv.stub('hello', 'first')
+			conv.stub('hello', 'second')
+			expect(await conv.ask('hello')).toBe('first')
+		})
+
+		it('appends user and assistant messages to history', async () => {
+			const conv = makeConversation()
+			conv.stub('hi', 'hello back')
+			await conv.ask('hi')
+			expect(conv.messages).toHaveLength(2)
+			expect(conv.messages[0]).toMatchObject({ role: 'user', content: 'hi' })
+			expect(conv.messages[1]).toMatchObject({ role: 'assistant', content: 'hello back' })
+		})
+
+		it('isStreaming is false after the call resolves', async () => {
+			const conv = makeConversation()
+			conv.stub('test', 'response')
+			await conv.ask('test')
+			expect(conv.isStreaming).toBe(false)
+		})
+
+		it('emits chunk events for each word', async () => {
+			const conv = makeConversation()
+			conv.stub('go', 'one two three')
+			const chunks: string[] = []
+			conv.on('chunk', (delta: string) => chunks.push(delta))
+			await conv.ask('go')
+			expect(chunks.join('')).toBe('one two three')
+		})
+
+		it('emits preview events with accumulating text', async () => {
+			const conv = makeConversation()
+			conv.stub('go', 'alpha beta')
+			const previews: string[] = []
+			conv.on('preview', (text: string) => previews.push(text))
+			await conv.ask('go')
+			expect(previews.at(-1)).toBe('alpha beta')
+			// Each preview should be longer than or equal to the previous
+			for (let i = 1; i < previews.length; i++) {
+				expect(previews[i]!.length).toBeGreaterThanOrEqual(previews[i - 1]!.length)
+			}
+		})
+
+		it('emits turnStart and turnEnd events', async () => {
+			const conv = makeConversation()
+			conv.stub('x', 'y')
+			const events: string[] = []
+			conv.on('turnStart', () => events.push('turnStart'))
+			conv.on('turnEnd', () => events.push('turnEnd'))
+			await conv.ask('x')
+			expect(events).toEqual(['turnStart', 'turnEnd'])
+		})
+
+		it('emits response event with the full text', async () => {
+			const conv = makeConversation()
+			conv.stub('question', 'the answer')
+			let emitted = ''
+			conv.on('response', (text: string) => { emitted = text })
+			await conv.ask('question')
+			expect(emitted).toBe('the answer')
+		})
+
+		it('stub is chainable', () => {
+			const conv = makeConversation()
+			const result = conv.stub('a', 'A').stub('b', 'B')
+			expect(result).toBe(conv)
+			expect(conv.availableTools).toHaveLength(0) // stubs don't affect tools
+		})
+	})
+})