lazyclaw 6.3.1 → 6.5.0

package/lib/args.mjs

@@ -8,6 +8,7 @@
 // dispatcher in main() is the runtime authority; this list mirrors it.
 export const SUBCOMMANDS = [
   'run', 'resume', 'inspect', 'clear', 'validate', 'graph',
+  'workflow',
   'config', 'chat', 'agent',
   'doctor', 'status', 'onboard',
   'sessions', 'skills', 'providers',
@@ -32,14 +33,20 @@ export const SUBCOMMANDS = [
   'matrix',
   // v5.0 — channels plugin loader (Phase F)
   'channels',
-  // v4.1.0 — multi-agent slack system (Phase 9+)
-  'agent', 'team', 'task',
+  // v4.1.0 — multi-agent slack system (Phase 9+); 'agent' already listed above
+  'team', 'task',
   // v5.0 Phase G — persona compose + cross-tool import (spec §9, §10)
   'personality', 'migrate', 'hermes', 'openclaw',
   // v5.0.6 — arrow-key launcher menu (was the no-arg default in v5.0.5-)
   'menu',
   // v5.0 Phase H1 — trajectory exporter (spec §2.7)
   'trajectories',
+  // FTS index maintenance — `index rebuild` is the documented recovery
+  // surface (mas/index_db.mjs, doctor failure-log) for a stale/corrupt index.
+  'index',
+  // MCP — read-only inspection of configured/connected MCP servers. The
+  // servers themselves boot from cfg.mcp.servers at daemon start.
+  'mcp',
 ];
 
 export const SUBCOMMAND_SUBS = {
@@ -52,7 +59,7 @@ export const SUBCOMMAND_SUBS = {
   completion: ['bash', 'zsh'],
   auth:      ['list', 'add', 'remove', 'use', 'rotate'],
   pairing:   ['list', 'add', 'remove'],
-  nodes:     ['list', 'register', 'remove', 'pending', 'approve', 'revoke', 'devices'],
+  nodes:     ['list', 'register', 'remove', 'pending', 'approve', 'revoke', 'rotate', 'devices'],
   message:   ['list', 'add', 'remove', 'send'],
   workspace: ['list', 'init', 'show', 'remove', 'path'],
   cron:      ['list', 'add', 'remove', 'show', 'sync', 'run'],
@@ -67,6 +74,9 @@ export const SUBCOMMAND_SUBS = {
   team:      ['add', 'list', 'show', 'edit', 'remove'],
   task:      ['start', 'list', 'show', 'abandon', 'done', 'remove'],
   trajectories: ['export'],
+  index:     ['rebuild', 'embed'],
+  workflow:  ['list', 'show', 'add', 'remove', 'run'],
+  mcp:       ['list', 'add', 'remove', 'call'],
 };
 
 // Flags whose presence is the signal — they don't consume the next arg
@@ -104,6 +114,62 @@ export const BOOLEAN_FLAGS = new Set([
   'force',        // goal tick --force: bypass schedule when invoked manually
 ]);
 
+// Levenshtein edit distance — small iterative DP, no allocation per char
+// beyond two rows. Used by nearest() to power the "did you mean" suggestion
+// on an unknown subcommand. Kept here (pure leaf) so cli.mjs and tests share it.
+function editDistance(a, b) {
+  const m = a.length, n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prev = new Array(n + 1);
+  let cur = new Array(n + 1);
+  for (let j = 0; j <= n; j++) prev[j] = j;
+  for (let i = 1; i <= m; i++) {
+    cur[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost);
+    }
+    [prev, cur] = [cur, prev];
+  }
+  return prev[n];
+}
+
+// Closest known subcommand for `input`, or null when nothing is close enough.
+// "Close" = a clear (unambiguous) prefix match, OR edit distance <= 2 with a
+// single best candidate. Returns the exact entry from `candidates` so callers
+// can echo a canonical spelling in the suggestion.
+export function nearest(input, candidates) {
+  if (!input) return null;
+  const word = String(input).toLowerCase();
+  // Exact prefix wins when it's unambiguous (e.g. "provid" -> "providers").
+  const prefixHits = candidates.filter(c => c.toLowerCase().startsWith(word) && c.toLowerCase() !== word);
+  if (prefixHits.length === 1) return prefixHits[0];
+  let best = null, bestDist = Infinity, tie = false;
+  for (const c of candidates) {
+    const d = editDistance(word, c.toLowerCase());
+    if (d < bestDist) { bestDist = d; best = c; tie = false; }
+    else if (d === bestDist) tie = true;
+  }
+  // Gate on distance <= 2 and require a unique winner to avoid a misleading
+  // suggestion when several commands are equidistant from the typo.
+  if (best && bestDist <= 2 && !tie) return best;
+  return null;
+}
+
+// One-line usage hint for a known subcommand, built from the inventory we
+// already own here (SUBCOMMANDS + SUBCOMMAND_SUBS). cli.mjs uses this as the
+// fallback for `lazyclaw help <name>` when the subcommand has no rich entry in
+// commands/setup.mjs's HELP_DETAILS — so help never errors on a real command.
+// Returns null for an unknown name (the caller then offers a did-you-mean).
+export function usageHint(name) {
+  if (!SUBCOMMANDS.includes(name)) return null;
+  const subs = SUBCOMMAND_SUBS[name];
+  return subs
+    ? `Usage: lazyclaw ${name} <${subs.join('|')}> ...`
+    : `Usage: lazyclaw ${name} ...`;
+}
+
 export function parseArgs(argv) {
   const out = { positional: [], flags: {} };
   for (let i = 0; i < argv.length; i++) {

package/lib/config.mjs

@@ -17,20 +17,102 @@ export function configPath() {
   return path.join(dir, 'config.json');
 }
 
+// Thrown when config.json EXISTS but is not parseable JSON. We fail fast here
+// instead of returning {} so a typo in the file can't masquerade as a fresh
+// install (silently dropping provider/keys/channels) and — critically — so a
+// downstream writeConfig never clobbers the recoverable, hand-editable bytes.
+export class ConfigError extends Error {
+  constructor(message, { path: p, cause } = {}) {
+    super(message);
+    this.name = 'ConfigError';
+    this.path = p;
+    if (cause) this.cause = cause;
+  }
+}
+
+// mtime-keyed parse cache. readConfig has ~97 callers and is hit on every
+// daemon HTTP request / dashboard poll / orchestrator turn; re-reading +
+// re-parsing the file each time is pure waste. Cache the parsed object keyed by
+// (path, mtimeMs) and hand out an independent clone so a caller mutating its
+// copy can't corrupt the cache. writeConfig() invalidates; a write from another
+// process is seen via the mtime check.
+let _cfgCache = null; // { path, mtimeMs, parsed }
+export function _invalidateConfigCache() { _cfgCache = null; }
+
 export function readConfig() {
   const p = configPath();
-  if (!fs.existsSync(p)) return {};
+  if (!fs.existsSync(p)) { _cfgCache = null; return {}; }
   // Migrate already-deployed world/group-readable config.json (plaintext keys)
   // to 0600 the first time we touch it. Best-effort, idempotent.
   tightenIfLoose(p);
-  try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
-  catch { return {}; }
+  let mtimeMs = null;
+  try { mtimeMs = fs.statSync(p).mtimeMs; } catch { /* fall through to a fresh read */ }
+  if (_cfgCache && _cfgCache.path === p && mtimeMs != null && _cfgCache.mtimeMs === mtimeMs) {
+    return structuredClone(_cfgCache.parsed);
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(p, 'utf8'));
+    if (mtimeMs != null) _cfgCache = { path: p, mtimeMs, parsed };
+    return structuredClone(parsed);
+  }
+  catch (e) {
+    // PRESENT-BUT-CORRUPT: never return {} (would look fresh and let a later
+    // writeConfig overwrite the file). Warn loudly + actionably, then throw so
+    // the CLI boot boundary fails fast with the settings still on disk.
+    process.stderr.write(
+      `\nlazyclaw: config.json is present but not valid JSON — refusing to ` +
+      `continue so your settings aren't lost.\n` +
+      `  path:  ${p}\n` +
+      `  error: ${e.message}\n` +
+      `  recover: fix the JSON, or move it aside ` +
+      `(e.g. \`mv ${p} ${p}.bak\`) to start fresh.\n\n`,
+    );
+    throw new ConfigError(`config.json at ${p} is not valid JSON: ${e.message}`, { path: p, cause: e });
+  }
 }
 
 export function writeConfig(cfg) {
   // 0600 file in a 0700 dir, atomically — config.json stores plaintext API
   // keys / auth profiles, so it must be owner-only on disk.
   writeJsonSecure(configPath(), cfg);
+  _cfgCache = null; // invalidate the read cache after a same-process write
+}
+
+// Persist the active model selection to disk so it survives a restart
+// (read-merge-write keeps unrelated keys). An empty/null name clears cfg.model
+// so the provider falls back to its own default. Mirrors onto the in-memory
+// `liveCfg` so the running session sees it without a re-read. Best-effort: a
+// write failure must not break the in-memory switch the caller already made.
+//
+// Why this exists: /model (and the legacy readline path) historically mutated
+// the in-memory active model only, so a model picked in one session reverted to
+// cfg.model on the next launch. Routing the setter through here makes the
+// choice stick.
+export function persistActiveModel(liveCfg, name) {
+  try {
+    const c = readConfig();
+    if (name) c.model = name; else delete c.model;
+    writeConfig(c);
+    if (liveCfg && typeof liveCfg === 'object') {
+      if (name) liveCfg.model = name; else delete liveCfg.model;
+    }
+  } catch { /* best-effort — keep the in-memory selection */ }
+}
+
+// Persist the active provider, with one guard: orchestrator routing is owned by
+// `/orchestrator on|off` (which stashes _prevProvider), so the model/provider
+// setters must never write 'orchestrator' themselves nor clobber a saved
+// 'orchestrator' provider. For ordinary provider switches it read-merge-writes
+// cfg.provider and mirrors onto liveCfg.
+export function persistActiveProvider(liveCfg, name) {
+  if (!name || name === 'orchestrator') return;
+  try {
+    const c = readConfig();
+    if (c.provider === 'orchestrator') return; // orchestrator active — leave its routing alone
+    c.provider = name;
+    writeConfig(c);
+    if (liveCfg && typeof liveCfg === 'object') liveCfg.provider = name;
+  } catch { /* best-effort */ }
 }
 
 // Injected built-in OpenAI-compat env-var resolver. registry_boot wires this

package/lib/render.mjs

@@ -0,0 +1,43 @@
+// lib/render.mjs — tiny shared pretty-printer for record-shaped command output.
+// Turns an object into readable `key: value` lines instead of a raw JSON dump,
+// so the *show handlers (/agent show, /team show, …) read cleanly in the chat
+// scrollback. Pure, no imports.
+
+// Format one value for a single line: empties → '(none)', arrays → [a, b],
+// one-level objects → {k: v, …}, scalars → String(v), deeper → compact JSON.
+function fmtValue(v) {
+  if (v === null || v === undefined || v === '') return '(none)';
+  if (Array.isArray(v)) return v.length ? `[${v.join(', ')}]` : '[]';
+  if (typeof v === 'object') {
+    const inner = Object.keys(v).map((k) => {
+      const iv = v[k];
+      const s = (iv && typeof iv === 'object') ? JSON.stringify(iv) : String(iv);
+      return `${k}: ${s}`;
+    });
+    return `{${inner.join(', ')}}`;
+  }
+  return String(v);
+}
+
+/**
+ * Render an object as `key: value` lines.
+ * @param {object} obj
+ * @param {{fields?: string[], hide?: string[]|Set<string>}} [opts]
+ *   fields: explicit key order (keys absent on obj are skipped);
+ *   hide: keys to omit (when fields not given).
+ * @returns {string}
+ */
+export function renderRecord(obj, { fields, hide } = {}) {
+  if (!obj || typeof obj !== 'object') return String(obj);
+  const skip = hide instanceof Set ? hide : new Set(hide || []);
+  const keys = Array.isArray(fields)
+    ? fields.filter((k) => Object.prototype.hasOwnProperty.call(obj, k))
+    : Object.keys(obj).filter((k) => !skip.has(k));
+  return keys.map((k) => `${k}: ${fmtValue(obj[k])}`).join('\n');
+}
+
+// Convenience: raw JSON when `raw` is true, else the pretty render. Lets each
+// handler offer a `<sub> <name> json` escape hatch in one line.
+export function renderRecordOrJson(obj, opts, raw) {
+  return raw ? JSON.stringify(obj, null, 2) : renderRecord(obj, opts);
+}

package/lib/service_install.mjs

@@ -190,7 +190,21 @@ export function serviceStatus(spec, depsIn = {}) {
   const p = servicePaths(name, { home, configDir });
 
   if (backend === 'launchd') {
-    return { backend, installed: deps.fs.existsSync(p.launchd), target: p.launchd };
+    const installed = deps.fs.existsSync(p.launchd);
+    // `launchctl list <label>` exits non-zero when the service isn't loaded
+    // and otherwise prints a dict that carries `"PID" = <n>;` only while the
+    // process is actually running (a loaded-but-idle KeepAlive job omits it).
+    // Parse that to report running+pid like the systemd/fallback branches.
+    const label = `com.lazyclaw.${name}`;
+    const r = deps.spawnSync('launchctl', ['list', label], { encoding: 'utf8' });
+    const loaded = !!r && r.status === 0;
+    let pid = null;
+    if (loaded && typeof r.stdout === 'string') {
+      const m = r.stdout.match(/"PID"\s*=\s*(\d+)/);
+      if (m) pid = parseInt(m[1], 10);
+    }
+    const running = pid != null && deps.isAlive(pid);
+    return { backend, installed, running, pid, target: p.launchd };
   }
   if (backend === 'systemd') {
     const installed = deps.fs.existsSync(p.systemd);

package/mas/agent_turn.mjs

@@ -3,13 +3,13 @@
 // the model emits a final text reply (or the iteration budget runs
 // out).
 //
-// Provider routing:
-//   anthropic → providers/tool_use/anthropic.mjs   (Phase 12b)
-//   openai    → providers/tool_use/openai.mjs      (Phase 12c — todo)
-//   gemini    → providers/tool_use/gemini.mjs      (Phase 12d — todo)
-//   claude-cli → not supported (subprocess provider — Phase 12 scope
-//                excludes it; runAgentTurn throws so callers can flag
-//                the agent in the dashboard).
+// Provider routing (all wired — see adapterFor below):
+//   anthropic  → providers/tool_use/anthropic.mjs
+//   openai     → providers/tool_use/openai.mjs
+//   gemini     → providers/tool_use/gemini.mjs
+//   claude-cli → providers/claude_cli.mjs; the tool-use loop runs INSIDE
+//                the binary, so the adapter normalises every reply to
+//                kind:'final' (no tool_calls envelope is ever observed).
 //
 // The loop:
 //   1. Build messages = [...history, {role:user, content:input}]
@@ -27,6 +27,7 @@ import * as gemini from '../providers/tool_use/gemini.mjs';
 import * as claudeCli from '../providers/tool_use/claude_cli.mjs';
 import { put as _trajPut } from './trajectory_store.mjs';
 import { composePromptStack } from './prompt_stack.mjs';
+import { emit as emitEvent } from './events.mjs';
 
 export class AgentTurnError extends Error {
   constructor(message, code) {
@@ -95,6 +96,11 @@ export async function runAgentTurn({
   signal,
   approve,
   security,
+  // Optional parsed sandbox spec (or null). Threaded into runTool so the
+  // bash tool runs inside the sandbox when one is configured. Default null
+  // keeps existing callers/tests byte-stable; see scope_notes for which
+  // callers should pass this to fully activate sandboxing.
+  sandbox = null,
   // v5 (Group A — C3): trajectoryRef is OPT-OUT, not opt-in. A caller
   // that doesn't pass one but DOES pass a configDir gets a
   // default-stamped record so every production agent turn lands in
@@ -132,6 +138,8 @@ export async function runAgentTurn({
         cfgDir: configDir,
         agent,
         workspace: agent.workspace || '',
+        // Auto-inject top-k recalled context relevant to THIS user message.
+        query: userMessage,
       });
       if (stacked && stacked.trim()) systemPrompt = stacked;
     } catch { /* best-effort — never block a turn on stack composition */ }
@@ -152,6 +160,15 @@ export async function runAgentTurn({
   const toolCalls = [];
   let iterations = 0;
   let lastText = '';
+  // Accumulate token usage across every callOnce in this turn's tool loop so
+  // the caller (e.g. the team router → cost cap) can account for what the turn
+  // spent. Stays null until an adapter actually reports usage.
+  const usageTotal = {
+    inputTokens: 0, outputTokens: 0,
+    cacheCreationInputTokens: 0, cacheReadInputTokens: 0, totalCostUsd: 0,
+  };
+  let usageSeen = false;
+  const _usage = () => (usageSeen ? { ...usageTotal } : null);
   if (trajectoryRef && typeof trajectoryRef === 'object' && !trajectoryRef.startedAt) trajectoryRef.startedAt = Date.now();
 
   const _maybePersistTrajectory = async (outcome) => {
@@ -183,17 +200,44 @@ export async function runAgentTurn({
   };
 
   while (iterations < maxIterations) {
-    if (signal?.aborted) return { text: lastText, iterations, stoppedBy: 'abort', toolCalls };
+    if (signal?.aborted) return { text: lastText, iterations, stoppedBy: 'abort', toolCalls, usage: _usage() };
     iterations++;
     const resp = await adapter.callOnce({
       messages, tools, model: agent.model, apiKey, system: systemPrompt,
+      // Forward-compat: thread an explicit per-agent output cap when the agent
+      // record carries one. No current config/setup path populates
+      // agent.maxTokens / agent.maxOutputTokens, so this is `undefined` today —
+      // each adapter then falls back to its own DEFAULT (anthropic/openai) or
+      // leaves the cap unset (gemini), keeping existing turns byte-stable. When
+      // a future config does set it, the cap reaches gemini (FIX D) too.
+      maxTokens: agent.maxTokens ?? agent.maxOutputTokens,
       fetchImpl, baseUrl, signal, cache,
     });
     if (resp.text) lastText = resp.text;
+    if (resp.usage) {
+      usageTotal.inputTokens += resp.usage.inputTokens || 0;
+      usageTotal.outputTokens += resp.usage.outputTokens || 0;
+      usageTotal.cacheCreationInputTokens += resp.usage.cacheCreationInputTokens || 0;
+      usageTotal.cacheReadInputTokens += resp.usage.cacheReadInputTokens || 0;
+      usageTotal.totalCostUsd += resp.usage.totalCostUsd || 0;
+      usageSeen = true;
+    }
+
+    // The model hit its output token ceiling: the final answer or the tool
+    // call(s) are partial/garbage. Stop with an explicit error rather than
+    // returning a cut-off answer or running an incomplete tool call.
+    if (resp.truncated) {
+      await _maybePersistTrajectory('error');
+      return {
+        text: lastText, iterations, stoppedBy: 'truncated',
+        error: 'response truncated at the model output token limit (raise maxTokens)',
+        toolCalls, usage: _usage(),
+      };
+    }
 
     if (resp.kind === 'final') {
       await _maybePersistTrajectory('done');
-      return { text: resp.text || '', iterations, stoppedBy: 'final', toolCalls };
+      return { text: resp.text || '', iterations, stoppedBy: 'final', toolCalls, usage: _usage() };
     }
 
     // tool_calls path: echo the model's assistant turn back so future
@@ -216,10 +260,21 @@ export async function runAgentTurn({
     for (const call of resp.calls) {
       let result;
       let ok = true;
+      // The adapter could not parse this tool call's arguments (e.g. OpenAI
+      // emitted malformed JSON). Surface a tool error so the model can retry
+      // instead of silently running the tool with empty input.
+      if (call.parseError) {
+        result = { ok: false, error: call.parseError };
+        toolCalls.push({ id: call.id, name: call.name, input: call.input, result, ok: false });
+        emitEvent('tool.call', { taskId, agent: agent.name, tool: call.name, ok: false });
+        results.push({ id: call.id, content: result, isError: true });
+        toolErrored = true;
+        continue;
+      }
       try {
         result = await runTool({
           agent, tool: call.name, args: call.input,
-          taskId, configDir, cwd, approve, security,
+          taskId, configDir, cwd, approve, security, sandbox,
         });
         if (result && result.ok === false) ok = false;
       } catch (err) {
@@ -231,6 +286,7 @@ export async function runAgentTurn({
         }
       }
       toolCalls.push({ id: call.id, name: call.name, input: call.input, result, ok });
+      emitEvent('tool.call', { taskId, agent: agent.name, tool: call.name, ok });
       results.push({ id: call.id, content: result, isError: !ok });
       if (!ok) toolErrored = true;
     }
@@ -243,10 +299,10 @@ export async function runAgentTurn({
     // provider returned a malformed envelope) bails out here.
     if (toolErrored && process.env.LAZYCLAW_TOOL_STRICT === '1') {
       await _maybePersistTrajectory('failed');
-      return { text: lastText, iterations, stoppedBy: 'tool_error', toolCalls };
+      return { text: lastText, iterations, stoppedBy: 'tool_error', toolCalls, usage: _usage() };
     }
   }
 
   await _maybePersistTrajectory('abandoned');
-  return { text: lastText, iterations, stoppedBy: 'budget', toolCalls };
+  return { text: lastText, iterations, stoppedBy: 'budget', toolCalls, usage: _usage() };
 }

package/mas/confidence.mjs

@@ -23,6 +23,20 @@ const Z = 1.96; // 95% confidence two-sided
 
 export const DEFAULT_CROSS_CLI_DAMPEN = 0.85;
 
+// Below this many trials the 95% Wilson lower bound is punitively pessimistic
+// (wilsonLowerBound(1,1)=0.206, under the 0.3 archive floor), so a brand-new
+// skill from one successful task would be deleted on its first recall miss. For
+// small n we use the Beta(1,1) posterior mean (Laplace rule of succession,
+// (s+1)/(n+2)) — a gentle, data-aware "unproven" estimate that keeps a fresh
+// success above the floor while still archiving a fresh failure (0/1 → 0.33).
+export const MIN_TRIALS_FOR_WILSON = 3;
+
+export function laplaceMean(successes, trials) {
+  const s = Math.max(0, Number(successes) || 0);
+  const n = Math.max(0, Number(trials) || 0);
+  return (s + 1) / (n + 2);
+}
+
 export function wilsonLowerBound(successes, trials) {
   const s = Number(successes) || 0;
   const n = Number(trials) || 0;
@@ -83,8 +97,13 @@ export function computeConfidence({
   workerProvider = null,
   halfLifeMs,
   dampenFactor,
+  minTrials = MIN_TRIALS_FOR_WILSON,
 } = {}) {
-  const base = wilsonLowerBound(successes, trials);
+  // Too few trials for a meaningful Wilson bound → use the unproven Laplace
+  // prior; otherwise the conservative 95% lower bound takes over.
+  const base = (Number(trials) || 0) < minTrials
+    ? laplaceMean(successes, trials)
+    : wilsonLowerBound(successes, trials);
   const decayed = base * recencyDecay(ageMs, halfLifeMs);
   const dampened = crossCliDampen(decayed, trainerProvider, workerProvider, dampenFactor);
   return Math.max(0, Math.min(1, dampened));

package/mas/embedder.mjs

@@ -0,0 +1,100 @@
+// mas/embedder.mjs — pluggable, opt-in text-embedding source for hybrid recall.
+//
+// Recall (mas/index_db.mjs) blends FTS5 bm25 with semantic similarity; the query
+// + document vectors come from here. This is OFF by default: getEmbedder returns
+// null unless cfg.recall.embeddings.enabled === true AND a source resolves, in
+// which case recall rides today's pure-FTS5 path unchanged.
+//
+// HONESTY (§1, §9): the bare $0 chat-subscription user (claude-cli / gemini-cli /
+// codex-cli spawn local chat binaries with no embed subcommand; the Anthropic
+// API has no embeddings endpoint) has NO embedding source — getEmbedder returns
+// null for them and they get pure FTS5. We deliberately do NOT bundle a heavy
+// local model (onnxruntime + weights are 50-150MB) to fake a semantic path for
+// a user who never asked for it. Embeddings light up only when a user opts in
+// with an OpenAI/Gemini API key, or a local Ollama embed model (zero npm
+// footprint — it talks to the user's own ollama server).
+
+const DEFAULTS = {
+  openai: { model: 'text-embedding-3-small', dims: 1536, url: 'https://api.openai.com/v1/embeddings' },
+  gemini: { model: 'text-embedding-004', dims: 768, base: 'https://generativelanguage.googleapis.com/v1beta' },
+  ollama: { model: 'nomic-embed-text', dims: 768, url: 'http://127.0.0.1:11434/api/embeddings' },
+};
+
+let _override = null;
+// Test seam: inject a fake embedder ({ id, dims, embed }) or a falsy value to
+// force the null (pure-FTS) path. Pass undefined to clear the override.
+export function __setEmbedder(fn) { _override = fn === undefined ? null : fn; }
+
+function toF32(arr) {
+  return arr instanceof Float32Array ? arr : Float32Array.from(arr || []);
+}
+
+async function _openaiEmbed(texts, { model, apiKey, url, fetchImpl }) {
+  const res = await fetchImpl(url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
+    body: JSON.stringify({ input: texts, model }),
+  });
+  if (!res.ok) throw new Error(`openai embeddings HTTP ${res.status}`);
+  const json = await res.json();
+  return (json.data || []).map((d) => toF32(d.embedding));
+}
+
+async function _geminiEmbed(texts, { model, apiKey, base, fetchImpl }) {
+  const url = `${base.replace(/\/$/, '')}/models/${model}:batchEmbedContents?key=${encodeURIComponent(apiKey)}`;
+  const res = await fetchImpl(url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ requests: texts.map((t) => ({ model: `models/${model}`, content: { parts: [{ text: String(t) }] } })) }),
+  });
+  if (!res.ok) throw new Error(`gemini embeddings HTTP ${res.status}`);
+  const json = await res.json();
+  return (json.embeddings || []).map((e) => toF32(e.values));
+}
+
+async function _ollamaEmbed(texts, { model, url, fetchImpl }) {
+  // The classic /api/embeddings endpoint takes one prompt at a time.
+  const out = [];
+  for (const t of texts) {
+    const res = await fetchImpl(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ model, prompt: String(t) }),
+    });
+    if (!res.ok) throw new Error(`ollama embeddings HTTP ${res.status}`);
+    const json = await res.json();
+    out.push(toF32(json.embedding));
+  }
+  return out;
+}
+
+/**
+ * Resolve the configured embedding source, or null (→ pure FTS5 recall).
+ * @returns {{ id: string, dims: number, embed: (texts: string[]) => Promise<Float32Array[]> } | null}
+ */
+export function getEmbedder(cfg, opts = {}) {
+  if (_override !== null) return _override;
+  const e = cfg?.recall?.embeddings;
+  if (!e || e.enabled !== true) return null;
+  const provider = String(e.provider || '').toLowerCase();
+  const d = DEFAULTS[provider];
+  if (!d) return null;
+  const model = e.model || d.model;
+  const dims = Number(e.dim) || d.dims;
+  const apiKey = e.apiKey || opts.apiKey || cfg['api-key'] || '';
+  const fetchImpl = opts.fetchImpl || globalThis.fetch;
+  if (typeof fetchImpl !== 'function') return null;
+  // openai/gemini need a key; ollama is keyless (local server).
+  if ((provider === 'openai' || provider === 'gemini') && !apiKey) return null;
+  return {
+    id: `${provider}/${model}`,
+    dims,
+    async embed(texts) {
+      const list = (Array.isArray(texts) ? texts : [texts]).map((t) => String(t ?? ''));
+      if (!list.length) return [];
+      if (provider === 'openai') return _openaiEmbed(list, { model, apiKey, url: e.url || d.url, fetchImpl });
+      if (provider === 'gemini') return _geminiEmbed(list, { model, apiKey, base: e.baseUrl || d.base, fetchImpl });
+      return _ollamaEmbed(list, { model, url: e.url || d.url, fetchImpl });
+    },
+  };
+}

package/mas/events.mjs

@@ -0,0 +1,57 @@
+// mas/events.mjs — tiny in-process event bus for live agent activity.
+//
+// Zero-dependency pub/sub plus a bounded ring buffer for replay-on-connect.
+// The daemon's GET /events SSE route subscribes here and streams events to the
+// dashboard; mention_router / agent_turn / delegation emit as agents work.
+//
+// emit() NEVER throws into the caller: an agent turn must not break because a
+// dashboard subscriber errored or because the bus is busy. Events are
+// process-local — in the always-on gateway/daemon (where Slack-routed tasks run
+// and SSE clients connect) they reach the dashboard; in a one-shot CLI process
+// with no subscriber they are simply buffered and dropped, which is harmless.
+
+const RING_MAX = 200;
+const _subs = new Set();
+const _ring = [];
+let _seq = 0;
+
+/**
+ * Publish an event. Returns the stamped event ({seq, ts, type, ...payload}).
+ * @param {string} type  e.g. 'turn.start' | 'tool.call' | 'delegate'
+ * @param {object} [payload]
+ */
+export function emit(type, payload = {}) {
+  const evt = { seq: ++_seq, ts: Date.now(), type, ...payload };
+  _ring.push(evt);
+  if (_ring.length > RING_MAX) _ring.shift();
+  for (const fn of _subs) {
+    try { fn(evt); } catch { /* a bad subscriber must never break emit */ }
+  }
+  return evt;
+}
+
+/**
+ * Subscribe to every subsequent event. Returns an unsubscribe function.
+ * @param {(evt: object) => void} fn
+ * @returns {() => void}
+ */
+export function subscribe(fn) {
+  _subs.add(fn);
+  return () => { _subs.delete(fn); };
+}
+
+/**
+ * Replay buffered events, optionally only those newer than `sinceSeq`. Used by
+ * the SSE route so a freshly-connected dashboard converges to current state.
+ * @param {number} [sinceSeq]
+ */
+export function recent(sinceSeq = 0) {
+  return sinceSeq ? _ring.filter((e) => e.seq > sinceSeq) : _ring.slice();
+}
+
+/** Test seam — clear subscribers + buffer + sequence. */
+export function _reset() {
+  _subs.clear();
+  _ring.length = 0;
+  _seq = 0;
+}