@maxiaochao/pi-toolkit 0.8.2 → 0.9.1

package/extensions/codex-edit/index.ts

@@ -0,0 +1,218 @@
+import { access, lstat, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { dirname } from "node:path";
+import { Text } from "@earendil-works/pi-tui";
+import {
+  generateDiffString,
+  generateUnifiedPatch,
+  withFileMutationQueue,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import {
+  APPLY_PATCH_LARK_GRAMMAR,
+  applyUpdate,
+  parsePatch,
+  resolveWorkspacePath,
+} from "./parser.ts";
+import { modelIsAllowed } from "./model-routing.ts";
+
+const editorToolNames = new Set(["edit", "apply_patch"]);
+const settingsUrl = new URL("./config.json", import.meta.url);
+
+async function loadSettings() {
+  try {
+    return JSON.parse(await readFile(settingsUrl, "utf8"));
+  } catch {
+    return { enabled: true, models: [] };
+  }
+}
+
+function syncEditorTools(pi, ctx, model, settings) {
+  const active = pi.getActiveTools();
+  if (!active.some((name) => editorToolNames.has(name))) return;
+  const selected = modelIsAllowed(model, settings) ? "apply_patch" : "edit";
+  const next = active.filter((name) => !editorToolNames.has(name));
+  next.push(selected);
+  pi.setActiveTools([...new Set(next)]);
+  if (ctx.hasUI) ctx.ui.setStatus("codex-edit", `editor: ${selected}`);
+}
+
+async function fileInfo(path, label) {
+  let info;
+  try {
+    info = await lstat(path);
+  } catch (error) {
+    const code = error && typeof error === "object" && "code" in error ? error.code : "unknown";
+    throw new Error(`${label} is unavailable (${code})`);
+  }
+  if (info.isSymbolicLink()) throw new Error(`${label} must not be a symbolic link`);
+  if (!info.isFile()) throw new Error(`${label} must be a regular file`);
+  await access(path, constants.R_OK | constants.W_OK);
+  return info;
+}
+
+async function ensureParentIsSafe(path, workspace) {
+  let current = dirname(path);
+  while (current !== workspace && current.startsWith(`${workspace}/`)) {
+    try {
+      const info = await lstat(current);
+      if (info.isSymbolicLink()) throw new Error(`Parent path is a symbolic link: ${current}`);
+      if (!info.isDirectory()) throw new Error(`Parent path is not a directory: ${current}`);
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+        current = dirname(current);
+        continue;
+      }
+      throw error;
+    }
+    current = dirname(current);
+  }
+  if (current !== workspace) throw new Error(`Parent path escapes workspace: ${path}`);
+}
+
+async function pathExists(path) {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function withPathQueues(paths, fn) {
+  const ordered = [...new Set(paths)].sort();
+  async function acquire(index) {
+    if (index === ordered.length) return fn();
+    return withFileMutationQueue(ordered[index], () => acquire(index + 1));
+  }
+  return acquire(0);
+}
+
+function buildFileDetail(path, action, before, after, moveTo) {
+  const diff = generateDiffString(before, after);
+  const patch = generateUnifiedPatch(path, before, after);
+  return { path, action, moveTo, diff: diff.diff, patch, firstChangedLine: diff.firstChangedLine };
+}
+
+export default async function (pi) {
+  const settings = await loadSettings();
+
+  pi.registerTool({
+    name: "apply_patch",
+    label: "apply_patch",
+    description: "Apply a Codex-style patch. This is a FREEFORM tool, so provide raw patch text and never wrap it in JSON or a Markdown fence.",
+    promptSnippet: "Apply Codex-style freeform patches to add, delete, update, or move files",
+    promptGuidelines: [
+      "Use apply_patch for file changes and provide raw text between *** Begin Patch and *** End Patch.",
+      "Do not wrap apply_patch input in JSON or a Markdown code fence.",
+    ],
+    parameters: Type.Object({
+      patch: Type.String({ description: "Raw Codex-style patch text" }),
+    }),
+    constrainedSampling: {
+      type: "grammar",
+      variants: { openai_lark: APPLY_PATCH_LARK_GRAMMAR },
+    },
+    executionMode: "sequential",
+    async execute(_toolCallId, { patch }, signal, _onUpdate, ctx) {
+      const operations = parsePatch(patch);
+      const resolved = [];
+      const targets = [];
+      for (const operation of operations) {
+        const source = resolveWorkspacePath(ctx.cwd, operation.path);
+        const destination = operation.moveTo ? resolveWorkspacePath(ctx.cwd, operation.moveTo) : undefined;
+        targets.push(source, ...(destination ? [destination] : []));
+        resolved.push({ ...operation, source, destination });
+      }
+      if (new Set(targets).size !== targets.length) throw new Error("Multiple patch operations target the same resolved path");
+
+      const committed = [];
+      return withPathQueues(targets, async () => {
+        const prepared = [];
+        for (const operation of resolved) {
+          if (signal?.aborted) throw new Error("Operation aborted");
+          await ensureParentIsSafe(operation.source, ctx.cwd);
+          if (operation.destination) await ensureParentIsSafe(operation.destination, ctx.cwd);
+          if (operation.action === "add") {
+            if (await pathExists(operation.source)) throw new Error(`Cannot add existing file ${operation.path}`);
+            prepared.push({ ...operation, before: "", after: operation.content });
+          } else {
+            await fileInfo(operation.source, `Source file ${operation.path}`);
+            const before = await readFile(operation.source, "utf8");
+            const after = operation.action === "delete" ? "" : applyUpdate(before, operation.chunks, operation.path);
+            if (operation.destination && await pathExists(operation.destination)) {
+              throw new Error(`Cannot move over existing file ${operation.moveTo}`);
+            }
+            prepared.push({ ...operation, before, after });
+          }
+        }
+
+        for (const operation of prepared) {
+          if (signal?.aborted) throw new Error("Operation aborted");
+          if (operation.action === "add") {
+            await mkdir(dirname(operation.source), { recursive: true });
+            await writeFile(operation.source, operation.after, "utf8");
+          } else if (operation.action === "delete") {
+            await unlink(operation.source);
+          } else if (operation.destination) {
+            await mkdir(dirname(operation.destination), { recursive: true });
+            await writeFile(operation.destination, operation.after, "utf8");
+            await unlink(operation.source);
+          } else {
+            await writeFile(operation.source, operation.after, "utf8");
+          }
+          committed.push(operation);
+        }
+
+        const files = committed.map((operation) => buildFileDetail(
+          operation.path,
+          operation.destination ? "move" : operation.action,
+          operation.before,
+          operation.after,
+          operation.moveTo,
+        ));
+        return {
+          content: [{ type: "text", text: `Applied ${committed.length} file operation(s): ${committed.map((operation) => operation.path).join(", ")}` }],
+          details: {
+            files,
+            committedPaths: committed.map((operation) => operation.path),
+            exact: true,
+            combinedPatch: files.map((file) => file.patch).join("\n"),
+          },
+        };
+      }).catch((error) => {
+        const prefix = committed.length ? ` Committed before failure: ${committed.map((operation) => operation.path).join(", ")}.` : "";
+        throw new Error(`${error instanceof Error ? error.message : String(error)}${prefix}`);
+      });
+    },
+    renderCall(args, theme, context) {
+      const component = context.lastComponent || new Text("", 0, 0);
+      const patch = typeof args?.patch === "string" ? args.patch : "";
+      const files = [...patch.matchAll(/\*\*\* (?:Add|Delete|Update) File: ([^\n]+)/g)].map((match) => match[1]);
+      component.setText(theme.fg("toolTitle", "apply_patch") + theme.fg("muted", files.length ? ` ${files.join(", ")}` : " patch"));
+      return component;
+    },
+    renderResult(result, options, theme, context) {
+      const details = result?.details;
+      const component = context.lastComponent || new Text("", 0, 0);
+      if (context.isError) {
+        component.setText(theme.fg("error", result?.content?.map((item) => item.text || "").join("\n") || "apply_patch failed"));
+        return component;
+      }
+      const files = details?.files || [];
+      let text = theme.fg("success", `Applied ${files.length} file operation(s)`);
+      if (options.expanded) {
+        for (const file of files) {
+          text += `\n${theme.fg("toolTitle", file.action)} ${file.path}`;
+          if (file.diff) text += `\n${theme.fg("dim", file.diff)}`;
+        }
+      }
+      component.setText(text);
+      return component;
+    },
+  });
+
+  pi.on("session_start", (_event, ctx) => syncEditorTools(pi, ctx, ctx.model, settings));
+  pi.on("model_select", (event, ctx) => syncEditorTools(pi, ctx, event.model, settings));
+}

package/extensions/codex-edit/model-routing.ts

@@ -0,0 +1,12 @@
+export function globMatches(value, pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replaceAll("*", ".*");
+  return new RegExp(`^${escaped}$`).test(value);
+}
+
+export function modelIsAllowed(model, settings) {
+  if (!settings.enabled || !model) return false;
+  if (model.api !== "openai-responses" && model.api !== "openai-codex-responses") return false;
+  return (settings.models || []).some((pattern) =>
+    typeof pattern === "string" && globMatches(model.id, pattern),
+  );
+}

package/extensions/codex-edit/parser.ts

@@ -0,0 +1,154 @@
+import { relative, resolve, sep } from "node:path";
+
+export const APPLY_PATCH_LARK_GRAMMAR = `start: begin_patch hunk+ end_patch
+begin_patch: "*** Begin Patch" LF
+end_patch: "*** End Patch" LF?
+hunk: add_hunk | delete_hunk | update_hunk
+add_hunk: "*** Add File: " filename LF add_line+
+delete_hunk: "*** Delete File: " filename LF
+update_hunk: "*** Update File: " filename LF change_move? change?
+filename: /(.+)/
+add_line: "+" /(.*)/ LF -> line
+change_move: "*** Move to: " filename LF
+change: (change_context | change_line)+ eof_line?
+change_context: ("@@" | "@@ " /(.+)/) LF
+change_line: ("+" | "-" | " ") /(.*)/ LF
+eof_line: "*** End of File" LF
+%import common.LF`;
+
+export function parsePatch(patch) {
+  const lines = patch.replace(/\r\n/g, "\n").replace(/\r/g, "\n").trim().split("\n");
+  if (lines[0]?.trim() !== "*** Begin Patch") throw new Error("The first line of the patch must be '*** Begin Patch'");
+  if (lines.at(-1)?.trim() !== "*** End Patch") throw new Error("The last line of the patch must be '*** End Patch'");
+  const operations = [];
+  let index = 1;
+  while (index < lines.length - 1) {
+    const line = lines[index];
+    if (line.startsWith("*** Add File: ")) {
+      const path = line.slice("*** Add File: ".length);
+      index += 1;
+      const content = [];
+      while (index < lines.length - 1 && !lines[index].startsWith("*** ")) {
+        if (!lines[index].startsWith("+")) throw new Error(`Invalid add line ${index + 1}`);
+        content.push(lines[index].slice(1));
+        index += 1;
+      }
+      if (content.length === 0) throw new Error(`Add file hunk for path '${path}' is empty`);
+      operations.push({ action: "add", path, content: `${content.join("\n")}\n` });
+      continue;
+    }
+    if (line.startsWith("*** Delete File: ")) {
+      const path = line.slice("*** Delete File: ".length);
+      if (!path) throw new Error(`Delete file hunk on line ${index + 1} has an empty path`);
+      operations.push({ action: "delete", path });
+      index += 1;
+      continue;
+    }
+    if (line.startsWith("*** Update File: ")) {
+      const path = line.slice("*** Update File: ".length);
+      index += 1;
+      let moveTo;
+      if (lines[index]?.startsWith("*** Move to: ")) {
+        moveTo = lines[index].slice("*** Move to: ".length);
+        index += 1;
+      }
+      const chunks = [];
+      while (index < lines.length - 1 && !lines[index].startsWith("*** ")) {
+        let context;
+        if (lines[index] === "@@" || lines[index].startsWith("@@ ")) {
+          context = lines[index].slice(2).trim() || undefined;
+          index += 1;
+        }
+        const oldLines = [];
+        const newLines = [];
+        const contextLineIndices = [];
+        while (index < lines.length - 1 && !lines[index].startsWith("*** ") && !lines[index].startsWith("@@")) {
+          const change = lines[index];
+          const marker = change[0];
+          if (!["+", "-", " "].includes(marker)) throw new Error(`Invalid update line ${index + 1}`);
+          const text = change.slice(1);
+          if (marker === "+") newLines.push(text);
+          else if (marker === "-") oldLines.push(text);
+          else {
+            contextLineIndices.push([oldLines.length, newLines.length]);
+            oldLines.push(text);
+            newLines.push(text);
+          }
+          index += 1;
+        }
+        const endOfFile = lines[index] === "*** End of File";
+        if (endOfFile) index += 1;
+        if (oldLines.length === 0 && newLines.length === 0) throw new Error(`Empty update chunk on line ${index + 1}`);
+        chunks.push({ context, oldLines, newLines, contextLineIndices, endOfFile });
+      }
+      if (chunks.length === 0) throw new Error(`Update file hunk for path '${path}' is empty`);
+      operations.push({ action: "update", path, moveTo, chunks });
+      continue;
+    }
+    throw new Error(`Invalid hunk header on line ${index + 1}: ${line}`);
+  }
+  if (operations.length === 0) throw new Error("Patch contains no file operations");
+  const targets = operations.flatMap((operation) => [operation.path, operation.moveTo].filter(Boolean));
+  if (new Set(targets).size !== targets.length) throw new Error("Multiple operations target the same path");
+  return operations;
+}
+
+function normalizeLineEndings(text) {
+  return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+
+function findCandidates(lines, pattern, start, eof, compare) {
+  const candidates = [];
+  for (let index = start; index + pattern.length <= lines.length; index += 1) {
+    if (pattern.every((line, offset) => compare(lines[index + offset], line))) candidates.push(index);
+  }
+  candidates.sort((left, right) => eof ? right - left : left - right);
+  return candidates;
+}
+
+function locate(lines, pattern, start, eof, label) {
+  if (pattern.length === 0) return Math.min(start, lines.length);
+  const comparisons = [
+    (left, right) => left === right,
+    (left, right) => left.trimEnd() === right.trimEnd(),
+    (left, right) => left.trim() === right.trim(),
+  ];
+  for (const compare of comparisons) {
+    const candidates = findCandidates(lines, pattern, start, eof, compare);
+    if (candidates.length === 1) return candidates[0];
+    if (candidates.length > 1) throw new Error(`Ambiguous ${label || "patch"} match: ${candidates.length} regions found`);
+  }
+  throw new Error(`Failed to find expected lines${label ? ` in ${label}` : ""}: ${pattern.join("\\n")}`);
+}
+
+export function applyUpdate(content, chunks, path) {
+  const bom = content.startsWith("\ufeff") ? "\ufeff" : "";
+  const withoutBom = bom ? content.slice(1) : content;
+  const ending = withoutBom.includes("\r\n") ? "\r\n" : "\n";
+  const normalized = normalizeLineEndings(withoutBom);
+  const hadFinalNewline = normalized.endsWith("\n");
+  const lines = normalized === "" ? [] : normalized.split("\n");
+  if (hadFinalNewline) lines.pop();
+  const replacements = [];
+  let cursor = 0;
+  for (const chunk of chunks) {
+    if (chunk.context !== undefined) cursor = locate(lines, [chunk.context], cursor, false, path) + 1;
+    const start = locate(lines, chunk.oldLines, cursor, chunk.endOfFile, path);
+    replacements.push({ start, length: chunk.oldLines.length, next: chunk.newLines });
+    cursor = start + chunk.oldLines.length;
+  }
+  const output = [...lines];
+  for (const replacement of [...replacements].reverse()) output.splice(replacement.start, replacement.length, ...replacement.next);
+  let next = output.join("\n");
+  if (hadFinalNewline || next.length > 0) next += "\n";
+  if (ending === "\r\n") next = next.replace(/\n/g, "\r\n");
+  return bom + next;
+}
+
+export function resolveWorkspacePath(cwd, rawPath) {
+  if (!rawPath || rawPath.includes("\0")) throw new Error(`Unsafe patch path: ${rawPath}`);
+  const absolute = resolve(cwd, rawPath);
+  const rel = relative(cwd, absolute);
+  if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`)) throw new Error(`Patch path escapes workspace: ${rawPath}`);
+  return absolute;
+}

package/extensions/codex-edit/summary.md

@@ -0,0 +1,56 @@
+# GPT-5.6 Edit Benchmark Final Report
+
+Generated: 2026-09-04
+
+## Isolation
+
+All Pi runs used no-context-files, a temporary PI_CODING_AGENT_DIR, a dedicated session directory, fresh temporary workspaces, and no ambient extensions. The global /home/maxiaochao/.pi/agent/AGENTS.md was not loaded. The fair comparison gave both arms read, bash, and write; only the editor tool differed.
+
+## Main comparison
+
+| Metric | A current edit | C production apply_patch | Difference |
+|---|---:|---:|---:|
+| Fixed fixtures | 20 | 20 | same |
+| Final exact correctness | 18/20 (90%) | 18/20 (90%) | 0 points |
+| First editor success | 85% | 95% | +10 points |
+| Median editor calls | 1 | 1 | same |
+| Median recovery editor calls | 0 | 0 | same |
+| Median agent turns | 4 | 4 | same |
+| Median input+output tokens | 9732 | 9978 | +2.5% |
+| Median all tokens including cache | 26722 | 26503 | -0.8% |
+| Median duration | 17.75s | 16.95s | -4.5% |
+| Protocol failures | 1 | 0 | improved |
+| Context files loaded | 0 | 0 | valid |
+
+A/B prompt exploration with the restricted read+edit tool set produced 75% final correctness for both current and neutral prompt arms. That result is not used as the main decision because it excluded the real Pi write and bash tools. It is useful only as evidence that the current edit contract cannot express add/delete/move operations by itself.
+
+## What apply_patch improved
+
+- GPT-5.6 emitted valid first-pass custom-tool calls in 19 of 20 fair cases; the remaining case used another available tool instead of apply_patch.
+- The production route eliminated the observed editor protocol failure in the fair set.
+- The Codex protocol naturally handles add, delete, update, and move in one patch, but the fair baseline could often complete those tasks through write/bash, so final correctness did not improve.
+- Custom Lark tool encoding was verified through persisted apply_patch calls with ctc_ identifiers.
+
+## What it did not improve
+
+- Exact final correctness remained 90% for both arms.
+- Median editor calls and agent turns were unchanged.
+- Input/output tokens were slightly higher; cache-inclusive token totals were effectively unchanged.
+- Median duration improved only 4.5%, below the 15% production threshold.
+- Codex CLI could not serve as a reference arm because the proxy returned HTTP 401 even when retried with the Pi-configured key.
+
+## Dynamic routing
+
+The production extension route probe passed:
+
+- GPT-5.6 Sol: active tools included read and apply_patch, with grammar capability true.
+- DeepSeek V4 Flash: active tools included read and edit, with grammar capability false.
+- The unrelated active tools were preserved and no extension errors occurred after fixing the settings closure bug.
+
+The probe conditions above reflect v0.1.5, when the route still required grammar capability. Since v0.1.6 the route is `model.api` plus the model-ID allowlist only; a provider without grammar tools falls back to a normal function tool.
+
+## Decision
+
+No-go for universal enablement in the original benchmark environment. The evidence did not justify routing every model through `apply_patch` or making it the default editor for the whole Pi workflow. The shipped route is therefore a model-ID allowlist (`gpt-5.6-*` plus an `openai-responses`/`openai-codex-responses` API check) that keeps `edit` as the fallback everywhere else. The implementation now ships inside `@maxiaochao/pi-toolkit` instead of as a standalone opt-in package, but the allowlist — not the packaging — is what bounds the change: for a non-allowlisted model the extension only re-syncs an already-active editor tool and otherwise returns early.
+
+The production route was validated with `pudu-openai-proxy/gpt-5.6-sol:high` and `pudu-openai-proxy/gpt-5.6-luna:high`. Sol's 20-case fair run improved first editor-call success from 85% to 95% with equal final correctness. A corrected Luna rerun used the fully qualified `pudu-openai-proxy/gpt-5.6-luna:high` in both arms, with 20/20 normally completed runs in each arm: both reached 18/20 final correctness, while first editor-call success was 18/20 for `edit` and 20/20 for `apply_patch`. Among the 17 cases correct in both arms, the paired median total-duration delta was +2.3s for `apply_patch`, with 8 cases faster and 9 slower; across all 20 paired runs, the median delta was +1.2s, with 9 cases faster and 11 slower. The measured tradeoff justified validating Sol first; the shipped `gpt-5.6-*` glob additionally enables Luna and Terra, whose gap is protocol adaptation rather than a stable duration win.

package/extensions/codex-edit/tests/package.test.mjs

@@ -0,0 +1,38 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import test from "node:test";
+import { modelIsAllowed } from "../model-routing.ts";
+
+const extensionDir = dirname(dirname(new URL(import.meta.url).pathname));
+
+test("config is next to the extension entry file", async () => {
+  const source = await readFile(join(extensionDir, "index.ts"), "utf8");
+  assert.match(source, /new URL\("\.\/config\.json", import\.meta\.url\)/);
+  assert.match(source, /model-routing\.ts/);
+  const config = JSON.parse(await readFile(join(extensionDir, "config.json"), "utf8"));
+  assert.equal(config.enabled, true);
+  assert.deepEqual(config.models, ["gpt-5.6-*"]);
+});
+
+test("matches allowed model IDs with globs independently of provider and grammar support", () => {
+  const settings = { enabled: true, models: ["gpt-5.6-*"] };
+  const baseModel = {
+    id: "gpt-5.6-terra",
+    api: "openai-codex-responses",
+    compat: { supportsOpenAIGrammarTools: true },
+  };
+  assert.equal(modelIsAllowed({ ...baseModel, provider: "openai-codex" }, settings), true);
+  assert.equal(modelIsAllowed({ ...baseModel, provider: "another-provider" }, settings), true);
+  assert.equal(modelIsAllowed({ ...baseModel, compat: { supportsOpenAIGrammarTools: false } }, settings), true);
+  assert.equal(
+    modelIsAllowed(
+      { ...baseModel, api: "openai-responses", compat: { sessionAffinityFormat: "openai-nosession" } },
+      settings,
+    ),
+    true,
+  );
+  assert.equal(modelIsAllowed({ ...baseModel, api: "openai-completions" }, settings), false);
+  assert.equal(modelIsAllowed({ ...baseModel, id: "gpt-5.5" }, settings), false);
+  assert.equal(modelIsAllowed(baseModel, { enabled: false, models: ["gpt-5.6-*"] }), false);
+});

package/extensions/codex-edit/tests/parser.test.mjs

@@ -0,0 +1,89 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { applyUpdate, parsePatch, resolveWorkspacePath } from "../parser.ts";
+
+test("parses add, delete, update, and move operations", () => {
+  const operations = parsePatch(`*** Begin Patch
+*** Add File: added.txt
++hello
+*** Delete File: removed.txt
+*** Update File: old.txt
+*** Move to: new.txt
+@@
+-old
++new
+*** End Patch`);
+  assert.deepEqual(operations.map((operation) => operation.action), ["add", "delete", "update"]);
+  assert.equal(operations[0].content, "hello\n");
+  assert.equal(operations[2].moveTo, "new.txt");
+  assert.deepEqual(operations[2].chunks[0].oldLines, ["old"]);
+  assert.deepEqual(operations[2].chunks[0].newLines, ["new"]);
+});
+
+test("rejects malformed patches and duplicate targets", () => {
+  assert.throws(() => parsePatch("bad"), /first line/);
+  assert.throws(() => parsePatch(`*** Begin Patch
+*** Add File: same.txt
++x
+*** Add File: same.txt
++y
+*** End Patch`), /same path/);
+});
+
+test("applies multiple chunks using context and preserves BOM and CRLF", () => {
+  const before = "\ufefffunction run() {\r\n  const value = 1;\r\n  return value;\r\n}\r\n";
+  const operations = parsePatch(`*** Begin Patch
+*** Update File: src/run.js
+@@ function run() {
+-  const value = 1;
++  const value = 2;
+@@
+-  return value;
++  return value + 1;
+*** End Patch`);
+  const after = applyUpdate(before, operations[0].chunks, "src/run.js");
+  assert.equal(after, "\ufefffunction run() {\r\n  const value = 2;\r\n  return value + 1;\r\n}\r\n");
+});
+
+test("supports insertion chunks and EOF matching", () => {
+  const operations = parsePatch(`*** Begin Patch
+*** Update File: file.txt
+@@
++first
+*** End of File
+*** End Patch`);
+  assert.equal(applyUpdate("", operations[0].chunks, "file.txt"), "first\n");
+});
+
+test("rejects ambiguous matches and workspace escapes", () => {
+  const operations = parsePatch(`*** Begin Patch
+*** Update File: file.txt
+@@
+-value
++changed
+*** End Patch`);
+  assert.throws(() => applyUpdate("value\nvalue\n", operations[0].chunks, "file.txt"), /Ambiguous/);
+  assert.equal(resolveWorkspacePath("/tmp/project", "/tmp/project/src/a.js"), "/tmp/project/src/a.js");
+  assert.throws(() => resolveWorkspacePath("/tmp/project", "/tmp/other/a.js"), /escapes/);
+});
+
+test("round-trips a temporary file operation fixture", async () => {
+  const workspace = await mkdtemp(join(tmpdir(), "codex-edit-test-"));
+  try {
+    const path = join(workspace, "file.txt");
+    await writeFile(path, "before\n", "utf8");
+    const operations = parsePatch(`*** Begin Patch
+*** Update File: file.txt
+@@
+-before
++after
+*** End Patch`);
+    await writeFile(path, applyUpdate(await readFile(path, "utf8"), operations[0].chunks, "file.txt"), "utf8");
+    assert.equal(await readFile(path, "utf8"), "after\n");
+  } finally {
+    await rm(workspace, { recursive: true, force: true });
+  }
+});

package/extensions/tests/todo-state.mjs

@@ -0,0 +1,84 @@
+import assert from "node:assert/strict";
+import {
+	activeTodos,
+	applyTodoAction,
+	restoreTodoState,
+} from "../todo-state.ts";
+
+const empty = { todos: [], nextId: 1 };
+
+const replaced = applyTodoAction(empty, {
+	action: "replace",
+	items: ["Inspect the failure", "Implement the fix", "Run verification"],
+});
+assert.deepEqual(
+	replaced.todos.map(({ id, text, status }) => ({ id, text, status })),
+	[
+		{ id: 1, text: "Inspect the failure", status: "doing" },
+		{ id: 2, text: "Implement the fix", status: "todo" },
+		{ id: 3, text: "Run verification", status: "todo" },
+	],
+	"replace installs a fresh ordered plan and starts its first task",
+);
+assert.equal(replaced.nextId, 4, "replace advances the ID sequence past the new plan");
+
+const completed = applyTodoAction(replaced, { action: "update", id: 1, status: "done" });
+assert.deepEqual(
+	completed.todos.map(({ id, status }) => ({ id, status })),
+	[
+		{ id: 1, status: "done" },
+		{ id: 2, status: "doing" },
+		{ id: 3, status: "todo" },
+	],
+	"finishing active work advances the next queued task",
+);
+
+const cancelled = applyTodoAction(completed, { action: "update", id: 2, status: "cancelled" });
+assert.equal(cancelled.todos[2].status, "doing", "cancelling active work advances the next queued task");
+assert.deepEqual(activeTodos(cancelled.todos).map((todo) => todo.id), [3], "closed work is absent from the active view");
+
+const restarted = applyTodoAction(cancelled, { action: "add", text: "Review the redirected implementation", status: "doing" });
+assert.equal(restarted.todos.find((todo) => todo.id === 3).status, "todo", "starting another task demotes the previous active task");
+assert.equal(restarted.todos.find((todo) => todo.id === 4).status, "doing", "the requested task becomes active");
+
+const removed = applyTodoAction(restarted, { action: "remove", id: 4 });
+assert.equal(removed.todos.find((todo) => todo.id === 3).status, "doing", "removing active work advances the queue");
+assert.equal(removed.nextId, 5, "removing a task does not reuse its ID");
+
+const duplicate = applyTodoAction(removed, { action: "add", text: "Run verification" });
+assert.match(duplicate.error ?? "", /already exists/, "active duplicates are rejected");
+assert.deepEqual(duplicate.todos, removed.todos, "a rejected mutation preserves the previous state");
+
+const replacedAgain = applyTodoAction(removed, { action: "replace", items: ["New direction"] });
+assert.deepEqual(
+	replacedAgain.todos,
+	[{ id: 5, text: "New direction", status: "doing" }],
+	"replace discards the obsolete plan without reusing an old task ID",
+);
+assert.equal(replacedAgain.nextId, 6);
+
+const invalidReplace = applyTodoAction(replacedAgain, { action: "replace", items: [" "] });
+assert.ok(invalidReplace.error, "replace rejects empty task text");
+assert.deepEqual(invalidReplace.todos, replacedAgain.todos, "invalid replacement is atomic");
+
+const restored = restoreTodoState([
+	{ id: 4, text: "legacy complete", done: true },
+	{ id: 2, text: "first active", status: "doing" },
+	{ id: 3, text: "second active", status: "doing" },
+], 2);
+assert.deepEqual(
+	restored.todos.map(({ id, status }) => ({ id, status })),
+	[
+		{ id: 2, status: "doing" },
+		{ id: 3, status: "todo" },
+		{ id: 4, status: "done" },
+	],
+	"restoration migrates legacy entries and enforces one active task",
+);
+assert.equal(restored.nextId, 5, "restoration repairs stale next IDs");
+
+const cleared = applyTodoAction(restored, { action: "clear" });
+assert.deepEqual(cleared.todos, []);
+assert.equal(cleared.nextId, 1, "clear resets the ID sequence");
+
+console.log("Todo state tests passed");