pim-agent 0.0.1 → 0.9.0

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

@@ -0,0 +1,228 @@
+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 {
+  if (options.platform === undefined && options.runCommand === undefined) {
+    cachedOs ??= computeOs(options);
+    return cachedOs;
+  }
+  return computeOs(options);
+}
+
+let cachedOs: string | undefined;
+
+function computeOs(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 parsed = fields(osRelease, parseOsReleaseLine);
+      const prettyName = parsed.get("PRETTY_NAME")?.trim();
+      if (prettyName) {
+        return prettyName;
+      }
+
+      const name = parsed.get("NAME")?.trim();
+      const version =
+        parsed.get("VERSION")?.trim() ?? parsed.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());
+    }
+  } else if (platform === "darwin") {
+    const swVers = runCommand(["sw_vers"]);
+    if (swVers) {
+      const parsed = fields(swVers, parseColonLine);
+      const name = parsed.get("ProductName") ?? "macOS";
+      const version = parsed.get("ProductVersion");
+      return [name, version].filter(Boolean).join(" ") || platform;
+    }
+  } else if (platform === "win32") {
+    const ver = runCommand(["cmd.exe", "/d", "/s", "/c", "ver"]);
+    return ver?.replace(/\s+/g, " ").trim() || platform;
+  }
+
+  return unixName() ?? platform;
+}
+
+type FieldParser = (line: string) => readonly [string, string] | undefined;
+
+function fields(text: string, parse: FieldParser): Map<string, string> {
+  const parsed = new Map<string, string>();
+  for (const line of text.split(/\r?\n/)) {
+    const entry = parse(line);
+    if (entry) {
+      parsed.set(entry[0], entry[1]);
+    }
+  }
+  return parsed;
+}
+
+function parseOsReleaseLine(
+  line: string
+): readonly [string, string] | undefined {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith("#")) {
+    return undefined;
+  }
+
+  const equalsIndex = trimmed.indexOf("=");
+  if (equalsIndex <= 0) {
+    return undefined;
+  }
+
+  const key = trimmed.slice(0, equalsIndex);
+  return /^[A-Z0-9_]+$/.test(key)
+    ? [key, unquoteValue(trimmed.slice(equalsIndex + 1))]
+    : undefined;
+}
+
+function parseColonLine(line: string): readonly [string, string] | undefined {
+  const match = line.match(/^([^:]+):\s*(.+)$/);
+  const key = match?.[1]?.trim();
+  const value = match?.[2]?.trim();
+  return key && value ? [key, value] : undefined;
+}
+
+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/packages/core/src/extensions/todo/index.ts

@@ -0,0 +1,123 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Tools } from "../../shared/Tools";
+import { renderWidgetLines, todoView } 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 the todo widget registers last, right above the 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:
+      "Update the session task list. " +
+      "Each call replaces the entire list; include every item that should remain, in priority order. " +
+      "Status values are pending, in_progress, completed, and cancelled. " +
+      "At most one item may be in_progress.",
+    parameters: todoSchema,
+    renderShell: "self",
+    effect: { kind: "readOnly" },
+    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),
+      };
+    },
+    toViewModel: todoView,
+  });
+
+  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 }
+    );
+  });
+}

package/packages/core/src/extensions/todo/render.ts

@@ -0,0 +1,156 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Format } from "../../shared/Format";
+import type { ToolViewInput } from "../../shared/Tools";
+import type { ToolView, ViewBlock } from "../../view/ViewBlock";
+import type { TodoInput, TodoItem, todoSchema } from "./schema";
+import { normalizeContent, 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;
+
+export type TodoViewInput = ToolViewInput<typeof todoSchema, TodoDetails>;
+
+export function todoView({ args }: TodoViewInput): ToolView {
+  const todos = ((args ?? {}) as Partial<TodoInput>).todos;
+  const items = Array.isArray(todos) ? todos : [];
+  return {
+    label: "Todo",
+    icon: "checklist",
+    title: [{ kind: "text", text: formatStatusSummary(items) }],
+    body: inProgressSection(items),
+  };
+}
+
+function inProgressSection(items: readonly TodoItem[]): readonly ViewBlock[] {
+  const current = items.findLast(
+    (item) => (item as Partial<TodoItem> | null)?.status === "in_progress"
+  );
+  const content =
+    typeof current?.content === "string"
+      ? normalizeContent(current.content)
+      : "";
+  if (content === "") {
+    return [];
+  }
+  return [
+    {
+      kind: "section",
+      label: "In progress",
+      icon: "checklist",
+      content: [{ kind: "spans", spans: [{ text: content, strong: true }] }],
+    },
+  ];
+}
+
+export function formatWidgetTitle(
+  items: readonly TodoItem[],
+  theme: Theme
+): string {
+  const total = theme.bold(Format.count(items.length, "todo"));
+  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 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/packages/core/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];