@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/codeAgent/agent/codeAgentRpcListener.test.ts

@@ -0,0 +1,113 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import type { CodeAgentEvent } from "akanjs/common";
+import type { CodeAgent } from "./CodeAgent";
+import { CodeAgentRpcHost } from "./CodeAgentRpcHost";
+import { CodeAgentRpcListener } from "./CodeAgentRpcListener";
+
+const dir = mkdtempSync(path.join(tmpdir(), "akan-rpc-"));
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+class FakeAgent {
+  seq = 0;
+  frames: CodeAgentEvent[] = [];
+  disposed = false;
+  aborted = false;
+  #listener: (event: CodeAgentEvent) => void = () => {};
+  on(listener: (event: CodeAgentEvent) => void) {
+    this.#listener = listener;
+    return () => {};
+  }
+  announce() {
+    this.emit();
+  }
+  emit() {
+    const event = { type: "idle", seq: ++this.seq } as CodeAgentEvent;
+    this.frames.push(event);
+    this.#listener(event);
+  }
+  async prompt() {
+    this.emit();
+  }
+  async abort() {
+    this.aborted = true;
+  }
+  async state({ sinceSeq }: { sinceSeq?: number } = {}) {
+    return { replayFrom: 0, frames: this.frames.filter((event) => event.seq > (sinceSeq ?? Number.MAX_SAFE_INTEGER)) };
+  }
+  dispose() {
+    this.disposed = true;
+  }
+}
+
+class Client {
+  lines: unknown[] = [];
+  #buffer = "";
+  #socket: Awaited<ReturnType<typeof Bun.connect>> | null = null;
+  static async connect(unix: string) {
+    const client = new Client();
+    client.#socket = await Bun.connect({
+      unix,
+      socket: {
+        data: (_socket, data) => {
+          client.#buffer += data.toString();
+          const parts = client.#buffer.split("\n");
+          client.#buffer = parts.pop() ?? "";
+          for (const part of parts) if (part) client.lines.push(JSON.parse(part));
+        },
+      },
+    });
+    return client;
+  }
+  send(id: string, command: object) {
+    this.#socket?.write(`${JSON.stringify({ id, command })}\n`);
+  }
+  async reply(id: string) {
+    for (let idx = 0; idx < 200; idx++) {
+      const found = this.lines.find((line) => (line as { id?: string }).id === id);
+      if (found) return found as { ok: boolean; data: { frames?: CodeAgentEvent[] } };
+      await Bun.sleep(5);
+    }
+    throw new Error(`no reply ${id}`);
+  }
+  close() {
+    this.#socket?.end();
+  }
+}
+
+describe("CodeAgentRpcListener", () => {
+  test("parses unix and tcp addresses, defaulting tcp to loopback", () => {
+    expect(CodeAgentRpcListener.parse("unix:/tmp/a.sock")).toEqual({ unix: "/tmp/a.sock" });
+    expect(CodeAgentRpcListener.parse("tcp:7000")).toEqual({ hostname: "127.0.0.1", port: 7000 });
+    expect(CodeAgentRpcListener.parse("0.0.0.0:7000")).toEqual({ hostname: "0.0.0.0", port: 7000 });
+    expect(() => CodeAgentRpcListener.parse("tcp:nope")).toThrow("--rpc-listen");
+  });
+
+  test("the agent outlives a dropped client, and the next one catches up by seq", async () => {
+    const agent = new FakeAgent();
+    const unix = path.join(dir, "agent.sock");
+    const listener = new CodeAgentRpcListener(new CodeAgentRpcHost(agent as unknown as CodeAgent, null), { unix });
+    listener.listen();
+    const served = listener.serve();
+
+    const first = await Client.connect(unix);
+    first.send("1", { type: "prompt", message: "hi" });
+    expect((await first.reply("1")).ok).toBe(true);
+    first.close();
+    await Bun.sleep(20);
+    agent.emit();
+    expect(agent.aborted).toBe(false);
+
+    const second = await Client.connect(unix);
+    second.send("2", { type: "get_state", sinceSeq: 2 });
+    const state = await second.reply("2");
+    expect(state.data.frames?.map((frame) => frame.seq)).toEqual([3]);
+
+    second.send("3", { type: "shutdown" });
+    await second.reply("3");
+    await served;
+    expect(agent.disposed).toBe(true);
+  });
+});

package/codeAgent/agent/codeAgentSuspended.test.ts

@@ -0,0 +1,47 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { CodeAgentSuspended } from "./CodeAgentSuspended";
+
+const dir = mkdtempSync(path.join(tmpdir(), "akan-suspended-"));
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+const question = {
+  questionId: "qx.1",
+  prompt: "Which app?",
+  kind: "select" as const,
+  options: [{ key: "a", label: "akan" }],
+};
+const approval = {
+  approvalId: "ax.2",
+  toolCallId: "c1",
+  name: "write",
+  summary: "write a.ts",
+  policy: "writes" as const,
+};
+
+describe("CodeAgentSuspended", () => {
+  test("a restarted worker reads back what it was waiting on, and each ask is taken once", () => {
+    const file = CodeAgentSuspended.fileOf(dir, "s1");
+    const before = new CodeAgentSuspended(file);
+    before.setQuestion(question);
+    before.addApproval(approval);
+
+    const after = new CodeAgentSuspended(file);
+    expect(after.question).toEqual(question);
+    expect(after.approvals).toEqual([approval]);
+    expect(after.takeQuestion("qx.1")).toEqual(question);
+    expect(after.takeQuestion("qx.1")).toBeUndefined();
+    expect(after.takeApproval("ax.2")).toEqual(approval);
+    expect(after.takeApproval("ax.2")).toBeUndefined();
+    expect(existsSync(file ?? "")).toBe(false);
+  });
+
+  test("a memory session keeps its asks without touching disk", () => {
+    const memory = new CodeAgentSuspended(CodeAgentSuspended.fileOf(undefined, "s2"));
+    memory.setQuestion(question);
+    expect(memory.takeQuestion("other")).toBeUndefined();
+    expect(memory.takeQuestion("qx.1")).toEqual(question);
+  });
+});

package/codeAgent/agent/codeMailbox.test.ts

@@ -0,0 +1,76 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { CodeMailbox } from "./CodeMailbox";
+
+const boxes: CodeMailbox[] = [];
+const open = (dir: string, id: string, name: string, onMail: (mail: { text: string }) => void = () => undefined) => {
+  const box = new CodeMailbox(dir, id, name);
+  box.open("/repo", onMail);
+  boxes.push(box);
+  return box;
+};
+
+afterEach(() => {
+  for (const box of boxes.splice(0)) box.close();
+});
+
+describe("CodeMailbox", () => {
+  test("each session sees the others and not itself", () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "akan-mail-"));
+    const one = open(dir, "aaaa1111", "gateway-work");
+    const two = open(dir, "bbbb2222", "store-work");
+    expect(one.peers().map((peer) => peer.name)).toEqual(["store-work"]);
+    expect(two.peers().map((peer) => peer.name)).toEqual(["gateway-work"]);
+  });
+
+  test("a message lands in the other session's inbox and is delivered once", async () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "akan-mail-"));
+    const got: string[] = [];
+    const one = open(dir, "aaaa1111", "gateway-work");
+    open(dir, "bbbb2222", "store-work", (mail) => got.push(mail.text));
+    one.send("bbbb2222", "the adapter moved to srvkit");
+    await Bun.sleep(CodeMailbox.pollMs + 400);
+    expect(got).toEqual(["the adapter moved to srvkit"]);
+    await Bun.sleep(CodeMailbox.pollMs + 200);
+    expect(got).toEqual(["the adapter moved to srvkit"]);
+  });
+
+  test("a session opening on a full inbox does not replay it", async () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "akan-mail-"));
+    open(dir, "cccc3333", "seeded").close();
+    const inbox = path.join(dir, "inbox", "cccc3333.jsonl");
+    writeFileSync(inbox, `${JSON.stringify({ from: "x", fromName: "x", text: "old" })}\n`);
+    const got: string[] = [];
+    open(dir, "cccc3333", "seeded", (mail) => got.push(mail.text));
+    await Bun.sleep(CodeMailbox.pollMs + 400);
+    expect(got).toEqual([]);
+  });
+
+  test("a session that stopped beating is not offered as somewhere to send", () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "akan-mail-"));
+    const one = open(dir, "aaaa1111", "alive");
+    const stale = { id: "dddd4444", name: "crashed", cwd: "/repo", pid: 1, at: Date.now() - CodeMailbox.staleMs * 2 };
+    writeFileSync(path.join(dir, "live", "dddd4444.json"), JSON.stringify(stale));
+    expect(one.peers()).toEqual([]);
+    expect(one.find("crashed")).toBeUndefined();
+  });
+
+  test("a name or the front of an id finds one peer, and an ambiguous one finds none", () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "akan-mail-"));
+    const one = open(dir, "aaaa1111", "alive");
+    open(dir, "bbbb2222", "store-work");
+    open(dir, "bbbb3333", "store-other");
+    expect(one.find("store-work")?.id).toBe("bbbb2222");
+    expect(one.find("bbbb2")?.id).toBe("bbbb2222");
+    expect(one.find("store")).toBeUndefined();
+  });
+
+  test("a runaway exchange is stopped by the ceiling rather than by the disk", () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "akan-mail-"));
+    const one = open(dir, "aaaa1111", "alive");
+    for (let at = 0; at < CodeMailbox.sendsPerMinute; at += 1) one.send("bbbb2222", "ping");
+    expect(() => one.send("bbbb2222", "ping")).toThrow("a minute is the ceiling");
+  });
+});

package/codeAgent/agent/codeSessionFork.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { CodeSessionFork } from "./CodeSessionFork";
+import { CodeSessionIndex } from "./CodeSessionIndex";
+
+const lines = (id: string) => [
+  JSON.stringify({ type: "session", version: 3, id, timestamp: "2026-09-20T14:35:32.579Z", cwd: "/repo" }),
+  JSON.stringify({ type: "session_info", id: "aa", parentId: null, name: "read-the-guard" }),
+  JSON.stringify({ type: "message", id: "bb", parentId: "aa", message: { role: "user", content: "who guards it" } }),
+];
+
+const seed = () => {
+  const dir = mkdtempSync(path.join(tmpdir(), "akan-fork-"));
+  const id = "01a0bf3e-6563-78f4-9017-c541ca067354";
+  const file = path.join(dir, `2026-09-20T14-35-32-579Z_${id}.jsonl`);
+  writeFileSync(file, `${lines(id).join("\n")}\n`);
+  return { dir, id, file };
+};
+
+const records = (file: string) =>
+  readFileSync(file, "utf8")
+    .split("\n")
+    .filter((line) => !!line.trim())
+    .map((line) => JSON.parse(line) as { type?: string; id?: string; name?: string });
+
+describe("CodeSessionFork", () => {
+  test("the copy carries the conversation under an id of its own", () => {
+    const { dir, id, file } = seed();
+    const forked = CodeSessionFork.fork(dir, id);
+    expect(forked.id).not.toBe(id);
+    expect(forked.file).not.toBe(file);
+    const copied = records(forked.file);
+    expect(copied.find((record) => record.type === "session")?.id).toBe(forked.id);
+    expect(copied.filter((record) => record.type === "message").length).toBe(1);
+    expect(CodeSessionIndex.fileOf(dir, forked.id)).toBe(forked.file);
+    expect(CodeSessionIndex.fileOf(dir, id)).toBe(file);
+  });
+
+  test("the original is left exactly as it was", () => {
+    const { dir, id, file } = seed();
+    const before = readFileSync(file, "utf8");
+    CodeSessionFork.fork(dir, id);
+    expect(readFileSync(file, "utf8")).toBe(before);
+  });
+
+  test("the copy says it is one, and takes a name when given one", () => {
+    const { dir, id } = seed();
+    expect(records(CodeSessionFork.fork(dir, id).file).at(-1)?.name).toBe("read-the-guard-fork");
+    expect(records(CodeSessionFork.fork(dir, id, "try the other guard").file).at(-1)?.name).toBe("try the other guard");
+  });
+
+  test("an id nothing on disk answers to is refused rather than opening a new session", () => {
+    const { dir } = seed();
+    expect(() => CodeSessionFork.fork(dir, "nope")).toThrow("No stored session nope");
+  });
+});

package/codeAgent/agent/codeSessionIndex.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { codeAgentSessionName } from "akanjs/common";
+import { CodeSessionIndex } from "./CodeSessionIndex";
+
+const write = (dir: string, id: string, lines: unknown[]) => {
+  const file = path.join(dir, `2026-09-20T10-00-00-000Z_${id}.jsonl`);
+  writeFileSync(file, `${lines.map((line) => JSON.stringify(line)).join("\n")}\n`);
+  return file;
+};
+
+const session = (id: string) => ({ type: "session", version: 3, id, cwd: "/repo" });
+const user = (text: string) => ({ type: "message", message: { role: "user", content: [{ type: "text", text }] } });
+const assistant = (text: string) => ({
+  type: "message",
+  message: { role: "assistant", content: [{ type: "text", text }] },
+});
+
+describe("CodeSessionIndex", () => {
+  test("reads the name, the opening ask and how many turns a session holds", () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "akan-sessions-"));
+    write(dir, "s1", [
+      session("s1"),
+      user("add a comment module"),
+      assistant("done"),
+      user("now wire it up"),
+      { type: "session_info", name: "add-a-comment-module" },
+      { type: "session_info", name: "comment-module" },
+    ]);
+    const [entry] = CodeSessionIndex.list(dir);
+    expect(entry?.id).toBe("s1");
+    expect(entry?.name).toBe("comment-module");
+    expect(entry?.opening).toBe("add a comment module");
+    expect(entry?.turns).toBe(2);
+  });
+
+  test("a file that is not a session is skipped rather than listed as a blank one", () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "akan-sessions-"));
+    writeFileSync(path.join(dir, "notes.txt"), "not a session");
+    write(dir, "s2", [{ type: "model_change", provider: "deepseek" }, user("hi")]);
+    write(dir, "s3", [session("s3"), user("hi")]);
+    expect(CodeSessionIndex.list(dir).map((entry) => entry.id)).toEqual(["s3"]);
+  });
+
+  test("a session past the read limit is still listed, from its opening lines", () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "akan-sessions-"));
+    const filler = assistant("x".repeat(64 * 1024));
+    write(dir, "big", [session("big"), user("port the dashboard"), ...Array.from({ length: 10 }, () => filler)]);
+    const [entry] = CodeSessionIndex.list(dir);
+    expect(entry?.id).toBe("big");
+    expect(entry?.opening).toBe("port the dashboard");
+  });
+
+  test("an id resolves to its file, and an unknown one to nothing", () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "akan-sessions-"));
+    const file = write(dir, "s4", [session("s4"), user("hi")]);
+    expect(CodeSessionIndex.fileOf(dir, "s4")).toBe(file);
+    expect(CodeSessionIndex.fileOf(dir, "s5")).toBeUndefined();
+  });
+
+  test("a missing directory lists nothing instead of throwing", () => {
+    expect(CodeSessionIndex.list(path.join(tmpdir(), "akan-sessions-missing"))).toEqual([]);
+  });
+});
+
+describe("codeAgentSessionName", () => {
+  test("names a session after what it was asked, in one glanceable line", () => {
+    expect(codeAgentSessionName("Add a comment module to apps/minimal")).toBe("add-a-comment-module-to-apps-minimal");
+    expect(codeAgentSessionName("Add a comment module to apps/minimal and wire up its dictionary")).toBe(
+      "add-a-comment-module-to-apps-minimal-and",
+    );
+    expect(codeAgentSessionName("안녕, 모듈 하나 만들어줘")).toBe("안녕-모듈-하나-만들어줘");
+    expect(codeAgentSessionName("```ts\nconst a = 1;\n```")).toBe("session");
+  });
+});

package/codeAgent/agent/consoleToStderr.ts

@@ -0,0 +1,8 @@
+import { Console } from "node:console";
+
+// Bun's native `console` writes to fd 1 directly, past the engine's stdout guard, corrupting the RPC stream.
+// Must be the first import of an RPC entry: ESM evaluates imports first, so an inline assignment runs too late.
+globalThis.console = new Console({
+  stdout: process.stderr,
+  stderr: process.stderr,
+}) as unknown as typeof globalThis.console;

package/codeAgent/agent/jsonLines.ts

@@ -0,0 +1,29 @@
+import { closeSync, openSync, readFileSync, readSync, statSync } from "node:fs";
+
+const readHead = (file: string, maxBytes: number) => {
+  const fd = openSync(file, "r");
+  try {
+    const head = Buffer.alloc(maxBytes);
+    return head.subarray(0, readSync(fd, head, 0, maxBytes, 0)).toString("utf8");
+  } finally {
+    closeSync(fd);
+  }
+};
+
+export const readJsonLines = (file: string, maxBytes?: number) => {
+  try {
+    const text =
+      maxBytes !== undefined && statSync(file).size > maxBytes ? readHead(file, maxBytes) : readFileSync(file, "utf8");
+    return text.split("\n").filter((line) => !!line.trim());
+  } catch {
+    return [];
+  }
+};
+
+export const parseJsonLine = <T>(line: string) => {
+  try {
+    return JSON.parse(line) as T;
+  } catch {
+    return undefined;
+  }
+};

package/codeAgent/agent/stringArg.ts

@@ -0,0 +1,5 @@
+export const stringArg = (args: unknown, key: "path" | "command") => {
+  if (!args || typeof args !== "object") return undefined;
+  const value = (args as Record<string, unknown>)[key];
+  return typeof value === "string" && value ? value : undefined;
+};

package/codeAgent/feedback/DevLogFeedback.ts

@@ -0,0 +1,82 @@
+import { existsSync, statSync } from "node:fs";
+import path from "node:path";
+import { AkanEditScope } from "../tools/AkanEditScope";
+import type { TurnFeedbackSource } from "./TurnFeedback";
+
+export interface DevLogFeedbackOptions {
+  workspaceRoot: string;
+  cwd: string;
+  apps: string[];
+  /** Hot reload finishes after the turn does, so the read waits for it. */
+  graceMs?: number;
+  maxLines?: number;
+}
+
+const errorPattern = /\bERROR\b|\bFATAL\b|\[stderr\]|error:|Error:|✖|Unhandled|Cannot find|is not a function/;
+const noisePattern = /DEBUG|\bWARN\b|MCP catalogue|rate limit/;
+
+// dev.log is the only file carrying the dev host's own build output; lint and typecheck pass on code that dies at run.
+export class DevLogFeedback implements TurnFeedbackSource {
+  readonly key = "dev-server";
+  readonly #options: Required<DevLogFeedbackOptions>;
+  readonly #marks = new Map<string, number>();
+  #baseline: ReadonlySet<string> = new Set();
+
+  constructor(options: DevLogFeedbackOptions) {
+    this.#options = { graceMs: 1_500, maxLines: 30, ...options };
+  }
+
+  async begin() {
+    for (const app of this.#options.apps) this.#marks.set(app, DevLogFeedback.#sizeOf(this.#pathOf(app)));
+    this.#baseline = await AkanEditScope.baseline(this.#options.cwd);
+  }
+
+  async observe() {
+    const running = this.#options.apps.filter((app) => existsSync(this.#pathOf(app)));
+    if (!running.length) return undefined;
+    // A turn that wrote nothing cannot have broken the app; without this gate another person's dev server reopens it.
+    if (!(await AkanEditScope.since(this.#options.cwd, this.#baseline)).paths.length) return undefined;
+    await Bun.sleep(this.#options.graceMs);
+    const reports: string[] = [];
+    for (const app of running) {
+      const lines = await this.#linesSince(app);
+      if (lines.length) reports.push(`**${app}** dev server:\n\`\`\`\n${lines.join("\n")}\n\`\`\``);
+    }
+    if (!reports.length) return undefined;
+    return [
+      "The dev server logged errors after your edits:",
+      ...reports,
+      `Full log: ${running.map((app) => path.relative(this.#options.workspaceRoot, this.#pathOf(app))).join(", ")}`,
+    ].join("\n\n");
+  }
+
+  async #linesSince(app: string) {
+    const file = this.#pathOf(app);
+    const from = this.#marks.get(app) ?? 0;
+    const size = DevLogFeedback.#sizeOf(file);
+    // A smaller file means `akan start` rotated to a new session mid-turn; its own boot output is not a finding.
+    if (size <= from) return [];
+    const text = await Bun.file(file).slice(from, size).text();
+    this.#marks.set(app, size);
+    return text
+      .split("\n")
+      .filter((line) => errorPattern.test(line) && !noisePattern.test(line))
+      .slice(-this.#options.maxLines);
+  }
+
+  #pathOf(app: string) {
+    return path.join(this.#options.workspaceRoot, "local", "apps", app, "runtime", "dev.log");
+  }
+
+  /** The port is allocated, not predicted, so the log's `ready` line is the only record of this session's URL. */
+  static async previewUrl(workspaceRoot: string, app: string) {
+    const file = path.join(workspaceRoot, "local", "apps", app, "runtime", "dev.log");
+    if (!existsSync(file)) return undefined;
+    const matches = [...(await Bun.file(file).text()).matchAll(/ready \(pid=\d+\) — (https?:\/\/\S+)/g)];
+    return matches.at(-1)?.[1];
+  }
+
+  static #sizeOf(file: string) {
+    return existsSync(file) ? statSync(file).size : 0;
+  }
+}

package/codeAgent/feedback/PreviewChrome.ts

@@ -0,0 +1,82 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+// Bun.WebView's `webkit` backend is the macOS system framework and throws on every other platform.
+export class PreviewChrome {
+  /** Read by `Bun.WebView` itself; listed so the availability check agrees with what the launcher will do. */
+  static readonly pathEnvKey = "BUN_CHROME_PATH";
+
+  /** Set this to drive Chrome on macOS too, e.g. to reproduce what a pod sees. */
+  static readonly backendEnvKey = "AKAN_CODE_WEBVIEW_BACKEND";
+
+  /** The executables Bun looks for on PATH before giving up. */
+  static readonly executables = [
+    "chromium",
+    "chromium-browser",
+    "google-chrome-stable",
+    "google-chrome",
+    "brave-browser",
+    "microsoft-edge",
+    "chrome",
+  ];
+
+  /** Must match the macOS app bundles Bun searches, or the probe refuses a browser the launcher would find. */
+  static readonly appBundles = [
+    "Google Chrome.app/Contents/MacOS/Google Chrome",
+    "Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
+    "Chromium.app/Contents/MacOS/Chromium",
+    "Brave Browser.app/Contents/MacOS/Brave Browser",
+    "Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+  ];
+
+  static get backend(): "webkit" | "chrome" {
+    const declared = process.env[PreviewChrome.backendEnvKey];
+    if (declared === "webkit" || declared === "chrome") return declared;
+    return process.platform === "darwin" ? "webkit" : "chrome";
+  }
+
+  static executable() {
+    const declared = process.env[PreviewChrome.pathEnvKey];
+    if (declared) return declared;
+    for (const name of PreviewChrome.executables) {
+      const found = Bun.which(name);
+      if (found) return found;
+    }
+    if (process.platform !== "darwin") return undefined;
+    for (const root of ["/Applications", path.join(homedir(), "Applications")])
+      for (const bundle of PreviewChrome.appBundles) {
+        const candidate = path.join(root, bundle);
+        if (existsSync(candidate)) return candidate;
+      }
+    return undefined;
+  }
+
+  static get available() {
+    return PreviewChrome.backend === "webkit" ? process.platform === "darwin" : !!PreviewChrome.executable();
+  }
+
+  static backendOption() {
+    if (PreviewChrome.backend === "webkit") return "webkit";
+    // Docker's default 64MB /dev/shm is below what Chromium's renderer allocates; the crash looks like a hung load.
+    const argv = ["--disable-dev-shm-usage"];
+    // Chromium refuses uid 0 with its sandbox on, and uid 0 is the ordinary uid in a container.
+    if (process.getuid?.() === 0) argv.push("--no-sandbox");
+    return { type: "chrome" as const, argv };
+  }
+
+  /** The generated image has no browser or fonts; a fontless container renders every glyph as a box. */
+  static readonly dockerRuns = [
+    "apt-get update && apt-get install -y --no-install-recommends chromium fonts-liberation fonts-noto-color-emoji fonts-noto-cjk && rm -rf /var/lib/apt/lists/*",
+  ];
+
+  static unavailableReason() {
+    if (PreviewChrome.available) return undefined;
+    if (PreviewChrome.backend === "webkit")
+      return `The webkit WebView backend exists only on macOS. Set ${PreviewChrome.backendEnvKey}=chrome and install a browser.`;
+    return [
+      "The page preview needs a browser and this machine has none on PATH.",
+      `Install one (${PreviewChrome.dockerRuns[0]}) or point ${PreviewChrome.pathEnvKey} at an existing Chrome.`,
+    ].join(" ");
+  }
+}

package/codeAgent/feedback/PreviewFeedback.ts

@@ -0,0 +1,46 @@
+import { AkanEditScope } from "../tools/AkanEditScope";
+import { PreviewView } from "./PreviewView";
+import type { TurnFeedbackFinding, TurnFeedbackSource } from "./TurnFeedback";
+
+export interface PreviewFeedbackOptions {
+  cwd: string;
+  /** Origin of a running dev server. Without one the source is inert. */
+  previewUrl?: string;
+  /** Every akan route sits under `/:lang`, so a bare path renders nothing. */
+  routes?: string[];
+  /** Only a model whose input includes images gets a screenshot attached. */
+  canSeeImages?: boolean;
+}
+
+// Findings are text, not screenshots: a few hundred tokens, readable by any model, and naming the defect.
+export class PreviewFeedback implements TurnFeedbackSource {
+  readonly key = "preview";
+  readonly #options: PreviewFeedbackOptions;
+  #baseline: ReadonlySet<string> = new Set();
+
+  constructor(options: PreviewFeedbackOptions) {
+    this.#options = options;
+  }
+
+  async begin() {
+    this.#baseline = await AkanEditScope.baseline(this.#options.cwd);
+  }
+
+  async observe(): Promise<TurnFeedbackFinding | undefined> {
+    if (!this.#options.previewUrl || !PreviewView.available) return undefined;
+    const scope = await AkanEditScope.since(this.#options.cwd, this.#baseline);
+    if (!scope.touchesTsx) return undefined;
+    const findings: string[] = [];
+    const images: { data: string; mimeType: string }[] = [];
+    for (const route of this.#options.routes ?? ["/en/"]) {
+      const url = new URL(route, this.#options.previewUrl).toString();
+      const probe = await PreviewView.probe(url, { screenshot: !!this.#options.canSeeImages });
+      const problems = [...probe.pageErrors, ...probe.consoleErrors, ...probe.domFindings];
+      if (!problems.length) continue;
+      findings.push(`**${url}**\n${problems.map((line) => `- ${line}`).join("\n")}`);
+      if (probe.screenshot) images.push({ data: probe.screenshot, mimeType: "image/png" });
+    }
+    if (!findings.length) return undefined;
+    return { text: ["The rendered page has problems after your UI edits:", ...findings].join("\n\n"), images };
+  }
+}