@syntheos/broca 0.1.0

package/bin.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+const dir = dirname(fileURLToPath(import.meta.url));
+spawn("node", ["--experimental-strip-types", resolve(dir, "src/server.ts")], { stdio: "inherit" }).on("exit", process.exit);

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@syntheos/broca",
+  "version": "0.1.0",
+  "description": "Agent action log and natural language narrator",
+  "type": "module",
+  "engines": { "node": ">=22.6.0" },
+  "bin": {
+    "syntheos-broca": "./bin.mjs"
+  },
+  "scripts": {
+    "dev": "node --experimental-strip-types src/server.ts",
+    "start": "node --experimental-strip-types src/server.ts"
+  },
+  "dependencies": {
+    "libsql": "^0.5.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/src/ask.ts

@@ -0,0 +1,171 @@
+// ============================================================================
+// ASK — natural language query over the agent OS stack
+// Takes a question, uses LLM to pick the right service + endpoint,
+// makes the call, then narrates the result back in plain English.
+// ============================================================================
+
+const LLM_URL = process.env.LLM_URL || "";
+const LLM_API_KEY = process.env.LLM_API_KEY || "";
+const LLM_MODEL = process.env.LLM_MODEL || "qwen2.5:14b";
+
+// Per-service base URLs and keys (all optional — services are skipped if not configured)
+const SERVICES: Record<string, { url: string; key: string }> = {
+  chiasm:  { url: process.env.CHIASM_URL  || "", key: process.env.CHIASM_API_KEY  || "" },
+  engram:  { url: process.env.ENGRAM_URL  || "", key: process.env.ENGRAM_API_KEY  || "" },
+  axon:    { url: process.env.AXON_URL    || "", key: process.env.AXON_API_KEY    || "" },
+  loom:    { url: process.env.LOOM_URL    || "", key: process.env.LOOM_API_KEY    || "" },
+  soma:    { url: process.env.SOMA_URL    || "", key: process.env.SOMA_API_KEY    || "" },
+  thymus:  { url: process.env.THYMUS_URL  || "", key: process.env.THYMUS_API_KEY  || "" },
+  broca:   { url: process.env.BROCA_SELF_URL || `http://localhost:${process.env.PORT || 5100}`, key: process.env.BROCA_API_KEY || "" },
+};
+
+const SERVICE_CATALOG = `
+Available services and endpoints (only call what is configured):
+
+chiasm (task tracker):
+  GET  /tasks?status=active|blocked|blocked_on_human|completed|paused&agent=X&project=X&limit=N
+  GET  /tasks/:id
+  GET  /feed?limit=N&offset=N
+
+engram (memory store):
+  POST /search   body: {"query":"...","limit":N}
+  POST /context  body: {"query":"...","budget":N}
+
+axon (event bus):
+  GET  /events?channel=X&limit=N&since=ISO
+  GET  /channels
+
+loom (workflow engine):
+  GET  /runs?status=running|completed|failed|cancelled&limit=N
+  GET  /runs/:id
+  GET  /workflows
+
+soma (agent registry):
+  GET  /agents?status=online|offline&type=service|agent
+  GET  /agents/:id
+
+thymus (evaluations):
+  GET  /evaluations?agent=X&limit=N
+
+broca (action log):
+  GET  /actions?agent=X&action=X&service=X&limit=N&since=ISO
+  GET  /feed?limit=N
+  GET  /stats
+`.trim();
+
+export interface AskPlan {
+  service: string;
+  method: "GET" | "POST";
+  path: string;
+  params?: Record<string, string | number>;
+  body?: Record<string, unknown>;
+}
+
+export interface AskResult {
+  answer: string;
+  plan: AskPlan;
+  raw: unknown;
+}
+
+async function callLLM(systemPrompt: string, userPrompt: string): Promise<string> {
+  if (!LLM_URL) throw new Error("LLM_URL not configured");
+
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (LLM_API_KEY) headers["Authorization"] = `Bearer ${LLM_API_KEY}`;
+
+  const isOllama = LLM_URL.includes("11434") || LLM_URL.includes("ollama");
+  const url = (isOllama && !LLM_URL.includes("/chat/completions"))
+    ? LLM_URL.replace(/\/?$/, "") + "/v1/chat/completions"
+    : LLM_URL;
+
+  const res = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      model: LLM_MODEL,
+      messages: [
+        { role: "system", content: systemPrompt },
+        { role: "user", content: userPrompt },
+      ],
+      temperature: 0.2,
+      stream: false,
+      keep_alive: "10m",
+    }),
+    signal: AbortSignal.timeout(180000),
+  });
+
+  if (!res.ok) throw new Error(`LLM HTTP ${res.status}`);
+  const data = await res.json() as any;
+  return (data.choices?.[0]?.message?.content ?? data.result ?? data.text ?? "").trim();
+}
+
+async function planQuery(question: string): Promise<AskPlan> {
+  const system = `You are a routing agent for an AI agent OS. Given a user question, decide which service API to call to answer it.
+
+${SERVICE_CATALOG}
+
+Respond with ONLY valid JSON matching this schema — no explanation, no markdown:
+{"service":"<name>","method":"GET|POST","path":"/...","params":{},"body":null}
+
+Rules:
+- Use GET with params for filtering. Use POST with body only for engram /search or /context.
+- For time-based questions ("today", "last hour", "recent") use limit=20 and omit since unless you know the exact time.
+- If no service fits, use broca /feed.`;
+
+  const raw = await callLLM(system, question);
+
+  // Extract JSON even if model wraps it in markdown
+  const match = raw.match(/\{[\s\S]*\}/);
+  if (!match) throw new Error(`LLM returned non-JSON plan: ${raw.slice(0, 200)}`);
+  return JSON.parse(match[0]) as AskPlan;
+}
+
+async function executeplan(plan: AskPlan): Promise<unknown> {
+  const svc = SERVICES[plan.service];
+  if (!svc?.url) throw new Error(`Service "${plan.service}" not configured`);
+
+  let url = svc.url.replace(/\/$/, "") + plan.path;
+
+  if (plan.method === "GET" && plan.params && Object.keys(plan.params).length > 0) {
+    const qs = new URLSearchParams(
+      Object.entries(plan.params).map(([k, v]) => [k, String(v)])
+    ).toString();
+    url += "?" + qs;
+  }
+
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (svc.key) headers["Authorization"] = `Bearer ${svc.key}`;
+
+  const res = await fetch(url, {
+    method: plan.method,
+    headers,
+    body: plan.method === "POST" && plan.body ? JSON.stringify(plan.body) : undefined,
+    signal: AbortSignal.timeout(15000),
+  });
+
+  if (!res.ok) throw new Error(`${plan.service} API returned HTTP ${res.status}`);
+  return res.json();
+}
+
+async function narrateResult(question: string, plan: AskPlan, raw: unknown): Promise<string> {
+  const system = "You answer questions about an AI agent system. Be concise, direct, and use plain English. No JSON, no technical terms, no IDs.";
+  const user = `User asked: "${question}"
+
+Data from ${plan.service} (${plan.method} ${plan.path}):
+${JSON.stringify(raw, null, 2).slice(0, 2000)}
+
+Answer the user's question directly in 1-3 sentences.`;
+
+  return callLLM(system, user);
+}
+
+export async function ask(question: string): Promise<AskResult> {
+  console.log("[ask] planning query:", question);
+  const plan = await planQuery(question);
+  console.log("[ask] plan:", JSON.stringify(plan));
+  const raw = await executeplan(plan);
+  console.log("[ask] got raw result, narrating...");
+  const answer = await narrateResult(question, plan, raw);
+  console.log("[ask] done");
+  return { answer, plan, raw };
+}

package/src/db.ts

@@ -0,0 +1,30 @@
+import Database from "libsql";
+
+export function initDb(path: string): InstanceType<typeof Database> {
+  const db = new Database(path);
+  db.pragma("journal_mode = WAL");
+  db.pragma("busy_timeout = 5000");
+  db.pragma("synchronous = NORMAL");
+
+  db.exec(`
+    -- Every action any agent takes
+    CREATE TABLE IF NOT EXISTS actions (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      agent TEXT NOT NULL,
+      service TEXT NOT NULL,
+      action TEXT NOT NULL,
+      payload TEXT NOT NULL DEFAULT '{}',
+      narrative TEXT,
+      axon_event_id INTEGER,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_actions_agent ON actions(agent, created_at DESC);
+    CREATE INDEX IF NOT EXISTS idx_actions_service ON actions(service, created_at DESC);
+    CREATE INDEX IF NOT EXISTS idx_actions_action ON actions(action, created_at DESC);
+    CREATE INDEX IF NOT EXISTS idx_actions_created ON actions(created_at DESC);
+  `);
+
+  return db;
+}
+
+export type Db = InstanceType<typeof Database>;

package/src/narrator.ts

@@ -0,0 +1,167 @@
+// ============================================================================
+// NARRATOR — converts raw action payloads into plain English sentences
+// Template-first, LLM fallback for unknowns
+// ============================================================================
+
+// LLM for fallback narration — supports Ollama, OpenAI-compat, or Engram-style endpoints
+const LLM_URL = process.env.LLM_URL || process.env.ENGRAM_URL || "";
+const LLM_API_KEY = process.env.LLM_API_KEY || process.env.ENGRAM_API_KEY || "";
+const LLM_MODEL = process.env.LLM_MODEL || "qwen2.5:14b";
+
+// Template registry: action -> (payload) -> string
+type Template = (p: Record<string, unknown>) => string;
+
+const templates: Record<string, Template> = {
+  // ---- Chiasm / tasks ----
+  "task.created":         p => `${p.agent || p.source || "An agent"} started a new task: "${p.title}" in ${p.project}`,
+  "task.updated":         p => `"${p.title}" status is now ${humanStatus(p.status)}${p.summary ? ` — ${p.summary}` : ""}`,
+  "task.completed":       p => `"${p.title || p.task_title}" was completed${p.agent ? ` by ${p.agent}` : ""}`,
+  "task.blocked":         p => `"${p.title}" is blocked${p.reason ? `: ${p.reason}` : ""}`,
+  "task.blocked_on_human": p => `"${p.title}" is waiting for human approval${p.summary ? `: ${p.summary}` : ""}`,
+  "task.feedback":        p => `Human feedback on "${p.title}": "${p.feedback}"`,
+  "task.output":          p => `Output submitted for "${p.title}"`,
+  "task.plan":            p => `A plan was generated for "${p.title}"`,
+
+  // ---- Loom / workflows ----
+  "workflow.run.created":    p => `${p.agent || "An agent"} started the "${p.workflow}" workflow`,
+  "workflow.run.completed":  p => `The "${p.workflow}" workflow finished successfully`,
+  "workflow.run.failed":     p => `The "${p.workflow}" workflow failed on step "${p.failed_step}"${p.error ? `: ${p.error}` : ""}`,
+  "workflow.run.cancelled":  p => `The "${p.workflow}" workflow was cancelled`,
+  "workflow.step.started":   p => `Step "${p.step}" started in the "${p.workflow}" workflow`,
+  "workflow.step.completed": p => `Step "${p.step}" finished in the "${p.workflow}" workflow`,
+  "workflow.step.failed":    p => `Step "${p.step}" failed in the "${p.workflow}" workflow: ${p.error}`,
+
+  // ---- Soma / agents ----
+  "agent.registered":    p => `${p.name} came online as a ${p.type}`,
+  "agent.deregistered":  p => `${p.name} went offline`,
+  "agent.online":        p => `${p.agent || p.name} is online`,
+  "agent.offline":       p => `${p.agent || p.name} went offline`,
+  "agent.heartbeat":     p => `${p.agent || p.name} checked in`,
+  "agent.error":         p => `${p.agent || p.name} reported an error: ${p.error}`,
+
+  // ---- Engram / memory ----
+  "memory.stored":   p => `${p.source || "An agent"} stored a memory${p.category ? ` (${p.category})` : ""}${p.content_preview ? `: "${String(p.content_preview).slice(0, 80)}${String(p.content_preview).length > 80 ? "…" : ""}"` : ""}`,
+  "memory.searched": p => `${p.agent || "An agent"} searched memory for "${p.query}"${p.results !== undefined ? ` — ${p.results} result${p.results === 1 ? "" : "s"}` : ""}`,
+  "memory.linked":   p => `Two memories were linked together`,
+  "memory.forgotten": p => `A memory was removed`,
+
+  // ---- Thymus / evaluations ----
+  "evaluation.completed": p => {
+    const pct = p.overall_score !== undefined ? ` — scored ${Math.round(Number(p.overall_score) * 100)}%` : "";
+    return `${p.agent}'s work on "${p.subject}" was evaluated${pct} using the ${p.rubric} rubric`;
+  },
+  "metric.recorded": p => `${p.agent} recorded ${p.metric}: ${p.value}`,
+
+  // ---- Axon / system ----
+  "system.started":   p => `${p.service || "A service"} started up`,
+  "system.stopped":   p => `${p.service || "A service"} shut down`,
+  "deploy.started":   p => `Deployment started${p.service ? ` for ${p.service}` : ""}`,
+  "deploy.succeeded": p => `${p.service || "Deployment"} deployed successfully`,
+  "deploy.failed":    p => `Deployment failed${p.service ? ` for ${p.service}` : ""}${p.error ? `: ${p.error}` : ""}`,
+  "deploy.rolled_back": p => `${p.service || "Deployment"} was rolled back`,
+  "alert.triggered":  p => `Alert triggered: ${p.message || p.name || "unknown"}`,
+};
+
+function humanStatus(status: unknown): string {
+  const map: Record<string, string> = {
+    active: "active",
+    paused: "paused",
+    blocked: "blocked",
+    completed: "done",
+    blocked_on_human: "waiting for a human",
+    running: "running",
+    failed: "failed",
+    cancelled: "cancelled",
+  };
+  return map[String(status)] ?? String(status);
+}
+
+export function narrateFromTemplate(action: string, payload: Record<string, unknown>): string | null {
+  const fn = templates[action];
+  if (!fn) return null;
+  try {
+    return fn(payload);
+  } catch {
+    return null;
+  }
+}
+
+export async function narrateWithLLM(
+  agent: string,
+  service: string,
+  action: string,
+  payload: Record<string, unknown>
+): Promise<string> {
+  if (!LLM_URL) {
+    return `${agent} performed ${action} on ${service}`;
+  }
+
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (LLM_API_KEY) headers["Authorization"] = `Bearer ${LLM_API_KEY}`;
+
+  const userPrompt = `Convert this agent action into a single plain English sentence a non-technical person would understand. Be concise and natural. No technical jargon, no IDs, no JSON terms.
+
+Agent: ${agent}
+Service: ${service}
+Action: ${action}
+Details: ${JSON.stringify(payload, null, 2)}
+
+Respond with only the sentence, nothing else.`;
+
+  const system = "You translate technical agent actions into plain English. One sentence only.";
+
+  // Detect endpoint style
+  const isOllama = LLM_URL.includes("11434") || LLM_URL.includes("ollama");
+  const isOpenAICompat = LLM_URL.includes("/v1/chat") || LLM_URL.includes("/chat/completions");
+
+  try {
+    let body: string;
+    let url = LLM_URL;
+
+    if (isOllama || isOpenAICompat) {
+      // OpenAI-compat format
+      if (isOllama && !LLM_URL.includes("/chat/completions")) {
+        url = LLM_URL.replace(/\/?$/, "") + "/v1/chat/completions";
+      }
+      body = JSON.stringify({
+        model: LLM_MODEL,
+        messages: [
+          { role: "system", content: system },
+          { role: "user", content: userPrompt },
+        ],
+        temperature: 0.3,
+        stream: false,
+        keep_alive: "10m",
+      });
+    } else {
+      // Engram-style /llm endpoint
+      body = JSON.stringify({ prompt: userPrompt, system });
+    }
+
+    const res = await fetch(url, {
+      method: "POST",
+      headers,
+      body,
+      signal: AbortSignal.timeout(60000),
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const data = await res.json() as any;
+    // OpenAI-compat response
+    const text = data.choices?.[0]?.message?.content
+      ?? data.result ?? data.text ?? data.content;
+    return text?.trim() ?? `${agent} performed ${action} on ${service}`;
+  } catch {
+    return `${agent} performed ${action} on ${service}`;
+  }
+}
+
+export async function narrate(
+  agent: string,
+  service: string,
+  action: string,
+  payload: Record<string, unknown>
+): Promise<string> {
+  const fromTemplate = narrateFromTemplate(action, payload);
+  if (fromTemplate) return fromTemplate;
+  return narrateWithLLM(agent, service, action, payload);
+}

package/src/server.ts

@@ -0,0 +1,339 @@
+import { createServer, type ServerResponse, type IncomingMessage } from "node:http";
+import { initDb } from "./db.ts";
+import { narrate, narrateFromTemplate } from "./narrator.ts";
+import { ask } from "./ask.ts";
+import { UI_HTML } from "./ui.ts";
+
+const DB_PATH = process.env.DB_PATH ?? "./broca.db";
+const HOST = process.env.HOST ?? "0.0.0.0";
+const PORT = Number(process.env.PORT ?? 5000);
+const AUTH_DISABLED = process.env.BROCA_AUTH === "disabled";
+const BROCA_API_KEY = process.env.BROCA_API_KEY;
+const CORS_ALLOW_ORIGIN = process.env.CORS_ALLOW_ORIGIN;
+const BODY_MAX = 64 * 1024;
+
+// Axon subscription: ingest events automatically
+const AXON_URL = process.env.AXON_URL || "";
+const AXON_API_KEY = process.env.AXON_API_KEY || "";
+
+if (!BROCA_API_KEY && !AUTH_DISABLED) {
+  console.error("FATAL: BROCA_API_KEY not set. Set BROCA_AUTH=disabled to run without auth.");
+  process.exit(1);
+}
+
+const db = initDb(DB_PATH);
+
+// ============================================================================
+// HELPERS
+// ============================================================================
+
+function json(res: ServerResponse, data: unknown, status = 200) {
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(data));
+}
+
+function err(res: ServerResponse, message: string, status = 400) {
+  json(res, { error: message }, status);
+}
+
+function applyCors(origin: string | undefined, res: ServerResponse) {
+  if (!CORS_ALLOW_ORIGIN) return;
+  if (CORS_ALLOW_ORIGIN === "*" || origin === CORS_ALLOW_ORIGIN) {
+    res.setHeader("Access-Control-Allow-Origin", CORS_ALLOW_ORIGIN === "*" ? "*" : origin ?? CORS_ALLOW_ORIGIN);
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+    res.setHeader("Vary", "Origin");
+  }
+}
+
+function authenticate(req: IncomingMessage): boolean {
+  if (AUTH_DISABLED) return true;
+  const auth = req.headers.authorization;
+  if (!auth?.startsWith("Bearer ")) return false;
+  return auth.slice(7) === BROCA_API_KEY;
+}
+
+async function readBody(req: IncomingMessage): Promise<Record<string, unknown>> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let total = 0;
+    let settled = false;
+    const done = (fn: () => void) => { if (!settled) { settled = true; fn(); } };
+    req.on("data", (chunk: Buffer) => {
+      if (settled) return;
+      total += chunk.length;
+      if (total > BODY_MAX) { done(() => { req.resume(); reject(new Error("Body too large")); }); return; }
+      chunks.push(chunk);
+    });
+    req.on("end", () => done(() => {
+      if (chunks.length === 0) { resolve({}); return; }
+      try {
+        const parsed = JSON.parse(Buffer.concat(chunks).toString());
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) { reject(new Error("Must be JSON object")); return; }
+        resolve(parsed);
+      } catch { reject(new Error("Invalid JSON")); }
+    }));
+    req.on("error", (e) => done(() => reject(e)));
+  });
+}
+
+function bounded(v: string | null, fallback: number, min: number, max: number): number {
+  const n = Number.parseInt(v ?? "", 10);
+  return Number.isFinite(n) ? Math.min(Math.max(n, min), max) : fallback;
+}
+
+// ============================================================================
+// CORE LOGIC
+// ============================================================================
+
+async function logAction(
+  agent: string,
+  service: string,
+  action: string,
+  payload: Record<string, unknown>,
+  axonEventId?: number,
+  preNarrate = true,
+): Promise<Record<string, unknown>> {
+  const narrative = preNarrate ? (narrateFromTemplate(action, payload) ?? null) : null;
+
+  const row = db.prepare(
+    "INSERT INTO actions (agent, service, action, payload, narrative, axon_event_id) VALUES (?, ?, ?, ?, ?, ?) RETURNING *"
+  ).get(agent, service, action, JSON.stringify(payload), narrative, axonEventId ?? null) as Record<string, unknown>;
+
+  if (typeof row.payload === "string") {
+    try { row.payload = JSON.parse(row.payload as string); } catch { /* leave as-is */ }
+  }
+  return row;
+}
+
+function getActions(opts: {
+  agent?: string;
+  service?: string;
+  action?: string;
+  since?: string;
+  limit?: number;
+  offset?: number;
+  narrated_only?: boolean;
+}) {
+  let query = "SELECT * FROM actions WHERE 1=1";
+  const params: Array<string | number> = [];
+
+  if (opts.agent) { query += " AND agent = ?"; params.push(opts.agent); }
+  if (opts.service) { query += " AND service = ?"; params.push(opts.service); }
+  if (opts.action) { query += " AND action = ?"; params.push(opts.action); }
+  if (opts.since) { query += " AND created_at >= ?"; params.push(opts.since); }
+  if (opts.narrated_only) { query += " AND narrative IS NOT NULL"; }
+
+  query += " ORDER BY id DESC LIMIT ? OFFSET ?";
+  params.push(opts.limit ?? 50, opts.offset ?? 0);
+
+  return (db.prepare(query).all(...params) as any[]).map(r => ({
+    ...r,
+    payload: JSON.parse(r.payload),
+  }));
+}
+
+function getStats() {
+  const total = (db.prepare("SELECT COUNT(*) as c FROM actions").get() as any).c;
+  const narrated = (db.prepare("SELECT COUNT(*) as c FROM actions WHERE narrative IS NOT NULL").get() as any).c;
+  const by_service = db.prepare("SELECT service, COUNT(*) as count FROM actions GROUP BY service ORDER BY count DESC").all();
+  const by_agent = db.prepare("SELECT agent, COUNT(*) as count FROM actions GROUP BY agent ORDER BY count DESC").all();
+  const by_action = db.prepare("SELECT action, COUNT(*) as count FROM actions GROUP BY action ORDER BY count DESC").all();
+  return { total, narrated, by_service, by_agent, by_action };
+}
+
+// ============================================================================
+// AXON WEBHOOK INGESTION
+// Subscribe to Axon and receive events as webhooks pointing back here
+// ============================================================================
+
+async function subscribeToAxon() {
+  if (!AXON_URL) return;
+
+  const selfUrl = process.env.SELF_URL || `http://localhost:${PORT}`;
+  const webhookUrl = `${selfUrl}/ingest`;
+
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (AXON_API_KEY) headers["Authorization"] = `Bearer ${AXON_API_KEY}`;
+
+  // Subscribe to all channels with wildcard
+  for (const channel of ["system", "memory", "tasks", "deploy", "alerts"]) {
+    try {
+      await fetch(`${AXON_URL}/subscribe`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ agent: "broca", channel, webhook_url: webhookUrl }),
+        signal: AbortSignal.timeout(5000),
+      });
+    } catch { /* Axon may not be up yet */ }
+  }
+  console.log(`Subscribed to Axon at ${AXON_URL}`);
+}
+
+// ============================================================================
+// HTTP SERVER
+// ============================================================================
+
+const server = createServer(async (req, res) => {
+  applyCors(req.headers.origin, res);
+  if (req.method === "OPTIONS") { res.writeHead(204); return res.end(); }
+
+  try {
+    const url = new URL(req.url!, `http://${req.headers.host}`);
+    const path = url.pathname;
+
+    if (path === "/" && req.method === "GET") {
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      return res.end(UI_HTML);
+    }
+
+    if (path === "/health" && req.method === "GET") {
+      return json(res, { status: "ok", version: "0.1.0", ...getStats() });
+    }
+
+    // ---- INGEST from Axon webhook (no auth — Axon pushes here) ----
+    if (path === "/ingest" && req.method === "POST") {
+      const body = await readBody(req);
+      // Axon event shape: { id, channel, source, type, payload, created_at }
+      const { id: axonId, source, type, payload } = body as {
+        id?: number; channel?: string; source?: string; type?: string; payload?: Record<string, unknown>;
+      };
+      if (!source || !type) return err(res, "source and type required");
+      await logAction(source, source, type, payload ?? {}, axonId);
+      return json(res, { ok: true });
+    }
+
+    if (!authenticate(req)) return err(res, "Unauthorized", 401);
+
+    // ---- LOG an action directly ----
+    if (path === "/actions" && req.method === "POST") {
+      const body = await readBody(req);
+      const { agent, service, action, payload } = body as {
+        agent?: string; service?: string; action?: string; payload?: Record<string, unknown>;
+      };
+      if (!agent || !service || !action) return err(res, "agent, service, and action required");
+      const result = await logAction(agent, service, action, payload ?? {});
+      return json(res, result, 201);
+    }
+
+    // ---- QUERY actions ----
+    if (path === "/actions" && req.method === "GET") {
+      const actions = getActions({
+        agent: url.searchParams.get("agent") ?? undefined,
+        service: url.searchParams.get("service") ?? undefined,
+        action: url.searchParams.get("action") ?? undefined,
+        since: url.searchParams.get("since") ?? undefined,
+        limit: bounded(url.searchParams.get("limit"), 50, 1, 500),
+        offset: bounded(url.searchParams.get("offset"), 0, 0, 1e9),
+        narrated_only: url.searchParams.get("narrated_only") === "true",
+      });
+      return json(res, actions);
+    }
+
+    // ---- GET single action ----
+    const actionMatch = path.match(/^\/actions\/(\d+)$/);
+    if (actionMatch && req.method === "GET") {
+      const row = db.prepare("SELECT * FROM actions WHERE id = ?").get(parseInt(actionMatch[1], 10)) as any;
+      if (!row) return err(res, "Action not found", 404);
+      return json(res, { ...row, payload: JSON.parse(row.payload) });
+    }
+
+    // ---- NARRATE a single action (LLM fallback if no template) ----
+    const narrateMatch = path.match(/^\/actions\/(\d+)\/narrate$/);
+    if (narrateMatch && req.method === "GET") {
+      const row = db.prepare("SELECT * FROM actions WHERE id = ?").get(parseInt(narrateMatch[1], 10)) as any;
+      if (!row) return err(res, "Action not found", 404);
+
+      const payload = JSON.parse(row.payload);
+      let narrative = row.narrative;
+
+      if (!narrative) {
+        narrative = await narrate(row.agent, row.service, row.action, payload);
+        db.prepare("UPDATE actions SET narrative = ? WHERE id = ?").run(narrative, row.id);
+      }
+
+      return json(res, { id: row.id, narrative, action: row.action, agent: row.agent, created_at: row.created_at });
+    }
+
+    // ---- FEED — human-readable activity feed ----
+    // Returns recent actions with narratives, auto-generates for any missing
+    if (path === "/feed" && req.method === "GET") {
+      const limit = bounded(url.searchParams.get("limit"), 20, 1, 100);
+      const offset = bounded(url.searchParams.get("offset"), 0, 0, 1e9);
+      const agent = url.searchParams.get("agent") ?? undefined;
+      const since = url.searchParams.get("since") ?? undefined;
+
+      const actions = getActions({ agent, since, limit, offset });
+
+      // Fill in missing narratives (template only, fast)
+      const feed = actions.map(a => {
+        const narrative = a.narrative ?? narrateFromTemplate(a.action, a.payload) ?? `${a.agent} performed ${a.action}`;
+        if (!a.narrative && narrative) {
+          db.prepare("UPDATE actions SET narrative = ? WHERE id = ?").run(narrative, a.id);
+        }
+        return {
+          id: a.id,
+          narrative,
+          agent: a.agent,
+          service: a.service,
+          action: a.action,
+          created_at: a.created_at,
+        };
+      });
+
+      return json(res, feed);
+    }
+
+    // ---- NARRATE BULK — translate a batch via LLM ----
+    if (path === "/narrate" && req.method === "POST") {
+      const body = await readBody(req);
+      const ids = body.ids as number[] | undefined;
+      if (!ids || !Array.isArray(ids) || ids.length === 0) return err(res, "ids array required");
+      if (ids.length > 50) return err(res, "max 50 ids per batch");
+
+      const results: { id: number; narrative: string }[] = [];
+      for (const id of ids) {
+        const row = db.prepare("SELECT * FROM actions WHERE id = ?").get(id) as any;
+        if (!row) continue;
+        const payload = JSON.parse(row.payload);
+        const narrative = row.narrative ?? await narrate(row.agent, row.service, row.action, payload);
+        if (!row.narrative) db.prepare("UPDATE actions SET narrative = ? WHERE id = ?").run(narrative, id);
+        results.push({ id, narrative });
+      }
+      return json(res, results);
+    }
+
+    // ---- STATS ----
+    if (path === "/stats" && req.method === "GET") {
+      return json(res, getStats());
+    }
+
+    // ---- ASK — natural language query over the stack ----
+    if (path === "/ask" && req.method === "POST") {
+      const body = await readBody(req);
+      const question = body.question as string | undefined;
+      if (!question || typeof question !== "string" || !question.trim()) {
+        return err(res, "question (string) required");
+      }
+      try {
+        const result = await ask(question.trim());
+        return json(res, result);
+      } catch (e: any) {
+        return err(res, e.message ?? "Ask failed", 502);
+      }
+    }
+
+    err(res, "Not found", 404);
+  } catch (e) {
+    console.error("Unhandled:", e);
+    if (!res.headersSent) res.writeHead(500, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "Internal server error" }));
+  }
+});
+
+server.listen(PORT, HOST, async () => {
+  console.log(`Broca running on http://${HOST}:${PORT}`);
+  console.log(`Database: ${DB_PATH}`);
+  console.log(`Auth: ${AUTH_DISABLED ? "DISABLED" : "enabled"}`);
+  await subscribeToAxon();
+});

package/src/ui.ts

@@ -0,0 +1,611 @@
+export const UI_HTML = `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>BROCA</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@300;400;500;600&family=Syne:wght@700;800&display=swap" rel="stylesheet">
+<style>
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+:root {
+  --bg: #060608;
+  --surface: #0c0c10;
+  --surface2: #111118;
+  --border: #1e1e2e;
+  --text: #c8ccd8;
+  --muted: #4a4a6a;
+  --dim: #2a2a3a;
+  --phosphor: #00e5a0;
+  --phosphor-dim: #00e5a015;
+  --amber: #f5a623;
+  --amber-dim: #f5a62318;
+  --cyan: #38bdf8;
+  --error: #ff5f5f;
+  --error-bg: #1a0808;
+  --mono: 'IBM Plex Mono', monospace;
+  --display: 'Syne', sans-serif;
+}
+
+html, body {
+  height: 100%;
+  background: var(--bg);
+  color: var(--text);
+  font-family: var(--mono);
+  font-size: 13px;
+  line-height: 1.6;
+  overflow: hidden;
+}
+
+/* ── Scanline overlay ── */
+body::before {
+  content: '';
+  position: fixed;
+  inset: 0;
+  background: repeating-linear-gradient(
+    0deg,
+    transparent,
+    transparent 2px,
+    rgba(0,0,0,0.08) 2px,
+    rgba(0,0,0,0.08) 4px
+  );
+  pointer-events: none;
+  z-index: 100;
+}
+
+/* ── Animated grid background ── */
+body::after {
+  content: '';
+  position: fixed;
+  inset: 0;
+  background-image:
+    linear-gradient(rgba(0,229,160,0.03) 1px, transparent 1px),
+    linear-gradient(90deg, rgba(0,229,160,0.03) 1px, transparent 1px);
+  background-size: 48px 48px;
+  animation: gridDrift 40s linear infinite;
+  pointer-events: none;
+  z-index: 0;
+}
+@keyframes gridDrift {
+  0%   { background-position: 0 0; }
+  100% { background-position: 48px 48px; }
+}
+
+/* ── Layout ── */
+.layout {
+  display: flex;
+  flex-direction: column;
+  height: 100vh;
+  max-width: 860px;
+  margin: 0 auto;
+  padding: 0 24px;
+  position: relative;
+  z-index: 1;
+}
+
+/* ── Header ── */
+header {
+  padding: 22px 0 18px;
+  border-bottom: 1px solid var(--border);
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  flex-shrink: 0;
+}
+
+.logo {
+  display: flex;
+  align-items: baseline;
+  gap: 12px;
+}
+
+.logo-word {
+  font-family: var(--display);
+  font-size: 26px;
+  font-weight: 800;
+  letter-spacing: 4px;
+  color: var(--phosphor);
+}
+
+.logo-sub {
+  font-size: 10px;
+  color: var(--muted);
+  letter-spacing: 2px;
+  text-transform: uppercase;
+}
+
+.status-bar {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  font-size: 10px;
+  color: var(--muted);
+  letter-spacing: 1px;
+}
+
+.status-dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--phosphor);
+  display: inline-block;
+  margin-right: 4px;
+}
+
+/* ── Feed ── */
+.feed {
+  flex: 1;
+  overflow-y: auto;
+  padding: 24px 0 12px;
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+  scrollbar-width: thin;
+  scrollbar-color: var(--border) transparent;
+}
+.feed::-webkit-scrollbar { width: 4px; }
+.feed::-webkit-scrollbar-thumb { background: var(--border); border-radius: 2px; }
+
+/* ── Messages ── */
+.msg {
+  display: flex;
+  flex-direction: column;
+  gap: 5px;
+  animation: msgIn 0.25s ease-out both;
+}
+@keyframes msgIn {
+  from { opacity: 0; transform: translateY(10px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+
+/* Question bubble — command prompt style */
+.msg.question .bubble {
+  align-self: flex-end;
+  max-width: 80%;
+  background: var(--amber-dim);
+  border: 1px solid #f5a62330;
+  border-radius: 2px 12px 12px 2px;
+  color: var(--amber);
+  padding: 10px 14px 10px 36px;
+  position: relative;
+  font-weight: 500;
+}
+.msg.question .bubble::before {
+  content: '>';
+  position: absolute;
+  left: 14px;
+  top: 10px;
+  color: var(--phosphor);
+  font-weight: 600;
+  text-shadow: 0 0 8px var(--phosphor);
+}
+
+/* Answer bubble — intelligence responding */
+.msg.answer .bubble {
+  align-self: flex-start;
+  max-width: 90%;
+  background: var(--surface2);
+  border: 1px solid var(--border);
+  border-left: 2px solid var(--phosphor);
+  border-radius: 0 12px 12px 0;
+  color: var(--text);
+  padding: 12px 16px;
+  box-shadow: inset 0 0 30px rgba(0,229,160,0.03);
+}
+
+/* Thinking ── */
+.msg.thinking .bubble {
+  align-self: flex-start;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-left: 2px solid var(--muted);
+  border-radius: 0 12px 12px 0;
+  padding: 12px 16px;
+  color: var(--muted);
+}
+
+.dot-flashing {
+  display: inline-flex;
+  gap: 5px;
+  align-items: center;
+}
+.dot-flashing span {
+  width: 5px;
+  height: 5px;
+  border-radius: 50%;
+  background: var(--phosphor);
+  animation: dotPulse 1.4s ease-in-out infinite;
+}
+.dot-flashing span:nth-child(2) { animation-delay: 0.2s; }
+.dot-flashing span:nth-child(3) { animation-delay: 0.4s; }
+@keyframes dotPulse {
+  0%, 80%, 100% { transform: scale(0.6); opacity: 0.3; }
+  40%            { transform: scale(1); opacity: 1; }
+}
+
+/* Scan line on thinking bubble */
+.thinking-scan {
+  height: 1px;
+  background: linear-gradient(90deg, transparent, var(--phosphor), transparent);
+  margin-top: 8px;
+  animation: scan 2s linear infinite;
+  opacity: 0.6;
+}
+@keyframes scan {
+  0%   { transform: translateX(-100%); }
+  100% { transform: translateX(200%); }
+}
+
+/* Error */
+.msg.error .bubble {
+  align-self: flex-start;
+  max-width: 90%;
+  background: var(--error-bg);
+  border: 1px solid #ff5f5f30;
+  border-left: 2px solid var(--error);
+  border-radius: 0 12px 12px 0;
+  color: var(--error);
+  padding: 12px 16px;
+}
+.msg.error .bubble::before {
+  content: '! ';
+  font-weight: 700;
+}
+
+.bubble { font-size: 13px; line-height: 1.65; }
+
+/* Meta + service tag */
+.meta {
+  font-size: 10px;
+  color: var(--muted);
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  padding: 0 6px;
+  letter-spacing: 0.5px;
+}
+.msg.question .meta { align-self: flex-end; }
+
+.meta .service {
+  background: var(--surface2);
+  border: 1px solid var(--border);
+  border-radius: 3px;
+  padding: 1px 7px;
+  font-family: var(--mono);
+  color: var(--phosphor);
+  letter-spacing: 1px;
+}
+
+/* Raw data */
+.details {
+  font-size: 11px;
+  color: var(--muted);
+  padding: 0 6px;
+}
+.details summary {
+  cursor: pointer;
+  user-select: none;
+  letter-spacing: 1px;
+  text-transform: uppercase;
+  font-size: 10px;
+}
+.details summary::marker { color: var(--phosphor); }
+.details summary:hover { color: var(--phosphor); }
+.details pre {
+  margin-top: 8px;
+  padding: 12px;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  overflow-x: auto;
+  white-space: pre-wrap;
+  word-break: break-all;
+  line-height: 1.5;
+  color: var(--muted);
+  max-height: 280px;
+  overflow-y: auto;
+}
+
+/* ── Recent activity feed ── */
+.feed-section {
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  background: var(--surface);
+  overflow: hidden;
+}
+.feed-section-header {
+  padding: 8px 14px;
+  background: var(--surface2);
+  border-bottom: 1px solid var(--border);
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.feed-section-header h2 {
+  font-size: 9px;
+  text-transform: uppercase;
+  letter-spacing: 2px;
+  color: var(--muted);
+  font-family: var(--mono);
+  font-weight: 400;
+}
+.feed-section-header::before {
+  content: '';
+  width: 4px;
+  height: 4px;
+  border-radius: 50%;
+  background: var(--phosphor);
+}
+.event {
+  font-size: 11px;
+  color: var(--muted);
+  padding: 7px 14px;
+  border-bottom: 1px solid #1e1e2e55;
+  display: flex;
+  gap: 14px;
+  align-items: baseline;
+  font-family: var(--mono);
+  transition: background 0.15s;
+}
+.event:last-child { border-bottom: none; }
+.event:hover { background: var(--surface2); color: var(--text); }
+.event .time {
+  white-space: nowrap;
+  font-size: 10px;
+  color: var(--dim);
+  min-width: 72px;
+  flex-shrink: 0;
+  font-variant-numeric: tabular-nums;
+}
+.event .text { color: #8888aa; }
+.event:hover .text { color: var(--text); }
+
+/* ── Input row ── */
+.input-row {
+  padding: 14px 0 22px;
+  display: flex;
+  gap: 10px;
+  border-top: 1px solid var(--border);
+  flex-shrink: 0;
+  position: relative;
+}
+.input-row::before {
+  content: '';
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  height: 1px;
+  background: linear-gradient(90deg, transparent, var(--phosphor), transparent);
+  opacity: 0.3;
+}
+
+.input-wrap {
+  flex: 1;
+  position: relative;
+  display: flex;
+  align-items: flex-start;
+}
+.input-wrap::before {
+  content: '>';
+  position: absolute;
+  left: 14px;
+  top: 11px;
+  color: var(--phosphor);
+  font-weight: 600;
+  font-size: 14px;
+  pointer-events: none;
+  z-index: 1;
+  line-height: 1.5;
+}
+
+textarea {
+  flex: 1;
+  width: 100%;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  color: var(--amber);
+  padding: 10px 14px 10px 34px;
+  font-size: 13px;
+  font-family: var(--mono);
+  resize: none;
+  outline: none;
+  line-height: 1.5;
+  min-height: 44px;
+  max-height: 140px;
+  transition: border-color 0.2s, box-shadow 0.2s;
+  caret-color: var(--phosphor);
+}
+textarea:focus {
+  border-color: #00e5a050;
+}
+textarea::placeholder { color: var(--muted); font-weight: 300; }
+
+button#send {
+  background: transparent;
+  border: 1px solid var(--phosphor);
+  border-radius: 6px;
+  color: var(--phosphor);
+  cursor: pointer;
+  font-family: var(--mono);
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: 2px;
+  text-transform: uppercase;
+  padding: 0 20px;
+  min-height: 44px;
+  min-width: 80px;
+  transition: background 0.15s, color 0.15s;
+}
+button#send:hover {
+  background: var(--phosphor);
+  color: var(--bg);
+}
+button#send:active {
+  opacity: 0.8;
+}
+button#send:disabled {
+  opacity: 0.25;
+  cursor: not-allowed;
+}
+</style>
+</head>
+<body>
+<div class="layout">
+  <header>
+    <div class="logo">
+      <span class="logo-word">BROCA</span>
+      <span class="logo-sub">agent OS explorer</span>
+    </div>
+    <div class="status-bar">
+      <span><span class="status-dot"></span>ONLINE</span>
+    </div>
+  </header>
+
+  <div class="feed" id="feed"></div>
+
+  <div class="input-row">
+    <div class="input-wrap">
+      <textarea id="input" placeholder="what tasks are blocked? what did loom do today? which agents are online?" rows="1"></textarea>
+    </div>
+    <button id="send">SEND</button>
+  </div>
+</div>
+
+<script>
+const feed = document.getElementById('feed');
+const input = document.getElementById('input');
+const send = document.getElementById('send');
+
+function timeAgo(iso) {
+  const d = new Date(iso.includes('T') ? iso : iso + 'Z');
+  const s = Math.floor((Date.now() - d) / 1000);
+  if (s < 60) return s + 's ago';
+  if (s < 3600) return Math.floor(s/60) + 'm ago';
+  if (s < 86400) return Math.floor(s/3600) + 'h ago';
+  return Math.floor(s/86400) + 'd ago';
+}
+
+function addMsg(type, content, meta) {
+  const div = document.createElement('div');
+  div.className = 'msg ' + type;
+
+  const bubble = document.createElement('div');
+  bubble.className = 'bubble';
+
+  if (type === 'thinking') {
+    bubble.innerHTML = '<div class="dot-flashing"><span></span><span></span><span></span></div><div class="thinking-scan"></div>';
+  } else {
+    bubble.textContent = content;
+  }
+  div.appendChild(bubble);
+
+  if (meta) {
+    const m = document.createElement('div');
+    m.className = 'meta';
+    if (meta.service) {
+      const s = document.createElement('span');
+      s.className = 'service';
+      s.textContent = meta.service + ' ' + meta.method + ' ' + meta.path;
+      m.appendChild(s);
+    }
+    div.appendChild(m);
+
+    if (meta.raw) {
+      const det = document.createElement('details');
+      det.className = 'details';
+      const sum = document.createElement('summary');
+      sum.textContent = 'raw data';
+      const pre = document.createElement('pre');
+      pre.textContent = JSON.stringify(meta.raw, null, 2);
+      det.appendChild(sum);
+      det.appendChild(pre);
+      div.appendChild(det);
+    }
+  }
+
+  feed.appendChild(div);
+  feed.scrollTop = feed.scrollHeight;
+  return div;
+}
+
+async function ask(question) {
+  addMsg('question', question);
+  const thinking = addMsg('thinking');
+  send.disabled = true;
+  input.disabled = true;
+
+  try {
+    const res = await fetch('/ask', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ question }),
+      signal: AbortSignal.timeout(360000),
+    });
+    const data = await res.json();
+    thinking.remove();
+
+    if (!res.ok) {
+      addMsg('error', data.error || 'Something went wrong.');
+    } else {
+      addMsg('answer', data.answer, { service: data.plan.service, method: data.plan.method, path: data.plan.path, raw: data.raw });
+    }
+  } catch (e) {
+    thinking.remove();
+    addMsg('error', e.name === 'TimeoutError' ? 'Timed out — the model is loading, try again in a moment.' : e.message);
+  } finally {
+    send.disabled = false;
+    input.disabled = false;
+    input.focus();
+  }
+}
+
+send.addEventListener('click', () => {
+  const q = input.value.trim();
+  if (!q) return;
+  input.value = '';
+  autoResize();
+  ask(q);
+});
+
+input.addEventListener('keydown', e => {
+  if (e.key === 'Enter' && !e.shiftKey) {
+    e.preventDefault();
+    send.click();
+  }
+});
+
+function autoResize() {
+  input.style.height = 'auto';
+  input.style.height = Math.min(input.scrollHeight, 140) + 'px';
+}
+input.addEventListener('input', autoResize);
+
+// Load recent feed on start
+fetch('/feed?limit=8').then(r => r.json()).then(events => {
+  if (!events.length) return;
+  const section = document.createElement('div');
+  section.className = 'feed-section';
+
+  const hdr = document.createElement('div');
+  hdr.className = 'feed-section-header';
+  const h = document.createElement('h2');
+  h.textContent = 'Recent activity';
+  hdr.appendChild(h);
+  section.appendChild(hdr);
+
+  events.reverse().forEach(e => {
+    const row = document.createElement('div');
+    row.className = 'event';
+    row.innerHTML = \`<span class="time">\${timeAgo(e.created_at)}</span><span class="text">\${e.narrative || e.action}</span>\`;
+    section.appendChild(row);
+  });
+  feed.appendChild(section);
+}).catch(() => {});
+
+input.focus();
+</script>
+</body>
+</html>`;