@akanjs/devkit 3.0.0-beta.14 → 3.0.0-beta.15

package/codeAgent/agent/codeSessionFork.test.ts

@@ -0,0 +1,60 @@
+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);
+    // Two live agents sharing one id would share one inbox, one presence entry and one resume target.
+    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");
+    // A name somebody typed is kept as typed, the way `/name` keeps one; only a derived name is kebabed.
+    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,72 @@
+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" },
+      // A rename appends rather than editing, so the last entry has to win.
+      { 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("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);
+    // Resuming a typo has to fail rather than open a new session that looks like one that lost its history.
+    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");
+    // Cut on a word, never mid-word: half a word reads as a typo rather than a shortening.
+    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("안녕-모듈-하나-만들어줘");
+    // A prompt that is all code says nothing about itself; a name is still better than none.
+    expect(codeAgentSessionName("```ts\nconst a = 1;\n```")).toBe("session");
+  });
+});

package/codeAgent/agent/consoleToStderr.ts

@@ -0,0 +1,18 @@
+import { Console } from "node:console";
+
+/**
+ * Sends every `console.*` call in this process to stderr, so stdout carries the RPC protocol and nothing else.
+ *
+ * The engine already installs a guard that rewrites `process.stdout.write`, which is enough on Node because
+ * `console.log` routes through it there. Bun's global `console` is native and writes to fd 1 directly, so it
+ * sails straight past that guard and corrupts the JSONL stream — measured: 203 non-JSON lines in one turn that
+ * logged while a tool ran.
+ *
+ * **This is a side-effect module and must be the first import of any RPC entry.** An assignment written beside
+ * the static imports would run *after* them: ESM hoists imports and evaluates those modules first, so anything
+ * the engine logs at module-evaluation time would already have escaped.
+ */
+globalThis.console = new Console({
+  stdout: process.stderr,
+  stderr: process.stderr,
+}) as unknown as typeof globalThis.console;

package/codeAgent/feedback/DevLogFeedback.ts

@@ -0,0 +1,97 @@
+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/;
+
+/**
+ * Feeds back what the dev server said after a turn edited code.
+ *
+ * `akan start` writes `local/apps/<app>/runtime/dev.log` with no ANSI, nothing truncated, and every process of
+ * the app in arrival order including the dev host's own build output — which reaches no other file. That is the
+ * one thing a coding agent working on an akan app has and a general one does not: lint and typecheck can both
+ * pass on code that dies the moment it runs.
+ */
+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 running app. Without this, one line from a dev server
+    // somebody else is driving reopens a turn that only read a file — and a reopened turn looks, from the
+    // transcript, exactly like an agent that will not stop.
+    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 dev server's own URL, read back from the line `akan start` prints when the app comes up.
+   *
+   * The port is allocated, not predicted — a second checkout or a stale listener shifts it — so the log is the
+   * only place that knows which one this session actually got.
+   */
+  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];
+  }
+
+  /** A dev server that is not running has no log, which is not an error — the source simply reports nothing. */
+  static #sizeOf(file: string) {
+    return existsSync(file) ? statSync(file).size : 0;
+  }
+}

package/codeAgent/feedback/PreviewChrome.ts

@@ -0,0 +1,106 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+/**
+ * Which `Bun.WebView` backend the preview probe runs on, and what an image needs to carry one.
+ *
+ * `webkit` is the macOS system framework — zero install, and it throws on every other platform — so anywhere
+ * else the probe drives Chrome. The generated akan image installs `ca-certificates` and `tzdata` and nothing
+ * else, which is why the install steps are named here instead of being reinvented per image.
+ */
+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",
+  ];
+
+  /**
+   * macOS keeps browsers in app bundles, off PATH, and Bun looks inside these before reporting none.
+   *
+   * The list has to match Bun's or the two disagree in the expensive direction: refusing to probe on a machine
+   * whose browser the launcher would have found.
+   */
+  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();
+  }
+
+  /**
+   * The `backend` value to construct a view with.
+   *
+   * Two flags are added on the Chrome path, and Bun adds neither:
+   * - Chromium refuses to run as uid 0 unless its sandbox is off, and uid 0 is the ordinary uid in a container.
+   * - Docker gives a container 64MB of `/dev/shm` by default, below what Chromium's renderer allocates, and the
+   *   crash it produces looks like a page that never loads rather than a resource limit.
+   */
+  static backendOption() {
+    if (PreviewChrome.backend === "webkit") return "webkit";
+    const argv = ["--disable-dev-shm-usage"];
+    if (process.getuid?.() === 0) argv.push("--no-sandbox");
+    return { type: "chrome" as const, argv };
+  }
+
+  /**
+   * `RUN` bodies for an image whose agent has to look at the page it just changed — an akan app's
+   * `docker.preRuns`, or a coding-agent pod.
+   *
+   * The font packages are not decoration: a container with no fonts renders every glyph as a box, so a
+   * screenshot says nothing and the "text is the same colour as its background" probe reads a blank page.
+   * `fonts-noto-cjk` is what keeps a Korean UI legible.
+   */
+  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,53 @@
+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 one attached; a screenshot is ~83KB per shot. */
+  canSeeImages?: boolean;
+}
+
+/**
+ * Looks at the page after a turn changed the UI.
+ *
+ * akan is a UI framework, so "does it run" is half the question. The default findings are **text** — page
+ * console errors, an empty body, an error overlay, horizontal overflow, a dropped colour slot — because they
+ * cost a few hundred tokens, work with any model, and name the defect rather than depicting it. A screenshot is
+ * attached only when the active model can actually read one.
+ */
+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 };
+  }
+}

package/codeAgent/feedback/PreviewView.ts

@@ -0,0 +1,107 @@
+import { PreviewChrome } from "./PreviewChrome";
+
+export interface PreviewProbeResult {
+  url: string;
+  title: string;
+  consoleErrors: string[];
+  pageErrors: string[];
+  /** Cheap structural smells that read as "the page is broken" without anyone looking at it. */
+  domFindings: string[];
+  screenshot?: string;
+}
+
+interface WebViewLike {
+  navigate(url: string): Promise<void>;
+  evaluate(expression: string): Promise<unknown>;
+  screenshot(options: { encoding: "base64" }): Promise<string>;
+  close(): void | Promise<void>;
+  readonly title: string;
+}
+
+/**
+ * Opens a page headlessly and reports what is wrong with it.
+ *
+ * `Bun.WebView` rather than a downloaded browser: on macOS the `webkit` backend is the system framework, so
+ * there is no Chromium to fetch and no executable path to track, and everywhere else it drives whatever Chrome
+ * the image carries. It is marked experimental, which is why the whole surface is behind this adapter — a Bun
+ * minor that changes it should break one file.
+ *
+ * Which backend, and what an image needs for it, is {@link PreviewChrome}.
+ */
+export class PreviewView {
+  static get available() {
+    return typeof (Bun as unknown as { WebView?: unknown }).WebView === "function" && PreviewChrome.available;
+  }
+
+  /** Why `available` is false, for a host that should say so rather than skip the check in silence. */
+  static unavailableReason() {
+    if (typeof (Bun as unknown as { WebView?: unknown }).WebView !== "function")
+      return "This Bun build has no WebView, so the page preview is off.";
+    return PreviewChrome.unavailableReason();
+  }
+
+  static async probe(url: string, { screenshot = false, width = 1280, height = 800 } = {}) {
+    const logs: string[] = [];
+    const view = PreviewView.#open({ width, height, onConsole: (line) => logs.push(line) });
+    try {
+      await view.navigate(url);
+      const result: PreviewProbeResult = {
+        url,
+        title: view.title,
+        consoleErrors: logs.filter((line) => line.startsWith("error") || line.startsWith("warn")),
+        pageErrors: PreviewView.#strings(await view.evaluate(pageErrorsExpression)),
+        domFindings: PreviewView.#strings(await view.evaluate(domFindingsExpression)),
+      };
+      if (screenshot) result.screenshot = await view.screenshot({ encoding: "base64" });
+      return result;
+    } finally {
+      await view.close();
+    }
+  }
+
+  static #open({ width, height, onConsole }: { width: number; height: number; onConsole: (line: string) => void }) {
+    const Ctor = (Bun as unknown as { WebView: new (options: unknown) => WebViewLike }).WebView;
+    return new Ctor({
+      width,
+      height,
+      dataStore: "ephemeral",
+      backend: PreviewChrome.backendOption(),
+      // The console option is a callback taking `(type, ...args)`, not an object of console methods.
+      console: (type: string, ...args: unknown[]) => onConsole(`${type} ${args.map(String).join(" ")}`),
+    });
+  }
+
+  static #strings(value: unknown) {
+    return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : [];
+  }
+}
+
+/**
+ * `evaluate` takes an expression, not a statement list — `const x = 1; x` is a `SyntaxError` — so each probe is
+ * wrapped in an IIFE. Only one may be in flight per view.
+ */
+const pageErrorsExpression = `(() => {
+  const found = [];
+  const root = document.getElementById("__next") || document.body;
+  const rendered = root ? Array.from(root.children).filter((el) => !["SCRIPT", "STYLE", "TEMPLATE", "LINK", "NOSCRIPT"].includes(el.tagName)) : [];
+  if (!rendered.length && !(root && root.innerText && root.innerText.trim())) found.push("The page body rendered empty.");
+  const overlay = document.querySelector("[data-nextjs-dialog], .error-overlay, #akan-error");
+  if (overlay) found.push("An error overlay is on the page: " + overlay.textContent.slice(0, 400));
+  return found;
+})()`;
+
+const domFindingsExpression = `(() => {
+  const found = [];
+  const all = Array.from(document.querySelectorAll("body *"));
+  const overflowing = all.filter((el) => el.scrollWidth > document.documentElement.clientWidth + 8);
+  if (overflowing.length) found.push(overflowing.length + " element(s) overflow the viewport horizontally, first: " + (overflowing[0].tagName + "." + overflowing[0].className).slice(0, 120));
+  const invisibleText = all.filter((el) => {
+    if (!el.textContent || !el.textContent.trim()) return false;
+    const style = getComputedStyle(el);
+    return style.color === style.backgroundColor && style.backgroundColor !== "rgba(0, 0, 0, 0)";
+  });
+  if (invisibleText.length) found.push(invisibleText.length + " element(s) render text in the same colour as their background.");
+  const unresolved = all.filter((el) => /(^|\\s)(bg|text|border)-(base-100|base-content|primary-content|error)(\\s|$)/.test(el.className || ""));
+  if (unresolved.length) found.push(unresolved.length + " element(s) use a dropped daisyUI colour slot that renders no CSS.");
+  return found;
+})()`;

package/codeAgent/feedback/TurnFeedback.ts

@@ -0,0 +1,113 @@
+import type { ExtensionAPI, InlineExtension } from "@earendil-works/pi-coding-agent";
+
+/** A base64 PNG, attached only when the active model can read one. */
+export interface TurnFeedbackImage {
+  data: string;
+  mimeType: string;
+}
+
+export interface TurnFeedbackFinding {
+  text: string;
+  images?: TurnFeedbackImage[];
+}
+
+export interface TurnFeedbackSource {
+  /** Budget is counted per key, so one stuck source cannot spend another's attempts. */
+  key: string;
+  /** Record whatever "before" this source compares against. Never throws — a source that cannot arm is skipped. */
+  begin(): Promise<void> | void;
+  /** What the turn caused that the agent cannot see, or `undefined` when there is nothing to say. */
+  observe(): Promise<TurnFeedbackFinding | string | undefined> | TurnFeedbackFinding | string | undefined;
+}
+
+export interface TurnFeedbackOptions {
+  /** How many times one source may reopen a turn before it gives up and lets the human see it. */
+  budget: number;
+  onNotice?: (message: string) => void;
+}
+
+/**
+ * Closes the loop between what a turn did and what the agent knows about it.
+ *
+ * The agent cannot see that the dev server died, that a generated barrel went stale, or that the page it built
+ * renders blank — so it finishes, satisfied, on a broken tree. Each source watermarks at the start of a run and
+ * reports at the end; a report is delivered as a follow-up message, which opens a new turn.
+ *
+ * **It is a follow-up, not a veto.** `agent_end` has no result type — of the engine's hooks only
+ * `before_agent_start`, `message_end`, `tool_call`, `tool_result`, `input`, `user_bash`, the `session_before_*`
+ * pair, `context` and `resources_discover` can change an outcome — so there is no way to refuse to end a turn.
+ *
+ * **The budget goes in before the feature.** A source that reports the same unfixable error every turn would
+ * otherwise loop until the context window or the wallet runs out, and the loop looks like progress from outside.
+ */
+export class TurnFeedback {
+  readonly #sources: TurnFeedbackSource[];
+  readonly #options: TurnFeedbackOptions;
+  readonly #spent = new Map<string, number>();
+
+  constructor(sources: TurnFeedbackSource[], options: TurnFeedbackOptions) {
+    this.#sources = sources;
+    this.#options = options;
+  }
+
+  extension(): InlineExtension {
+    return {
+      name: "akan-turn-feedback",
+      factory: (pi: ExtensionAPI) => {
+        pi.on("agent_start", async () => {
+          await Promise.all(this.#sources.map((source) => TurnFeedback.#quietly(() => source.begin())));
+        });
+        pi.on("agent_end", async () => {
+          const message = await this.collect();
+          if (message) pi.sendUserMessage(message, { deliverAs: "followUp" });
+        });
+      },
+    };
+  }
+
+  /** Exposed so a host can drive the same machine without an engine session behind it. */
+  async collect() {
+    const texts: string[] = [];
+    const images: TurnFeedbackImage[] = [];
+    const reopened: string[] = [];
+    for (const source of this.#sources) {
+      const finding = await TurnFeedback.#quietly(() => source.observe());
+      if (!finding) {
+        this.#spent.delete(source.key);
+        continue;
+      }
+      const spent = this.#spent.get(source.key) ?? 0;
+      if (spent >= this.#options.budget) {
+        this.#options.onNotice?.(`${source.key}: still failing after ${spent} attempts — handing back to you.`);
+        continue;
+      }
+      this.#spent.set(source.key, spent + 1);
+      reopened.push(source.key);
+      if (typeof finding === "string") texts.push(finding);
+      else {
+        texts.push(finding.text);
+        images.push(...(finding.images ?? []));
+      }
+    }
+    if (!texts.length) return undefined;
+    // Said out loud, because the turn that follows is one nobody asked for: the transcript shows more tool
+    // calls after the answer and carries nothing that names who sent the agent back to work.
+    this.#options.onNotice?.(`${reopened.join(" · ")} reopened the turn — esc stops it`);
+    const text = [
+      "The previous turn left problems you cannot see from the transcript. Fix them, then stop.",
+      ...texts,
+    ].join("\n\n");
+    return images.length
+      ? [{ type: "text" as const, text }, ...images.map((image) => ({ type: "image" as const, ...image }))]
+      : text;
+  }
+
+  /** Every source is best-effort: no dev server, no git, no preview — all of them mean "nothing to report". */
+  static async #quietly<T>(fn: () => T | Promise<T>) {
+    try {
+      return await fn();
+    } catch {
+      return undefined;
+    }
+  }
+}