@aaroncql/pim-agent 0.0.1

package/src/extensions/system-prompt/prompt.ts

@@ -0,0 +1,213 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+type BuildOptions = {
+  readonly model?: ExtensionContext["model"];
+  readonly cwd: string;
+  readonly contextFiles: ReadonlyArray<{
+    readonly path: string;
+    readonly content: string;
+  }>;
+  readonly skillsBlock: string;
+  readonly toolGuidelines: ReadonlyArray<string>;
+  readonly appendSystemPrompt?: string;
+  readonly customPrompt?: string;
+  readonly os?: string;
+};
+
+type RunCommand = (cmd: ReadonlyArray<string>) => string | undefined;
+
+type OsDescriptionOptions = {
+  readonly platform?: typeof process.platform;
+  readonly runCommand?: RunCommand;
+};
+
+function dynamicGuidelines(): ReadonlyArray<string> {
+  const guidelines: string[] = [];
+  if (Bun.which("gh")) {
+    guidelines.push(
+      "Always prefer `gh` CLI instead of raw API calls when viewing GitHub content (eg. PRs, issues, comments)."
+    );
+  }
+  return guidelines;
+}
+
+export function buildSystemPrompt(opts: BuildOptions): string {
+  const sections: string[] = [];
+
+  if (opts.customPrompt && opts.customPrompt.trim().length > 0) {
+    sections.push(opts.customPrompt);
+  } else {
+    sections.push(
+      [
+        "<system_instructions>",
+        "You are pim (Pi IMproved), a Bun-native, opinionated extension pack for the [pi agent harness](https://pi.dev/).",
+        ...opts.toolGuidelines.map((g) => `- ${g}`),
+        ...dynamicGuidelines().map((g) => `- ${g}`),
+        "</system_instructions>",
+      ].join("\n")
+    );
+  }
+
+  const model = opts.model
+    ? `${opts.model.id} via ${opts.model.provider}`
+    : "unknown";
+  sections.push(
+    [
+      "<environment>",
+      `- cwd: ${opts.cwd}`,
+      `- os: ${opts.os ?? describeOs()}`,
+      `- model: ${model}`,
+      `- datetime: ${formatDatetime(new Date())}`,
+      "</environment>",
+    ].join("\n")
+  );
+
+  if (opts.contextFiles.length > 0) {
+    const files = opts.contextFiles
+      .map(
+        ({ path, content }) =>
+          `<file path="${escapeXmlAttr(path)}">\n${content}\n</file>`
+      )
+      .join("\n");
+    sections.push(`<project_instructions>\n${files}\n</project_instructions>`);
+  }
+
+  if (opts.skillsBlock) {
+    sections.push(opts.skillsBlock.trimStart());
+  }
+
+  if (opts.appendSystemPrompt && opts.appendSystemPrompt.trim().length > 0) {
+    sections.push(opts.appendSystemPrompt);
+  }
+
+  return sections.join("\n\n");
+}
+
+export function describeOs(options: OsDescriptionOptions = {}): string {
+  const platform = options.platform ?? process.platform;
+  const runCommand =
+    options.runCommand ??
+    ((cmd) => {
+      try {
+        const result = Bun.spawnSync({ cmd: [...cmd] });
+        if (result.exitCode !== 0) {
+          return undefined;
+        }
+
+        const output = result.stdout.toString().trim();
+        return output || undefined;
+      } catch {
+        return undefined;
+      }
+    });
+  const unixName = (): string | undefined => runCommand(["uname", "-sr"]);
+
+  if (platform === "linux") {
+    const osRelease = runCommand(["cat", "/etc/os-release"]);
+    if (osRelease) {
+      const fields = new Map<string, string>();
+      for (const line of osRelease.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#")) {
+          continue;
+        }
+
+        const equalsIndex = trimmed.indexOf("=");
+        if (equalsIndex <= 0) {
+          continue;
+        }
+
+        const key = trimmed.slice(0, equalsIndex);
+        if (/^[A-Z0-9_]+$/.test(key)) {
+          fields.set(key, unquoteValue(trimmed.slice(equalsIndex + 1)));
+        }
+      }
+
+      const prettyName = fields.get("PRETTY_NAME")?.trim();
+      if (prettyName) {
+        return prettyName;
+      }
+
+      const name = fields.get("NAME")?.trim();
+      const version =
+        fields.get("VERSION")?.trim() ?? fields.get("VERSION_ID")?.trim();
+      const described = [name, version].filter(Boolean).join(" ");
+      if (described) {
+        return described;
+      }
+    }
+
+    const lsbRelease = runCommand(["lsb_release", "-ds"]);
+    if (lsbRelease) {
+      return unquoteValue(lsbRelease.trim());
+    }
+
+    return unixName() ?? platform;
+  }
+
+  if (platform === "darwin") {
+    const swVers = runCommand(["sw_vers"]);
+    if (swVers) {
+      const fields = new Map<string, string>();
+      for (const line of swVers.split(/\r?\n/)) {
+        const match = line.match(/^([^:]+):\s*(.+)$/);
+        const key = match?.[1]?.trim();
+        const value = match?.[2]?.trim();
+        if (key && value) {
+          fields.set(key, value);
+        }
+      }
+
+      const name = fields.get("ProductName") ?? "macOS";
+      const version = fields.get("ProductVersion");
+      return [name, version].filter(Boolean).join(" ") || platform;
+    }
+
+    return unixName() ?? platform;
+  }
+
+  if (platform === "win32") {
+    const ver = runCommand(["cmd.exe", "/d", "/s", "/c", "ver"]);
+    return ver?.replace(/\s+/g, " ").trim() || platform;
+  }
+
+  return unixName() ?? platform;
+}
+
+function unquoteValue(value: string): string {
+  if (value.length < 2) {
+    return value;
+  }
+
+  const quote = value.charAt(0);
+  if (
+    (quote !== '"' && quote !== "'") ||
+    value.charAt(value.length - 1) !== quote
+  ) {
+    return value;
+  }
+
+  const unquoted = value.slice(1, -1);
+  return quote === "'" ? unquoted : unquoted.replace(/\\(["\\$`])/g, "$1");
+}
+
+function formatDatetime(d: Date): string {
+  const pad = (n: number): string => String(n).padStart(2, "0");
+  const offsetMinutes = -d.getTimezoneOffset();
+  const sign = offsetMinutes >= 0 ? "+" : "-";
+  const absMinutes = Math.abs(offsetMinutes);
+  const offset = `${sign}${pad(Math.floor(absMinutes / 60))}:${pad(absMinutes % 60)}`;
+  const iso =
+    `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}` +
+    `T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}${offset}`;
+  const day = d.toLocaleDateString("en-US", { weekday: "long" });
+  return `${iso} (${day})`;
+}
+
+function escapeXmlAttr(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}

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

@@ -0,0 +1,244 @@
+import { describe, expect, test } from "bun:test";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  Theme,
+} from "@earendil-works/pi-coding-agent";
+import type { TodoItem } from "./schema";
+import registerTodo from "./index";
+import { getCurrentItems } from "./todo";
+
+type Handler = (event: unknown, ctx: ExtensionContext) => unknown;
+type RegisteredTool = {
+  readonly executionMode?: string;
+  readonly execute: (...args: readonly unknown[]) => unknown;
+};
+type AppendedEntry = {
+  readonly customType: string;
+  readonly data: unknown;
+};
+type SentMessage = {
+  readonly message: unknown;
+  readonly options: unknown;
+};
+type MockPi = {
+  readonly api: ExtensionAPI;
+  readonly handlers: Map<string, Handler[]>;
+  readonly tools: RegisteredTool[];
+  readonly appendedEntries: AppendedEntry[];
+  readonly sentMessages: SentMessage[];
+};
+type WidgetUpdate = {
+  readonly id: string;
+  readonly lines: readonly string[] | undefined;
+};
+
+type MockContext = ExtensionContext & {
+  readonly widgetUpdates: WidgetUpdate[];
+};
+
+const stubTheme = {
+  fg: (color: string, text: string) => `<${color}>${text}</${color}>`,
+  bold: (text: string) => `**${text}**`,
+  strikethrough: (text: string) => `~~${text}~~`,
+} as unknown as Theme;
+
+describe("todo extension", () => {
+  test("clears an all-done widget on the next user input", async () => {
+    const pi = createPi();
+    const ctx = createContext();
+    registerTodo(pi.api);
+
+    await setTodos(pi, ctx, [
+      { content: "Ship it", status: "completed" },
+      { content: "Skip obsolete", status: "cancelled" },
+    ]);
+    await emit(pi, "turn_end", { type: "turn_end" }, ctx);
+    await flush();
+
+    expect(ctx.widgetUpdates.at(-1)?.lines).toEqual([
+      "**2 todos** (1 done, 1 cancelled)",
+      "<success>✔</success> <muted>Ship it</muted>",
+      "<muted>✘</muted> <muted>~~Skip obsolete~~</muted>",
+    ]);
+
+    const results = await emit(pi, "input", { type: "input" }, ctx);
+
+    expect(results).toEqual([{ action: "continue" }]);
+    expect(getCurrentItems(ctx.sessionManager)).toEqual([]);
+    expect(ctx.widgetUpdates.at(-1)).toEqual({
+      id: "pim-todo",
+      lines: undefined,
+    });
+  });
+
+  test("keeps the widget when any todo is still active", async () => {
+    const pi = createPi();
+    const ctx = createContext();
+    registerTodo(pi.api);
+
+    const todos: readonly TodoItem[] = [
+      { content: "Done", status: "completed" },
+      { content: "Next", status: "pending" },
+    ];
+    await setTodos(pi, ctx, todos);
+    await emit(pi, "turn_end", { type: "turn_end" }, ctx);
+    await flush();
+    const updatesBeforeInput = ctx.widgetUpdates.length;
+
+    const results = await emit(pi, "input", { type: "input" }, ctx);
+
+    expect(results).toEqual([{ action: "continue" }]);
+    expect(getCurrentItems(ctx.sessionManager)).toEqual(todos);
+    expect(ctx.widgetUpdates).toHaveLength(updatesBeforeInput);
+  });
+
+  test("checkpoints todo state on session_compact so the widget survives a reload", async () => {
+    const pi = createPi();
+    const ctx = createContext();
+    registerTodo(pi.api);
+
+    const todos: readonly TodoItem[] = [
+      { content: "Ship", status: "in_progress" },
+      { content: "Verify", status: "pending" },
+    ];
+    await setTodos(pi, ctx, todos);
+    await emit(pi, "session_compact", { type: "session_compact" }, ctx);
+
+    expect(pi.appendedEntries).toEqual([
+      { customType: "pim-todo-state", data: { todos } },
+    ]);
+    expect(pi.sentMessages).toEqual([
+      {
+        message: {
+          customType: "pim-todo-snapshot",
+          content: "Current todo list:\n[>] Ship\n[ ] Verify",
+          display: false,
+        },
+        options: { triggerTurn: false },
+      },
+    ]);
+  });
+
+  test("session_compact is a no-op when there are no items", async () => {
+    const pi = createPi();
+    const ctx = createContext();
+    registerTodo(pi.api);
+
+    await emit(pi, "session_compact", { type: "session_compact" }, ctx);
+
+    expect(pi.appendedEntries).toEqual([]);
+    expect(pi.sentMessages).toEqual([]);
+  });
+
+  test("subagent ctx mutating todos does not leak into the parent ctx", async () => {
+    const pi = createPi();
+    const parent = createContext();
+    const child = createContext();
+    registerTodo(pi.api);
+
+    await setTodos(pi, parent, [{ content: "parent", status: "pending" }]);
+    await setTodos(pi, child, [{ content: "child", status: "in_progress" }]);
+
+    expect(getCurrentItems(parent.sessionManager)).toEqual([
+      { content: "parent", status: "pending" },
+    ]);
+    expect(getCurrentItems(child.sessionManager)).toEqual([
+      { content: "child", status: "in_progress" },
+    ]);
+  });
+
+  test("todo tool executes sequentially and returns a compact update summary", async () => {
+    const pi = createPi();
+    const ctx = createContext();
+    registerTodo(pi.api);
+
+    expect(pi.tools[0]?.executionMode).toBe("sequential");
+    expect(await setTodos(pi, ctx, [])).toEqual({
+      content: [
+        {
+          type: "text",
+          text: "Todos cleared.",
+        },
+      ],
+      details: {
+        todos: [],
+        summary: {
+          pending: 0,
+          in_progress: 0,
+          completed: 0,
+          cancelled: 0,
+        },
+      },
+    });
+  });
+});
+
+function createPi(): MockPi {
+  const handlers = new Map<string, Handler[]>();
+  const tools: RegisteredTool[] = [];
+  const appendedEntries: AppendedEntry[] = [];
+  const sentMessages: SentMessage[] = [];
+  const api = {
+    on(event: string, handler: Handler): void {
+      const existing = handlers.get(event) ?? [];
+      existing.push(handler);
+      handlers.set(event, existing);
+    },
+    registerTool(tool: RegisteredTool): void {
+      tools.push(tool);
+    },
+    appendEntry(customType: string, data: unknown): void {
+      appendedEntries.push({ customType, data });
+    },
+    sendMessage(message: unknown, options: unknown): void {
+      sentMessages.push({ message, options });
+    },
+  } as unknown as ExtensionAPI;
+
+  return { api, handlers, tools, appendedEntries, sentMessages };
+}
+
+function createContext(): MockContext {
+  const widgetUpdates: WidgetUpdate[] = [];
+  return {
+    hasUI: true,
+    sessionManager: {},
+    ui: {
+      theme: stubTheme,
+      setWidget(id: string, lines: readonly string[] | undefined): void {
+        widgetUpdates.push({ id, lines });
+      },
+    },
+    widgetUpdates,
+  } as unknown as MockContext;
+}
+
+async function emit(
+  pi: MockPi,
+  event: string,
+  payload: unknown,
+  ctx: ExtensionContext
+): Promise<unknown[]> {
+  const results: unknown[] = [];
+  for (const handler of pi.handlers.get(event) ?? []) {
+    results.push(await handler(payload, ctx));
+  }
+  return results;
+}
+
+function flush(): Promise<void> {
+  return new Promise((resolve) => setImmediate(resolve));
+}
+
+async function setTodos(
+  pi: MockPi,
+  ctx: ExtensionContext,
+  todos: readonly TodoItem[]
+): Promise<unknown> {
+  const tool = pi.tools[0];
+  if (!tool) {
+    throw new Error("todo tool was not registered");
+  }
+  return await tool.execute("todo-call", { todos }, undefined, undefined, ctx);
+}

package/src/extensions/todo/index.ts

@@ -0,0 +1,122 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Tools } from "../../shared/Tools";
+import { renderCall, renderResult, renderWidgetLines } from "./render";
+import { todoSchema } from "./schema";
+import {
+  formatChecklist,
+  formatUpdateSummary,
+  getCurrentItems,
+  hasActiveItems,
+  makeDetails,
+  reconstructFromBranch,
+  replaceItems,
+  resetItems,
+  TODO_STATE_CUSTOM_TYPE,
+} from "./todo";
+
+const WIDGET_ID = "pim-todo";
+
+export default function (pi: ExtensionAPI): void {
+  let pendingRefresh: ReturnType<typeof setImmediate> | undefined;
+
+  const refreshWidget = (ctx: ExtensionContext): void => {
+    if (pendingRefresh !== undefined) {
+      clearImmediate(pendingRefresh);
+      pendingRefresh = undefined;
+    }
+    if (!ctx.hasUI) {
+      return;
+    }
+    const items = getCurrentItems(ctx.sessionManager);
+    if (items.length === 0) {
+      ctx.ui.setWidget(WIDGET_ID, undefined);
+      return;
+    }
+    // Defer so todo widget is always the last widget to show up (right above editor)
+    pendingRefresh = setImmediate(() => {
+      pendingRefresh = undefined;
+      ctx.ui.setWidget(WIDGET_ID, renderWidgetLines(items, ctx.ui.theme));
+    });
+  };
+
+  const reconstructAndRefresh = (ctx: ExtensionContext): void => {
+    reconstructFromBranch(ctx.sessionManager, ctx.sessionManager.getBranch());
+    refreshWidget(ctx);
+  };
+
+  const clearInactiveTodos = (ctx: ExtensionContext): void => {
+    const items = getCurrentItems(ctx.sessionManager);
+    if (items.length === 0 || hasActiveItems(items)) {
+      return;
+    }
+
+    resetItems(ctx.sessionManager);
+    refreshWidget(ctx);
+  };
+
+  Tools.register(pi, {
+    name: "todo",
+    label: "todo",
+    description:
+      "Manage your to-dos. ALWAYS use for tasks with 3+ steps; skip only for trivial one-step tasks. " +
+      "Each call replaces the entire list; include every item in priority order. " +
+      "Keep at most one item in_progress, mark items completed immediately after finishing, and preserve skipped work as cancelled.",
+    parameters: todoSchema,
+    renderShell: "self",
+    executionMode: "sequential",
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const items = replaceItems(ctx.sessionManager, params.todos);
+      return {
+        content: [
+          {
+            type: "text",
+            text: formatUpdateSummary(items),
+          },
+        ],
+        details: makeDetails(items),
+      };
+    },
+    renderCall,
+    renderResult,
+  });
+
+  pi.on("session_start", (_event, ctx) => {
+    reconstructAndRefresh(ctx);
+  });
+
+  pi.on("session_tree", (_event, ctx) => {
+    reconstructAndRefresh(ctx);
+  });
+
+  pi.on("turn_end", (_event, ctx) => {
+    refreshWidget(ctx);
+  });
+
+  pi.on("input", (_event, ctx) => {
+    clearInactiveTodos(ctx);
+    return { action: "continue" };
+  });
+
+  pi.on("session_compact", (_event, ctx) => {
+    const items = getCurrentItems(ctx.sessionManager);
+    if (items.length === 0) {
+      return;
+    }
+    pi.appendEntry(TODO_STATE_CUSTOM_TYPE, { todos: items });
+    const snapshot = formatChecklist(items, { activeOnly: true });
+    if (!snapshot) {
+      return;
+    }
+    pi.sendMessage(
+      {
+        customType: "pim-todo-snapshot",
+        content: `Current todo list:\n${snapshot}`,
+        display: false,
+      },
+      { triggerTurn: false }
+    );
+  });
+}