@aaroncql/pim-agent 0.0.1

package/src/extensions/working-indicator/index.ts

@@ -0,0 +1,77 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+
+const FINAL_WIDGET_ID = "pim-working-finished";
+
+export function formatElapsed(ms: number): string {
+  const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+  return hours > 0
+    ? `${hours}h ${minutes}m ${seconds}s`
+    : minutes > 0
+      ? `${minutes}m ${seconds}s`
+      : `${seconds}s`;
+}
+
+export default function (pi: ExtensionAPI): void {
+  let startedAt = 0;
+  let timer: ReturnType<typeof setInterval> | undefined;
+
+  const stopTimer = (): void => {
+    if (timer !== undefined) {
+      clearInterval(timer);
+      timer = undefined;
+    }
+  };
+
+  const setWorkingMessage = (ctx: ExtensionContext): void => {
+    ctx.ui.setWorkingMessage(
+      `Clanking… ${formatElapsed(Date.now() - startedAt)}`
+    );
+  };
+
+  const setWorkingIndicator = (ctx: ExtensionContext): void => {
+    ctx.ui.setWorkingIndicator({
+      frames: ["⣼", "⣹", "⢻", "⠿", "⡟", "⣏", "⣧", "⣶"].map((frame) =>
+        ctx.ui.theme.fg("accent", frame)
+      ),
+      intervalMs: 80,
+    });
+  };
+
+  pi.on("agent_start", (_event, ctx) => {
+    if (!ctx.hasUI) {
+      return;
+    }
+
+    startedAt = Date.now();
+    ctx.ui.setWidget(FINAL_WIDGET_ID, undefined);
+    setWorkingIndicator(ctx);
+    setWorkingMessage(ctx);
+    stopTimer();
+    timer = setInterval(() => setWorkingMessage(ctx), 1000);
+  });
+
+  pi.on("agent_end", (_event, ctx) => {
+    stopTimer();
+    if (!ctx.hasUI) {
+      return;
+    }
+    // Trailing newline to separate from other widgets right below; newline will
+    // not show up when this widget is the only one shown
+    const message = `⣿ Clanked for ${formatElapsed(Date.now() - startedAt)}\n`;
+    ctx.ui.setWidget(FINAL_WIDGET_ID, [ctx.ui.theme.fg("muted", message)]);
+  });
+
+  pi.on("session_shutdown", (_event, ctx) => {
+    stopTimer();
+    if (!ctx.hasUI) {
+      return;
+    }
+    ctx.ui.setWidget(FINAL_WIDGET_ID, undefined);
+  });
+}

package/src/extensions/write/index.ts

@@ -0,0 +1,76 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type DiffRenderState, DiffView } from "../../shared/DiffView";
+import { Paths } from "../../shared/Paths";
+import { Tools } from "../../shared/Tools";
+import { type WriteInput, writeSchema } from "./schema";
+import { writeContent, type WriteOutcome } from "./write";
+
+const ERROR_PREVIEW_LINES = 12;
+
+export default function (pi: ExtensionAPI): void {
+  Tools.register(pi, {
+    name: "write",
+    label: "write",
+    description:
+      "Create or overwrite UTF-8 text files. Use write only for new files or full rewrites - prefer edit for changes to existing files.",
+    parameters: writeSchema,
+    renderShell: "self",
+    executionMode: "sequential",
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      const { path, content } = params as WriteInput;
+
+      if (signal?.aborted) {
+        throw new Error("Write aborted before execution.");
+      }
+
+      const absolutePath = Paths.resolve(path, ctx.cwd);
+      const outcome = await writeContent(absolutePath, content);
+
+      return {
+        content: [{ type: "text", text: formatSummary(path, outcome) }],
+        details: outcome,
+      };
+    },
+    renderCall(args, theme, context) {
+      const rawPath = typeof args?.path === "string" ? args.path : undefined;
+      return DiffView.renderDiffCall({
+        label: "Write",
+        rawPath,
+        theme,
+        context: context as typeof context & { state: DiffRenderState },
+      });
+    },
+    renderResult(result, options, theme, context) {
+      return DiffView.renderDiffResult({
+        label: "Write",
+        result,
+        options,
+        theme,
+        context: context as typeof context & { state: DiffRenderState },
+        previewLines: ERROR_PREVIEW_LINES,
+      });
+    },
+  });
+}
+
+function formatSummary(path: string, outcome: WriteOutcome): string {
+  const verb = outcome.created ? "Created" : "Wrote";
+  const eofNote =
+    outcome.trailingNewlineChange === undefined
+      ? ""
+      : ` Trailing newline ${outcome.trailingNewlineChange}.`;
+
+  if (
+    outcome.diff === undefined &&
+    !outcome.created &&
+    outcome.diffSkipped === undefined
+  ) {
+    return `Wrote ${outcome.bytesWritten} bytes to ${path} (no content changes).${eofNote}`;
+  }
+
+  if (outcome.diffSkipped !== undefined) {
+    return `${verb} ${outcome.bytesWritten} bytes at ${path} (diff omitted: file exceeds ${outcome.diffSkipped.thresholdBytes}-byte render cap).${eofNote}`;
+  }
+
+  return `${verb} ${outcome.bytesWritten} bytes at ${path}.${eofNote}`;
+}

package/src/extensions/write/render.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { DiffLines } from "../../shared/DiffLines";
+import { DiffView } from "../../shared/DiffView";
+
+const stubTheme = {
+  fg: (color: string, text: string) => `<${color}>${text}</${color}>`,
+} as unknown as Theme;
+
+describe("DiffView.countStats", () => {
+  test("returns zeros when diff is undefined", () => {
+    expect(DiffView.countStats(undefined)).toEqual({ added: 0, removed: 0 });
+  });
+
+  test("counts added and removed lines across hunks", () => {
+    const diff = DiffLines.buildToolDiff(
+      "/tmp/x.ts",
+      {
+        lines: ["alpha", "beta", "gamma", "delta"],
+        hasTrailingNewline: true,
+      },
+      {
+        lines: ["alpha", "BETA", "gamma", "DELTA"],
+        hasTrailingNewline: true,
+      },
+      0
+    );
+    expect(DiffView.countStats(diff)).toEqual({ added: 2, removed: 2 });
+  });
+
+  test("counts a brand-new file as all added", () => {
+    const diff = DiffLines.buildToolDiff(
+      "/tmp/new.ts",
+      { lines: [], hasTrailingNewline: false },
+      { lines: ["one", "two", "three"], hasTrailingNewline: true },
+      0
+    );
+    expect(DiffView.countStats(diff)).toEqual({ added: 3, removed: 0 });
+  });
+});
+
+describe("DiffView.formatStats", () => {
+  test("emits both segments separated by a slash", () => {
+    expect(DiffView.formatStats({ added: 5, removed: 2 }, stubTheme)).toBe(
+      "<toolDiffAdded>+5</toolDiffAdded>/<toolDiffRemoved>-2</toolDiffRemoved>"
+    );
+  });
+
+  test("omits the removed segment when zero", () => {
+    expect(DiffView.formatStats({ added: 5, removed: 0 }, stubTheme)).toBe(
+      "<toolDiffAdded>+5</toolDiffAdded>"
+    );
+  });
+
+  test("omits the added segment when zero", () => {
+    expect(DiffView.formatStats({ added: 0, removed: 2 }, stubTheme)).toBe(
+      "<toolDiffRemoved>-2</toolDiffRemoved>"
+    );
+  });
+
+  test("returns empty string when both are zero", () => {
+    expect(DiffView.formatStats({ added: 0, removed: 0 }, stubTheme)).toBe("");
+  });
+});

package/src/extensions/write/schema.ts

@@ -0,0 +1,14 @@
+import { type Static, Type } from "typebox";
+
+export const writeSchema = Type.Object({
+  path: Type.String({
+    description:
+      "Absolute or relative path to file (resolved against cwd). Parent directories are created if missing.",
+  }),
+  content: Type.String({
+    description:
+      "UTF-8 text written verbatim. Include a trailing newline if needed.",
+  }),
+});
+
+export type WriteInput = Static<typeof writeSchema>;

package/src/extensions/write/write.test.ts

@@ -0,0 +1,108 @@
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "bun:test";
+import { writeContent } from "./write";
+
+const tempRoots: string[] = [];
+
+const tempRoot = async (): Promise<string> => {
+  const root = await mkdtemp(join(tmpdir(), "pim-write-tool-"));
+  tempRoots.push(root);
+  return root;
+};
+
+afterAll(async () => {
+  await Promise.all(
+    tempRoots.map((root) => rm(root, { force: true, recursive: true }))
+  );
+});
+
+describe("writeContent", () => {
+  test("creates a new file and reports an all-added diff", async () => {
+    const root = await tempRoot();
+    const path = join(root, "fresh.ts");
+
+    const outcome = await writeContent(path, "alpha\nbeta\n");
+
+    expect(outcome.created).toBe(true);
+    expect(outcome.bytesWritten).toBe(11);
+    expect(await readFile(path, "utf8")).toBe("alpha\nbeta\n");
+    expect(outcome.diff).toBeDefined();
+    const lines = outcome.diff?.hunks[0]?.lines ?? [];
+    expect(lines.map((line) => line.kind)).toEqual(["added", "added"]);
+    expect(lines.map((line) => line.text)).toEqual(["alpha", "beta"]);
+  });
+
+  test("creates parent directories when missing", async () => {
+    const root = await tempRoot();
+    const path = join(root, "deep", "nest", "file.txt");
+
+    const outcome = await writeContent(path, "hello");
+
+    expect(outcome.created).toBe(true);
+    expect(await readFile(path, "utf8")).toBe("hello");
+  });
+
+  test("emits no diff when content is unchanged", async () => {
+    const root = await tempRoot();
+    const path = join(root, "same.txt");
+    await writeFile(path, "alpha\nbeta\n", "utf8");
+
+    const outcome = await writeContent(path, "alpha\nbeta\n");
+
+    expect(outcome.created).toBe(false);
+    expect(outcome.diff).toBeUndefined();
+  });
+
+  test("reports a trailing-newline removal even when content matches and produces no diff hunks", async () => {
+    const root = await tempRoot();
+    const path = join(root, "eof.txt");
+    await writeFile(path, "alpha\n", "utf8");
+
+    const outcome = await writeContent(path, "alpha");
+
+    expect(outcome.created).toBe(false);
+    expect(outcome.diff).toBeUndefined();
+    expect(outcome.trailingNewlineChange).toBe("removed");
+  });
+
+  test("reports a trailing-newline addition", async () => {
+    const root = await tempRoot();
+    const path = join(root, "eof2.txt");
+    await writeFile(path, "alpha", "utf8");
+
+    const outcome = await writeContent(path, "alpha\n");
+
+    expect(outcome.created).toBe(false);
+    expect(outcome.trailingNewlineChange).toBe("added");
+  });
+
+  test("does not report trailing-newline change for newly created files", async () => {
+    const root = await tempRoot();
+    const path = join(root, "fresh.txt");
+
+    const outcome = await writeContent(path, "alpha");
+
+    expect(outcome.created).toBe(true);
+    expect(outcome.trailingNewlineChange).toBeUndefined();
+  });
+
+  test("emits a diff capturing modified lines", async () => {
+    const root = await tempRoot();
+    const path = join(root, "edit.txt");
+    await writeFile(path, "alpha\nbeta\ngamma\n", "utf8");
+
+    const outcome = await writeContent(path, "alpha\nBETA\ngamma\n");
+
+    expect(outcome.created).toBe(false);
+    const lines = outcome.diff?.hunks[0]?.lines ?? [];
+    const kinds = lines.map((line) => line.kind);
+    expect(kinds).toContain("removed");
+    expect(kinds).toContain("added");
+    const removed = lines.find((line) => line.kind === "removed");
+    const added = lines.find((line) => line.kind === "added");
+    expect(removed?.text).toBe("beta");
+    expect(added?.text).toBe("BETA");
+  });
+});

package/src/extensions/write/write.ts

@@ -0,0 +1,104 @@
+import { DiffLines, type ToolDiff } from "../../shared/DiffLines";
+import { Fs } from "../../shared/Fs";
+
+const CONTEXT_LINES = 3;
+
+// Diff.diffLines is O(n*d); skip rendering for multi-MB writes. The write
+// itself still happens — only the diff is omitted.
+const MAX_DIFF_BYTES = 2 * 1024 * 1024;
+
+export type WriteOutcome = {
+  readonly bytesWritten: number;
+  readonly created: boolean;
+  readonly diff?: ToolDiff;
+  readonly diffSkipped?: {
+    readonly reason: "size";
+    readonly thresholdBytes: number;
+    readonly comparedBytes: number;
+  };
+  // Surfaced in the result text since the renderer doesn't visualize EOF state.
+  readonly trailingNewlineChange?: "added" | "removed";
+};
+
+export async function writeContent(
+  absolutePath: string,
+  content: string
+): Promise<WriteOutcome> {
+  const prior = await readPriorContent(absolutePath);
+  const bytesWritten = Buffer.byteLength(content, "utf8");
+
+  if (prior === content) {
+    return { bytesWritten, created: false };
+  }
+
+  await Fs.writeAtomic(absolutePath, content);
+
+  const created = prior === undefined;
+  const priorBytes = prior === undefined ? 0 : Buffer.byteLength(prior, "utf8");
+  const comparedBytes = Math.max(priorBytes, bytesWritten);
+
+  const oldSide =
+    prior === undefined
+      ? { lines: [], hasTrailingNewline: false }
+      : DiffLines.fromText(prior);
+  const newSide = DiffLines.fromText(content);
+  const trailingNewlineChange = diffEofChange(oldSide, newSide, created);
+
+  if (comparedBytes > MAX_DIFF_BYTES) {
+    return {
+      bytesWritten,
+      created,
+      diffSkipped: {
+        reason: "size",
+        thresholdBytes: MAX_DIFF_BYTES,
+        comparedBytes,
+      },
+      ...(trailingNewlineChange === undefined ? {} : { trailingNewlineChange }),
+    };
+  }
+
+  const diff = DiffLines.buildToolDiff(
+    absolutePath,
+    oldSide,
+    newSide,
+    CONTEXT_LINES
+  );
+
+  return {
+    bytesWritten,
+    created,
+    ...(diff === undefined ? {} : { diff }),
+    ...(trailingNewlineChange === undefined ? {} : { trailingNewlineChange }),
+  };
+}
+
+function diffEofChange(
+  oldSide: { readonly hasTrailingNewline: boolean },
+  newSide: { readonly hasTrailingNewline: boolean },
+  created: boolean
+): "added" | "removed" | undefined {
+  if (created || oldSide.hasTrailingNewline === newSide.hasTrailingNewline) {
+    return undefined;
+  }
+
+  return newSide.hasTrailingNewline ? "added" : "removed";
+}
+
+async function readPriorContent(
+  absolutePath: string
+): Promise<string | undefined> {
+  try {
+    return await Bun.file(absolutePath).text();
+  } catch (error) {
+    if (
+      typeof error === "object" &&
+      error !== null &&
+      "code" in error &&
+      (error as { code: unknown }).code === "ENOENT"
+    ) {
+      return undefined;
+    }
+
+    throw error;
+  }
+}

package/src/shared/DiffLines.test.ts

@@ -0,0 +1,193 @@
+import { describe, expect, test } from "bun:test";
+import { DiffLines, type ToolDiffSide } from "./DiffLines";
+
+const side = (
+  lines: readonly string[],
+  hasTrailingNewline = true
+): ToolDiffSide => ({
+  lines,
+  hasTrailingNewline,
+});
+
+describe("DiffLines.buildToolDiff", () => {
+  test("returns undefined when content and EOF state are identical", () => {
+    const result = DiffLines.buildToolDiff(
+      "/tmp/x.ts",
+      side(["alpha", "beta", "gamma"]),
+      side(["alpha", "beta", "gamma"]),
+      2
+    );
+    expect(result).toBeUndefined();
+  });
+
+  test("captures a single-line modification with surrounding context", () => {
+    const result = DiffLines.buildToolDiff(
+      "/tmp/x.ts",
+      side(["alpha", "beta", "gamma"]),
+      side(["alpha", "BETA", "gamma"]),
+      2
+    );
+    expect(result).toBeDefined();
+    const hunk = result?.hunks[0];
+    expect(hunk).toBeDefined();
+    expect(hunk?.lines.map((line) => line.kind)).toEqual([
+      "context",
+      "removed",
+      "added",
+      "context",
+    ]);
+    expect(hunk?.lines.map((line) => line.text)).toEqual([
+      "alpha",
+      "beta",
+      "BETA",
+      "gamma",
+    ]);
+  });
+
+  test("represents an all-added diff for a brand-new file", () => {
+    const result = DiffLines.buildToolDiff(
+      "/tmp/new.ts",
+      side([], false),
+      side(["alpha", "beta"]),
+      2
+    );
+    const hunk = result?.hunks[0];
+    expect(hunk?.lines.map((line) => line.kind)).toEqual(["added", "added"]);
+  });
+
+  test("collapses far-apart changes into separate hunks", () => {
+    const oldLines = Array.from({ length: 20 }, (_, i) => `line ${i + 1}`);
+    const newLines = oldLines.slice();
+    newLines[1] = "EARLY";
+    newLines[18] = "LATE";
+
+    const result = DiffLines.buildToolDiff(
+      "/tmp/x.ts",
+      side(oldLines),
+      side(newLines),
+      1
+    );
+    expect(result?.hunks.length).toBe(2);
+  });
+
+  test("attaches intra-line emphasis to a paired removed/added line", () => {
+    const result = DiffLines.buildToolDiff(
+      "/tmp/x.ts",
+      side(["const x = 1;"]),
+      side(["const y = 2;"]),
+      1
+    );
+    const lines = result?.hunks[0]?.lines ?? [];
+    const removed = lines.find((line) => line.kind === "removed");
+    const added = lines.find((line) => line.kind === "added");
+
+    expect(removed?.emphasis?.length ?? 0).toBeGreaterThan(0);
+    expect(added?.emphasis?.length ?? 0).toBeGreaterThan(0);
+
+    for (const range of removed?.emphasis ?? []) {
+      const slice = removed?.text.slice(range.start, range.end) ?? "";
+      expect(slice.includes("x") || slice.includes("1")).toBe(true);
+    }
+  });
+
+  test("skips emphasis when removed and added runs are unequal length", () => {
+    const result = DiffLines.buildToolDiff(
+      "/tmp/x.ts",
+      side(["alpha"]),
+      side(["beta", "gamma"]),
+      1
+    );
+    const lines = result?.hunks[0]?.lines ?? [];
+
+    for (const line of lines) {
+      expect(line.emphasis).toBeUndefined();
+    }
+  });
+
+  test("does not emphasize leading whitespace", () => {
+    const result = DiffLines.buildToolDiff(
+      "/tmp/x.ts",
+      side(["  foo();"]),
+      side(["    foo();"]),
+      1
+    );
+    const lines = result?.hunks[0]?.lines ?? [];
+
+    for (const line of lines) {
+      for (const range of line.emphasis ?? []) {
+        const slice = line.text.slice(range.start, range.end);
+        expect(/^\s/.test(slice)).toBe(false);
+      }
+    }
+  });
+
+  test("skips emphasis when lines share no content", () => {
+    const result = DiffLines.buildToolDiff(
+      "/tmp/x.ts",
+      side(["foo"]),
+      side(["bar"]),
+      1
+    );
+    const lines = result?.hunks[0]?.lines ?? [];
+
+    for (const line of lines) {
+      expect(line.emphasis).toBeUndefined();
+    }
+  });
+
+  test("returns undefined when only EOF newline state differs (callers surface EOF themselves)", () => {
+    const result = DiffLines.buildToolDiff(
+      "/tmp/x.ts",
+      side(["alpha"], true),
+      side(["alpha"], false),
+      2
+    );
+    expect(result).toBeUndefined();
+  });
+
+  test("does not emit a phantom empty added line when appending to a newline-terminated file", () => {
+    const result = DiffLines.buildToolDiff(
+      "/tmp/x.ts",
+      side(["foo", "bar"], true),
+      side(["foo", "bar", "baz"], true),
+      1
+    );
+    const lines = result?.hunks[0]?.lines ?? [];
+    const added = lines.filter((line) => line.kind === "added");
+    expect(added).toHaveLength(1);
+    expect(added[0]?.text).toBe("baz");
+  });
+
+  test("throws on negative contextSize", () => {
+    expect(() =>
+      DiffLines.buildToolDiff("/tmp/x.ts", side(["a"]), side(["b"]), -1)
+    ).toThrow();
+  });
+});
+
+describe("DiffLines.fromText", () => {
+  test("treats the empty string as zero lines, no trailing newline", () => {
+    expect(DiffLines.fromText("")).toEqual({
+      lines: [],
+      hasTrailingNewline: false,
+    });
+  });
+
+  test("distinguishes 'a' from 'a\\n'", () => {
+    expect(DiffLines.fromText("a")).toEqual({
+      lines: ["a"],
+      hasTrailingNewline: false,
+    });
+    expect(DiffLines.fromText("a\n")).toEqual({
+      lines: ["a"],
+      hasTrailingNewline: true,
+    });
+  });
+
+  test("preserves embedded blank lines without collapsing them", () => {
+    expect(DiffLines.fromText("a\n\nb\n")).toEqual({
+      lines: ["a", "", "b"],
+      hasTrailingNewline: true,
+    });
+  });
+});