@soederpop/luca 0.1.2 → 0.2.1

package/docs/examples/entity.md

@@ -0,0 +1,124 @@
+---
+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.

package/docs/ideas/assistant-factory-pattern.md

@@ -0,0 +1,142 @@
+---
+title: Assistant Factory Pattern — Eliminate Wrapper Duplication
+status: idea
+tags: [agi, assistant, refactor, lucaCoder, autonomousAssistant]
+---
+
+# Assistant Factory Pattern
+
+## Problem
+
+`LucaCoder` and `AutonomousAssistant` both duplicate the same pattern: create an inner `Assistant`, stack tool bundles, wire a permission interceptor, forward events. The permission system, approval flow, and event forwarding are copy-pasted between them. `LucaCoder` is just `AutonomousAssistant` + coding opinions (bash tool, skill loading, project instructions).
+
+Both features **wrap** an assistant rather than **composing** one. This means every method on `Assistant` (ask, tools, messages, conversation) has to be proxied through the wrapper.
+
+## Proposal
+
+### 1. Extract the permission layer into a `use()`-able plugin
+
+The permission system (allow/ask/deny per tool, pending approvals, approval history) is just a `beforeToolCall` interceptor. It doesn't need to be a feature — it's a plugin function.
+
+```typescript
+import type { Assistant } from './assistant'
+
+interface PermissionConfig {
+  permissions?: Record<string, 'allow' | 'ask' | 'deny'>
+  defaultPermission?: 'allow' | 'ask' | 'deny'
+}
+
+function withPermissions(config: PermissionConfig = {}) {
+  return (assistant: Assistant) => {
+    const perms = config.permissions || {}
+    const defaultPerm = config.defaultPermission || 'ask'
+    const pendingResolvers = new Map<string, (d: 'approve' | 'deny') => void>()
+
+    assistant.intercept('beforeToolCall', async (ctx, next) => {
+      const policy = perms[ctx.name] || defaultPerm
+
+      if (policy === 'deny') {
+        ctx.skip = true
+        ctx.result = JSON.stringify({ blocked: true, tool: ctx.name, reason: 'Permission denied.' })
+        assistant.emit('toolBlocked', ctx.name, 'deny policy')
+        return
+      }
+
+      if (policy === 'allow') {
+        await next()
+        return
+      }
+
+      // 'ask' — emit event and block until resolved
+      const id = assistant.container.utils.uuid()
+      const decision = await new Promise<'approve' | 'deny'>((resolve) => {
+        pendingResolvers.set(id, resolve)
+        assistant.emit('permissionRequest', { id, toolName: ctx.name, args: ctx.args })
+      })
+
+      pendingResolvers.delete(id)
+
+      if (decision === 'approve') {
+        await next()
+      } else {
+        ctx.skip = true
+        ctx.result = JSON.stringify({ blocked: true, tool: ctx.name, reason: 'User denied.' })
+      }
+    })
+
+    // Expose approve/deny on the assistant instance
+    ;(assistant as any).approve = (id: string) => pendingResolvers.get(id)?.('approve')
+    ;(assistant as any).deny = (id: string) => pendingResolvers.get(id)?.('deny')
+  }
+}
+```
+
+### 2. LucaCoder becomes an assistant factory, not a wrapper
+
+Instead of owning an inner assistant and proxying everything, `LucaCoder` creates and returns a configured `Assistant`:
+
+```typescript
+export class LucaCoder extends Feature {
+  createAssistant(overrides?: Partial<AssistantOptions>): Assistant {
+    const assistant = this.container.feature('assistant', {
+      systemPrompt: this.buildSystemPrompt(),
+      ...overrides,
+    })
+
+    // This is the runtime equivalent of hooks.ts started()
+    assistant.use(this.container.feature('codingTools'))
+
+    const fileTools = this.container.feature('fileTools')
+    assistant.use(fileTools.toTools({ only: ['editFile', 'writeFile', 'deleteFile'] }))
+    fileTools.setupToolsConsumer(assistant)
+
+    assistant.use(this.container.feature('processManager'))
+    assistant.use(this.container.feature('skillsLibrary'))
+
+    // Permission layer as a plugin
+    if (this.options.permissions || this.options.defaultPermission) {
+      assistant.use(withPermissions({
+        permissions: this.options.permissions,
+        defaultPermission: this.options.defaultPermission,
+      }))
+    }
+
+    return assistant
+  }
+}
+```
+
+### 3. Usage
+
+```typescript
+// Runtime — no disk files, works in compiled binary
+const coder = container.feature('lucaCoder')
+const assistant = await coder.createAssistant()
+await assistant.ask('refactor the auth module')
+
+// With permission gating
+const coder = container.feature('lucaCoder', {
+  permissions: { editFile: 'ask', writeFile: 'ask', deleteFile: 'ask' },
+  defaultPermission: 'allow',
+})
+const assistant = await coder.createAssistant()
+assistant.on('permissionRequest', ({ id }) => assistant.approve(id))
+```
+
+### 4. AutonomousAssistant collapses
+
+`AutonomousAssistant` becomes either:
+- Deleted entirely (replaced by `withPermissions` plugin on any assistant)
+- Or a thin factory like LucaCoder but with no coding opinions — just `createAssistant()` + permissions
+
+## What This Achieves
+
+- **No duplication** — permission logic lives in one place (the plugin)
+- **No proxying** — you get back a real `Assistant`, not a wrapper that forwards `.ask()`, `.tools`, `.messages`, `.conversation`
+- **Binary-compatible** — the factory pattern doesn't need disk files, so it works in the compiled `luca` binary
+- **Composable** — `assistants/codingAssistant/hooks.ts` and `LucaCoder.createAssistant()` produce the exact same result through the same mechanism (`assistant.use()`)
+- **The folder-based assistant becomes the reference implementation** of what the factory does programmatically
+
+## Relationship to assistants/codingAssistant
+
+The disk-based `assistants/codingAssistant/` (CORE.md + hooks.ts + tools.ts) is the "editable" version. `LucaCoder.createAssistant()` is the "compiled" version. Same tools, same prompt, same behavior — one loads from files, the other is baked in code.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soederpop/luca",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "website": "https://luca.soederpop.com",
   "description": "lightweight universal conversational architecture AKA Le Ultimate Component Architecture AKA Last Universal Common Ancestor, part AI part Human",
   "author": "jon soeder aka the people's champ <jon@soederpop.com>",
@@ -19,26 +19,77 @@
     "coding assistant"
   ],
   "main": "./src/node.ts",
-  "types": "./src/node.ts",
+  "types": "./dist/node.d.ts",
   "browser": "./src/browser.ts",
   "exports": {
-    ".": "./src/node.ts",
-    "./node": "./src/node.ts",
-    "./node/*": "./src/node/*",
-    "./web": "./src/browser.ts",
-    "./web/*": "./src/web/*",
-    "./agi": "./src/agi/index.ts",
-    "./agi/*": "./src/agi/*",
-    "./schemas": "./src/schemas/base.ts",
-    "./schemas/*": "./src/schemas/*",
-    "./container": "./src/container.ts",
-    "./client": "./src/client.ts",
-    "./clients/*": "./src/clients/*",
-    "./server": "./src/server.ts",
-    "./servers/*": "./src/servers/*",
-    "./feature": "./src/feature.ts",
-    "./react": "./src/react/index.ts",
-    "./introspection": "./src/introspection/index.ts"
+    ".": {
+      "types": "./dist/node.d.ts",
+      "default": "./src/node.ts"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./src/node.ts"
+    },
+    "./node/*": {
+      "types": "./dist/node/*.d.ts",
+      "default": "./src/node/*"
+    },
+    "./web": {
+      "types": "./dist/browser.d.ts",
+      "default": "./src/browser.ts"
+    },
+    "./web/*": {
+      "types": "./dist/web/*.d.ts",
+      "default": "./src/web/*"
+    },
+    "./agi": {
+      "types": "./dist/agi/index.d.ts",
+      "default": "./src/agi/index.ts"
+    },
+    "./agi/*": {
+      "types": "./dist/agi/*.d.ts",
+      "default": "./src/agi/*"
+    },
+    "./schemas": {
+      "types": "./dist/schemas/base.d.ts",
+      "default": "./src/schemas/base.ts"
+    },
+    "./schemas/*": {
+      "types": "./dist/schemas/*.d.ts",
+      "default": "./src/schemas/*"
+    },
+    "./container": {
+      "types": "./dist/container.d.ts",
+      "default": "./src/container.ts"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./src/client.ts"
+    },
+    "./clients/*": {
+      "types": "./dist/clients/*.d.ts",
+      "default": "./src/clients/*"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./src/server.ts"
+    },
+    "./servers/*": {
+      "types": "./dist/servers/*.d.ts",
+      "default": "./src/servers/*"
+    },
+    "./feature": {
+      "types": "./dist/feature.d.ts",
+      "default": "./src/feature.ts"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./src/react/index.ts"
+    },
+    "./introspection": {
+      "types": "./dist/introspection/index.d.ts",
+      "default": "./src/introspection/index.ts"
+    }
   },
   "bin": {
     "luca": "./src/cli/cli.ts"
@@ -51,13 +102,15 @@
     "build:web": "bun run scripts/build-web.ts",
     "build:introspection": "bun run src/cli/cli.ts introspect",
     "compile": "bun run build:introspection && bun run build:scaffolds && bun run build:bootstrap && bun run build:python-bridge && bash scripts/stamp-build.sh && bun build ./src/cli/cli.ts --compile --outfile dist/luca --external node-llama-cpp",
+    "build:types": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "build:scaffolds": "bun run src/cli/cli.ts build-scaffolds",
     "build:bootstrap": "bun run src/cli/cli.ts build-bootstrap",
     "build:python-bridge": "bun run src/cli/cli.ts build-python-bridge",
     "test": "bun test test/*.test.ts",
     "update-all-docs": "bun run test && bun run build:introspection && bun run src/cli/cli.ts generate-api-docs && bun run build:scaffolds && bun run build:bootstrap && bun run build:python-bridge",
-    "precommit": "bun run update-all-docs && git add docs/apis/ src/introspection/generated.*.ts src/scaffolds/generated.ts src/bootstrap/generated.ts src/python/generated.ts && bun compile",
+    "setup": "git update-index --skip-worktree src/introspection/generated.node.ts src/introspection/generated.web.ts src/introspection/generated.agi.ts src/scaffolds/generated.ts src/bootstrap/generated.ts src/python/generated.ts",
+    "precommit": "bun run typecheck && bun run update-all-docs && git add docs/apis/ && bun compile",
     "test:integration": "bun test ./test-integration/"
   },
   "devDependencies": {
@@ -97,7 +150,7 @@
     "@supabase/supabase-js": "^2.95.3",
     "@types/marked": "^6.0.0",
     "@types/marked-terminal": "^6.1.1",
-    "axios": "^1.3.5",
+    "axios": "1.13.6",
     "cacache": "^17.0.7",
     "chalk": "^5.2.0",
     "child-process-promise": "^2.2.1",

package/src/agi/container.server.ts

@@ -3,6 +3,7 @@ import { type NodeFeatures, NodeContainer } from '../node/container'
 import '@/introspection/generated.agi.js'
 import { OpenAIClient } from '../clients/openai'
 import { ElevenLabsClient } from '../clients/elevenlabs'
+import { VoiceBoxClient } from '../clients/voicebox'
 import { ClaudeCode } from './features/claude-code'
 import { OpenAICodex } from './features/openai-codex'
 import { Conversation } from './features/conversation'
@@ -16,6 +17,8 @@ import { SemanticSearch } from '@soederpop/luca/node/features/semantic-search'
 import { ContentDb } from '@soederpop/luca/node/features/content-db'
 import { FileTools } from './features/file-tools'
 import { LucaCoder } from './features/luca-coder'
+import { Memory } from './features/agent-memory'
+import { CodingTools } from './features/coding-tools'
 
 import type { ConversationTool } from './features/conversation'
 import type { ZodType } from 'zod'
@@ -32,6 +35,8 @@ export {
 	BrowserUse,
 	FileTools,
 	LucaCoder,
+	Memory,
+	CodingTools,
 	SemanticSearch,
 	ContentDb,
 	NodeContainer,
@@ -58,6 +63,8 @@ export interface AGIFeatures extends NodeFeatures {
 	browserUse: typeof BrowserUse
 	fileTools: typeof FileTools
 	lucaCoder: typeof LucaCoder
+	memory: typeof Memory
+	codingTools: typeof CodingTools
 }
 
 export interface ConversationFactoryOptions {
@@ -122,6 +129,7 @@ export class AGIContainer<
 const container = new AGIContainer()
 	.use(OpenAIClient)
 	.use(ElevenLabsClient)
+	.use(VoiceBoxClient)
 	.use(ClaudeCode)
 	.use(OpenAICodex)
 	.use(Conversation)
@@ -133,6 +141,8 @@ const container = new AGIContainer()
 	.use(BrowserUse)
 	.use(FileTools)
 	.use(LucaCoder)
+	.use(Memory)
+	.use(CodingTools)
 	.use(SemanticSearch)
 
 container.docs = container.feature('contentDb', {

package/src/agi/feature.ts

@@ -0,0 +1,13 @@
+import type { AGIFeatures, AGIContainer } from './container.server.js'
+import type { FeatureOptions, FeatureState } from '../feature.ts'
+import { features, Feature as NodeFeature } from '../node/feature.ts'
+
+export { features }
+
+export type { FeatureState, FeatureOptions }
+
+export class Feature<T extends FeatureState = FeatureState, K extends FeatureOptions = FeatureOptions> extends NodeFeature<T, K> {
+    override get container(): AGIContainer<AGIFeatures> {
+        return super.container as AGIContainer<AGIFeatures>
+    }
+}