@taicho-ai/framework 0.1.0

package/src/core/e2e-model.ts

@@ -0,0 +1,315 @@
+/** Deterministic model used only by real-binary e2e tests.
+ *  It lets tui-test drive the compiled CLI through multi-agent flows without external network.
+ *
+ *  Plan 07: the loop now unifies on `streamText` for EVERY provider, so the AI SDK calls a model's
+ *  `doStream` (not `doGenerate`). This model therefore implements `doStream` — emitting the same
+ *  text / tool-call it used to return from `doGenerate`, drained to completion by the loop. */
+import { MockLanguageModelV3 } from "ai/test";
+import { simulateReadableStream } from "ai";
+import type { Model } from "./model";
+
+// Raw provider-level usage (LanguageModelV3Usage: `{ inputTokens: { total }, outputTokens: { total } }`);
+// the SDK normalizes it to the user-facing `{ inputTokens, outputTokens }` the loop meters.
+const usage = { inputTokens: { total: 3 }, outputTokens: { total: 2 } } as const;
+
+// A doStream result: the given LanguageModelV3 stream parts. `initialDelayInMs` holds the FIRST
+// chunk back (the whole call stays in-flight that long) — used by the slow-mode scenarios below to
+// keep an agent visibly live long enough for VHS to freeze-frame its pane + bar segment.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function stream(chunks: unknown[], initialDelayInMs = 0): any {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return { stream: simulateReadableStream({ initialDelayInMs, chunkDelayInMs: 0, chunks: chunks as any }) };
+}
+
+// Streamed text response: start → one delta carrying the whole text → end → finish(stop).
+// `delayMs` (default 0) holds the model call in-flight before ANY output — the loop has already
+// emitted `model_start` (→ live "thinking" status) by then, so the agent renders as a live pane +
+// bar segment for the whole delay. Plan 12: there is no loop-level watchdog; the only deadline is the
+// provider fetch's transport timeout (120s default), which this mock never touches. Deterministic
+// (fixed delay, no network).
+function text(t: string, delayMs = 0) {
+  return stream([
+    { type: "stream-start", warnings: [] },
+    { type: "text-start", id: "t" },
+    { type: "text-delta", id: "t", delta: t },
+    { type: "text-end", id: "t" },
+    { type: "finish", finishReason: { unified: "stop", raw: "stop" }, usage },
+  ], delayMs);
+}
+
+// Streamed tool call: a single tool-call part → finish(tool-calls). The loop drains it, counts the
+// call, executes the tool, and loops.
+function call(name: string, input: object) {
+  return stream([
+    { type: "stream-start", warnings: [] },
+    { type: "tool-call", toolCallId: "c1", toolName: name, input: JSON.stringify(input) },
+    { type: "finish", finishReason: { unified: "tool-calls", raw: "tool_use" }, usage },
+  ]);
+}
+
+/** agent-flow: create_agent → approve → delegate_task → roll the child's proof back up. */
+function agentFlowModel(): Model {
+  let n = 0;
+  return new MockLanguageModelV3({
+    provider: "taicho-e2e",
+    modelId: "agent-flow",
+    doStream: async () => {
+      n += 1;
+      if (n === 1) return call("create_agent", {
+        id: "proof-agent",
+        role: "Proof worker",
+        identity: "You are proof-agent. Complete delegated work with a concise proof message.",
+      });
+      if (n === 2) return text("Created proof-agent.");
+      if (n === 3) return call("delegate_task", {
+        to: "proof-agent",
+        goal: "Produce proof that the created agent was used.",
+      });
+      if (n === 4) return text("proof-agent completed delegated work");
+      return text("Root used proof-agent: proof-agent completed delegated work");
+    },
+  }) as unknown as Model;
+}
+
+/** conversation-audit: the run gets one quick, offline tool cycle, then the NEXT model call HANGS
+ *  until the run's abort signal fires — so the run is genuinely in-flight and an Esc mid-run marks it
+ *  `interrupted` (not a race with an instant return). On abort we error the stream with the signal's
+ *  reason (a real AbortError), which the loop treats as a clean cancellation — the same
+ *  interrupted-turn path the tui-test drives, but deterministic under vhs.
+ *
+ *  Under the unified streaming path (Plan 07) the model implements `doStream`: the hang is a
+ *  ReadableStream that emits nothing and only errors when the abort fires (immediate, not on the
+ *  idle-timeout grace), so the interrupt stays deterministic.
+ *
+ *  Why the first call is a `find_skills` tool call (not an immediate hang): it makes the loop finish
+ *  one full model→tool cycle BEFORE hanging, which (a) writes model_request/model_response/tool_call
+ *  to `transcript.jsonl` so the interrupted turn still has a transcript (the tui-test asserts this),
+ *  and (b) emits a "↳ root → find_skills()" breadcrumb the tape gates the Esc on — a deterministic
+ *  screen signal that the run has moved past first-turn workspace setup into a hanging model call, so
+ *  no load-bearing fixed Sleep is needed. `find_skills` is granted to every agent and runs offline
+ *  (keyword ranking over the seeded skills — no network, no approval, no side effects). */
+function conversationAuditModel(): Model {
+  let n = 0;
+  return new MockLanguageModelV3({
+    provider: "taicho-e2e",
+    modelId: "conversation-audit",
+    doStream: async (options: { abortSignal?: AbortSignal }) => {
+      n += 1;
+      if (n === 1) return call("find_skills", { query: "delegate work to a worker agent" });
+      const signal = options.abortSignal;
+      // A stream that emits nothing and errors only when the run aborts. consumeStream then settles,
+      // the loop surfaces the abort, and the top-of-iteration abort check marks the turn interrupted.
+      const hanging = new ReadableStream({
+        start(controller) {
+          const onAbort = () =>
+            controller.error(signal?.reason ?? new Error("aborted by e2e conversation-audit model"));
+          if (signal?.aborted) { onAbort(); return; }
+          signal?.addEventListener("abort", onAbort, { once: true });
+        },
+      });
+      return { stream: hanging };
+    },
+  }) as unknown as Model;
+}
+
+/** artifact-handoff (Plan 01): prove the hand-off store end-to-end through the real binary.
+ *  root creates a researcher (agent A) and a writer (agent B), then wires A→B BY REFERENCE:
+ *    - A (researcher) save_artifacts a dossier whose body carries a distinctive payload marker.
+ *    - root delegates to B (writer) with inputArtifacts:[dossier@v1] — a HANDLE, not the body.
+ *    - B read_artifacts the dossier (the consumer legitimately pulls it) and save_artifacts a brief
+ *      linked back via parents:[dossier@v1].
+ *    - root's own context only ever sees handles + thin summaries — the dossier BODY payload never
+ *      enters root's transcript. The scenario asserts exactly that (parent context stays thin).
+ *  One shared counter drives the interleaved root/child turns in execution order (delegate BLOCKS, so
+ *  the child's turns run inline between the two root delegations — a deterministic linear script). */
+export const DOSSIER_PAYLOAD = "DOSSIER_PAYLOAD_XYZZY_do_not_inline_into_the_parent_context";
+function artifactHandoffModel(): Model {
+  let n = 0;
+  return new MockLanguageModelV3({
+    provider: "taicho-e2e",
+    modelId: "artifact-handoff",
+    doStream: async () => {
+      n += 1;
+      // root run 1 — create agent A (researcher)
+      if (n === 1) return call("create_agent", {
+        id: "researcher", role: "Researches topics and writes dossiers",
+        identity: "You are researcher. Produce a dossier artifact and hand it off by reference.",
+      });
+      if (n === 2) return text("Created researcher.");
+      // root run 2 — create agent B (writer)
+      if (n === 3) return call("create_agent", {
+        id: "writer", role: "Turns dossiers into briefs",
+        identity: "You are writer. Read the input dossier by reference and produce a brief.",
+      });
+      if (n === 4) return text("Created writer.");
+      // root run 3 — A produces, root wires A→B by reference, B consumes + derives
+      if (n === 5) return call("delegate_task", { to: "researcher", goal: "Produce a research dossier on foo." });
+      if (n === 6) return call("save_artifact", {
+        id: "dossier", title: "Foo dossier", type: "dossier",
+        summary: "a short summary of foo (safe to carry in context)",
+        body: `# Foo dossier\n\n${DOSSIER_PAYLOAD}\n\n(...the heavy body that must NOT pollute the parent...)`,
+      });
+      if (n === 7) return text("Saved dossier@v1.");
+      if (n === 8) return call("delegate_task", { to: "writer", goal: "Turn the dossier into a one-paragraph brief.", inputArtifacts: ["dossier@v1"] });
+      if (n === 9) return call("read_artifact", { id: "dossier@v1", includeBody: true });
+      if (n === 10) return call("save_artifact", { id: "brief", title: "Foo brief", type: "brief", summary: "the brief derived from the dossier", body: "Foo, briefly: it is what the dossier says.", parents: ["dossier@v1"] });
+      if (n === 11) return text("Wrote brief@v1 from dossier@v1.");
+      return text("Root wired researcher to writer by reference: brief@v1 from dossier@v1.");
+    },
+  }) as unknown as Model;
+}
+
+/** How long (ms) the squad-panes child holds its model call in-flight so its live pane + bar segment
+ *  are on screen long enough for VHS to `Wait+Screen` + screenshot. Fixed default, overridable via
+ *  TAICHO_E2E_SLOW_MS (deterministic — a duration, never a race). ~4s dwarfs VHS's poll interval and
+ *  sits far under the provider fetch's 120s transport deadline (Plan 12; no loop-level watchdog). */
+const SQUAD_PANES_SLOW_MS = Number(process.env.TAICHO_E2E_SLOW_MS ?? 4000);
+
+/** How long (ms) the consistent-blocks child holds its model call in-flight so its live block + bar
+ *  segment are on screen long enough for VHS to `Wait+Screen` + screenshot. Same rationale as above. */
+const CONSISTENT_BLOCKS_SLOW_MS = Number(process.env.TAICHO_E2E_SLOW_MS ?? 4000);
+
+/** How long (ms) the artifact-viewer child holds its model call in-flight so the completion bar +
+ *  viewer are on screen long enough for VHS to `Wait+Screen` + screenshot. Same rationale as above. */
+const ARTIFACT_VIEWER_SLOW_MS = Number(process.env.TAICHO_E2E_SLOW_MS ?? 4000);
+
+/** squad-panes (Plan 10 Phase 5): the SLOW-MODE delegation that makes the split-pane view provable.
+ *  Same shape as agent-flow (create proof-agent → approve → delegate → roll the proof up), but the
+ *  child's single model call is HELD in-flight for SQUAD_PANES_SLOW_MS. During that window two agents
+ *  are live at once — root `delegating` (its delegate_task tool is blocked on the child) and
+ *  proof-agent `thinking` (its model call is running) — so taicho renders a pane + bar segment for
+ *  each, long enough for VHS to freeze-frame the two-agents-in-panes+bar state before it completes.
+ *  Without the hold the child returns sub-second and the pane flashes faster than a recorded frame. */
+function squadPanesModel(): Model {
+  let n = 0;
+  return new MockLanguageModelV3({
+    provider: "taicho-e2e",
+    modelId: "squad-panes",
+    doStream: async () => {
+      n += 1;
+      // root run 1 — create proof-agent
+      if (n === 1) return call("create_agent", {
+        id: "proof-agent",
+        role: "Proof worker",
+        identity: "You are proof-agent. Complete delegated work with a concise proof message.",
+      });
+      if (n === 2) return text("Created proof-agent.");
+      // root run 2 — delegate (root stays `delegating`, blocked on the child below)
+      if (n === 3) return call("delegate_task", {
+        to: "proof-agent",
+        goal: "Produce proof that the created agent was used.",
+      });
+      // the child's only model call — SLOW: proof-agent stays visibly `thinking` while root delegates
+      if (n === 4) return text("proof-agent completed delegated work", SQUAD_PANES_SLOW_MS);
+      // root rolls the child's proof back up
+      return text("Root used proof-agent: proof-agent completed delegated work");
+    },
+  }) as unknown as Model;
+}
+
+/** consistent-blocks (Plan 13 corrected): the SLOW-MODE delegation that makes the consistent-blocks
+ *  view provable. Same shape as squad-panes, but proves the consistent-blocks view: during the
+ *  delegation, taicho renders a BLOCK (header + 2-line body) for each sub-agent, and the sub-agent's
+ *  full reply text does NOT appear in scrollback. */
+function consistentBlocksModel(): Model {
+  let n = 0;
+  return new MockLanguageModelV3({
+    provider: "taicho-e2e",
+    modelId: "consistent-blocks",
+    doStream: async () => {
+      n += 1;
+      // root run 1 — create proof-agent
+      if (n === 1) return call("create_agent", {
+        id: "proof-agent",
+        role: "Proof worker",
+        identity: "You are proof-agent. Complete delegated work with a concise proof message.",
+      });
+      if (n === 2) return text("Created proof-agent.");
+      // root run 2 — delegate (root stays `delegating`, blocked on the child below)
+      if (n === 3) return call("delegate_task", {
+        to: "proof-agent",
+        goal: "Produce proof that the created agent was used.",
+      });
+      // the child's only model call — SLOW: proof-agent stays visibly `thinking` while root delegates
+      if (n === 4) return text("proof-agent completed delegated work", CONSISTENT_BLOCKS_SLOW_MS);
+      // root rolls the child's proof back up
+      return text("Root used proof-agent: proof-agent completed delegated work");
+    },
+  }) as unknown as Model;
+}
+
+/** artifact-viewer (Plan 15): the SLOW-MODE delegation that makes the completion action bar + artifact
+ *  viewer provable. Same shape as squad-panes, but the child saves an artifact (so the completion bar
+ *  appears), and root names the handle (not the body). The tape opens the viewer to prove the markdown
+ *  body renders on screen. */
+function artifactViewerModel(): Model {
+  let n = 0;
+  return new MockLanguageModelV3({
+    provider: "taicho-e2e",
+    modelId: "artifact-viewer",
+    doStream: async () => {
+      n += 1;
+      // root run 1 — create proof-agent
+      if (n === 1) return call("create_agent", {
+        id: "proof-agent",
+        role: "Proof worker",
+        identity: "You are proof-agent. Save the deliverable as an artifact.",
+      });
+      if (n === 2) return text("Created proof-agent.");
+      // root run 2 — delegate (root stays `delegating`, blocked on the child below)
+      if (n === 3) return call("delegate_task", {
+        to: "proof-agent",
+        goal: "Save a proof document as an artifact.",
+      });
+      // the child saves an artifact — SLOW so the completion bar is visible
+      if (n === 4) return call("save_artifact", {
+        id: "proof-doc",
+        title: "Proof Document",
+        type: "document",
+        summary: "A proof that the artifact viewer works.",
+        body: "# Proof Document\n\nThis document proves the artifact viewer renders markdown bodies correctly.\n\n## Section 1\n\nThe completion action bar appeared after the run finished.\n\n## Section 2\n\nThe viewer opened on the newest artifact and rendered the full body.",
+      });
+      if (n === 5) return text("Saved proof-doc@v1.", ARTIFACT_VIEWER_SLOW_MS);
+      // root names the handle (not the body) — the completion bar makes it one keystroke away
+      return text("Done. See artifact proof-doc@v1.");
+    },
+  }) as unknown as Model;
+}
+
+
+/** plan-teams (Plan 18 + Plan 19): root opens a plan, delegates one item to a leadless TEAM (which the
+ *  engine routes to the best-ranked member), the child works, and root finishes. Exercises, in one real
+ *  binary run: the plan store, the tail-slot injection, team resolution, engine-owned correlation, and
+ *  every OTel span the run emits. Used by scripts/otel-verify.ts against a real OTLP endpoint. */
+function planTeamsModel(): Model {
+  let n = 0;
+  return new MockLanguageModelV3({
+    provider: "taicho-e2e",
+    modelId: "plan-teams",
+    doStream: async () => {
+      n += 1;
+      if (n === 1) return call("write_plan", {
+        goal: "ship the notifier",
+        items: [
+          { id: "it_survey", text: "survey the existing code" },
+          { id: "it_story", text: "file the announcement", assignee: "news" },
+        ],
+      });
+      if (n === 2) return call("update_plan_item", { itemId: "it_survey", status: "done" });
+      if (n === 3) return call("delegate_task", { to: "news", goal: "files stories on deadline", itemId: "it_story" });
+      if (n === 4) return text("Filed the announcement."); // the routed team member
+      return text("Plan complete: surveyed the code and filed the announcement.");
+    },
+  }) as unknown as Model;
+}
+
+export function createE2eModel(mode: string | undefined): Model | null {
+  if (mode === "agent-flow") return agentFlowModel();
+  if (mode === "plan-teams") return planTeamsModel();
+  if (mode === "conversation-audit") return conversationAuditModel();
+  if (mode === "artifact-handoff") return artifactHandoffModel();
+  if (mode === "squad-panes") return squadPanesModel();
+  if (mode === "consistent-blocks") return consistentBlocksModel();
+  if (mode === "artifact-viewer") return artifactViewerModel();
+  return null;
+}

package/src/core/embed.ts

@@ -0,0 +1,221 @@
+/** The KB embedder: turns text into a vector for semantic recall. Two optional, null-degrading
+ *  backends (→ keyword+graph when absent): a LOCAL model (transformers.js all-MiniLM-L6-v2 — no API
+ *  key) and OpenAI text-embedding-3-small (needs OPENAI_API_KEY). Config-selected; both loaded via
+ *  RUNTIME dynamic import so neither is statically bundled into the single binary.
+ *
+ *  The local backend runs the native ONNX model, which CANNOT bundle into a `bun build --compile`
+ *  binary (native `onnxruntime-node` fails `dlopen` from bunfs). So it has two paths, tried in order:
+ *   1. IN-PROCESS  — `import(pkg)` resolves from an ambient node_modules (i.e. `bun run dev`/source).
+ *   2. SIDECAR     — the shipped binary has no node_modules, so we self-install the package into
+ *      `~/.taicho/runtime` (once) and run the model in a spawned `bun`/`node` worker over stdin/stdout
+ *      — exactly how taicho already spawns MCP servers. Native resolution works in a normal runtime.
+ *  Any failure (no package manager, offline, spawn error) rejects → callers fall back to keyword+graph.
+ *  Model weights cache in ~/.taicho/models; the sidecar package installs into ~/.taicho/runtime. */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+
+export interface Embedder {
+  model: string;
+  dim: number;
+  embed: (text: string) => Promise<Float32Array>;
+  embedMany: (texts: string[]) => Promise<Float32Array[]>;
+}
+
+export type EmbedProvider = "off" | "local" | "openai";
+
+const LOCAL = { pkg: "@huggingface/transformers", version: "4.2.0", model: "Xenova/all-MiniLM-L6-v2", dim: 384 };
+const OPENAI = { pkg: "@ai-sdk/openai", model: "text-embedding-3-small", dim: 1536 };
+const WORKER_FILE = "embed-worker.mjs";
+const READY_TIMEOUT_MS = 180_000; // first start self-installs + downloads weights; generous, then fast.
+
+/** Build the configured embedder, or null (→ keyword+graph). Default: openai when OPENAI_API_KEY is
+ *  set, else local. Never throws — an unavailable backend degrades at embed()-time. */
+export function createEmbedder(opts: { provider?: EmbedProvider; env?: Record<string, string | undefined>; home?: string } = {}): Embedder | null {
+  const env = opts.env ?? process.env;
+  const provider: EmbedProvider = opts.provider ?? (env.OPENAI_API_KEY ? "openai" : "local");
+  if (provider === "off") return null;
+  if (provider === "openai") return env.OPENAI_API_KEY ? openaiEmbedder() : null;
+  const home = opts.home ?? join(homedir(), ".taicho");
+  return localEmbedder(join(home, "models"), join(home, "runtime"));
+}
+
+function openaiEmbedder(): Embedder {
+  const embedMany = async (texts: string[]): Promise<Float32Array[]> => {
+    const { openai } = await import(OPENAI.pkg);         // installed; dynamic keeps it out of the hot path
+    const { embedMany: aiEmbedMany } = await import("ai");
+    const { embeddings } = await aiEmbedMany({ model: openai.embedding(OPENAI.model), values: texts });
+    return embeddings.map((e: number[]) => new Float32Array(e));
+  };
+  return { model: OPENAI.model, dim: OPENAI.dim, embed: async (t) => (await embedMany([t]))[0]!, embedMany };
+}
+
+// --- local backend selection helpers (pure; unit-tested) --------------------------------------
+
+/** Runtime to run the sidecar worker in — prefer bun, else node. null ⇒ neither on PATH. */
+export function pickRuntime(which: (cmd: string) => string | null): "bun" | "node" | null {
+  return which("bun") ? "bun" : which("node") ? "node" : null;
+}
+
+/** Package manager to self-install the embedder — prefer bun, else npm. null ⇒ neither on PATH. */
+export function pickPackageManager(which: (cmd: string) => string | null): "bun" | "npm" | null {
+  return which("bun") ? "bun" : which("npm") ? "npm" : null;
+}
+
+export function installArgs(pm: "bun" | "npm", spec: string): string[] {
+  return pm === "bun" ? ["add", spec] : ["install", spec, "--no-save", "--no-audit", "--no-fund"];
+}
+
+/** The sidecar worker: a standalone ESM module that loads the model and serves embeddings over
+ *  stdin/stdout as newline-delimited JSON ({id,text} → {id,vec} | {id,error}). Runs in a normal
+ *  bun/node process (native onnxruntime resolves), NOT inside the compiled binary. */
+export const WORKER_SOURCE = `import { createInterface } from "node:readline";
+import { pipeline, env } from "@huggingface/transformers";
+if (process.env.TAICHO_MODELS_DIR) env.cacheDir = process.env.TAICHO_MODELS_DIR;
+env.allowRemoteModels = true;
+const extractor = await pipeline("feature-extraction", process.env.TAICHO_EMBED_MODEL);
+process.stdout.write("READY\\n");
+const rl = createInterface({ input: process.stdin });
+for await (const line of rl) {
+  const t = line.trim();
+  if (!t) continue;
+  const { id, text } = JSON.parse(t);
+  try {
+    const out = await extractor(text, { pooling: "mean", normalize: true });
+    process.stdout.write(JSON.stringify({ id, vec: Array.from(out.data) }) + "\\n");
+  } catch (e) {
+    process.stdout.write(JSON.stringify({ id, error: String(e && e.message || e) }) + "\\n");
+  }
+}
+`;
+
+// --- local backend orchestration --------------------------------------------------------------
+
+type EmbedFn = (text: string) => Promise<Float32Array>;
+
+function localEmbedder(modelsDir: string, runtimeDir: string): Embedder {
+  let backend: Promise<EmbedFn> | null = null;
+  const load = () => (backend ??= startLocalBackend(modelsDir, runtimeDir));
+  const embed = async (t: string) => (await load())(t);
+  return { model: LOCAL.model, dim: LOCAL.dim, embed, embedMany: (ts) => Promise.all(ts.map(embed)) };
+}
+
+async function startLocalBackend(modelsDir: string, runtimeDir: string): Promise<EmbedFn> {
+  try {
+    return await inProcessBackend(modelsDir);            // dev / source run: ambient node_modules
+  } catch {
+    return await sidecarBackend(modelsDir, runtimeDir);  // shipped binary: self-installed worker
+  }
+}
+
+/** Load the model in-process. Works wherever the package resolves from an ambient node_modules
+ *  (dev). In the compiled binary `import(pkg)` throws (module not found / dlopen) → sidecar path. */
+async function inProcessBackend(modelsDir: string): Promise<EmbedFn> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const tf: any = await import(LOCAL.pkg);               // variable specifier ⇒ NOT statically bundled
+  tf.env.cacheDir = modelsDir;
+  tf.env.allowRemoteModels = true;
+  const extractor = await tf.pipeline("feature-extraction", LOCAL.model);
+  return async (t: string) => {
+    const out = await extractor(t, { pooling: "mean", normalize: true });
+    return new Float32Array(out.data as Float32Array);
+  };
+}
+
+/** Self-install the package into runtimeDir (once) + write the worker, then drive it as a subprocess. */
+async function sidecarBackend(modelsDir: string, runtimeDir: string): Promise<EmbedFn> {
+  await ensureRuntime(runtimeDir);
+  const runtime = pickRuntime((c) => Bun.which(c));
+  if (!runtime) throw new Error("no bun/node on PATH to run the local embedder");
+  const client = await startWorker(runtime, join(runtimeDir, WORKER_FILE), runtimeDir, {
+    TAICHO_MODELS_DIR: modelsDir,
+    TAICHO_EMBED_MODEL: LOCAL.model,
+  });
+  return (t) => client.submit(t);
+}
+
+/** Ensure runtimeDir has @huggingface/transformers installed and a fresh worker script. The install
+ *  is async (Bun.spawn, not spawnSync) so it never blocks the event loop / freezes the Ink TUI. */
+async function ensureRuntime(runtimeDir: string): Promise<void> {
+  const pkgDir = join(runtimeDir, "node_modules", "@huggingface", "transformers");
+  if (!existsSync(pkgDir)) {
+    mkdirSync(runtimeDir, { recursive: true });
+    const manifest = join(runtimeDir, "package.json");
+    if (!existsSync(manifest)) writeFileSync(manifest, JSON.stringify({ name: "taicho-embed-runtime", private: true }) + "\n");
+    const pm = pickPackageManager((c) => Bun.which(c));
+    if (!pm) throw new Error("no bun/npm on PATH to install the local embedder");
+    const proc = Bun.spawn([pm, ...installArgs(pm, `${LOCAL.pkg}@${LOCAL.version}`)], { cwd: runtimeDir, stdout: "ignore", stderr: "pipe" });
+    const code = await proc.exited;
+    if (code !== 0) throw new Error("local embedder install failed: " + (await new Response(proc.stderr).text()).slice(-300));
+  }
+  writeFileSync(join(runtimeDir, WORKER_FILE), WORKER_SOURCE); // (re)write so it tracks this build
+}
+
+interface WorkerClient { submit: EmbedFn; close: () => void; }
+
+/** Spawn the worker and speak newline-delimited JSON to it. Resolves once the worker signals READY
+ *  (model loaded). Correlates concurrent requests by id; a worker exit rejects all pending + future
+ *  calls so the embedder degrades to keyword+graph rather than hanging. */
+function startWorker(runtime: string, workerPath: string, cwd: string, envVars: Record<string, string>): Promise<WorkerClient> {
+  const proc = Bun.spawn([runtime, workerPath], {
+    cwd, stdin: "pipe", stdout: "pipe", stderr: "pipe",
+    env: { ...process.env, ...envVars },
+  });
+  const pending = new Map<number, { resolve: (v: Float32Array) => void; reject: (e: Error) => void }>();
+  let nextId = 1;
+  let dead: Error | null = null;
+  let onReady!: () => void;
+  let onReadyFail!: (e: Error) => void;
+  const ready = new Promise<void>((res, rej) => { onReady = res; onReadyFail = rej; });
+
+  const failAll = (e: Error) => {
+    dead = e;
+    for (const p of pending.values()) p.reject(e);
+    pending.clear();
+    onReadyFail(e);
+  };
+
+  void (async () => {
+    const reader = proc.stdout.getReader();
+    const dec = new TextDecoder();
+    let buf = "";
+    let isReady = false;
+    for (;;) {
+      const chunk = await reader.read().catch(() => ({ done: true as const, value: undefined }));
+      if (chunk.done) break;
+      buf += dec.decode(chunk.value, { stream: true });
+      let nl: number;
+      while ((nl = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, nl).trim();
+        buf = buf.slice(nl + 1);
+        if (!line) continue;
+        if (!isReady) { if (line === "READY") { isReady = true; onReady(); } continue; }
+        try {
+          const msg = JSON.parse(line) as { id: number; vec?: number[]; error?: string };
+          const p = pending.get(msg.id);
+          if (!p) continue;
+          pending.delete(msg.id);
+          if (msg.error) p.reject(new Error(msg.error));
+          else p.resolve(new Float32Array(msg.vec!));
+        } catch { /* ignore non-JSON noise on stdout */ }
+      }
+    }
+  })();
+
+  void proc.exited.then((code) => { if (!dead) failAll(new Error(`embed worker exited (code ${code})`)); });
+
+  const timer = setTimeout(() => { if (!dead) { proc.kill(); failAll(new Error("embed worker did not become ready in time")); } }, READY_TIMEOUT_MS);
+  if (typeof timer.unref === "function") timer.unref();
+
+  const submit: EmbedFn = (text) => {
+    if (dead) return Promise.reject(dead);
+    const id = nextId++;
+    return new Promise<Float32Array>((resolve, reject) => {
+      pending.set(id, { resolve, reject });
+      proc.stdin.write(JSON.stringify({ id, text }) + "\n");
+      void proc.stdin.flush();
+    });
+  };
+
+  return ready.then(() => { clearTimeout(timer); return { submit, close: () => proc.kill() }; });
+}

package/src/core/events.ts

@@ -0,0 +1,133 @@
+/** Reader-side helpers for the on-disk run event stream — the observable surface a headless or
+ *  external observer watches (documented in `docs/events.md`).
+ *
+ *  Each run writes `runs/<agent>/<recordId>/transcript.jsonl`: one JSON object per line, appended in
+ *  order. This module reads that stream, finds the latest run, formats an event as a single human
+ *  line, and provides a simple *tail* (print-then-follow) so an observer no longer has to poll files
+ *  by hand. All output is passed through `redact()` so a tail can never leak auth material. */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { paths } from "../store/files";
+import type { RunTranscriptEvent } from "../store/run-transcript";
+import { redact } from "./logger";
+
+export type { RunTranscriptEvent } from "../store/run-transcript";
+
+/** Parse a run's transcript.jsonl into events (skips blank/half-written trailing lines). */
+export function readTranscript(ws: string, runId: string): RunTranscriptEvent[] {
+  const file = join(paths.runRecordDir(ws, runId), "transcript.jsonl");
+  if (!existsSync(file)) return [];
+  const out: RunTranscriptEvent[] = [];
+  for (const line of readFileSync(file, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try { out.push(JSON.parse(line) as RunTranscriptEvent); } catch { /* skip a partially-flushed line */ }
+  }
+  return out;
+}
+
+/** All known run ids (`<agent>/<recordId>`), discovered from the per-agent trace JSON files. */
+export function listRunIds(ws: string): string[] {
+  const runsDir = join(ws, "runs");
+  if (!existsSync(runsDir)) return [];
+  const ids: string[] = [];
+  for (const agent of readdirSync(runsDir)) {
+    const agentDir = join(runsDir, agent);
+    let entries: string[];
+    try { entries = readdirSync(agentDir); } catch { continue; }
+    for (const f of entries) {
+      if (f.endsWith(".json")) ids.push(`${agent}/${f.slice(0, -".json".length)}`);
+    }
+  }
+  return ids;
+}
+
+/** The most recently written run id, by trace-file mtime. Undefined when there are no runs. */
+export function latestRunId(ws: string): string | undefined {
+  let best: { id: string; mtime: number } | undefined;
+  for (const id of listRunIds(ws)) {
+    const i = id.indexOf("/");
+    const traceFile = join(ws, "runs", id.slice(0, i), `${id.slice(i + 1)}.json`);
+    let mtime = 0;
+    try { mtime = statSync(traceFile).mtimeMs; } catch { /* ignore */ }
+    if (!best || mtime > best.mtime) best = { id, mtime };
+  }
+  return best?.id;
+}
+
+/** One truncated, redacted line for an event (used by the tail). Never assumes a payload shape. */
+export function formatEvent(event: RunTranscriptEvent): string {
+  const iter = event.iteration != null ? ` iter ${event.iteration}` : "";
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const d = event.data as any;
+  let detail = "";
+  switch (event.kind) {
+    case "model_request":
+      detail = [d?.messageCount != null ? `${d.messageCount} msgs` : "", d?.contextTokens != null ? `~${d.contextTokens} tok` : "", d?.compacted ? "compacted" : ""].filter(Boolean).join(" · ");
+      break;
+    case "compaction":
+      detail = `folded ${d?.foldedRoundTrips ?? "?"} round-trip(s) / ${d?.foldedMessages ?? "?"} msgs · ${d?.before ?? "?"}→${d?.after ?? "?"} tok`;
+      break;
+    case "model_response": {
+      const text = typeof d?.text === "string" ? d.text.replace(/\s+/g, " ").trim() : "";
+      const calls = Array.isArray(d?.toolCalls) ? d.toolCalls.length : 0;
+      detail = [text ? `"${truncate(text, 60)}"` : "", calls ? `${calls} tool call(s)` : ""].filter(Boolean).join(" · ");
+      break;
+    }
+    case "model_error":
+      detail = typeof d?.error === "string" ? d.error : "";
+      break;
+    case "tool_call":
+      detail = d?.toolName ? `${d.toolName}(${truncate(JSON.stringify(d.input ?? {}), 60)})` : "";
+      break;
+    case "verification":
+      detail = d?.verdict ? `${d.verdict.pass ? "pass" : "FAIL"}${d.criteria ? ` — ${truncate(d.criteria, 50)}` : ""}` : "";
+      break;
+    default:
+      detail = d ? truncate(JSON.stringify(d), 60) : "";
+  }
+  return redact(`[${event.ts}]${iter} ${event.kind}${detail ? `: ${detail}` : ""}`);
+}
+
+function truncate(s: string, n: number): string {
+  return s.length > n ? s.slice(0, n - 1) + "…" : s;
+}
+
+/** Print a run's events then (optionally) follow appends. Returns when done (non-follow) or when the
+ *  signal aborts (follow). Polls rather than fs.watch — robust on macOS and fine for a human tail. */
+export async function tailRun(opts: {
+  ws: string;
+  runId?: string;
+  follow?: boolean;
+  out?: (line: string) => void;
+  intervalMs?: number;
+  signal?: AbortSignal;
+  /** In follow mode, wait up to this long for a not-yet-created transcript to appear. */
+  waitForMs?: number;
+}): Promise<void> {
+  const out = opts.out ?? ((l: string) => process.stdout.write(l + "\n"));
+  const interval = opts.intervalMs ?? 250;
+  const runId = opts.runId ?? latestRunId(opts.ws);
+  if (!runId) { out("(no runs found)"); return; }
+
+  let printed = 0;
+  const flush = () => {
+    const events = readTranscript(opts.ws, runId);
+    for (const e of events.slice(printed)) out(formatEvent(e));
+    printed = events.length;
+  };
+
+  flush();
+  if (!opts.follow) return;
+
+  const deadline = Date.now() + (opts.waitForMs ?? 0);
+  while (!opts.signal?.aborted) {
+    await sleep(interval);
+    flush();
+    // If we've never seen an event and the grace window for a pending run elapsed, stop waiting.
+    if (printed === 0 && opts.waitForMs != null && Date.now() > deadline) break;
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}