@aaroncql/pim-agent 0.0.1

package/src/extensions/read/read.ts

@@ -0,0 +1,206 @@
+import { FsErrors } from "../../shared/FsErrors";
+import { Lines } from "../../shared/Lines";
+import { OutputBudget } from "../../shared/OutputBudget";
+import type { ReadRange } from "./schema";
+
+type RenderedLine = {
+  readonly lineNumber: number;
+  readonly text: string;
+};
+
+export type ReadOutcome = {
+  readonly body: string;
+  readonly totalLines: number;
+  readonly visibleStart: number;
+  readonly visibleEnd: number;
+  readonly truncatedByByteCap: boolean;
+  readonly truncatedByEnd: boolean;
+  readonly hadBom: boolean;
+  readonly nextStart?: number;
+};
+
+export function buildReadRange(
+  start: number | undefined,
+  end: number | undefined
+): ReadRange {
+  const startLine = start ?? 1;
+
+  if (start !== undefined && (!Number.isInteger(start) || start <= 0)) {
+    throw new Error(`Read start ${start} must be a positive integer.`);
+  }
+
+  if (end !== undefined && (!Number.isInteger(end) || end <= 0)) {
+    throw new Error(`Read end ${end} must be a positive integer.`);
+  }
+
+  if (end !== undefined && end < startLine) {
+    throw new Error(`Read end line ${end} must be >= start line ${startLine}.`);
+  }
+
+  return {
+    start: startLine,
+    ...(end === undefined ? {} : { end }),
+  };
+}
+
+export async function readFile(
+  path: string,
+  range: ReadRange
+): Promise<ReadOutcome> {
+  const metadata = await FsErrors.statOrThrow(path);
+
+  if (metadata.isDirectory()) {
+    throw new Error(
+      `Path is a directory: ${path}. Use grep or glob to inspect directories.`
+    );
+  }
+
+  const file = Bun.file(path);
+
+  let head: Uint8Array;
+  try {
+    head = new Uint8Array(await file.slice(0, 8192).arrayBuffer());
+  } catch (error) {
+    rethrowFsError(error, path, "read");
+  }
+
+  if (head.includes(0)) {
+    throw new Error(
+      `Read only supports UTF-8 text files but given path is a binary file. Use bash with 'file' or 'xxd' to inspect binary contents.`
+    );
+  }
+
+  let bytes: Uint8Array;
+  try {
+    bytes = await file.bytes();
+  } catch (error) {
+    rethrowFsError(error, path, "read");
+  }
+
+  const hadBom = Lines.hasUtf8Bom(bytes);
+  const text = new TextDecoder("utf-8").decode(bytes);
+
+  return renderText(Lines.stripUtf8Bom(text), range, path, hadBom);
+}
+
+function renderText(
+  content: string,
+  range: ReadRange,
+  path: string,
+  hadBom: boolean
+): ReadOutcome {
+  const lines = Lines.split(content);
+  const totalLines = lines.length;
+
+  if (totalLines === 0) {
+    throw new Error("File is empty. Use the write tool to create content.");
+  }
+
+  if (range.start > totalLines) {
+    throw new Error(
+      `Start ${range.start} is beyond end of file (${totalLines} lines total). Use start=1 to read from the beginning, or start=${totalLines} to read the last line.`
+    );
+  }
+
+  const lastLine = Math.min(range.end ?? totalLines, totalLines);
+  const rendered = renderLines(lines, range.start, lastLine);
+  const { visible, firstLineTooBig } = applyByteCap(rendered);
+
+  if (firstLineTooBig !== undefined) {
+    throw new Error(
+      `Line ${firstLineTooBig.line} is ${formatBytes(firstLineTooBig.bytes)}, exceeds the ${formatBytes(OutputBudget.maxBytes)} read cap. Use bash: sed -n '${firstLineTooBig.line}p' ${path} | head -c ${OutputBudget.maxBytes}${range.start < totalLines ? `, or call read again with start=${range.start + 1} to skip this line.` : "."}`
+    );
+  }
+
+  const lastVisibleLine = visible.at(-1)?.lineNumber ?? range.start;
+  const body = visible.map((line) => line.text).join("\n");
+  const truncatedByByteCap = lastVisibleLine < lastLine;
+  const truncatedByEnd = lastVisibleLine < totalLines;
+
+  return {
+    body,
+    totalLines,
+    visibleStart: range.start,
+    visibleEnd: lastVisibleLine,
+    truncatedByByteCap,
+    truncatedByEnd,
+    hadBom,
+    ...(truncatedByEnd ? { nextStart: lastVisibleLine + 1 } : {}),
+  };
+}
+
+function renderLines(
+  lines: readonly string[],
+  start: number,
+  end: number
+): readonly RenderedLine[] {
+  const rendered: RenderedLine[] = [];
+
+  for (let lineNumber = start; lineNumber <= end; lineNumber += 1) {
+    const line = OutputBudget.truncateLine(lines[lineNumber - 1] ?? "");
+    rendered.push({
+      lineNumber,
+      text: `${lineNumber}:${line}`,
+    });
+  }
+
+  return rendered;
+}
+
+function applyByteCap(lines: readonly RenderedLine[]): {
+  readonly visible: readonly RenderedLine[];
+  readonly firstLineTooBig:
+    | { readonly line: number; readonly bytes: number }
+    | undefined;
+} {
+  const visible: RenderedLine[] = [];
+  let bytes = 0;
+
+  for (const line of lines) {
+    const separatorBytes = visible.length === 0 ? 0 : 1;
+    const lineBytes = Buffer.byteLength(line.text, "utf8");
+
+    if (visible.length === 0 && lineBytes > OutputBudget.maxBytes) {
+      return {
+        visible,
+        firstLineTooBig: { line: line.lineNumber, bytes: lineBytes },
+      };
+    }
+
+    if (
+      visible.length > 0 &&
+      bytes + separatorBytes + lineBytes > OutputBudget.maxBytes
+    ) {
+      break;
+    }
+
+    visible.push(line);
+    bytes += separatorBytes + lineBytes;
+  }
+
+  return { visible, firstLineTooBig: undefined };
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+
+  if (bytes < 1024 * 1024) {
+    return `${(bytes / 1024).toFixed(1)} KiB`;
+  }
+
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+}
+
+function rethrowFsError(error: unknown, path: string, action: string): never {
+  const code = FsErrors.code(error);
+
+  if (code === "EACCES" || code === "EPERM") {
+    throw new Error(`Permission denied reading ${path}.`);
+  }
+
+  throw new Error(
+    `Cannot ${action} ${path}: ${code ?? (error instanceof Error ? error.message : "unknown error")}.`
+  );
+}

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

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+import { formatTitlePath } from "./render";
+
+describe("formatTitlePath", () => {
+  const cwd = "/work/repo";
+
+  test("renders relative path without format suffix", () => {
+    expect(
+      formatTitlePath({
+        path: "/work/repo/src/foo.ts",
+        cwd,
+        start: undefined,
+        end: undefined,
+      })
+    ).toBe("src/foo.ts");
+  });
+
+  test("renders explicit start-end range", () => {
+    expect(
+      formatTitlePath({
+        path: "/work/repo/src/foo.ts",
+        cwd,
+        start: 40,
+        end: 80,
+      })
+    ).toBe("src/foo.ts:40-80");
+  });
+
+  test("renders start-only range", () => {
+    expect(
+      formatTitlePath({
+        path: "/work/repo/src/foo.ts",
+        cwd,
+        start: 40,
+        end: undefined,
+      })
+    ).toBe("src/foo.ts:40");
+  });
+
+  test("falls back to absolute path when outside cwd", () => {
+    expect(
+      formatTitlePath({
+        path: "/etc/hosts",
+        cwd,
+        start: undefined,
+        end: undefined,
+      })
+    ).toBe("/etc/hosts");
+  });
+
+  test("placeholder when path is missing", () => {
+    expect(
+      formatTitlePath({
+        path: undefined,
+        cwd,
+        start: undefined,
+        end: undefined,
+      })
+    ).toBe("...");
+  });
+});

package/src/extensions/read/render.ts

@@ -0,0 +1,33 @@
+import { Paths } from "../../shared/Paths";
+
+export type TitlePathOptions = {
+  readonly path: string | undefined;
+  readonly cwd: string;
+  readonly start: number | undefined;
+  readonly end: number | undefined;
+};
+
+export function formatTitlePath(options: TitlePathOptions): string {
+  const path = options.path
+    ? Paths.displayRelative(options.path, options.cwd)
+    : "...";
+  const range = formatRange(options.start, options.end);
+  return `${path}${range}`;
+}
+
+function formatRange(
+  start: number | undefined,
+  end: number | undefined
+): string {
+  if (start === undefined && end === undefined) {
+    return "";
+  }
+
+  const startLine = start ?? 1;
+
+  if (end === undefined) {
+    return `:${startLine}`;
+  }
+
+  return `:${startLine}-${end}`;
+}

package/src/extensions/read/schema.ts

@@ -0,0 +1,27 @@
+import { type Static, Type } from "typebox";
+
+export const readSchema = Type.Object({
+  path: Type.String({
+    description: "Absolute or relative path to file (resolved against cwd).",
+  }),
+  start: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      description: "First line to return, 1-indexed. Defaults to 1.",
+    })
+  ),
+  end: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      description:
+        "Last line to return, 1-indexed and inclusive. Defaults to EOF or the byte cap.",
+    })
+  ),
+});
+
+export type ReadInput = Static<typeof readSchema>;
+
+export type ReadRange = {
+  readonly start: number;
+  readonly end?: number;
+};

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

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { validateToolArguments } from "@earendil-works/pi-ai";
+import registerSubagent from "./index";
+import { subagentSchema } from "./schema";
+
+function validate(args: unknown): void {
+  validateToolArguments(
+    { name: "subagent", parameters: subagentSchema } as never,
+    {
+      type: "toolCall",
+      id: "1",
+      name: "subagent",
+      arguments: args as Record<string, unknown>,
+    }
+  );
+}
+
+describe("subagent extension registration", () => {
+  test("schema rejects an empty prompt", () => {
+    expect(() => validate({ prompt: "" })).toThrow();
+  });
+
+  test("registers one parallel tool without a prompt snippet", () => {
+    let tool:
+      | {
+          readonly name: string;
+          readonly executionMode?: string;
+          readonly promptSnippet?: string;
+          readonly parameters: unknown;
+        }
+      | undefined;
+    registerSubagent({
+      registerTool(def) {
+        tool = def;
+      },
+    } as ExtensionAPI);
+
+    expect(tool?.name).toBe("subagent");
+    expect(tool?.executionMode).toBe("parallel");
+    expect(tool?.promptSnippet).toBeUndefined();
+    expect(tool?.parameters).toBe(subagentSchema);
+  });
+});

package/src/extensions/subagent/index.ts

@@ -0,0 +1,30 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Tools } from "../../shared/Tools";
+import { renderCall, renderResult } from "./render";
+import { subagentSchema, type SubagentInput } from "./schema";
+import { runSubagent, type SubagentDetails } from "./subagent";
+
+export default function (pi: ExtensionAPI): void {
+  Tools.register<typeof subagentSchema, SubagentDetails>(pi, {
+    name: "subagent",
+    label: "subagent",
+    description:
+      "Delegate a task to an isolated subagent to keep your main context clean. The subagent inherits your currently active tools (except subagent itself) and runs in a fresh in-memory session. Multiple subagent calls in one turn run in parallel. Subagent responses are capped at 32KB; the full output is preserved in tool details.",
+    parameters: subagentSchema,
+    renderShell: "self",
+    executionMode: "parallel",
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      const input = params as SubagentInput;
+      return runSubagent(
+        input.prompt,
+        ctx,
+        signal,
+        onUpdate,
+        undefined,
+        pi.getActiveTools()
+      );
+    },
+    renderCall,
+    renderResult,
+  });
+}

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

@@ -0,0 +1,292 @@
+import { describe, expect, test } from "bun:test";
+import type {
+  AgentToolResult,
+  Theme,
+  ThemeColor,
+} from "@earendil-works/pi-coding-agent";
+import type { SubagentDetails } from "./subagent";
+import {
+  formatCallTitle,
+  formatTopLine,
+  renderCall,
+  renderResult,
+} from "./render";
+
+const stubTheme = {
+  bold: (text: string) => text,
+  italic: (text: string) => text,
+  strikethrough: (text: string) => text,
+  underline: (text: string) => text,
+  fg: (_color: string, text: string) => text,
+} as unknown as Theme;
+
+type ColorCall = {
+  readonly color: ThemeColor;
+  readonly text: string;
+};
+
+function tracingTheme(): {
+  readonly theme: Theme;
+  readonly calls: ColorCall[];
+} {
+  const calls: ColorCall[] = [];
+  return {
+    calls,
+    theme: {
+      bold: (text: string) => text,
+      italic: (text: string) => text,
+      strikethrough: (text: string) => text,
+      underline: (text: string) => text,
+      fg: (color: ThemeColor, text: string) => {
+        calls.push({ color, text });
+        return text;
+      },
+    } as unknown as Theme,
+  };
+}
+
+const baseDetails: SubagentDetails = {
+  returnedOutput: "body",
+  fullOutput: "body",
+  outputTruncated: false,
+  omittedBytes: 0,
+  usage: {
+    input: 10,
+    output: 5,
+    cacheRead: 2,
+    cacheWrite: 0,
+    cost: 0.23,
+    turns: 3,
+    contextTokens: 4000,
+  },
+  toolCalls: [{ name: "read", isError: false }],
+  activeToolNames: [],
+  lastToolName: "read",
+  stopReason: "stop",
+  errorMessage: undefined,
+  model: "deepseek-v4-flash",
+  contextWindow: 1_000_000,
+  topLine: "$0.23 ⬝ 0.4%/1.0M ⬝ deepseek-v4-flash ⬝ 3 turns ⬝ 1 tool",
+};
+
+function result(text: string): AgentToolResult<SubagentDetails> {
+  return { content: [{ type: "text", text }], details: baseDetails };
+}
+
+describe("subagent render formatting", () => {
+  test("call title uses the first line without truncating", () => {
+    const long = `${"x".repeat(140)}\nsecond`;
+
+    expect(formatCallTitle(long)).toBe("x".repeat(140));
+  });
+
+  test("top line includes cost, context, model, and activity", () => {
+    expect(formatTopLine(baseDetails)).toBe(
+      "$0.23 ⬝ 0.4%/1.0M ⬝ deepseek-v4-flash ⬝ 3 turns ⬝ 1 tool"
+    );
+  });
+
+  test("call title renders prompt markdown", () => {
+    const component = renderCall(
+      { prompt: "Review **bold** and `code`" },
+      stubTheme,
+      {
+        lastComponent: undefined,
+        isPartial: false,
+        isError: false,
+      }
+    );
+
+    expect(component.render(80)[0]?.trimEnd()).toBe(
+      " ▪ Subagent: Review bold and code"
+    );
+  });
+
+  test("call title uses the default color for prompt text", () => {
+    const rendered = tracingTheme();
+    renderCall({ prompt: "plain prompt" }, rendered.theme, {
+      lastComponent: undefined,
+      isPartial: false,
+      isError: false,
+    }).render(80);
+
+    expect(rendered.calls).not.toContainEqual({
+      color: "toolTitle",
+      text: "plain prompt",
+    });
+  });
+
+  test("call title colors the Subagent label by running status", () => {
+    const pending = tracingTheme();
+    renderCall({ prompt: "investigate" }, pending.theme, {
+      lastComponent: undefined,
+      isPartial: true,
+      isError: false,
+    }).render(80);
+
+    expect(pending.calls).toContainEqual({
+      color: "warning",
+      text: "Subagent",
+    });
+
+    const done = tracingTheme();
+    renderCall({ prompt: "investigate" }, done.theme, {
+      lastComponent: undefined,
+      isPartial: false,
+      isError: false,
+    }).render(80);
+
+    expect(done.calls).toContainEqual({ color: "accent", text: "Subagent" });
+  });
+
+  test("top line uses muted dots with accent or warning content", () => {
+    const done = tracingTheme();
+    renderResult(
+      result("body"),
+      { expanded: false, isPartial: false },
+      done.theme,
+      { lastComponent: undefined, isPartial: false, isError: false }
+    ).render(80);
+
+    expect(done.calls).toContainEqual({ color: "accent", text: "$0.23 " });
+    expect(done.calls).toContainEqual({ color: "muted", text: "⬝" });
+
+    const running = tracingTheme();
+    renderResult(
+      {
+        content: [{ type: "text", text: "ignored body" }],
+        details: { ...baseDetails, stopReason: undefined },
+      },
+      { expanded: false, isPartial: true },
+      running.theme,
+      { lastComponent: undefined, isPartial: true, isError: false }
+    ).render(80);
+
+    expect(running.calls).toContainEqual({ color: "warning", text: "$0.23 " });
+    expect(running.calls).toContainEqual({ color: "muted", text: "⬝" });
+  });
+
+  test("partial render displays only the running top line", () => {
+    const runningDetails: SubagentDetails = {
+      ...baseDetails,
+      toolCalls: [],
+      activeToolNames: ["grep"],
+      stopReason: undefined,
+      topLine: "$0.23 ⬝ 0.4%/1.0M ⬝ deepseek-v4-flash ⬝ 3 turns ⬝ grep",
+    };
+    const component = renderResult(
+      {
+        content: [{ type: "text", text: "ignored body" }],
+        details: runningDetails,
+      },
+      { expanded: false, isPartial: true },
+      stubTheme,
+      { lastComponent: undefined, isPartial: true, isError: false }
+    );
+
+    expect(component.render(80)).toEqual([` │ ${runningDetails.topLine}`]);
+  });
+
+  test("collapsed done render hides the final message", () => {
+    const body = Array.from({ length: 12 }, (_, i) => `line ${i + 1}`).join(
+      "\n"
+    );
+    const component = renderResult(
+      result(body),
+      { expanded: false, isPartial: false },
+      stubTheme,
+      { lastComponent: undefined, isPartial: false, isError: false }
+    );
+
+    expect(component.render(80)).toEqual([` │ ${baseDetails.topLine}`]);
+  });
+
+  test("expanded done render keeps the top line above the final message", () => {
+    const component = renderResult(
+      result("line 1\nline 2"),
+      { expanded: true, isPartial: false },
+      stubTheme,
+      { lastComponent: undefined, isPartial: false, isError: false }
+    );
+
+    expect(component.render(80)).toEqual([
+      ` │ ${baseDetails.topLine}`,
+      " │ line 1",
+      " │ line 2",
+    ]);
+  });
+
+  test("expanded done render renders final message markdown", () => {
+    const component = renderResult(
+      result("Final **answer** and `code`"),
+      { expanded: true, isPartial: false },
+      stubTheme,
+      { lastComponent: undefined, isPartial: false, isError: false }
+    );
+
+    expect(component.render(80)).toEqual([
+      ` │ ${baseDetails.topLine}`,
+      " │ Final answer and code",
+    ]);
+  });
+
+  test("expanded done render uses configured markdown theme tokens", () => {
+    const rendered = tracingTheme();
+    renderResult(
+      result(
+        [
+          "# Heading",
+          "",
+          "[docs](https://example.test)",
+          "",
+          "`inline`",
+          "",
+          "> quoted",
+          "",
+          "- item",
+          "",
+          "```",
+          "plain code",
+          "```",
+          "",
+          "---",
+        ].join("\n")
+      ),
+      { expanded: true, isPartial: false },
+      rendered.theme,
+      { lastComponent: undefined, isPartial: false, isError: false }
+    ).render(120);
+
+    const colors = new Set(rendered.calls.map((call) => call.color));
+    const expectedColors = [
+      "mdHeading",
+      "mdLink",
+      "mdCode",
+      "mdQuote",
+      "mdQuoteBorder",
+      "mdListBullet",
+      "mdCodeBlock",
+      "mdCodeBlockBorder",
+      "mdHr",
+    ] satisfies readonly ThemeColor[];
+
+    for (const color of expectedColors) {
+      expect(colors.has(color)).toBe(true);
+    }
+  });
+
+  test("expanded done render uses the default color for final message text", () => {
+    const rendered = tracingTheme();
+    renderResult(
+      result("plain final"),
+      { expanded: true, isPartial: false },
+      rendered.theme,
+      { lastComponent: undefined, isPartial: false, isError: false }
+    ).render(80);
+
+    expect(rendered.calls).not.toContainEqual({
+      color: "toolOutput",
+      text: "plain final",
+    });
+  });
+});