@aaroncql/pim-agent 0.0.1

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

@@ -0,0 +1,180 @@
+import { describe, expect, test } from "bun:test";
+import type {
+  AgentToolResult,
+  Theme,
+  ToolRenderResultOptions,
+} from "@earendil-works/pi-coding-agent";
+import type { TodoItem } from "./schema";
+import {
+  formatCallTitle,
+  formatWidgetTitle,
+  renderCall,
+  renderResult,
+  renderWidgetLines,
+} from "./render";
+import { makeDetails } from "./todo";
+
+const items: readonly TodoItem[] = [
+  { content: "Plan", status: "pending" },
+  { content: "Build", status: "in_progress" },
+  { content: "Verify", status: "completed" },
+  { content: "Skip", status: "cancelled" },
+];
+
+const stubTheme = {
+  fg: (color: string, text: string) => `<${color}>${text}</${color}>`,
+  bold: (text: string) => `**${text}**`,
+  strikethrough: (text: string) => `~~${text}~~`,
+} as unknown as Theme;
+
+const expandedOptions = {
+  expanded: true,
+  isPartial: false,
+} as ToolRenderResultOptions;
+const context = {
+  lastComponent: undefined,
+  isPartial: false,
+  isError: false,
+};
+
+describe("todo render", () => {
+  test("renderCall shows only the compact status summary", () => {
+    expect(formatCallTitle(items)).toBe("1 done, 2 pending, 1 cancelled");
+    const rendered = renderCall({ todos: items }, stubTheme, context).render(
+      120
+    )[0];
+    expect(rendered).toContain("**Todo**");
+    expect(rendered).toContain("1 done, 2 pending, 1 cancelled");
+  });
+
+  test("renderCall shows cleared when the todo list is empty", () => {
+    expect(formatCallTitle([])).toBe("cleared");
+    const rendered = renderCall({ todos: [] }, stubTheme, context).render(
+      120
+    )[0];
+
+    expect(rendered).toContain("**Todo**");
+    expect(rendered).toContain(": cleared");
+  });
+
+  test("renderResult is hidden so the widget is the only TUI checklist", () => {
+    expect(
+      renderResult(
+        toolResult(items),
+        expandedOptions,
+        stubTheme,
+        context
+      ).render(120)
+    ).toEqual([]);
+  });
+
+  test("widget title bolds total and wraps status summary", () => {
+    const pendingItems: readonly TodoItem[] = [
+      { content: "One", status: "pending" },
+      { content: "Two", status: "pending" },
+      { content: "Three", status: "pending" },
+      { content: "Four", status: "pending" },
+    ];
+
+    expect(formatWidgetTitle(pendingItems, stubTheme)).toBe(
+      "**4 todos** (4 pending)"
+    );
+  });
+
+  test("widget colours only status markers", () => {
+    const lines = renderWidgetLines(items, stubTheme);
+
+    expect(formatWidgetTitle(items, stubTheme)).toBe(
+      "**4 todos** (1 done, 2 pending, 1 cancelled)"
+    );
+    expect(lines).toEqual([
+      "**4 todos** (1 done, 2 pending, 1 cancelled)",
+      "□ Plan",
+      "<warning>➤</warning> **Build**",
+      "<success>✔</success> <muted>Verify</muted>",
+      "<muted>✘</muted> <muted>~~Skip~~</muted>",
+    ]);
+  });
+
+  test("widget shows all rows instead of trading one todo for a +1 hint", () => {
+    const many = makePendingItems(6);
+
+    const lines = renderWidgetLines(many, stubTheme);
+
+    expect(lines).toHaveLength(7);
+    expect(lines.slice(1)).toEqual([
+      "□ Task 1",
+      "□ Task 2",
+      "□ Task 3",
+      "□ Task 4",
+      "□ Task 5",
+      "□ Task 6",
+    ]);
+  });
+
+  test("widget caps rows with a muted hidden-count hint", () => {
+    const many = makePendingItems(10);
+
+    const lines = renderWidgetLines(many, stubTheme);
+
+    expect(lines).toHaveLength(7);
+    expect(lines.slice(1, -1)).toEqual([
+      "□ Task 1",
+      "□ Task 2",
+      "□ Task 3",
+      "□ Task 4",
+      "□ Task 5",
+    ]);
+    expect(lines.at(-1)).toBe("<muted>… +5 more</muted>");
+  });
+
+  test("widget centers the visible rows around the in-progress item", () => {
+    const many = makePendingItems(50, { index: 24, status: "in_progress" });
+
+    const lines = renderWidgetLines(many, stubTheme);
+
+    expect(lines).toHaveLength(7);
+    expect(lines.slice(1, -1)).toEqual([
+      "□ Task 23",
+      "□ Task 24",
+      "<warning>➤</warning> **Task 25**",
+      "□ Task 26",
+      "□ Task 27",
+    ]);
+    expect(lines.at(-1)).toBe("<muted>… +45 more</muted>");
+  });
+
+  test("widget falls back to the last non-pending item when none are in progress", () => {
+    const many = makePendingItems(12, { index: 6, status: "completed" });
+
+    const lines = renderWidgetLines(many, stubTheme);
+
+    expect(lines.slice(1, -1)).toEqual([
+      "□ Task 5",
+      "□ Task 6",
+      "<success>✔</success> <muted>Task 7</muted>",
+      "□ Task 8",
+      "□ Task 9",
+    ]);
+    expect(lines.at(-1)).toBe("<muted>… +7 more</muted>");
+  });
+});
+
+function toolResult(
+  items: readonly TodoItem[]
+): AgentToolResult<ReturnType<typeof makeDetails>> {
+  return {
+    content: [{ type: "text", text: "" }],
+    details: makeDetails(items),
+  };
+}
+
+function makePendingItems(
+  count: number,
+  override?: { readonly index: number; readonly status: TodoItem["status"] }
+): readonly TodoItem[] {
+  return Array.from({ length: count }, (_, index) => ({
+    content: `Task ${index + 1}`,
+    status: override?.index === index ? override.status : "pending",
+  }));
+}

package/src/extensions/todo/render.ts

@@ -0,0 +1,172 @@
+import type {
+  AgentToolResult,
+  Theme,
+  ToolRenderResultOptions,
+} from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+import { Renderer } from "../../shared/Renderer";
+import type { TodoItem } from "./schema";
+import type { TodoDetails } from "./todo";
+
+const MAX_WIDGET_LINES = 7;
+const WIDGET_TITLE_LINES = 1;
+const WIDGET_HINT_LINES = 1;
+const MAX_UNTRUNCATED_WIDGET_TODOS = MAX_WIDGET_LINES - WIDGET_TITLE_LINES;
+const MAX_TRUNCATED_WIDGET_TODOS =
+  MAX_UNTRUNCATED_WIDGET_TODOS - WIDGET_HINT_LINES;
+const WIDGET_ANCHOR_SLOT = Math.floor(MAX_WIDGET_LINES / 2) - 1;
+
+type RenderContext = {
+  readonly lastComponent: Component | undefined;
+  readonly isPartial: boolean;
+  readonly isError: boolean;
+};
+
+class HiddenTodoToolRender implements Component {
+  public render(): string[] {
+    return [];
+  }
+
+  public invalidate(): void {}
+}
+
+export function renderCall(
+  args: { readonly todos?: readonly TodoItem[] } | undefined,
+  theme: Theme,
+  context: RenderContext
+): Component {
+  return Renderer.renderToolCallTitle({
+    label: "Todo",
+    title: formatCallTitle(args?.todos ?? []),
+    theme,
+    context,
+  });
+}
+
+export function renderResult(
+  _result: AgentToolResult<TodoDetails>,
+  _options: ToolRenderResultOptions,
+  _theme: Theme,
+  context: RenderContext
+): Component {
+  return reuseHiddenComponent(context);
+}
+
+export function formatCallTitle(items: readonly TodoItem[]): string {
+  return formatStatusSummary(items);
+}
+
+export function formatWidgetTitle(
+  items: readonly TodoItem[],
+  theme: Theme
+): string {
+  const noun = items.length === 1 ? "todo" : "todos";
+  const total = theme.bold(`${items.length} ${noun}`);
+  const summary = formatStatusSummary(items);
+  return summary ? `${total} (${summary})` : total;
+}
+
+export function renderWidgetLines(
+  items: readonly TodoItem[],
+  theme: Theme
+): string[] {
+  if (items.length === 0) {
+    return [];
+  }
+
+  const visibleItems = selectVisibleWidgetItems(items);
+  const hidden = items.length - visibleItems.length;
+
+  return [
+    formatWidgetTitle(items, theme),
+    ...visibleItems.map((item) => styleItem(item, theme)),
+    ...(hidden > 0 ? [theme.fg("muted", `… +${hidden} more`)] : []),
+  ];
+}
+
+function reuseHiddenComponent(context: RenderContext): Component {
+  return context.lastComponent instanceof HiddenTodoToolRender
+    ? context.lastComponent
+    : new HiddenTodoToolRender();
+}
+
+function selectVisibleWidgetItems(
+  items: readonly TodoItem[]
+): readonly TodoItem[] {
+  if (items.length <= MAX_UNTRUNCATED_WIDGET_TODOS) {
+    return items;
+  }
+
+  const anchorIndex = findWidgetAnchorIndex(items);
+  const start = clamp(
+    anchorIndex - WIDGET_ANCHOR_SLOT,
+    0,
+    items.length - MAX_TRUNCATED_WIDGET_TODOS
+  );
+
+  return items.slice(start, start + MAX_TRUNCATED_WIDGET_TODOS);
+}
+
+function findWidgetAnchorIndex(items: readonly TodoItem[]): number {
+  const inProgress = items.findIndex((item) => item.status === "in_progress");
+  if (inProgress >= 0) {
+    return inProgress;
+  }
+
+  const lastNonPending = items.findLastIndex(
+    (item) => item.status !== "pending"
+  );
+  return lastNonPending >= 0 ? lastNonPending : 0;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+function formatStatusSummary(items: readonly TodoItem[]): string {
+  let pending = 0;
+  let done = 0;
+  let cancelled = 0;
+  for (const item of items) {
+    switch (item.status) {
+      case "pending":
+      case "in_progress":
+        pending += 1;
+        break;
+      case "completed":
+        done += 1;
+        break;
+      case "cancelled":
+        cancelled += 1;
+        break;
+    }
+  }
+
+  const segments: string[] = [];
+  if (done > 0) {
+    segments.push(`${done} done`);
+  }
+  if (pending > 0) {
+    segments.push(`${pending} pending`);
+  }
+  if (cancelled > 0) {
+    segments.push(`${cancelled} cancelled`);
+  }
+  if (segments.length === 0) {
+    return "cleared";
+  }
+  return segments.join(", ");
+}
+
+function styleItem(item: TodoItem, theme: Theme): string {
+  switch (item.status) {
+    case "pending":
+      return `□ ${item.content}`;
+    case "in_progress":
+      return `${theme.fg("warning", "➤")} ${theme.bold(item.content)}`;
+    case "completed":
+      return `${theme.fg("success", "✔")} ${theme.fg("muted", item.content)}`;
+    case "cancelled":
+      return `${theme.fg("muted", "✘")} ${theme.fg("muted", theme.strikethrough(item.content))}`;
+  }
+}

package/src/extensions/todo/schema.ts

@@ -0,0 +1,24 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { type Static, Type } from "typebox";
+
+export const STATUSES = [
+  "pending",
+  "in_progress",
+  "completed",
+  "cancelled",
+] as const;
+
+export const todoItemSchema = Type.Object({
+  content: Type.String(),
+  status: StringEnum(STATUSES),
+});
+
+export const todoSchema = Type.Object({
+  todos: Type.Array(todoItemSchema, {
+    description: "The complete replacement task list, in priority order.",
+  }),
+});
+
+export type TodoInput = Static<typeof todoSchema>;
+export type TodoItem = Static<typeof todoItemSchema>;
+export type TodoStatus = (typeof STATUSES)[number];

package/src/extensions/todo/todo.test.ts

@@ -0,0 +1,222 @@
+import { describe, expect, test } from "bun:test";
+import type { TodoItem } from "./schema";
+import {
+  formatChecklist,
+  formatUpdateSummary,
+  getCurrentItems,
+  hasActiveItems,
+  makeDetails,
+  normalizeItems,
+  reconstructFromBranch,
+  replaceItems,
+  summarizeItems,
+  type TodoSessionKey,
+} from "./todo";
+
+const allStatuses: readonly TodoItem[] = [
+  { content: "Plan", status: "pending" },
+  { content: "Build", status: "in_progress" },
+  { content: "Verify", status: "completed" },
+  { content: "Skip obsolete step", status: "cancelled" },
+];
+
+function fakeSession(): TodoSessionKey {
+  return {} as TodoSessionKey;
+}
+
+describe("todo state", () => {
+  test("replace semantics keep the latest write only", () => {
+    const sm = fakeSession();
+    replaceItems(sm, [
+      { content: "a", status: "pending" },
+      { content: "b", status: "pending" },
+      { content: "c", status: "pending" },
+    ]);
+    const latest = replaceItems(sm, [{ content: "d", status: "in_progress" }]);
+
+    expect(latest).toEqual([{ content: "d", status: "in_progress" }]);
+    expect(formatChecklist(getCurrentItems(sm))).toBe("[>] d");
+  });
+
+  test("state is isolated between sessions (parent vs subagent)", () => {
+    const parent = fakeSession();
+    const child = fakeSession();
+    replaceItems(parent, [{ content: "parent task", status: "pending" }]);
+    replaceItems(child, [{ content: "child task", status: "in_progress" }]);
+
+    expect(getCurrentItems(parent)).toEqual([
+      { content: "parent task", status: "pending" },
+    ]);
+    expect(getCurrentItems(child)).toEqual([
+      { content: "child task", status: "in_progress" },
+    ]);
+  });
+
+  test("content is normalized to a single trimmed line and blank content is dropped", () => {
+    expect(
+      normalizeItems([
+        { content: "", status: "pending" },
+        { content: "   ", status: "in_progress" },
+        { content: "  keep\nthis\titem  ", status: "completed" },
+      ])
+    ).toEqual([{ content: "keep this item", status: "completed" }]);
+  });
+
+  test("multiple in_progress items are accepted as-is", () => {
+    const items = normalizeItems([
+      { content: "one", status: "in_progress" },
+      { content: "two", status: "in_progress" },
+    ]);
+
+    expect(formatChecklist(items)).toBe("[>] one\n[>] two");
+  });
+
+  test("duplicate content strings are accepted", () => {
+    const items = normalizeItems([
+      { content: "repeat", status: "pending" },
+      { content: "repeat", status: "completed" },
+    ]);
+
+    expect(items).toEqual([
+      { content: "repeat", status: "pending" },
+      { content: "repeat", status: "completed" },
+    ]);
+  });
+
+  test("active-only checklist drops completed and cancelled", () => {
+    expect(formatChecklist(allStatuses, { activeOnly: true })).toBe(
+      "[ ] Plan\n[>] Build"
+    );
+    expect(
+      formatChecklist(
+        [
+          { content: "done", status: "completed" },
+          { content: "skipped", status: "cancelled" },
+        ],
+        { activeOnly: true }
+      )
+    ).toBe("");
+  });
+
+  test("active item detection treats pending and in-progress as active", () => {
+    expect(hasActiveItems(allStatuses)).toBe(true);
+    expect(
+      hasActiveItems([
+        { content: "done", status: "completed" },
+        { content: "skipped", status: "cancelled" },
+      ])
+    ).toBe(false);
+  });
+
+  test("full checklist includes all marker styles", () => {
+    expect(formatChecklist(allStatuses)).toBe(
+      ["[ ] Plan", "[>] Build", "[x] Verify", "[~] Skip obsolete step"].join(
+        "\n"
+      )
+    );
+  });
+
+  test("reconstruction finds the most recent todo tool result", () => {
+    const branch = [
+      toolResult("todo", [{ content: "old", status: "pending" }]),
+      toolResult("grep", [{ content: "ignored", status: "completed" }]),
+      toolResult("todo", [{ content: "new", status: "in_progress" }]),
+    ];
+
+    expect(reconstructFromBranch(fakeSession(), branch)).toEqual([
+      { content: "new", status: "in_progress" },
+    ]);
+  });
+
+  test("reconstruction restores from a pim-todo-state checkpoint after compaction", () => {
+    const branch = [
+      { type: "compaction", summary: "old todos summarized away" },
+      todoStateEntry([{ content: "kept", status: "in_progress" }]),
+    ];
+
+    expect(reconstructFromBranch(fakeSession(), branch)).toEqual([
+      { content: "kept", status: "in_progress" },
+    ]);
+  });
+
+  test("reconstruction prefers a later tool result over an older checkpoint", () => {
+    const branch = [
+      todoStateEntry([{ content: "old", status: "pending" }]),
+      toolResult("todo", [{ content: "new", status: "completed" }]),
+    ];
+
+    expect(reconstructFromBranch(fakeSession(), branch)).toEqual([
+      { content: "new", status: "completed" },
+    ]);
+  });
+
+  test("reconstruction prefers a later checkpoint over an older tool result", () => {
+    const branch = [
+      toolResult("todo", [{ content: "old", status: "pending" }]),
+      todoStateEntry([{ content: "checkpointed", status: "in_progress" }]),
+    ];
+
+    expect(reconstructFromBranch(fakeSession(), branch)).toEqual([
+      { content: "checkpointed", status: "in_progress" },
+    ]);
+  });
+
+  test("update summary formats model-visible acknowledgement", () => {
+    expect(
+      formatUpdateSummary([
+        { content: "one", status: "completed" },
+        { content: "two", status: "completed" },
+        { content: "three", status: "in_progress" },
+        { content: "four", status: "pending" },
+        { content: "five", status: "pending" },
+      ])
+    ).toBe("Todos updated: 2 completed, 1 in progress, 2 pending.");
+  });
+
+  test("update summary omits zero counts and includes cancelled only when nonzero", () => {
+    expect(formatUpdateSummary(allStatuses)).toBe(
+      "Todos updated: 1 completed, 1 in progress, 1 pending, 1 cancelled."
+    );
+    expect(formatUpdateSummary([{ content: "next", status: "pending" }])).toBe(
+      "Todos updated: 1 pending."
+    );
+  });
+
+  test("update summary handles a cleared list", () => {
+    expect(formatUpdateSummary([])).toBe("Todos cleared.");
+  });
+
+  test("summary counts statuses", () => {
+    expect(summarizeItems(allStatuses)).toEqual({
+      pending: 1,
+      in_progress: 1,
+      completed: 1,
+      cancelled: 1,
+    });
+    expect(makeDetails(allStatuses).summary).toEqual({
+      pending: 1,
+      in_progress: 1,
+      completed: 1,
+      cancelled: 1,
+    });
+  });
+});
+
+function toolResult(toolName: string, todos: readonly TodoItem[]): unknown {
+  return {
+    type: "message",
+    message: {
+      role: "toolResult",
+      toolName,
+      details: { todos },
+    },
+  };
+}
+
+function todoStateEntry(todos: readonly TodoItem[]): unknown {
+  return {
+    type: "custom",
+    customType: "pim-todo-state",
+    data: { todos },
+  };
+}