pim-agent 0.0.1 → 0.10.0

package/packages/core/src/extensions/grep/schema.ts

@@ -0,0 +1,92 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { type Static, Type } from "typebox";
+
+export const GREP_HEAD_LIMIT_MAX = 1000;
+export const GREP_CONTEXT_MAX = 20;
+
+export const GREP_OUTPUT_MODES = [
+  "files_with_matches",
+  "content",
+  "count",
+] as const;
+
+export const GREP_PATH_FORMATS = ["relative", "absolute"] as const;
+
+export const grepSchema = Type.Object({
+  pattern: Type.String({
+    description: "JavaScript regex source, without /.../ delimiters.",
+  }),
+  path: Type.Optional(
+    Type.String({
+      description:
+        "Absolute or relative path to file/directory (resolved against cwd). Defaults to cwd.",
+    })
+  ),
+  glob: Type.Optional(
+    Type.String({
+      description:
+        "Relative glob filter under path when path is a directory. Brace expansion spans sibling dirs (eg. {src,docs}/**/*.ts); a bare directory (eg. src/tools) expands to everything under it. Gitignored files and dotfiles are skipped during directory scans unless includeIgnored/includeDotfiles is true.",
+    })
+  ),
+  exclude: Type.Optional(
+    Type.Array(Type.String(), {
+      description:
+        "Glob patterns to exclude from directory searches, relative to path (eg. **/*.test.ts or dist/**).",
+    })
+  ),
+  outputMode: Type.Optional(
+    StringEnum(GREP_OUTPUT_MODES, {
+      description:
+        "`files_with_matches` (default): returns file paths. `content`: returns path:line:text. `count`: returns path:count.",
+    })
+  ),
+  matchAcrossLines: Type.Optional(
+    Type.Boolean({
+      description:
+        "Search whole files so one match can span line breaks. Defaults to false.",
+    })
+  ),
+  context: Type.Optional(
+    Type.Integer({
+      minimum: 0,
+      maximum: GREP_CONTEXT_MAX,
+      description:
+        "For outputMode='content', include this many lines before and after each match. Defaults to 0.",
+    })
+  ),
+  includeDotfiles: Type.Optional(
+    Type.Boolean({
+      description:
+        "Include dot-prefixed files and directories such as .env or .github during directory scans. Defaults to false.",
+    })
+  ),
+  includeIgnored: Type.Optional(
+    Type.Boolean({
+      description:
+        "Include gitignored and normally ignored paths such as node_modules during directory scans. Defaults to false.",
+    })
+  ),
+  pathFormat: Type.Optional(
+    StringEnum(GREP_PATH_FORMATS, {
+      description:
+        "`relative` (default): output paths relative to cwd when possible. `absolute`: output absolute paths.",
+    })
+  ),
+  caseInsensitive: Type.Optional(
+    Type.Boolean({
+      description: "Search case-insensitively. Defaults to false.",
+    })
+  ),
+  headLimit: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      maximum: GREP_HEAD_LIMIT_MAX,
+      description: `Maximum returned items. Defaults to ${GREP_HEAD_LIMIT_MAX}.`,
+    })
+  ),
+});
+
+export type GrepInput = Static<typeof grepSchema>;
+
+export type GrepOutputMode = (typeof GREP_OUTPUT_MODES)[number];
+export type GrepPathFormat = (typeof GREP_PATH_FORMATS)[number];

package/packages/core/src/extensions/read/ImageMemory.ts

@@ -0,0 +1,42 @@
+import { PimSettings } from "../../shared/PimSettings";
+import type { ReadImageDetails } from "./schema";
+
+/** What the file looked like when its picture was last sent to the model. */
+export type ImageStamp = {
+  readonly mtimeMs: number;
+  readonly size: number;
+};
+
+type Sent = ImageStamp & { readonly details: ReadImageDetails };
+
+/**
+ * The pictures already in this conversation, so a screenshot loop pays the
+ * resize once. One instance per extension factory, which is one per session;
+ * a resumed session starts empty and re-sends every image once.
+ */
+export class ImageMemory {
+  private readonly sent = new Map<string, Sent>();
+
+  /** The settings flag is the escape hatch, so it is read only once a picture repeats. */
+  async recall(
+    path: string,
+    stamp: ImageStamp
+  ): Promise<ReadImageDetails | undefined> {
+    const sent = this.sent.get(path);
+
+    if (
+      sent === undefined ||
+      sent.mtimeMs !== stamp.mtimeMs ||
+      sent.size !== stamp.size
+    ) {
+      return undefined;
+    }
+
+    const { dedupImages } = await PimSettings.get("read");
+    return dedupImages ? sent.details : undefined;
+  }
+
+  remember(path: string, stamp: ImageStamp, details: ReadImageDetails): void {
+    this.sent.set(path, { ...stamp, details });
+  }
+}

package/packages/core/src/extensions/read/image.ts

@@ -0,0 +1,57 @@
+import {
+  Images,
+  type NormalisedImage,
+  type VisionModel,
+} from "../../shared/Images";
+import type { ReadImageDetails } from "./schema";
+
+export type ImageReadOutcome = {
+  readonly kind: "image";
+  readonly image: NormalisedImage;
+  readonly details: ReadImageDetails;
+};
+
+/** The picture is already in the transcript: the row still draws it, the model is only told so. */
+export type UnchangedImageReadOutcome = {
+  readonly kind: "image-unchanged";
+  readonly details: ReadImageDetails;
+};
+
+/** Bytes that are a picture, or a name that claims one — a claim that fails is a diagnostic, not text. */
+export function isImageRead(head: Uint8Array, path: string): boolean {
+  return Images.sniff(head) !== null || Images.looksLikeImageName(path);
+}
+
+/** Both refusals that must land before the file is pulled into memory. */
+export function assertImageReadable(
+  path: string,
+  sizeOnDisk: number,
+  model: VisionModel | undefined
+): void {
+  if (model !== undefined && !model.input.includes("image")) {
+    throw new Error(
+      `Cannot read images: the current model (${model.id}) has no vision input. Switch models with /model, or inspect it with bash: file ${path}`
+    );
+  }
+  Images.assertWithinSourceCap(sizeOnDisk, path);
+}
+
+export async function readImage(
+  bytes: Uint8Array,
+  path: string
+): Promise<ImageReadOutcome> {
+  const image = await Images.normalise(bytes, path);
+  return {
+    kind: "image",
+    image,
+    details: {
+      kind: "image",
+      absolutePath: path,
+      ...Images.detailsOf(image),
+    },
+  };
+}
+
+export function unchangedImageNote(path: string): string {
+  return `[read tool: ${path} is unchanged since it was read earlier in this conversation; use the image already above. Touch the file or read a different path to force a re-send.]`;
+}

package/packages/core/src/extensions/read/index.ts

@@ -0,0 +1,88 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Images } from "../../shared/Images";
+import { Paths } from "../../shared/Paths";
+import { Tools } from "../../shared/Tools";
+import { unchangedImageNote } from "./image";
+import { ImageMemory } from "./ImageMemory";
+import { buildReadRange, readFile } from "./read";
+import { readView } from "./render";
+import { type ReadDetails, type ReadInput, readSchema } from "./schema";
+
+export default function (pi: ExtensionAPI): void {
+  const memory = new ImageMemory();
+
+  Tools.register<typeof readSchema, ReadDetails>(pi, {
+    name: "read",
+    label: "read",
+    description:
+      "Read a local UTF-8 text file or image (png, jpeg, gif, webp). " +
+      "Text output is `LINE:CONTENT` with no space after the colon.",
+    parameters: readSchema,
+    renderShell: "self",
+    effect: { kind: "readOnly" },
+    executionMode: "parallel",
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      const { path, start, end } = params as ReadInput;
+
+      if (signal?.aborted) {
+        throw new Error("Read aborted before execution.");
+      }
+
+      const range = buildReadRange(start, end);
+      const absolutePath = Paths.resolve(path, ctx.cwd);
+      const outcome = await readFile(absolutePath, range, {
+        model: ctx.model,
+        memory,
+      });
+
+      if (outcome.kind === "image") {
+        return {
+          content: Images.contentOf(
+            outcome.image,
+            Images.noteOf(outcome.image)
+          ),
+          details: outcome.details,
+        };
+      }
+
+      if (outcome.kind === "image-unchanged") {
+        return {
+          content: [
+            {
+              type: "text",
+              text: unchangedImageNote(outcome.details.absolutePath),
+            },
+          ],
+          details: outcome.details,
+        };
+      }
+
+      const content: Array<{ type: "text"; text: string }> = [
+        { type: "text", text: outcome.body },
+      ];
+
+      if (outcome.truncatedByEnd && outcome.nextStart !== undefined) {
+        content.push({
+          type: "text",
+          text: `[read tool: showing lines ${outcome.visibleStart}-${outcome.visibleEnd} of ${outcome.totalLines}; call read again with start=${outcome.nextStart} to continue.]`,
+        });
+      }
+
+      return {
+        content,
+        details: {
+          kind: "text",
+          absolutePath,
+          totalLines: outcome.totalLines,
+          visibleStart: outcome.visibleStart,
+          visibleEnd: outcome.visibleEnd,
+          truncatedByByteCap: outcome.truncatedByByteCap,
+          truncatedByEnd: outcome.truncatedByEnd,
+          hadBom: outcome.hadBom,
+          nextStart: outcome.nextStart,
+        },
+      };
+    },
+    toViewModel: readView,
+  });
+}

package/packages/core/src/extensions/read/read.ts

@@ -0,0 +1,191 @@
+import { Format } from "../../shared/Format";
+import { FsErrors } from "../../shared/FsErrors";
+import type { VisionModel } from "../../shared/Images";
+import { Lines } from "../../shared/Lines";
+import { OutputBudget } from "../../shared/OutputBudget";
+import {
+  assertImageReadable,
+  type ImageReadOutcome,
+  isImageRead,
+  readImage,
+  type UnchangedImageReadOutcome,
+} from "./image";
+import type { ImageMemory } from "./ImageMemory";
+import type { ReadRange } from "./schema";
+
+export type TextReadOutcome = {
+  readonly kind: "text";
+  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 type ReadOutcome =
+  | TextReadOutcome
+  | ImageReadOutcome
+  | UnchangedImageReadOutcome;
+
+export type ReadOptions = {
+  readonly model?: VisionModel;
+  /** The pictures this session has already sent; absent when the caller keeps none. */
+  readonly memory?: ImageMemory;
+};
+
+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,
+  options: ReadOptions = {}
+): 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);
+
+  // One head serves both verdicts: the signature is in its first bytes, a NUL anywhere in it.
+  const head = await bytesOf(file.slice(0, Lines.binarySniffBytes), path);
+
+  if (isImageRead(head, path)) {
+    assertImageReadable(path, metadata.size, options.model);
+
+    const stamp = { mtimeMs: metadata.mtimeMs, size: metadata.size };
+    const remembered = await options.memory?.recall(path, stamp);
+
+    if (remembered !== undefined) {
+      return {
+        kind: "image-unchanged",
+        details: { ...remembered, deduped: true },
+      };
+    }
+
+    const outcome = await readImage(await bytesOf(file, path), path);
+    options.memory?.remember(path, stamp, outcome.details);
+    return outcome;
+  }
+
+  if (Lines.isBinaryBytes(head)) {
+    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.`
+    );
+  }
+
+  const bytes = await bytesOf(file, path);
+  const hadBom = Lines.hasUtf8Bom(bytes);
+  const text = new TextDecoder("utf-8").decode(bytes);
+
+  return renderText(Lines.stripUtf8Bom(text), range, path, hadBom);
+}
+
+async function bytesOf(file: Bun.BunFile, path: string): Promise<Uint8Array> {
+  try {
+    return await file.bytes();
+  } catch (error) {
+    rethrowFsError(error, path, "read");
+  }
+}
+
+function renderText(
+  content: string,
+  range: ReadRange,
+  path: string,
+  hadBom: boolean
+): TextReadOutcome {
+  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 visible: string[] = [];
+  let bytes = 0;
+  let lastVisibleLine = range.start;
+
+  for (let lineNumber = range.start; lineNumber <= lastLine; lineNumber += 1) {
+    const text = `${lineNumber}:${OutputBudget.truncateLine(lines[lineNumber - 1] ?? "")}`;
+    const separatorBytes = visible.length === 0 ? 0 : 1;
+    const lineBytes = Buffer.byteLength(text, "utf8");
+
+    if (visible.length === 0) {
+      if (lineBytes > OutputBudget.maxBytes) {
+        throw new Error(
+          `Line ${lineNumber} is ${Format.bytes(lineBytes)}, exceeds the ${Format.bytes(OutputBudget.maxBytes)} read cap. Use bash: sed -n '${lineNumber}p' ${path} | head -c ${OutputBudget.maxBytes}${range.start < totalLines ? `, or call read again with start=${range.start + 1} to skip this line.` : "."}`
+        );
+      }
+    } else if (bytes + separatorBytes + lineBytes > OutputBudget.maxBytes) {
+      break;
+    }
+
+    visible.push(text);
+    bytes += separatorBytes + lineBytes;
+    lastVisibleLine = lineNumber;
+  }
+
+  const body = visible.join("\n");
+  const truncatedByByteCap = lastVisibleLine < lastLine;
+  const truncatedByEnd = lastVisibleLine < totalLines;
+
+  return {
+    kind: "text",
+    body,
+    totalLines,
+    visibleStart: range.start,
+    visibleEnd: lastVisibleLine,
+    truncatedByByteCap,
+    truncatedByEnd,
+    hadBom,
+    ...(truncatedByEnd ? { nextStart: lastVisibleLine + 1 } : {}),
+  };
+}
+
+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/packages/core/src/extensions/read/render.ts

@@ -0,0 +1,58 @@
+import { Paths } from "../../shared/Paths";
+import { Renderer } from "../../shared/Renderer";
+import type { ToolViewInput } from "../../shared/Tools";
+import { Painting } from "../../view/Painting";
+import type { ToolView, ViewBlock } from "../../view/ViewBlock";
+import type { ReadDetails, ReadInput, readSchema } from "./schema";
+
+export type ReadViewInput = ToolViewInput<typeof readSchema, ReadDetails>;
+
+export function readView({ args, result, cwd }: ReadViewInput): ToolView {
+  const input: Partial<ReadInput> = args ?? {};
+  const details = result?.details;
+  const image = details?.kind === "image" ? details : undefined;
+  const path = Paths.titleOr(input.path, cwd);
+  return {
+    label: "Read",
+    icon: "file",
+    title: [image ? { kind: "file", path } : titleBlock(input, details, path)],
+    body: image
+      ? Painting.imageBlocks(
+          image,
+          path,
+          image.deduped ? [["reused", "unchanged since the earlier read"]] : []
+        )
+      : [{ kind: "text", text: Renderer.firstText(result) }],
+  };
+}
+
+function titleBlock(
+  input: Partial<ReadInput>,
+  details: ReadDetails | undefined,
+  path: string
+): ViewBlock {
+  const visible = visibleRange(details);
+
+  if (visible) {
+    return { kind: "file", path, range: visible };
+  }
+
+  if (input.start === undefined && input.end === undefined) {
+    return { kind: "file", path };
+  }
+
+  return { kind: "file", path, range: [input.start ?? 1, input.end] };
+}
+
+/** Legacy sessions predate the tag, so an untagged result is read for the range it may still carry. */
+function visibleRange(
+  details: ReadDetails | undefined
+): readonly [number, number] | undefined {
+  if (details === undefined || details.kind === "image") {
+    return undefined;
+  }
+  const { visibleStart, visibleEnd } = details;
+  return typeof visibleStart === "number" && typeof visibleEnd === "number"
+    ? [visibleStart, visibleEnd]
+    : undefined;
+}

package/packages/core/src/extensions/read/schema.ts

@@ -0,0 +1,49 @@
+import { type Static, Type } from "typebox";
+import type { ImageDetails } from "../../shared/Images";
+
+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;
+};
+
+export type ReadTextDetails = {
+  readonly kind: "text";
+  readonly absolutePath: string;
+  readonly totalLines: number;
+  readonly visibleStart: number;
+  readonly visibleEnd: number;
+  readonly truncatedByByteCap: boolean;
+  readonly truncatedByEnd: boolean;
+  readonly hadBom: boolean;
+  readonly nextStart?: number;
+};
+
+export type ReadImageDetails = ImageDetails & {
+  readonly kind: "image";
+  readonly absolutePath: string;
+  /** Sent earlier in this conversation and unchanged since, so only the note went to the model. */
+  readonly deduped?: boolean;
+};
+
+export type ReadDetails = ReadTextDetails | ReadImageDetails;

package/packages/core/src/extensions/subagent/index.ts

@@ -0,0 +1,33 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { SubagentLogs } from "../../shared/SubagentLogs";
+import { Tools } from "../../shared/Tools";
+import { subagentView } from "./render";
+import { subagentSchema, type SubagentInput } from "./schema";
+import { runSubagent, type SubagentDetails } from "./subagent";
+
+export default function (pi: ExtensionAPI): void {
+  SubagentLogs.installSweeper();
+  Tools.register<typeof subagentSchema, SubagentDetails>(pi, {
+    name: "subagent",
+    label: "subagent",
+    description:
+      "Run a task in an isolated subagent with a fresh context. " +
+      "The subagent inherits the currently active tools, except subagent itself. " +
+      "Multiple subagent calls in one turn run in parallel. " +
+      "Subagent output returned to the main agent is capped at 32KB.",
+    parameters: subagentSchema,
+    renderShell: "self",
+    effect: { kind: "unbounded" },
+    executionMode: "parallel",
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const input = params as SubagentInput;
+      return runSubagent(input.prompt, ctx, {
+        callId: toolCallId,
+        signal,
+        onUpdate,
+        activeToolNames: pi.getActiveTools(),
+      });
+    },
+    toViewModel: subagentView,
+  });
+}