@botcord/daemon 0.2.88 → 0.2.90

package/src/gateway/__tests__/gemini-adapter.test.ts

@@ -0,0 +1,357 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { GeminiAdapter } from "../runtimes/gemini.js";
+import { geminiModule } from "../runtimes/registry.js";
+
+// The adapter spawns whatever binary we point it at; we point it at a small
+// Node script so we control stdout/stderr/exit precisely without needing the
+// real `gemini` CLI.
+const tmpRoot = mkdtempSync(path.join(os.tmpdir(), "gateway-gemini-"));
+
+const originalHome = process.env.HOME;
+const agentHomeRoot = mkdtempSync(path.join(os.tmpdir(), "gateway-gemini-home-"));
+
+beforeAll(() => {
+  process.env.HOME = agentHomeRoot;
+});
+
+afterAll(() => {
+  if (originalHome === undefined) delete process.env.HOME;
+  else process.env.HOME = originalHome;
+  rmSync(tmpRoot, { recursive: true, force: true });
+  rmSync(agentHomeRoot, { recursive: true, force: true });
+});
+
+function makeScript(name: string, body: string): string {
+  const p = path.join(tmpRoot, name);
+  writeFileSync(p, `#!/usr/bin/env node\n${body}\n`, { mode: 0o755 });
+  chmodSync(p, 0o755);
+  return p;
+}
+
+function runAdapter(
+  script: string,
+  opts: {
+    sessionId?: string | null;
+    systemContext?: string;
+    extraArgs?: string[];
+    onBlock?: (kind: string) => void;
+    onStatus?: (e: { phase: string; label?: string }) => void;
+  } = {},
+) {
+  const adapter = new GeminiAdapter({ binary: script });
+  const ctrl = new AbortController();
+  return adapter.run({
+    text: "hi",
+    sessionId: opts.sessionId ?? null,
+    accountId: "ag_test",
+    cwd: tmpRoot,
+    signal: ctrl.signal,
+    trustLevel: "owner",
+    systemContext: opts.systemContext,
+    extraArgs: opts.extraArgs,
+    onBlock: opts.onBlock ? (b) => opts.onBlock!(b.kind) : undefined,
+    onStatus: opts.onStatus
+      ? (e) => {
+          if (e.kind === "thinking") opts.onStatus!({ phase: e.phase, label: e.label });
+        }
+      : undefined,
+  });
+}
+
+describe("GeminiAdapter", () => {
+  it("captures session_id from init and concatenates assistant deltas as final text", async () => {
+    const script = makeScript(
+      "happy.js",
+      `
+const lines = [
+  {type:"init", timestamp:"t0", session_id:"abc-123-session", model:"gemini-2.5-pro"},
+  {type:"message", timestamp:"t1", role:"user", content:"hi"},
+  {type:"message", timestamp:"t2", role:"assistant", content:"hello ", delta:true},
+  {type:"message", timestamp:"t3", role:"assistant", content:"from gemini", delta:true},
+  {type:"result", timestamp:"t4", status:"success", stats:{}},
+];
+for (const l of lines) process.stdout.write(JSON.stringify(l) + "\\n");
+process.exit(0);
+`,
+    );
+    const res = await runAdapter(script);
+    expect(res.newSessionId).toBe("abc-123-session");
+    expect(res.text).toBe("hello from gemini");
+    expect(res.error).toBeUndefined();
+  });
+
+  it("emits StreamBlocks for assistant_text / tool_use / tool_result / system kinds", async () => {
+    const script = makeScript(
+      "blocks.js",
+      `
+const lines = [
+  {type:"init", timestamp:"t0", session_id:"sess1", model:"gemini-2.5-pro"},
+  {type:"tool_use", timestamp:"t1", tool_name:"read_file", tool_id:"t_0", parameters:{path:"x"}},
+  {type:"tool_result", timestamp:"t2", tool_id:"t_0", status:"success", output:"ok"},
+  {type:"message", timestamp:"t3", role:"assistant", content:"done", delta:true},
+  {type:"result", timestamp:"t4", status:"success", stats:{}},
+];
+for (const l of lines) process.stdout.write(JSON.stringify(l) + "\\n");
+`,
+    );
+    const seen: string[] = [];
+    const res = await runAdapter(script, { onBlock: (k) => seen.push(k) });
+    expect(res.text).toBe("done");
+    expect(seen).toContain("system"); // init + result
+    expect(seen).toContain("tool_use");
+    expect(seen).toContain("tool_result");
+    expect(seen).toContain("assistant_text");
+  });
+
+  it("emits thinking onStatus events for init, tool_use, assistant message, and result", async () => {
+    const script = makeScript(
+      "thinkflow.js",
+      `
+const lines = [
+  {type:"init", timestamp:"t0", session_id:"sess2"},
+  {type:"tool_use", timestamp:"t1", tool_name:"shell", tool_id:"t_0", parameters:{}},
+  {type:"tool_result", timestamp:"t2", tool_id:"t_0", status:"success"},
+  {type:"message", timestamp:"t3", role:"assistant", content:"ok", delta:true},
+  {type:"result", timestamp:"t4", status:"success", stats:{}},
+];
+for (const l of lines) process.stdout.write(JSON.stringify(l) + "\\n");
+`,
+    );
+    const status: Array<{ phase: string; label?: string }> = [];
+    await runAdapter(script, { onStatus: (e) => status.push(e) });
+    expect(status).toEqual([
+      { phase: "started", label: "Starting session" },
+      { phase: "updated", label: "shell" },
+      { phase: "stopped", label: undefined },
+      { phase: "stopped", label: undefined },
+    ]);
+  });
+
+  it("no sessionId → spawn without --resume", async () => {
+    const script = makeScript(
+      "fresh-argv.js",
+      `
+const argv = process.argv.slice(2);
+process.stdout.write(JSON.stringify({type:"init", session_id:"new-sess"}) + "\\n");
+process.stdout.write(JSON.stringify({type:"message", role:"assistant", content:JSON.stringify(argv), delta:true}) + "\\n");
+process.stdout.write(JSON.stringify({type:"result", status:"success", stats:{}}) + "\\n");
+`,
+    );
+    const res = await runAdapter(script, { sessionId: null });
+    const argv = JSON.parse(res.text) as string[];
+    expect(argv).not.toContain("--resume");
+    expect(argv).toContain("-p");
+    expect(argv).toContain("hi");
+    expect(argv).toContain("--output-format");
+    expect(argv).toContain("stream-json");
+    expect(argv).toContain("--yolo");
+    expect(argv).toContain("--skip-trust");
+  });
+
+  it("with sessionId → spawn with `--resume <id>`", async () => {
+    const script = makeScript(
+      "resume-argv.js",
+      `
+const argv = process.argv.slice(2);
+process.stdout.write(JSON.stringify({type:"init", session_id:"continued"}) + "\\n");
+process.stdout.write(JSON.stringify({type:"message", role:"assistant", content:JSON.stringify(argv), delta:true}) + "\\n");
+process.stdout.write(JSON.stringify({type:"result", status:"success", stats:{}}) + "\\n");
+`,
+    );
+    const sid = "abc-123-session";
+    const res = await runAdapter(script, { sessionId: sid });
+    const argv = JSON.parse(res.text) as string[];
+    expect(argv).toContain("--resume");
+    expect(argv[argv.indexOf("--resume") + 1]).toBe(sid);
+  });
+
+  it("rejects invalid sessionId before spawn", async () => {
+    const script = makeScript("noop.js", "process.exit(0);");
+    const adapter = new GeminiAdapter({ binary: script });
+    const ctrl = new AbortController();
+    await expect(
+      adapter.run({
+        text: "x",
+        sessionId: "../bad space",
+        accountId: "ag_test",
+        cwd: tmpRoot,
+        signal: ctrl.signal,
+        trustLevel: "owner",
+      }),
+    ).rejects.toThrow(/invalid sessionId/);
+  });
+
+  it("prepends systemContext to the positional prompt", async () => {
+    const script = makeScript(
+      "echo-prompt.js",
+      `
+const argv = process.argv.slice(2);
+const pIdx = argv.indexOf("-p");
+const prompt = pIdx >= 0 ? argv[pIdx + 1] : "";
+process.stdout.write(JSON.stringify({type:"init", session_id:"s1"}) + "\\n");
+process.stdout.write(JSON.stringify({type:"message", role:"assistant", content:prompt, delta:true}) + "\\n");
+process.stdout.write(JSON.stringify({type:"result", status:"success", stats:{}}) + "\\n");
+`,
+    );
+    const res = await runAdapter(script, {
+      systemContext: "MEMORY: remember X\nDIGEST: room Y was active",
+    });
+    expect(res.text).toContain("MEMORY: remember X");
+    expect(res.text).toContain("DIGEST: room Y was active");
+    expect(res.text).toContain("---");
+    expect(res.text.endsWith("hi")).toBe(true);
+  });
+
+  it("empty systemContext leaves the prompt unchanged", async () => {
+    const script = makeScript(
+      "echo-prompt-empty.js",
+      `
+const argv = process.argv.slice(2);
+const pIdx = argv.indexOf("-p");
+const prompt = pIdx >= 0 ? argv[pIdx + 1] : "";
+process.stdout.write(JSON.stringify({type:"init", session_id:"s2"}) + "\\n");
+process.stdout.write(JSON.stringify({type:"message", role:"assistant", content:prompt, delta:true}) + "\\n");
+process.stdout.write(JSON.stringify({type:"result", status:"success", stats:{}}) + "\\n");
+`,
+    );
+    const res = await runAdapter(script, { systemContext: "   \n\n  " });
+    expect(res.text).toBe("hi");
+  });
+
+  it("does not double-add --yolo when extraArgs already supplies --approval-mode", async () => {
+    const script = makeScript(
+      "echo-yolo.js",
+      `
+const argv = process.argv.slice(2);
+process.stdout.write(JSON.stringify({type:"init", session_id:"s3"}) + "\\n");
+process.stdout.write(JSON.stringify({type:"message", role:"assistant", content:JSON.stringify(argv), delta:true}) + "\\n");
+process.stdout.write(JSON.stringify({type:"result", status:"success", stats:{}}) + "\\n");
+`,
+    );
+    const res = await runAdapter(script, {
+      extraArgs: ["--approval-mode", "plan"],
+    });
+    const argv = JSON.parse(res.text) as string[];
+    expect(argv).toContain("--approval-mode");
+    expect(argv[argv.indexOf("--approval-mode") + 1]).toBe("plan");
+    expect(argv).not.toContain("--yolo");
+  });
+
+  it("strips claude-code / codex foreign flags from extraArgs", async () => {
+    const script = makeScript(
+      "echo-strip.js",
+      `
+const argv = process.argv.slice(2);
+process.stdout.write(JSON.stringify({type:"init", session_id:"s4"}) + "\\n");
+process.stdout.write(JSON.stringify({type:"message", role:"assistant", content:JSON.stringify(argv), delta:true}) + "\\n");
+process.stdout.write(JSON.stringify({type:"result", status:"success", stats:{}}) + "\\n");
+`,
+    );
+    const res = await runAdapter(script, {
+      extraArgs: [
+        "--append-system-prompt",
+        "ignored content",
+        "--permission-mode",
+        "bypassPermissions",
+        "--setting-sources=project",
+        "--dangerously-bypass-approvals-and-sandbox",
+        "--model",
+        "gemini-2.5-pro",
+      ],
+    });
+    const argv = JSON.parse(res.text) as string[];
+    // Foreign flags + their values are dropped …
+    expect(argv).not.toContain("--append-system-prompt");
+    expect(argv).not.toContain("ignored content");
+    expect(argv).not.toContain("--permission-mode");
+    expect(argv).not.toContain("bypassPermissions");
+    expect(argv).not.toContain("--setting-sources=project");
+    expect(argv).not.toContain("--dangerously-bypass-approvals-and-sandbox");
+    // … but gemini-native flags survive.
+    expect(argv).toContain("--model");
+    expect(argv[argv.indexOf("--model") + 1]).toBe("gemini-2.5-pro");
+  });
+
+  it("surfaces result.status=error as the run error and wipes session id", async () => {
+    const script = makeScript(
+      "failed.js",
+      `
+const lines = [
+  {type:"init", timestamp:"t0", session_id:"will-be-wiped"},
+  {type:"message", timestamp:"t1", role:"assistant", content:"partial", delta:true},
+  {type:"result", timestamp:"t2", status:"error", error:{type:"AUTH", message:"please run gemini auth login"}, stats:{}},
+];
+for (const l of lines) process.stdout.write(JSON.stringify(l) + "\\n");
+process.exit(1);
+`,
+    );
+    const res = await runAdapter(script);
+    expect(res.error).toMatch(/gemini auth login/);
+    expect(res.newSessionId).toBe("");
+    expect(res.text).toBe("");
+  });
+
+  it("surfaces non-zero exit + stderr when no result event is emitted", async () => {
+    const script = makeScript(
+      "boom.js",
+      `
+process.stderr.write("FATAL: gemini setup incomplete\\n");
+process.exit(7);
+`,
+    );
+    const res = await runAdapter(script);
+    expect(res.error).toBeDefined();
+    expect(res.error).toMatch(/code 7/);
+    expect(res.error).toMatch(/setup incomplete/);
+  });
+
+  it("non-fatal `error` events with severity=warning do not override assistant text", async () => {
+    const script = makeScript(
+      "warning.js",
+      `
+const lines = [
+  {type:"init", timestamp:"t0", session_id:"sess-warn"},
+  {type:"error", timestamp:"t1", severity:"warning", message:"loop detected, retrying"},
+  {type:"message", timestamp:"t2", role:"assistant", content:"final answer", delta:true},
+  {type:"result", timestamp:"t3", status:"success", stats:{}},
+];
+for (const l of lines) process.stdout.write(JSON.stringify(l) + "\\n");
+`,
+    );
+    const res = await runAdapter(script);
+    expect(res.text).toBe("final answer");
+    expect(res.error).toBeUndefined();
+  });
+
+  it("returns early when signal is already aborted", async () => {
+    const script = makeScript("noop.js", "process.exit(0);");
+    const adapter = new GeminiAdapter({ binary: script });
+    const ctrl = new AbortController();
+    ctrl.abort();
+    const res = await adapter.run({
+      text: "x",
+      sessionId: null,
+      accountId: "ag_test",
+      cwd: tmpRoot,
+      signal: ctrl.signal,
+      trustLevel: "owner",
+    });
+    expect(res.text).toBe("");
+    expect(res.error).toMatch(/aborted before spawn/);
+  });
+});
+
+describe("geminiModule registration", () => {
+  it("declares supportsRun (via default) so the dispatcher routes turns to it", () => {
+    // The registry treats `supportsRun === undefined` as true. We assert
+    // the field isn't set to `false` so a regression on registry.ts shows
+    // up here rather than as a confusing runtime "probe-only stub" error.
+    expect(geminiModule.supportsRun).not.toBe(false);
+    expect(geminiModule.id).toBe("gemini");
+    expect(geminiModule.envVar).toBe("BOTCORD_GEMINI_BIN");
+    expect(geminiModule.installHint).toBeDefined();
+  });
+});

package/src/gateway/runtimes/gemini.ts

@@ -1,15 +1,91 @@
+import { NdjsonStreamAdapter, type NdjsonEventCtx } from "./ndjson-stream.js";
 import {
   readCommandVersion,
   resolveCommandOnPath,
   type ProbeDeps,
 } from "./probe.js";
 import type {
-  RuntimeAdapter,
   RuntimeProbeResult,
   RuntimeRunOptions,
-  RuntimeRunResult,
+  RuntimeStatusEvent,
+  StreamBlock,
 } from "../types.js";
 
+/**
+ * Gemini's `--session-id` / `--resume` accept only `[A-Za-z0-9-_]+` and we
+ * forward whatever the CLI emitted in its `init` event. Rejecting anything
+ * else keeps argv safe even if the upstream session id format ever changes.
+ */
+const GEMINI_SESSION_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
+
+function isValidGeminiSessionId(id: string): boolean {
+  return GEMINI_SESSION_ID_RE.test(id);
+}
+
+function invalidGeminiSessionIdError(id: string): string {
+  return `gemini: invalid sessionId ${JSON.stringify(id)} (expected [A-Za-z0-9_-]+)`;
+}
+
+/**
+ * Drop adapter-foreign flags inherited from other runtimes' route configs
+ * (claude-code, codex). Each entry that takes a value also swallows the
+ * value that follows. Anything else is forwarded verbatim so operators can
+ * still push gemini-native flags through.
+ */
+const GEMINI_FOREIGN_FLAGS_WITH_VALUE = new Set([
+  "--append-system-prompt",
+  "--permission-mode",
+  "--setting-sources",
+  "--sandbox",
+  "-c",
+]);
+const GEMINI_FOREIGN_BOOLEAN_FLAGS = new Set([
+  "--dangerously-bypass-approvals-and-sandbox",
+  "--full-auto",
+  "--skip-git-repo-check",
+  "--json",
+  "--verbose",
+]);
+
+function extraFlagName(arg: string): string {
+  if (!arg.startsWith("-")) return arg;
+  const eq = arg.indexOf("=");
+  return eq === -1 ? arg : arg.slice(0, eq);
+}
+
+function nextExtraValue(args: string[], index: number): string | undefined {
+  const next = args[index + 1];
+  if (typeof next !== "string") return undefined;
+  if (!next.startsWith("-")) return next;
+  return /^-\d/.test(next) ? next : undefined;
+}
+
+function sanitizeGeminiExtraArgs(extraArgs: string[] | undefined): string[] {
+  if (!extraArgs?.length) return [];
+  const out: string[] = [];
+  for (let i = 0; i < extraArgs.length; i += 1) {
+    const arg = extraArgs[i];
+    const name = extraFlagName(arg);
+    if (GEMINI_FOREIGN_FLAGS_WITH_VALUE.has(name)) {
+      if (!arg.includes("=") && nextExtraValue(extraArgs, i) !== undefined) i += 1;
+      continue;
+    }
+    if (GEMINI_FOREIGN_BOOLEAN_FLAGS.has(name)) {
+      continue;
+    }
+    out.push(arg);
+  }
+  return out;
+}
+
+function hasFlag(args: string[], name: string): boolean {
+  for (const arg of args) {
+    if (arg === name) return true;
+    if (arg.startsWith(`${name}=`)) return true;
+  }
+  return false;
+}
+
 /** Resolve the Gemini CLI executable on PATH. */
 export function resolveGeminiCommand(deps: ProbeDeps = {}): string | null {
   return resolveCommandOnPath("gemini", deps);
@@ -27,17 +103,235 @@ export function probeGemini(deps: ProbeDeps = {}): RuntimeProbeResult {
 }
 
 /**
- * Gemini adapter stub — probe() is wired up so `botcord-daemon doctor` can report it.
- * run() is not implemented yet; routing a turn here will surface the error upstream.
+ * Gemini adapter — spawns `gemini -p "<text>" --output-format stream-json
+ * --yolo` (with `--resume <sid>` for continuing sessions) and parses the
+ * newline-delimited JSON stream.
+ *
+ * stream-json event shape (abridged, sourced from `@google/gemini-cli`
+ * bundle `nonInteractiveCliAgentSession.ts`):
+ *
+ *   {type:"init", timestamp, session_id, model}
+ *   {type:"message", timestamp, role:"user", content}            // echo of input
+ *   {type:"message", timestamp, role:"assistant", content, delta:true}
+ *   {type:"tool_use", timestamp, tool_name, tool_id, parameters}
+ *   {type:"tool_result", timestamp, tool_id, status, output?, error?}
+ *   {type:"error", timestamp, severity, message}                 // non-fatal warning
+ *   {type:"result", timestamp, status:"success", stats}          // terminal
+ *   {type:"result", timestamp, status:"error", error:{type,message}, stats}
+ *
+ * Unlike Claude Code's `result` event, gemini's terminal event carries NO
+ * final assistant text — the reply must be assembled by concatenating every
+ * `message` event with `role:"assistant"` (the CLI emits them as deltas).
+ *
+ * ## systemContext
+ *
+ * Gemini's headless mode has no `--append-system-prompt` equivalent and
+ * `GEMINI_SYSTEM_MD` replaces the entire core system prompt (which would
+ * brick the agent — that core prompt scaffolds tool use). For v1 the
+ * adapter prepends `systemContext` directly to the positional prompt. Each
+ * turn re-injects the dynamic context so memory / digest updates take
+ * effect immediately; the trade-off is the resumed session transcript
+ * accumulates one prompt prefix per turn. Acceptable while we ship the
+ * connectivity layer — a follow-up can move systemContext into a
+ * daemon-managed `GEMINI.md` once we decide where to isolate it.
+ *
+ * ## Session continuity
+ *
+ * `gemini --session-id <uuid>` is for FRESH sessions only — it errors if
+ * the id already exists. `gemini --resume <uuid>` resolves the UUID against
+ * the project's existing session pool (gemini stores sessions per
+ * cwd-derived project hash, so the per-agent workspace already isolates
+ * them from the user's interactive sessions). We therefore:
+ *   - new turn (sessionId=null): omit both flags; capture `init.session_id`.
+ *   - continuation: pass `--resume <uuid>`. If gemini cannot resolve the id
+ *     it exits with `FATAL_INPUT_ERROR` and stderr; we surface that as
+ *     `errorText` and wipe `newSessionId` so the dispatcher discards the
+ *     stale entry.
  */
-export class GeminiAdapter implements RuntimeAdapter {
+export class GeminiAdapter extends NdjsonStreamAdapter {
   readonly id = "gemini" as const;
 
+  private readonly explicitBinary: string | undefined;
+  private resolvedBinary: string | null = null;
+
+  constructor(opts?: { binary?: string }) {
+    super();
+    this.explicitBinary = opts?.binary ?? process.env.BOTCORD_GEMINI_BIN;
+  }
+
   probe(): RuntimeProbeResult {
     return probeGemini();
   }
 
-  async run(_opts: RuntimeRunOptions): Promise<RuntimeRunResult> {
-    throw new Error("gemini adapter not implemented");
+  override async run(opts: RuntimeRunOptions) {
+    if (opts.sessionId && !isValidGeminiSessionId(opts.sessionId)) {
+      throw new Error(invalidGeminiSessionIdError(opts.sessionId));
+    }
+    return super.run(opts);
+  }
+
+  protected resolveBinary(): string {
+    if (this.explicitBinary) return this.explicitBinary;
+    if (this.resolvedBinary) return this.resolvedBinary;
+    this.resolvedBinary = resolveGeminiCommand() ?? "gemini";
+    return this.resolvedBinary;
+  }
+
+  protected buildArgs(opts: RuntimeRunOptions): string[] {
+    const extraArgs = sanitizeGeminiExtraArgs(opts.extraArgs);
+
+    const args: string[] = [
+      "-p",
+      composePrompt(opts.text, opts.systemContext),
+      "--output-format",
+      "stream-json",
+    ];
+
+    // Daemon-driven gemini turns are non-interactive. Auto-approve all tool
+    // use to avoid deadlocks; operators with stricter requirements can
+    // override via extraArgs `--approval-mode plan` etc.
+    if (
+      !hasFlag(extraArgs, "--approval-mode") &&
+      !hasFlag(extraArgs, "-y") &&
+      !hasFlag(extraArgs, "--yolo")
+    ) {
+      args.push("--yolo");
+    }
+
+    // Trust the workspace so gemini doesn't downgrade the approval mode the
+    // moment cwd isn't in `~/.gemini/trustedFolders.json`. Without this the
+    // CLI silently flips back to "default" approval — which then deadlocks
+    // on tool calls because we have no prompt relay.
+    if (!hasFlag(extraArgs, "--skip-trust")) {
+      args.push("--skip-trust");
+    }
+
+    if (opts.sessionId) {
+      if (!isValidGeminiSessionId(opts.sessionId)) {
+        throw new Error(invalidGeminiSessionIdError(opts.sessionId));
+      }
+      args.push("--resume", opts.sessionId);
+    }
+
+    if (extraArgs.length) args.push(...extraArgs);
+    return args;
+  }
+
+  protected override spawnEnv(opts: RuntimeRunOptions): NodeJS.ProcessEnv {
+    return {
+      ...super.spawnEnv(opts),
+      // Keep stream-json clean regardless of the user's terminal settings.
+      FORCE_COLOR: "0",
+      NO_COLOR: "1",
+      // Prevent gemini's launcher from re-spawning itself with --max-old-space
+      // tuning; the relaunch races with our stdio piping in tests and shaves
+      // ~200ms off every spawn in production.
+      GEMINI_CLI_NO_RELAUNCH: "1",
+    };
+  }
+
+  protected handleEvent(raw: unknown, ctx: NdjsonEventCtx): void {
+    const obj = raw as {
+      type?: string;
+      session_id?: string;
+      role?: string;
+      content?: string;
+      delta?: boolean;
+      tool_name?: string;
+      tool_id?: string;
+      status?: string;
+      severity?: string;
+      message?: string;
+      error?: { type?: string; message?: string };
+    };
+
+    const status = geminiStatusEvent(obj);
+    if (status) ctx.emitStatus(status);
+
+    ctx.emitBlock(normalizeBlock(obj, ctx.seq));
+
+    if (obj.type === "init" && typeof obj.session_id === "string") {
+      ctx.state.newSessionId = obj.session_id;
+      return;
+    }
+
+    if (obj.type === "message" && obj.role === "assistant" && typeof obj.content === "string") {
+      ctx.appendAssistantText(obj.content);
+      return;
+    }
+
+    if (obj.type === "result") {
+      if (obj.status === "error") {
+        const errMsg = obj.error?.message;
+        ctx.state.errorText =
+          typeof errMsg === "string" && errMsg ? errMsg : "gemini run failed";
+        // Drop the captured session id so the dispatcher doesn't try to
+        // resume a session that may not have been persisted to disk.
+        ctx.state.newSessionId = "";
+        ctx.state.finalText = "";
+        ctx.state.assistantTextChunks = [];
+        ctx.state.assistantTextBytes = 0;
+      }
+      return;
+    }
+
+    if (obj.type === "error" && obj.severity === "error" && typeof obj.message === "string") {
+      // Severity "error" is fatal in gemini's classification; "warning" is
+      // recoverable and shouldn't override the assistant's output.
+      ctx.state.errorText = obj.message;
+    }
+  }
+}
+
+/**
+ * Prepend systemContext to the user prompt. Empty systemContext (the common
+ * case for direct DMs) returns the prompt unchanged so we don't bloat the
+ * token count with a marker prefix that conveys nothing.
+ */
+function composePrompt(text: string, systemContext: string | undefined): string {
+  if (!systemContext || !systemContext.trim()) return text;
+  return `${systemContext.trim()}\n\n---\n\n${text}`;
+}
+
+/**
+ * Map a gemini stream-json event to a `RuntimeStatusEvent`. Only the
+ * lifecycle transitions the dispatcher can't infer from `StreamBlock.kind`
+ * land here; everything else is left to auto-synthesis.
+ */
+function geminiStatusEvent(obj: {
+  type?: string;
+  role?: string;
+  delta?: boolean;
+  status?: string;
+  tool_name?: string;
+}): RuntimeStatusEvent | undefined {
+  if (obj.type === "init") {
+    return { kind: "thinking", phase: "started", label: "Starting session" };
+  }
+  if (obj.type === "tool_use") {
+    const name = typeof obj.tool_name === "string" && obj.tool_name ? obj.tool_name : "tool";
+    return { kind: "thinking", phase: "updated", label: name };
+  }
+  if (obj.type === "message" && obj.role === "assistant") {
+    return { kind: "thinking", phase: "stopped" };
+  }
+  if (obj.type === "result") {
+    return { kind: "thinking", phase: "stopped" };
+  }
+  return undefined;
+}
+
+function normalizeBlock(obj: any, seq: number): StreamBlock {
+  let kind: StreamBlock["kind"] = "other";
+  const type: string | undefined = obj?.type;
+  if (type === "message" && obj?.role === "assistant") {
+    kind = "assistant_text";
+  } else if (type === "tool_use") {
+    kind = "tool_use";
+  } else if (type === "tool_result") {
+    kind = "tool_result";
+  } else if (type === "init" || type === "result") {
+    kind = "system";
   }
+  return { raw: obj, kind, seq };
 }