freddie 0.0.41 → 0.0.42

package/AGENTS.md

@@ -12,10 +12,40 @@ Instructions for AI coding assistants working on Freddie.
 - `anentrypoint-design` v0.0.27 — webjsx + ripple-ui. Use for any web UI; do NOT add React. Source in C:/dev/anentrypoint-design; freddie links via `file:../anentrypoint-design`.
 - `xstate` v5 — every long-lived state machine (agent turns, gateway lifecycle, approvals).
 
+## Plugin architecture (2026-05-03, pre-v1, no compat shims)
+
+The monolith was decomposed into a universal plugin contract. Every tool, platform, memory provider, GUI route, and core subsystem is a plugin under `plugins/<name>/`. The old paths (`src/tools/registry.js`, `src/tools/*.js`, `src/gateway/platforms/*.js`, `src/plugins/memory/*.js`) are GONE — do not reach for them.
+
+Contract: `{ name, version?, surfaces: 'pi'|'gui'|'both', requires?: [...names], register(ctx) }` — defined in `src/host/contract.js` (39L).
+- PI_VERBS: tool, env, command, cron, platform, memory, skill, context, agentExt, cli
+- GUI_VERBS: route, page, nav, debug, api, asset
+- HOOK_NAMES: preToolCall, postToolCall, preLlmCall, postLlmCall, onSessionStart, onSessionEnd, onTurnStart, onTurnEnd, onMessageInbound, onMessageOutbound
+- Surface guard throws `plugin <name>: surface verb '<verb>' not allowed (declared surfaces=<name>)` at load
+- `requires` cycles throw `plugin cycle: a -> b -> a` synchronously
+
+Host: `src/host/host.js` (157L) — `createHost({surfaces, configStore, env})` + `discoverPlugins(roots)`. Singleton in `src/host/index.js`: `host()`, `bootHost(extraRoots)`, `resetHostForTests()`. Roots walked: `<repo>/plugins`, `~/.freddie/plugins/`, `<cwd>/.freddie/plugins/`.
+
+`register(ctx)` receives `{ pi, gui, hooks, log, config, host, env }`:
+- `log` — scoped JSONL with plugin name
+- `config` — scoped under `plugins.<name>` (`get/set/all`)
+- `host` — `{plugins(), get(name)}`
+
+Migrated 120+ in-tree plugins: 70 tools, 27 platforms, 8 memory providers, 11 GUI dashboard plugins (`gui-sessions/tools/cron/skills/config/env/debug/chat/batch/gateway/profiles-commands-health`), 6 core plugins (`core-cli/skills/cron/commands/agent-machine/context-engine/compressor`). Tool plugins lay out as `plugins/<name>/{plugin,handler}.js` where handler exports `_tool` or `_tool0`/`_tool1` for multi-tool files; `plugin.js` calls `pi.tools.register(_tool)`.
+
+Thin shims (still resolved through host, do not bypass):
+- `src/plugins/manager.js` — over the host
+- `src/web/server.js` (23L) — iterates `host.gui.routes.list()`
+- `bin/freddie.js` (19L) — iterates `host.pi.cli.list()` and registers commander commands
+- `src/gateway/platforms.js` — `makePlatform/getPlatformAdapter/listPlatformNames` (finds adapter by `*Adapter$` name match)
+- `src/plugins/memory/provider.js` — host-router (`createMemoryProvider`, `listMemoryProviders`, `registerMemoryProvider`, `MemoryProvider`)
+- All consumers (`acp/server.js`, `acp/tools.js`, `mcp/server.js`, `agent/machine.js`, `toolsets.js`, `cli/gateway_cli.js`) resolve via `bootHost()`
+
+Witness 2026-05-03: test.js 12/12 green @ 195L (asserts `host.plugins().length>=100`, `platforms.list>=18`, `memory.list>=8`, surface guard throws, cycle throws). `node bin/freddie.js tools` shows 70. `help-all` 32 lines. 11 dashboard `/api/*` routes return 200.
+
 ## Layout
 
 ```
-src/home.js                      # getFophHome, applyProfileOverride
+src/home.js                      # getFreddieHome, applyProfileOverride
 src/config.js                    # loadConfig, saveConfigValue, DEFAULT_CONFIG, _config_version migrations
 src/sessions.js                  # better-sqlite3 + FTS5
 src/auth.js                      # FileAuthStore for credentials
@@ -49,20 +79,29 @@ bin/freddie.js                     # commander CLI: tools, skills, profile, skin
 
 ## Adding a tool
 
-```js
-import { registry } from './tools/registry.js'
+Tools are now plugins. Create `plugins/<name>/plugin.js` + `plugins/<name>/handler.js`:
 
-registry.register({
+```js
+// plugins/my-tool/handler.js
+export const _tool = {
     name: 'my_tool',
     toolset: 'core',
     schema: { name: 'my_tool', description: '…', parameters: { type: 'object', properties: { x: { type: 'string' } }, required: ['x'] } },
     handler: async (args, ctx) => ({ ok: true, x: args.x }),
     checkFn: () => !!process.env.MY_KEY,
     requiresEnv: ['MY_KEY'],
-})
+}
+
+// plugins/my-tool/plugin.js
+import { _tool } from './handler.js'
+export default {
+    name: 'my-tool',
+    surfaces: 'pi',
+    register({ pi }) { pi.tools.register(_tool) },
+}
 ```
 
-Drop the file in `src/tools/`. Auto-discovered by `discoverBuiltinTools()`.
+Auto-discovered on `bootHost()`. For multi-tool files export `_tool0`, `_tool1`, ….
 
 ## Adding a slash command
 
@@ -76,14 +115,31 @@ Dispatch happens against the canonical name resolved via `resolveCommand()`. Gat
 
 ## Adding a gateway platform
 
-1. Drop `src/gateway/platforms/<name>.js`
-2. Extend `EventEmitter`, implement `start/stop/send`, emit `'message'`
-3. `Gateway.register('name', adapter)` wires inbound to the agent
+Platforms are plugins. Create `plugins/platform-<name>/{plugin,handler}.js`:
+
+```js
+// handler.js — class name MUST end with `Adapter` for getPlatformAdapter() to resolve it
+export class MynameAdapter extends EventEmitter {
+    async start() { /* … */ }
+    async stop() { /* … */ }
+    async send(msg) { /* … */ }
+}
+
+// plugin.js
+import * as module from './handler.js'
+export default {
+    name: 'platform-myname',
+    surfaces: 'pi',
+    register({ pi }) { pi.platforms.register({ name: 'myname', module }) },
+}
+```
+
+`makePlatform('myname', opts)` (from `src/gateway/platforms.js`) instantiates the adapter via `*Adapter$` name match.
 
 ## Profile-safe code
 
-- Always `getFophHome()` for state paths. Never `path.join(os.homedir(), '.freddie')`.
-- Always `displayFophHome()` for user-visible messages (returns `~/.freddie` or `~/.freddie/profiles/<name>`).
+- Always `getFreddieHome()` for state paths. Never `path.join(os.homedir(), '.freddie')`.
+- Always `displayFreddieHome()` for user-visible messages (returns `~/.freddie` or `~/.freddie/profiles/<name>`).
 - Profile operations are HOME-anchored: `getProfilesRoot()` returns `~/.freddie/profiles` regardless of active profile.
 
 ## Cache safety
@@ -100,6 +156,9 @@ One `test.js` at project root. ≤200 lines. Plain assertions, real data, real s
 - `pi-ai` reads provider keys via `findEnvKeys` / `getEnvApiKey`. Match its env var names (`ANTHROPIC_API_KEY`, etc.).
 - `floosie.ProcessorMachine` is an xstate machine. Compose, don't fork.
 - **Browser inline `<script type="module">` syntax errors** — When a pageerror reports "missing ) after argument list" with no file:line info, extract the script body to a separate `.js` file and run `node --check path/to/file.js`. Browsers swallow line numbers for inline modules; node's V8 parser prints exact line. Essential for debugging unbalanced parens in webjsx-style nested `h()` calls. (Confirmed 2026-04-30: freddie dashboard app.js, line 133.)
+- **src/web/app.js 200-line policy violation** — File is 548 lines, violating gm hard cap (2.7× over). Only file in 283-file codebase over limit. Likely waived intentionally or is drift to fix. When touching app.js, prefer splitting into `{app,routes,components,state}.js` over expanding further. Do not add 50+ more lines without addressing the split.
+- **libsql async debt class** — `src/sessions.js` (listSessions/search/getMessages/createSession/appendMessage) and `src/cron/scheduler.js` (listJobs/createJob/cancelJob/deleteJob) are async after the libsql migration. Sync callsites silently wrap each call in a Promise that rejects on iteration, surfacing as `TypeError: ... is not iterable` via `node bin/freddie.js sessions` or `freddie cron list`. Rule: every call into those modules must be awaited; tool ACTIONS inner functions async + handler awaits dispatched fn. Fixed 2026-05-03 across bin/freddie.js, src/web/server.js, src/cli/dump.js, src/cli/status.js, src/tools/session_search.js, src/tools/cronjob.js, src/acp/session.js. test.js can pass while CLI is broken — exercise the cli verb in test.js or smoke `node bin/freddie.js <verb>` after changes.
+- **Bulk-rename: git grep is case-sensitive on literal patterns** — `git grep -lI <name>` only matches lowercase. For case-variant sweep during rename refactors, use `git grep -liI -e <lower> -e <Title> -e <UPPER>` (per-pattern `-i` requires `-e` form). Single-form check is a false-clean trap.
 
 ## Subsystem guide
 
@@ -157,10 +216,19 @@ All 21 named integration tests in `test.js` pass (exit 0). Subsystem coverage:
 - **LLM resolver priority** — (1) explicit `callLLM` arg, (2) pi-bridge if `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GROQ_API_KEY` / `OPENROUTER_API_KEY` env set, (3) acptoapi if `/v1/models` returns 200, (4) throw with actionable error. Configurable via `FREDDIE_LLM_URL` and `FREDDIE_LLM_MODEL` env vars.
 - **acptoapi Claude backend tool-call mismatch** — acptoapi's Claude backend returns Anthropic-style XML `<function_calls><invoke name="bash">…</invoke></function_calls>` in message content, not OpenAI `tool_calls` JSON array. This breaks the agent's tool-loop auto-fire. Workaround: use real Anthropic API key + pi-bridge for proper tool dispatch, or use structured `callLLM` stubs in tests.
 
+## Pre-rename validation snapshot (2026-05-03)
+
+All 12 test.js named groups passing: home+config+skin, sessions+FTS5, tools+toolsets, agent-machine, gateway+platforms+hooks, acp-full, plugins+memory, profiles+observability+auth+env+context+cron+batch+slash+skills, utils+time+redact+model-meta+agent-helpers, mcp+swe+distributions+account+credpool, compressor+trajectory, env+pi+cli+tui+setup+website+helpers. CLI boots (`node bin/freddie.js --version` → 0.1.0), tools list 25+ across core/browse/creative, commander 14 commands. 284 source files, test.js 198/200 lines, pkg.version 0.0.39 but bin reports 0.1.0. Node_modules installed, lockfile present. Baseline established before rename; re-run test.js post-rename to isolate rename-induced failures.
+
 ## Learning audit
 
 - 2026-05-01: 5 items queried (pi-ai keys, profile paths, cache safety, floosie composition, browser errors); rs-learn store unavailable (exec:recall returned no results). 0 items migrated. New facts (anentrypoint-design build, dashboard live-rerender caveat, libuv spawn caveat) ingested directly into rs-learn; audit will retry in future sessions.
 - 2026-05-01 (session 2): 5 items queried (pi-ai env keys, profile safe paths, cache safety, floosie composition, browser syntax errors). rs-learn store still empty. 0 items migrated. Refined anentrypoint-design source/dist skew entry in AGENTS.md to include silent-failure pageerror diagnostic. New fact `reference/anentrypoint-design-dist-rebuild` ingested.
+- 2026-05-03: Pre-rename validation snapshot recorded (all 12 test.js groups, CLI, tools, 284 files, version drift). Baseline stored to isolate post-rename regressions.
+- 2026-05-03 (session 2): Ingested feedback/app-js-size-violation (src/web/app.js 548L violation) into AGENTS.md Substrate gotchas. rs-learn store unavailable (exec:memorize missing binary). 0 migration audit items queried. 1 new fact added.
+- 2026-05-03 (session 3): Added Website theme + YAML caveats section (3 items: structured-YAML rendering, YAML colon-space trap, SSR innerHTML injection). rs-learn store still unavailable (exec:memorize → exit 127, command not found). 0 migration audit items queried. 3 new facts added to AGENTS.md only.
+- 2026-05-03 (session 3): Ingested libsql-async-debt-class into AGENTS.md Substrate gotchas (sessions.js + cron/scheduler.js async callsites; silent TypeError class; test.js passes while CLI broken). rs-learn store still unavailable (exec:memorize/exec:recall not on PATH). 0 migration audit items queried. 1 new fact added.
+- 2026-05-03 (session 4): Plugin-architecture decomposition recorded — added "Plugin architecture" section before Layout, rewrote "Adding a tool" + "Adding a gateway platform" for plugins/<name>/{plugin,handler}.js shape. Ingested 6 facts to rs-learn (project/freddie-plugin-architecture, reference/freddie-host-contract, reference/freddie-plugin-ctx, project/freddie-migrated-subsystems, reference/freddie-thin-shims, project/freddie-plugin-witness). Audit: 5 queries fired (pi-ai env keys, profile safe paths, libsql async debt, browser inline module errors, yaml colon space trap, plus self-test on freddie-plugin-architecture) — all returned "No recall results". rs-learn ingest path live but retrieval side empty for this session (likely needs learn-build propagation). 0 items migrated; AGENTS.md items retained.
 
 ## Dashboard web UI caveats
 
@@ -168,6 +236,12 @@ All 21 named integration tests in `test.js` pass (exit 0). Subsystem coverage:
 - **Live page rerender caveat** — AppState.body caching (page computed once at navigation, body saved) breaks for live routes like #/chat where AppState is mutated mid-flight (SSE pushes new messages). Fix: detect live routes in rerender(), recompute body: `if (AppState.hash === '#/chat') { Promise.resolve(PAGES['#/chat']()).then(b => { AppState.body = b; _mount() }); return }`. Any future live-streaming pages (cron output, traces) need the same treatment.
 - **libuv spawn caveat** — Spawning createDashboard() from exec:nodejs and keeping process alive triggers libuv UV_HANDLE_CLOSING crash on shutdown. Reliable alternative: boot via `node bin/freddie.js dashboard --port <port>`. Liveness checks: exec:browser → page.goto → window.__debug.dashboard() returns {booted, ts, framework, route}; window.__debug.chat() exposes {messages, streaming, draft}; window.__debug.sendChat(text) drives round-trips.
 
+## Website theme + YAML caveats (2026-05-03)
+
+- **Structured-YAML rendering** — `website/theme.mjs` (164L) renders structured YAML via 247420 design vocabulary, not raw markdown. Consumes `page.hero` (heading/subheading/accent/body/badges/ctas), `page.sections[]` (rotating rail color green→purple→mascot→sun→flame→sky by section index, optional `lede` + per-item `benefit` italic), `page.examples[]` (railed link list with mono numeric ranks + ↗ glyph). Falls back to `page.body` markdown for prose. Style block inlined so rail/dot/chip/btn classes work without ds-247420 SDK CSS loading first. To get a specific rail color, reorder sections. Prefer enriching hero+sections+examples over expanding body markdown; copy existing YAML structure as template for new pages.
+- **YAML colon-space trap** — In `website/content/pages/*.yaml`, any value containing `: ` outside backticks (e.g. `[linux, macos, windows]`, `requiresEnv: ['MY_KEY']` code snippets) MUST be double-quoted. The parser otherwise interprets the embedded colon as a mapping and the file fails to load. Hit twice: tools.yaml line 72, skills.yaml line 40. Fix is wrapping the whole value in `"..."`.
+- **SSR innerHTML injection beats client dispatch** — anentrypoint-design v0.0.27 exposes Hero/HomeView/Panel/Row/Section/WorksList, but pre-mounted SSR injection via innerHTML is more reliable than dispatching components client-side at build — avoids depending on SDK loading before the static HTML paints. Emitted HTML carries rail/dot/chip/btn classes with inline styles to be self-sufficient.
+
 ## Residual complement (NOT ported this session)
 
 Genuinely out of session reach, with reasons:

package/CHANGELOG.md

@@ -30,3 +30,19 @@ All notable changes to this project will be documented in this file.
 ## Previous Releases
 
 See git history for earlier versions.
+
+## v0.1.1 — Website expressiveness + async callsite repair
+
+- website: theme.mjs now consumes structured YAML (hero/sections/examples) and renders via the 247420 design vocabulary — railed panels, badges, CTAs, mono-rank explore lists. Six content pages rewritten to express explicit when/why/how lines + per-row benefit framings.
+- bug: repaired async callsite debt across bin/freddie.js, src/web/server.js, src/cli/dump.js, src/cli/status.js, src/tools/session_search.js, src/tools/cronjob.js, src/acp/session.js — every consumer of sessions.js and cron/scheduler.js now awaits. `freddie sessions`, `freddie cron list`, `freddie search` exit 0.
+- tests: test.js still 12/12. tools registered: 70.
+
+## v0.2.0 — Plugin architecture foundation
+
+- Universal plugin contract at src/host/contract.js: { name, surfaces: pi|gui|both, requires?, register(ctx) } with topo-sorted load, surface guards, dep cycle detection, hook registry.
+- src/host/host.js implements createHost, surface registries (pi: tools/envs/commands/crons/platforms/memory/skills/contexts/agentExts; gui: routes/pages/nav/debug/api/asset), and discoverPlugins.
+- src/host/index.js exposes singleton bootHost() that walks bundled plugins/ + ~/.freddie/plugins/ + .freddie/plugins/.
+- 103 in-tree plugins shipped: 70 tools (plugins/<name>/), 27 platforms (plugins/platform-<name>/), 8 memory providers (plugins/memory-<name>/), plus the prior 6 stub plugins.
+- src/tools/registry.js, src/tools/*.js, src/gateway/platforms/*.js all deleted; legacy src/plugins/manager.js becomes a thin shim over the new host.
+- Consumers (bin/freddie.js, src/agent/machine.js, src/web/server.js, src/acp/server.js, src/acp/tools.js, src/mcp/server.js, src/cli/gateway_cli.js, src/toolsets.js) now resolve everything via bootHost().
+- test.js asserts surface-guard throws, requires-cycle throws, plugin counts (>=100 plugins, >=18 platforms, >=8 memory). 12/12 groups green at 195 lines.

package/README.md

@@ -1,5 +1,5 @@
 # Freddie
- 
+
 An open JS agent harness built on pi-mono, xstate, floosie, and anentrypoint-design. Features a full gateway, context compressor, multi-platform adapters, and a live dashboard — built with:
 
 - [`@mariozechner/pi-coding-agent`](https://www.npmjs.com/package/@mariozechner/pi-coding-agent) — agent + tools + interactive TUI substrate
@@ -81,7 +81,7 @@ Built-in: `bash`, `read`, `write`, `edit`, `grep`, `todo`, `memory`, `delegate`,
 freddie/
 ├── bin/freddie.js                  # commander CLI: tools, skills, profile, skin, sessions, search, gateway, acp, run, cron, batch, dashboard, help-all
 ├── src/
-│   ├── home.js                   # getFophHome + profiles
+│   ├── home.js                   # getFreddieHome + profiles
 │   ├── config.js                 # YAML + migrations
 │   ├── sessions.js               # SQLite + FTS5
 │   ├── auth.js                   # FileAuthStore (~/.freddie/auth/)

package/bin/freddie.js

@@ -1,116 +1,19 @@
 #!/usr/bin/env node
 import { Command } from 'commander'
-import { registry, discoverBuiltinTools } from '../src/tools/registry.js'
-import { listAllProfiles, createProfile, deleteProfile, switchProfile } from '../src/commands/profile.js'
-import { listSkills } from '../src/skills/index.js'
-import { Gateway } from '../src/gateway/run.js'
-import { WebhookAdapter } from '../src/gateway/platforms/webhook.js'
-import { ApiServerAdapter } from '../src/gateway/platforms/api_server.js'
-import { AcpServer } from '../src/acp/server.js'
-import { COMMAND_REGISTRY, COMMANDS_BY_CATEGORY } from '../src/commands/registry.js'
-import { getActiveSkin, listBuiltinSkins, setActiveSkin } from '../src/skin/engine.js'
-import { listSessions, search } from '../src/sessions.js'
+import { bootHost } from '../src/host/index.js'
 
 const program = new Command()
-program.name('freddie').version('0.1.0').description('Freddie — JS port of hermes-agent built on pi-mono')
-
-program.command('tools')
-    .description('List/inspect tools')
-    .argument('[action]', 'list | get', 'list')
-    .argument('[name]')
-    .action(async (action, name) => {
-        await discoverBuiltinTools()
-        if (action === 'get' && name) { console.log(JSON.stringify(registry.get(name)?.schema, null, 2)); return }
-        for (const t of registry.list()) console.log(`${t.toolset.padEnd(10)} ${t.name}\t${t.schema.description.slice(0, 60)}`)
-    })
-
-program.command('skills')
-    .description('List skills')
-    .argument('[action]', 'list', 'list')
-    .action(() => {
-        for (const s of listSkills()) console.log(`${s.name}\t${s.description.slice(0, 80)}`)
-    })
-
-program.command('profile')
-    .argument('[action]', 'list | create | switch | delete', 'list')
-    .argument('[name]')
-    .action((action, name) => {
-        if (action === 'list') { for (const p of listAllProfiles()) console.log(p); return }
-        if (action === 'create') { createProfile(name); console.log('created:', name); return }
-        if (action === 'delete') { deleteProfile(name); console.log('deleted:', name); return }
-        if (action === 'switch') { switchProfile(name); console.log('switched:', name || 'default'); return }
-    })
-
-program.command('skin')
-    .argument('[name]')
-    .action((name) => {
-        if (!name) { console.log('active:', getActiveSkin().name); console.log('available:', listBuiltinSkins().join(', ')); return }
-        setActiveSkin(name); console.log('switched to:', name)
-    })
-
-program.command('sessions').action(() => { for (const s of listSessions()) console.log(`${s.id}\t${s.platform}\t${new Date(s.updated_at).toISOString()}\t${s.title || ''}`) })
-program.command('search').argument('<query>').action((q) => { for (const r of search(q)) console.log(`${r.session_id}\t${(r.content || '').slice(0, 100)}`) })
-
-program.command('gateway')
-    .option('--port <port>', 'webhook port', '0')
-    .action(async (opts) => {
-        const webhook = new WebhookAdapter({ port: Number(opts.port) })
-        const api = new ApiServerAdapter({ port: 0 })
-        const gw = new Gateway({ platforms: { webhook, api_server: api } })
-        await gw.start()
-        console.log('webhook port:', webhook.port, '\napi_server port:', api.port)
-        process.on('SIGINT', async () => { await gw.stop(); process.exit(0) })
-    })
-
-program.command('acp').action(() => { const s = new AcpServer(); s.start() })
-
-program.command('help-all').action(() => {
-    for (const [cat, cmds] of Object.entries(COMMANDS_BY_CATEGORY)) {
-        console.log(`\n# ${cat}`)
-        for (const c of cmds) console.log(`  /${c.name}${c.args_hint ? ' ' + c.args_hint : ''}\t${c.description}`)
+program.name('freddie').version('0.1.0').description('Freddie — open JS agent harness, plugin-driven')
+
+const host = await bootHost()
+for (const def of host.pi.cli.list()) {
+    const cmd = program.command(def.name).description(def.description || '')
+    for (const a of def.args || []) {
+        const tag = a.required ? `<${a.name}>` : `[${a.name}]`
+        cmd.argument(tag, a.description || '', a.default)
     }
-})
-
-program.command('run').description('Run interactive REPL').action(async () => {
-    const { interactive } = await import('../src/cli/interactive.js')
-    let callLLM = null
-    try { ({ callLLM } = await import('../src/agent/pi-bridge.js')) } catch {}
-    await interactive({ callLLM })
-})
-
-program.command('cron')
-    .argument('[action]', 'list | add | cancel | delete | tick', 'list')
-    .argument('[arg1]')
-    .argument('[arg2]')
-    .action(async (action, a1, a2) => {
-        const { listJobs, createJob, cancelJob, deleteJob, tick } = await import('../src/cron/scheduler.js')
-        if (action === 'list') { for (const j of listJobs()) console.log(`${j.id}\t${j.cron}\t${j.enabled ? 'on ' : 'off'}\t${j.prompt.slice(0, 60)}`); return }
-        if (action === 'add') { const id = createJob({ cron: a1, prompt: a2 }); console.log('created:', id); return }
-        if (action === 'cancel') { cancelJob(Number(a1)); console.log('cancelled:', a1); return }
-        if (action === 'delete') { deleteJob(Number(a1)); console.log('deleted:', a1); return }
-        if (action === 'tick') { console.log('fired:', (await tick()).length); return }
-    })
-
-program.command('batch')
-    .argument('<file>', 'JSONL or TXT prompts file')
-    .option('--concurrency <n>', '', '4')
-    .option('--model <model>', '', '')
-    .action(async (file, opts) => {
-        const fs = await import('node:fs')
-        const { runBatch } = await import('../src/batch.js')
-        const raw = fs.readFileSync(file, 'utf8').trim().split('\n')
-        const prompts = raw.map(l => { try { return JSON.parse(l).prompt || JSON.parse(l) } catch { return l } }).filter(Boolean)
-        const out = await runBatch({ prompts, concurrency: Number(opts.concurrency), model: opts.model })
-        console.log('batch:', out.id, '\nfile:', out.file, '\nresults:', out.results.length)
-    })
-
-program.command('dashboard')
-    .option('--port <port>', '', '0')
-    .action(async (opts) => {
-        const { createDashboard } = await import('../src/web/server.js')
-        const d = await createDashboard({ port: Number(opts.port) })
-        console.log('dashboard:', d.url)
-        process.on('SIGINT', async () => { await d.stop(); process.exit(0) })
-    })
+    for (const o of def.options || []) cmd.option(o.flag, o.description || '', o.default)
+    cmd.action(def.action)
+}
 
 program.parseAsync(process.argv).catch(e => { console.error(e); process.exit(1) })

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "freddie",
-  "version": "0.0.41",
+  "version": "0.0.42",
   "type": "module",
-  "description": "Freddie — Free Realtime Dynamic Dialogue Information Engine. Open JS agent harness built on pi-mono, floosie, xstate, and anentrypoint-design",
+  "description": "Open JS agent harness built on pi-mono, floosie, xstate, and anentrypoint-design",
   "bin": {
     "freddie": "./bin/freddie.js"
   },
@@ -26,6 +26,15 @@
     "xstate": "^5.31.0",
     "zod": "^4.0.0"
   },
+  "optionalDependencies": {
+    "@libsql/darwin-arm64": "0.3.19",
+    "@libsql/darwin-x64": "0.3.19",
+    "@libsql/linux-arm64-gnu": "0.3.19",
+    "@libsql/linux-arm64-musl": "0.3.19",
+    "@libsql/linux-x64-gnu": "0.3.19",
+    "@libsql/linux-x64-musl": "0.3.19",
+    "@libsql/win32-x64-msvc": "0.3.19"
+  },
   "engines": {
     "node": ">=20.6.0"
   },

package/src/acp/server.js

@@ -1,6 +1,6 @@
 import readline from 'node:readline'
 import { EventEmitter } from 'node:events'
-import { registry, discoverBuiltinTools } from '../tools/registry.js'
+import { bootHost } from '../host/index.js'
 import { runTurn } from '../agent/machine.js'
 import { logger } from '../observability/log.js'
 import { Events } from './events.js'
@@ -59,8 +59,8 @@ const METHODS = {
     'session.list': (srv) => srv.sessions.list(),
     'session.end': (srv, { sessionId }) => { Events.sessionEnded((o) => srv.send(o), { sessionId }); return srv.sessions.end(sessionId) },
     'tool.list': async () => {
-        await discoverBuiltinTools()
-        return { tools: registry.list().map(t => ({ name: t.name, toolset: t.toolset, schema: t.schema })) }
+        const h = await bootHost()
+        return { tools: h.pi.tools.list().map(t => ({ name: t.name, toolset: t.toolset, schema: t.schema })) }
     },
     'permission.respond': (srv, { reqId, decision }) => {
         const pending = srv._pendingPerm.get(reqId)

package/src/acp/session.js

@@ -2,25 +2,25 @@ import { createSession, appendMessage, getMessages, listSessions } from '../sess
 
 export class AcpSessionManager {
     constructor() { this.active = new Map() }
-    new(opts = {}) {
-        const id = createSession({ platform: 'acp', ...opts })
+    async new(opts = {}) {
+        const id = await createSession({ platform: 'acp', ...opts })
         this.active.set(id, { id, created: Date.now(), opts })
         return { sessionId: id }
     }
-    resume(sessionId) {
-        const messages = getMessages(sessionId)
+    async resume(sessionId) {
+        const messages = await getMessages(sessionId)
         if (!messages) return null
         this.active.set(sessionId, { id: sessionId, resumed: Date.now(), messages })
         return { sessionId, messages }
     }
-    list() {
-        return { sessions: listSessions(50).filter(s => s.platform === 'acp') }
+    async list() {
+        return { sessions: (await listSessions(50)).filter(s => s.platform === 'acp') }
     }
     end(sessionId) {
         this.active.delete(sessionId)
         return { ended: sessionId }
     }
-    appendUser(sessionId, content) { appendMessage(sessionId, { role: 'user', content }) }
-    appendAssistant(sessionId, content) { appendMessage(sessionId, { role: 'assistant', content }) }
+    async appendUser(sessionId, content) { await appendMessage(sessionId, { role: 'user', content }) }
+    async appendAssistant(sessionId, content) { await appendMessage(sessionId, { role: 'assistant', content }) }
     isActive(sessionId) { return this.active.has(sessionId) }
 }

package/src/acp/tools.js

@@ -1,13 +1,14 @@
-import { registry, discoverBuiltinTools } from '../tools/registry.js'
+import { bootHost } from '../host/index.js'
 import { Events } from './events.js'
 export async function listToolsForAcp() {
-    await discoverBuiltinTools()
-    return registry.list().map(t => ({ name: t.name, toolset: t.toolset, schema: t.schema, requiresEnv: t.requiresEnv || [] }))
+    const h = await bootHost()
+    return h.pi.tools.list().map(t => ({ name: t.name, toolset: t.toolset, schema: t.schema, requiresEnv: t.requiresEnv || [] }))
 }
 export async function dispatchWithEvents({ name, args, send, sessionId = null }) {
+    const h = await bootHost()
     Events.toolStart(send, { sessionId, name, args })
     try {
-        const result = await registry.dispatch(name, args, { sessionId })
+        const result = await h.pi.dispatchTool(name, args, { sessionId })
         Events.toolComplete(send, { sessionId, name, result })
         return { ok: true, result }
     } catch (e) {

package/src/agent/account_usage.js

@@ -2,18 +2,18 @@ import { db } from '../db.js'
 
 async function init() {
     const d = await db()
-    d.exec(`CREATE TABLE IF NOT EXISTS account_usage (id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT, model TEXT, prompt_tokens INTEGER, completion_tokens INTEGER, cost_usd REAL, ts INTEGER NOT NULL)`)
+    await d.exec(`CREATE TABLE IF NOT EXISTS account_usage (id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT, model TEXT, prompt_tokens INTEGER, completion_tokens INTEGER, cost_usd REAL, ts INTEGER NOT NULL)`)
     return d
 }
 export async function record({ sessionId = null, model, promptTokens = 0, completionTokens = 0, costUsd = 0 } = {}) {
-    (await init()).prepare(`INSERT INTO account_usage (session_id, model, prompt_tokens, completion_tokens, cost_usd, ts) VALUES (?, ?, ?, ?, ?, ?)`).run(sessionId, model, promptTokens, completionTokens, costUsd, Date.now())
+    await (await init()).prepare(`INSERT INTO account_usage (session_id, model, prompt_tokens, completion_tokens, cost_usd, ts) VALUES (?, ?, ?, ?, ?, ?)`).run(sessionId, model, promptTokens, completionTokens, costUsd, Date.now())
 }
 export async function totalForSession(sessionId) {
-    return (await init()).prepare(`SELECT SUM(prompt_tokens) AS prompt, SUM(completion_tokens) AS completion, SUM(cost_usd) AS cost FROM account_usage WHERE session_id = ?`).get(sessionId) || { prompt: 0, completion: 0, cost: 0 }
+    return await (await init()).prepare(`SELECT SUM(prompt_tokens) AS prompt, SUM(completion_tokens) AS completion, SUM(cost_usd) AS cost FROM account_usage WHERE session_id = ?`).get(sessionId) || { prompt: 0, completion: 0, cost: 0 }
 }
 export async function totalLifetime() {
-    return (await init()).prepare(`SELECT SUM(prompt_tokens) AS prompt, SUM(completion_tokens) AS completion, SUM(cost_usd) AS cost FROM account_usage`).get() || { prompt: 0, completion: 0, cost: 0 }
+    return await (await init()).prepare(`SELECT SUM(prompt_tokens) AS prompt, SUM(completion_tokens) AS completion, SUM(cost_usd) AS cost FROM account_usage`).get() || { prompt: 0, completion: 0, cost: 0 }
 }
 export async function listRecent(limit = 50) {
-    return (await init()).prepare(`SELECT * FROM account_usage ORDER BY id DESC LIMIT ?`).all(limit)
+    return await (await init()).prepare(`SELECT * FROM account_usage ORDER BY id DESC LIMIT ?`).all(limit)
 }

package/src/agent/credential_sources.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs'
 import path from 'node:path'
-import { getFophHome } from '../home.js'
+import { getFreddieHome } from '../home.js'
 import { getAuthStore } from '../auth.js'
 const ENV_MAP = { anthropic: 'ANTHROPIC_API_KEY', openai: 'OPENAI_API_KEY', groq: 'GROQ_API_KEY', xai: 'XAI_API_KEY', openrouter: 'OPENROUTER_API_KEY', mistral: 'MISTRAL_API_KEY', deepseek: 'DEEPSEEK_API_KEY' }
 export async function resolveKey(provider) {
@@ -8,7 +8,7 @@ export async function resolveKey(provider) {
     if (process.env[env]) return { source: 'env', value: process.env[env] }
     const stored = await getAuthStore().getCredential(env)
     if (stored?.value) return { source: 'auth-store', value: stored.value }
-    const dotEnv = path.join(getFophHome(), '.env')
+    const dotEnv = path.join(getFreddieHome(), '.env')
     if (fs.existsSync(dotEnv)) {
         const m = fs.readFileSync(dotEnv, 'utf8').match(new RegExp('^' + env + '=(.+)$', 'm'))
         if (m) return { source: 'dotenv', value: m[1].replace(/^["']|["']$/g, '') }

package/src/agent/curator.js

@@ -1,5 +1,5 @@
-import { db } from '../sessions.js'
-function init() { const d = db(); d.exec(`CREATE TABLE IF NOT EXISTS curated (id INTEGER PRIMARY KEY AUTOINCREMENT, kind TEXT, key TEXT, value TEXT, ts INTEGER NOT NULL)`); return d }
-export function add(kind, key, value) { init().prepare(`INSERT INTO curated (kind, key, value, ts) VALUES (?, ?, ?, ?)`).run(kind, key, JSON.stringify(value), Date.now()); return { added: true } }
-export function list(kind) { return init().prepare(`SELECT * FROM curated WHERE kind = ? ORDER BY id DESC`).all(kind).map(r => ({ ...r, value: JSON.parse(r.value) })) }
-export function clear(kind) { init().prepare(`DELETE FROM curated WHERE kind = ?`).run(kind); return { cleared: kind } }
+import { db } from '../db.js'
+async function init() { const d = await db(); await d.exec(`CREATE TABLE IF NOT EXISTS curated (id INTEGER PRIMARY KEY AUTOINCREMENT, kind TEXT, key TEXT, value TEXT, ts INTEGER NOT NULL)`); return d }
+export async function add(kind, key, value) { await (await init()).prepare(`INSERT INTO curated (kind, key, value, ts) VALUES (?, ?, ?, ?)`).run(kind, key, JSON.stringify(value), Date.now()); return { added: true } }
+export async function list(kind) { const rows = await (await init()).prepare(`SELECT * FROM curated WHERE kind = ? ORDER BY id DESC`).all(kind); return rows.map(r => ({ ...r, value: JSON.parse(r.value) })) }
+export async function clear(kind) { await (await init()).prepare(`DELETE FROM curated WHERE kind = ?`).run(kind); return { cleared: kind } }

package/src/agent/machine.js

@@ -1,5 +1,5 @@
 import { createMachine, createActor, assign, fromPromise } from 'xstate'
-import { registry } from '../tools/registry.js'
+import { bootHost } from '../host/index.js'
 import { getEnabledToolSchemas } from '../toolsets.js'
 import { logger } from '../observability/log.js'
 import { resolveCallLLM } from './llm_resolver.js'
@@ -59,11 +59,12 @@ export function createAgentMachine({ provider, model, maxIterations = 90, callLL
             executing_tools: {
                 invoke: {
                     src: fromPromise(async ({ input }) => {
+                        const h = await bootHost()
                         const last = input.messages[input.messages.length - 1]
                         const calls = last.tool_calls || []
                         const results = []
                         for (const call of calls) {
-                            const res = await registry.dispatch(call.name || call.function?.name, call.arguments || call.function?.arguments || {})
+                            const res = await h.pi.dispatchTool(call.name || call.function?.name, call.arguments || call.function?.arguments || {})
                             results.push({ tool_call_id: call.id || call.tool_call_id, content: res })
                         }
                         return results

package/src/agent/manual_compression_feedback.js

@@ -1,5 +1,5 @@
-import { db } from '../sessions.js'
-function init() { const d = db(); d.exec(`CREATE TABLE IF NOT EXISTS compression_feedback (id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT, summary TEXT, rating INTEGER, notes TEXT, ts INTEGER NOT NULL)`); return d }
-export function record({ sessionId, summary, rating, notes = '' }) { init().prepare(`INSERT INTO compression_feedback (session_id, summary, rating, notes, ts) VALUES (?, ?, ?, ?, ?)`).run(sessionId, summary || '', rating, notes, Date.now()); return { recorded: true } }
-export function listForSession(sessionId) { return init().prepare(`SELECT * FROM compression_feedback WHERE session_id = ? ORDER BY id DESC`).all(sessionId) }
-export function aggregate() { return init().prepare(`SELECT AVG(rating) AS avg, COUNT(*) AS n FROM compression_feedback`).get() }
+import { db } from '../db.js'
+async function init() { const d = await db(); await d.exec(`CREATE TABLE IF NOT EXISTS compression_feedback (id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT, summary TEXT, rating INTEGER, notes TEXT, ts INTEGER NOT NULL)`); return d }
+export async function record({ sessionId, summary, rating, notes = '' }) { await (await init()).prepare(`INSERT INTO compression_feedback (session_id, summary, rating, notes, ts) VALUES (?, ?, ?, ?, ?)`).run(sessionId, summary || '', rating, notes, Date.now()); return { recorded: true } }
+export async function listForSession(sessionId) { return await (await init()).prepare(`SELECT * FROM compression_feedback WHERE session_id = ? ORDER BY id DESC`).all(sessionId) }
+export async function aggregate() { return await (await init()).prepare(`SELECT AVG(rating) AS avg, COUNT(*) AS n FROM compression_feedback`).get() }

package/src/agent/shell_hooks.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
-import { getFophHome } from '../home.js'
-function hookFile() { return path.join(getFophHome(), 'shell-hooks.json') }
+import { getFreddieHome } from '../home.js'
+function hookFile() { return path.join(getFreddieHome(), 'shell-hooks.json') }
 export function loadHooks() { try { return JSON.parse(fs.readFileSync(hookFile(), 'utf8')) } catch { return { pre_run: [], post_run: [] } } }
 export function saveHooks(h) { fs.writeFileSync(hookFile(), JSON.stringify(h, null, 2), 'utf8') }
 export function addHook(stage, command) { const h = loadHooks(); (h[stage] = h[stage] || []).push(command); saveHooks(h); return h }

package/src/auth.js

@@ -1,9 +1,9 @@
 import fs from 'node:fs'
 import path from 'node:path'
-import { getFophHome } from './home.js'
+import { getFreddieHome } from './home.js'
 
 class FileAuthStore {
-    constructor() { this.dir = path.join(getFophHome(), 'auth'); fs.mkdirSync(this.dir, { recursive: true }) }
+    constructor() { this.dir = path.join(getFreddieHome(), 'auth'); fs.mkdirSync(this.dir, { recursive: true }) }
     _path(name) { return path.join(this.dir, name + '.json') }
     async setCredential(name, value) {
         fs.writeFileSync(this._path(name), JSON.stringify({ name, value, updated: Date.now() }), { encoding: 'utf8', mode: 0o600 })

package/src/batch.js

@@ -1,13 +1,13 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { runTurn } from './agent/machine.js'
-import { getFophHome } from './home.js'
+import { getFreddieHome } from './home.js'
 import { randomUUID } from 'node:crypto'
 
 export async function runBatch({ prompts = [], concurrency = 4, model, callLLM } = {}) {
     if (!Array.isArray(prompts) || prompts.length === 0) throw new Error('prompts required')
     const id = randomUUID()
-    const dir = path.join(getFophHome(), 'batches')
+    const dir = path.join(getFreddieHome(), 'batches')
     fs.mkdirSync(dir, { recursive: true })
     const file = path.join(dir, id + '.jsonl')
     const stream = fs.createWriteStream(file, { flags: 'a' })

package/src/cli/backup.js

@@ -1,8 +1,8 @@
 import fs from 'node:fs'
 import path from 'node:path'
-import { getFophHome } from '../home.js'
+import { getFreddieHome } from '../home.js'
 export async function createBackup({ outFile } = {}) {
-    const home = getFophHome()
+    const home = getFreddieHome()
     const out = outFile || path.join(home, 'backups', 'freddie-' + new Date().toISOString().replace(/[:.]/g, '-') + '.tar.gz')
     fs.mkdirSync(path.dirname(out), { recursive: true })
     const { spawnSync } = await import('node:child_process')
@@ -11,7 +11,7 @@ export async function createBackup({ outFile } = {}) {
     return { ok: false, stderr: r.stderr, hint: 'tar may be missing on Windows; install GNU tar or use a different archiver.' }
 }
 export function listBackups() {
-    const dir = path.join(getFophHome(), 'backups')
+    const dir = path.join(getFreddieHome(), 'backups')
     if (!fs.existsSync(dir)) return []
     return fs.readdirSync(dir).filter(f => f.endsWith('.tar.gz')).map(f => ({ name: f, file: path.join(dir, f), mtime: fs.statSync(path.join(dir, f)).mtimeMs }))
 }

package/src/cli/doctor.js

@@ -1,14 +1,14 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { spawnSync } from 'node:child_process'
-import { getFophHome } from '../home.js'
+import { getFreddieHome } from '../home.js'
 const CHECKS = [
-    { name: 'freddie-home', run: () => fs.existsSync(getFophHome()) ? { ok: true } : { ok: false, fix: 'mkdir -p ' + getFophHome() } },
+    { name: 'freddie-home', run: () => fs.existsSync(getFreddieHome()) ? { ok: true } : { ok: false, fix: 'mkdir -p ' + getFreddieHome() } },
     { name: 'node-version', run: () => { const v = process.versions.node; const major = Number(v.split('.')[0]); return major >= 20 ? { ok: true, value: v } : { ok: false, fix: 'install node >=20', value: v } } },
     { name: 'better-sqlite3', run: () => { try { require.resolve('better-sqlite3'); return { ok: true } } catch { return { ok: false, fix: 'npm install' } } } },
     { name: 'gh-cli', run: () => { const r = spawnSync('gh', ['--version'], { encoding: 'utf8' }); return r.status === 0 ? { ok: true, value: r.stdout.split('\n')[0] } : { ok: false, fix: 'install gh CLI' } } },
     { name: 'git', run: () => { const r = spawnSync('git', ['--version'], { encoding: 'utf8' }); return r.status === 0 ? { ok: true, value: r.stdout.trim() } : { ok: false, fix: 'install git' } } },
-    { name: 'config-file', run: () => { const p = path.join(getFophHome(), 'config.yaml'); return fs.existsSync(p) ? { ok: true } : { ok: false, fix: 'freddie setup' } } },
+    { name: 'config-file', run: () => { const p = path.join(getFreddieHome(), 'config.yaml'); return fs.existsSync(p) ? { ok: true } : { ok: false, fix: 'freddie setup' } } },
 ]
 export function runDoctor() {
     return CHECKS.map(c => { try { return { name: c.name, ...c.run() } } catch (e) { return { name: c.name, ok: false, error: String(e.message || e) } } })