@tt-a1i/openpi 0.3.1 → 0.5.0

package/extensions/git-read/index.ts

@@ -0,0 +1,328 @@
+/**
+ * git-read — read-only git inspection tools for pi.
+ *
+ * Registers git_show, git_diff, and git_log: the minimal surface a review or
+ * exploration agent needs from git history without any write path. All three
+ * share the file-search output discipline (bounded preview, complete output
+ * persisted up to 10 MiB) and every user-controlled argument is validated
+ * before it reaches a child process, so a revision or path can never inject
+ * flags or escape the repository. The tools are child-safe by design and are
+ * classified in CHILD_SAFE_PACKAGE_TOOL_NAMES so review/advisor subagents can
+ * read diffs their tool boundary otherwise excludes (issue #61).
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type {
+  AgentToolResult,
+  ExtensionAPI,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Cause, Effect, Exit } from "effect";
+import { Type } from "typebox";
+import { formatCapturedOutput } from "../file-search/src/output.ts";
+import { sanitizeTerminalText } from "../shared/terminal-text.ts";
+import {
+  OPENPI_TOOL_SURFACE,
+  patchOwnedTools,
+} from "../shared/tool-surface.ts";
+import {
+  buildDiffArgs,
+  buildLogArgs,
+  buildShowArgs,
+  type GitDiffParams,
+  type GitLogParams,
+  type GitShowParams,
+  InvalidPathError,
+  InvalidRevisionError,
+} from "./src/args.ts";
+import { type GitOutcome, runGit } from "./src/process.ts";
+import {
+  GIT_DIFF_PARAMETER_DESCRIPTIONS,
+  GIT_DIFF_PROMPT_GUIDELINES,
+  GIT_DIFF_PROMPT_SNIPPET,
+  GIT_DIFF_TOOL_DESCRIPTION,
+  GIT_LOG_PARAMETER_DESCRIPTIONS,
+  GIT_LOG_PROMPT_GUIDELINES,
+  GIT_LOG_PROMPT_SNIPPET,
+  GIT_LOG_TOOL_DESCRIPTION,
+  GIT_SHOW_PARAMETER_DESCRIPTIONS,
+  GIT_SHOW_PROMPT_GUIDELINES,
+  GIT_SHOW_PROMPT_SNIPPET,
+  GIT_SHOW_TOOL_DESCRIPTION,
+} from "./src/prompt.ts";
+
+interface GitToolDetails {
+  readonly command: string;
+  readonly truncated: boolean;
+  readonly lineCount?: number;
+  readonly fullOutputPath?: string;
+}
+
+function causeMessage(cause: unknown): string {
+  if (
+    cause instanceof InvalidRevisionError ||
+    cause instanceof InvalidPathError
+  ) {
+    return cause.message;
+  }
+  if (cause instanceof Error) return cause.message;
+  return String(cause);
+}
+
+function unwrapToolExit<A, E>(exit: Exit.Exit<A, E>, tool: string) {
+  if (Exit.isSuccess(exit)) return exit.value;
+  if (Cause.hasInterruptsOnly(exit.cause)) {
+    throw new Error(`${tool} was cancelled.`);
+  }
+  throw new Error(causeMessage(Cause.squash(exit.cause)));
+}
+
+function gitResult(
+  outcome: GitOutcome,
+  command: string,
+): AgentToolResult<GitToolDetails> {
+  const formatted = formatCapturedOutput(outcome.output);
+  return {
+    content: [
+      {
+        type: "text",
+        text: sanitizeTerminalText(formatted.text) || "(no output)",
+      },
+    ],
+    details: {
+      command,
+      truncated: formatted.truncated,
+      lineCount: formatted.lineCount,
+      fullOutputPath: formatted.fullOutputPath,
+    },
+  };
+}
+
+function showParameters() {
+  return Type.Object({
+    revision: Type.String({
+      description: GIT_SHOW_PARAMETER_DESCRIPTIONS.revision,
+    }),
+    path: Type.Optional(
+      Type.String({ description: GIT_SHOW_PARAMETER_DESCRIPTIONS.path }),
+    ),
+  });
+}
+
+function diffParameters() {
+  return Type.Object({
+    from: Type.Optional(
+      Type.String({ description: GIT_DIFF_PARAMETER_DESCRIPTIONS.from }),
+    ),
+    to: Type.Optional(
+      Type.String({ description: GIT_DIFF_PARAMETER_DESCRIPTIONS.to }),
+    ),
+    staged: Type.Optional(
+      Type.Boolean({ description: GIT_DIFF_PARAMETER_DESCRIPTIONS.staged }),
+    ),
+    stat: Type.Optional(
+      Type.Boolean({ description: GIT_DIFF_PARAMETER_DESCRIPTIONS.stat }),
+    ),
+    path: Type.Optional(
+      Type.String({ description: GIT_DIFF_PARAMETER_DESCRIPTIONS.path }),
+    ),
+  });
+}
+
+function logParameters() {
+  return Type.Object({
+    revision: Type.Optional(
+      Type.String({ description: GIT_LOG_PARAMETER_DESCRIPTIONS.revision }),
+    ),
+    file: Type.Optional(
+      Type.String({ description: GIT_LOG_PARAMETER_DESCRIPTIONS.file }),
+    ),
+    limit: Type.Optional(
+      Type.Integer({
+        description: GIT_LOG_PARAMETER_DESCRIPTIONS.limit,
+        minimum: 1,
+        maximum: 1000,
+      }),
+    ),
+    oneline: Type.Optional(
+      Type.Boolean({ description: GIT_LOG_PARAMETER_DESCRIPTIONS.oneline }),
+    ),
+  });
+}
+
+function displayRevision(value: string | undefined, fallback = "HEAD") {
+  return value === undefined || value.trim() === "" ? fallback : value.trim();
+}
+
+export default function gitReadTools(pi: ExtensionAPI) {
+  const resultDirectories = new Set<string>();
+  const rememberOutput = (outcome: GitOutcome) => {
+    if (outcome.output.fullOutputPath) {
+      resultDirectories.add(path.dirname(outcome.output.fullOutputPath));
+    }
+  };
+
+  pi.on("session_start", () => {
+    patchOwnedTools(pi, "gitRead", {
+      enable: OPENPI_TOOL_SURFACE.gitRead.entry,
+    });
+  });
+
+  pi.on("session_shutdown", () => {
+    for (const directory of resultDirectories) {
+      try {
+        fs.rmSync(directory, { recursive: true, force: true });
+      } catch {
+        // Temporary git artifacts are best-effort cleanup.
+      }
+    }
+    resultDirectories.clear();
+  });
+
+  pi.registerTool<ReturnType<typeof showParameters>, GitToolDetails>({
+    name: "git_show",
+    label: "Git Show",
+    description: GIT_SHOW_TOOL_DESCRIPTION,
+    promptSnippet: GIT_SHOW_PROMPT_SNIPPET,
+    promptGuidelines: GIT_SHOW_PROMPT_GUIDELINES,
+    parameters: showParameters(),
+
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const exit = await Effect.runPromiseExit(
+        Effect.gen(function* () {
+          const args = buildShowArgs(params as GitShowParams);
+          const outcome = yield* runGit(args, ctx.cwd);
+          rememberOutput(outcome);
+          return gitResult(outcome, args.join(" "));
+        }),
+        signal ? { signal } : undefined,
+      );
+      return unwrapToolExit(exit, "git_show");
+    },
+
+    renderCall(args) {
+      return new Text(`git show ${displayRevision(args.revision)}`, 0, 0);
+    },
+
+    renderResult(result, { expanded }, theme) {
+      const details = result.details;
+      let text = details?.command
+        ? `showed ${details.lineCount ?? 0} lines`
+        : "shown";
+      if (details?.truncated) text += " (truncated)";
+      if (expanded)
+        text += expandedResultPreview(result, details?.fullOutputPath, theme);
+      return new Text(text, 0, 0);
+    },
+  });
+
+  pi.registerTool<ReturnType<typeof diffParameters>, GitToolDetails>({
+    name: "git_diff",
+    label: "Git Diff",
+    description: GIT_DIFF_TOOL_DESCRIPTION,
+    promptSnippet: GIT_DIFF_PROMPT_SNIPPET,
+    promptGuidelines: GIT_DIFF_PROMPT_GUIDELINES,
+    parameters: diffParameters(),
+
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const exit = await Effect.runPromiseExit(
+        Effect.gen(function* () {
+          const args = buildDiffArgs(params as GitDiffParams);
+          const outcome = yield* runGit(args, ctx.cwd);
+          rememberOutput(outcome);
+          return gitResult(outcome, args.join(" "));
+        }),
+        signal ? { signal } : undefined,
+      );
+      return unwrapToolExit(exit, "git_diff");
+    },
+
+    renderCall(args) {
+      const from = displayRevision(
+        args.from,
+        args.staged ? "HEAD (staged)" : "index",
+      );
+      const to = args.to ? displayRevision(args.to) : "worktree";
+      let text = `git diff ${from} → ${to}`;
+      if (args.stat) text += " (stat)";
+      if (args.path) text += ` ${args.path}`;
+      return new Text(text, 0, 0);
+    },
+
+    renderResult(result, { expanded }, theme) {
+      const details = result.details;
+      let text = details?.command
+        ? `${details.lineCount ?? 0} diff lines`
+        : "diffed";
+      if (details?.truncated) text += " (truncated)";
+      if (expanded)
+        text += expandedResultPreview(result, details?.fullOutputPath, theme);
+      return new Text(text, 0, 0);
+    },
+  });
+
+  pi.registerTool<ReturnType<typeof logParameters>, GitToolDetails>({
+    name: "git_log",
+    label: "Git Log",
+    description: GIT_LOG_TOOL_DESCRIPTION,
+    promptSnippet: GIT_LOG_PROMPT_SNIPPET,
+    promptGuidelines: GIT_LOG_PROMPT_GUIDELINES,
+    parameters: logParameters(),
+
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const exit = await Effect.runPromiseExit(
+        Effect.gen(function* () {
+          const args = buildLogArgs(params as GitLogParams);
+          const outcome = yield* runGit(args, ctx.cwd);
+          rememberOutput(outcome);
+          return gitResult(outcome, args.join(" "));
+        }),
+        signal ? { signal } : undefined,
+      );
+      return unwrapToolExit(exit, "git_log");
+    },
+
+    renderCall(args) {
+      let text = `git log ${displayRevision(args.revision)}`;
+      if (args.file) text += ` -- ${args.file}`;
+      if (args.limit !== undefined) text += ` -n ${args.limit}`;
+      return new Text(text, 0, 0);
+    },
+
+    renderResult(result, { expanded }, theme) {
+      const details = result.details;
+      let text = details?.command
+        ? `${details.lineCount ?? 0} output lines`
+        : "logged";
+      if (details?.truncated) text += " (truncated)";
+      if (expanded)
+        text += expandedResultPreview(result, details?.fullOutputPath, theme);
+      return new Text(text, 0, 0);
+    },
+  });
+}
+
+const EXPANDED_PREVIEW_LINES = 20;
+
+export function expandedResultPreview(
+  result: { content: { type: string; text?: string }[] },
+  fullOutputPath: string | undefined,
+  theme: { fg(color: string, text: string): string },
+) {
+  let text = "";
+  const content = result.content[0];
+  if (content?.type === "text" && content.text) {
+    const lines = sanitizeTerminalText(content.text).split("\n");
+    for (const line of lines.slice(0, EXPANDED_PREVIEW_LINES)) {
+      text += `\n${theme.fg("dim", line)}`;
+    }
+    if (lines.length > EXPANDED_PREVIEW_LINES) {
+      text += `\n${theme.fg("muted", `... ${lines.length - EXPANDED_PREVIEW_LINES} more lines`)}`;
+    }
+  }
+  if (fullOutputPath) {
+    text += `\n${theme.fg("dim", `Full output: ${sanitizeTerminalText(fullOutputPath)}`)}`;
+  }
+  return text;
+}

package/extensions/git-read/src/args.ts

@@ -0,0 +1,171 @@
+/**
+ * Read-only git commands: pure argv construction.
+ *
+ * Everything here is synchronous and side-effect free so the exact argv
+ * passed to the child process can be asserted in tests. Revision and path
+ * inputs are validated against strict shapes before they are ever placed
+ * in an argument list, and every user-controlled value goes after a `--`
+ * separator so it can never be parsed as a flag. Only argv subcommands that
+ * cannot write are reachable at all.
+ */
+
+export const GIT_TIMEOUT_MS = 10_000;
+export const GIT_LOG_DEFAULT_LIMIT = 100;
+export const GIT_LOG_MAX_LIMIT = 1000;
+
+/** Revisions may be a sha-ish hex string, HEAD~n, HEAD^n, or a plain name; a
+ * leading `-` is rejected so a revision can never smuggle a git flag. */
+const REVISION_PATTERN =
+  /^(?:[0-9a-fA-F]{4,40}|HEAD(?:[~^]\d*)*|[A-Za-z_][\w./@-]{0,199})$/;
+/** Diffs compare two revisions; worktree comparison uses one revision. */
+const MAX_REVISION_LENGTH = 200;
+
+export function isSafeRevision(revision: string): boolean {
+  const trimmed = revision.trim();
+  if (trimmed.length === 0 || trimmed.length > MAX_REVISION_LENGTH)
+    return false;
+  return REVISION_PATTERN.test(trimmed);
+}
+
+/** A relative repo path; `..` escapes and absolute paths are rejected. */
+const REPO_PATH_PATTERN = /^[^:/\\?#*[\]'"\s][^:/\\?#*[\]'"\s]*$/;
+
+export function isSafeRepoPath(value: string): boolean {
+  if (value.length === 0 || value.length > 512) return false;
+  const segments = value.split("/");
+  for (const segment of segments) {
+    if (segment === "" || segment === "." || segment === "..") return false;
+    if (!REPO_PATH_PATTERN.test(segment)) return false;
+  }
+  return true;
+}
+
+function revision(value: string): string | undefined {
+  return isSafeRevision(value) ? value.trim() : undefined;
+}
+
+export class InvalidRevisionError extends Error {
+  constructor(value: string) {
+    super(
+      `Invalid git revision: ${JSON.stringify(value.slice(0, 80))}. Allowed: a commit sha, branch or tag name, or HEAD with ~ / ^ modifiers.`,
+    );
+    this.name = "InvalidRevisionError";
+  }
+}
+
+export class InvalidPathError extends Error {
+  constructor(value: string) {
+    super(
+      `Invalid repository path: ${JSON.stringify(value.slice(0, 80))}. Use a relative path inside the repository.`,
+    );
+    this.name = "InvalidPathError";
+  }
+}
+
+export class InvalidDiffCombinationError extends Error {
+  constructor(message: string) {
+    super(`Invalid git diff options: ${message}`);
+    this.name = "InvalidDiffCombinationError";
+  }
+}
+
+export interface GitShowParams {
+  revision: string;
+  path?: string;
+}
+
+export function buildShowArgs(params: GitShowParams): string[] {
+  if (!isSafeRevision(params.revision))
+    throw new InvalidRevisionError(params.revision);
+  const args = [
+    "show",
+    "--no-color",
+    "--no-ext-diff",
+    "--no-textconv",
+    "--format=fuller",
+    params.revision.trim(),
+  ];
+  if (params.path !== undefined) {
+    if (!isSafeRepoPath(params.path)) throw new InvalidPathError(params.path);
+    args.push("--", params.path);
+  }
+  return args;
+}
+
+export interface GitDiffParams {
+  /** Base revision, e.g. HEAD, HEAD~1, a branch name, or a sha. */
+  from?: string;
+  /** Compared revision; omit to compare `from` against the worktree. */
+  to?: string;
+  /** Compare against the index (staged changes) instead of the worktree. */
+  staged?: boolean;
+  stat?: boolean;
+  path?: string;
+}
+
+export function buildDiffArgs(params: GitDiffParams): string[] {
+  const from = params.from !== undefined ? revision(params.from) : undefined;
+  if (params.from !== undefined && from === undefined) {
+    throw new InvalidRevisionError(params.from);
+  }
+  const to = params.to !== undefined ? revision(params.to) : undefined;
+  if (params.to !== undefined && to === undefined) {
+    throw new InvalidRevisionError(params.to);
+  }
+  if (params.to !== undefined && params.from === undefined) {
+    throw new InvalidDiffCombinationError("to requires from");
+  }
+  if (params.staged && (params.from !== undefined || params.to !== undefined)) {
+    throw new InvalidDiffCombinationError(
+      "staged cannot be combined with from or to",
+    );
+  }
+
+  const args = ["diff", "--no-color", "--no-ext-diff", "--no-textconv"];
+  if (params.staged) args.push("--cached");
+  if (params.stat) args.push("--stat");
+
+  if (from !== undefined && to !== undefined) {
+    // An explicit `--` separator is unnecessary for the range form; a
+    // validated revision can never start with `-` anyway.
+    args.push(`${from}...${to}`);
+  } else if (from !== undefined) {
+    args.push(from);
+  }
+  // No revisions: worktree vs index (or HEAD with --cached).
+
+  if (params.path !== undefined) {
+    if (!isSafeRepoPath(params.path)) throw new InvalidPathError(params.path);
+    args.push("--", params.path);
+  }
+  return args;
+}
+
+export interface GitLogParams {
+  revision?: string;
+  file?: string;
+  limit?: number;
+  oneline?: boolean;
+}
+
+export function buildLogArgs(params: GitLogParams): string[] {
+  const args = ["log", "--no-color", "--no-ext-diff"];
+  if (params.oneline !== false) args.push("--oneline");
+  const limit = Math.min(
+    GIT_LOG_MAX_LIMIT,
+    Math.max(1, Math.floor(params.limit ?? GIT_LOG_DEFAULT_LIMIT)),
+  );
+  args.push(`-n`, String(limit));
+
+  if (params.revision !== undefined) {
+    if (!isSafeRevision(params.revision)) {
+      throw new InvalidRevisionError(params.revision);
+    }
+    args.push(params.revision.trim());
+  }
+  if (params.file !== undefined) {
+    if (!isSafeRepoPath(params.file)) throw new InvalidPathError(params.file);
+    args.push("--", params.file);
+  }
+  return args;
+}

package/extensions/git-read/src/process.ts

@@ -0,0 +1,81 @@
+/**
+ * Bounded git process execution for the read-only git tools.
+ *
+ * Reuses the file-search capture discipline: a preview is retained in memory
+ * under pi's standard truncation limits while the complete output (up to the
+ * 10 MiB capture cap) streams to a temporary file, and the process group is
+ * terminated when the cap is exceeded.
+ */
+
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { Data, Effect } from "effect";
+import type { CapturedOutput } from "../../file-search/src/output.ts";
+import {
+  discardCapturedOutput,
+  executeSearchProcess,
+} from "../../file-search/src/process.ts";
+import { GIT_TIMEOUT_MS } from "./args.ts";
+
+export const GIT_CAPTURE_MAX_BYTES = 10 * 1024 * 1024;
+
+export class GitCommandError extends Data.TaggedError("GitCommandError")<{
+  readonly message: string;
+}> {}
+
+export interface GitOutcome {
+  readonly output: CapturedOutput;
+  readonly exitCode: number;
+}
+
+/**
+ * Run one git subcommand. Exit code 128 (not a repository / bad revision) and
+ * 129 (usage) surface as a GitCommandError carrying stderr; other non-zero
+ * exits also fail with the captured stderr detail.
+ */
+export function runGit(
+  args: readonly string[],
+  cwd: string,
+  timeoutMs = GIT_TIMEOUT_MS,
+): Effect.Effect<GitOutcome, GitCommandError> {
+  return Effect.gen(function* () {
+    const result = yield* Effect.catchTags(
+      executeSearchProcess({
+        command: "git",
+        args,
+        cwd,
+        tempPrefix: "pi-git-",
+        maxCaptureBytes: GIT_CAPTURE_MAX_BYTES,
+      }),
+      {
+        SearchProcessError: (error) =>
+          new GitCommandError({
+            message: `failed to run git: ${error.message}`,
+          }),
+        PlatformError: (error) =>
+          new GitCommandError({
+            message: `git output capture failed: ${String(error.reason ?? "")}`,
+          }),
+      },
+    );
+    if (result.code !== 0) {
+      const detail =
+        result.stderr.trim() || `git exited with code ${result.code}`;
+      // A failure means nothing useful was captured; drop the artifact.
+      yield* Effect.ignore(discardCapturedOutput(result.output));
+      return yield* new GitCommandError({ message: detail });
+    }
+    return {
+      output: result.output,
+      exitCode: result.code,
+    } satisfies GitOutcome;
+  }).pipe(
+    Effect.timeout(timeoutMs),
+    Effect.mapError((error) => {
+      if (error._tag === "GitCommandError") return error;
+      return new GitCommandError({
+        message: `git command timed out after ${timeoutMs}ms`,
+      });
+    }),
+    Effect.provide(NodeServices.layer),
+  );
+}

package/extensions/git-read/src/prompt.ts

@@ -0,0 +1,56 @@
+/** Model-facing text for the read-only git tools. */
+
+export const GIT_SHOW_TOOL_DESCRIPTION =
+  "Show a git commit (message, author, and patch), optionally limited to one repository path. Read-only.";
+
+export const GIT_SHOW_PROMPT_SNIPPET =
+  "Inspect a specific git commit with git_show.";
+
+export const GIT_SHOW_PROMPT_GUIDELINES = [
+  "Use git_show to review what a single commit changed instead of reading the whole file tree and guessing.",
+  "Use git_diff to compare revisions or the worktree, and git_log to find commits first.",
+];
+
+export const GIT_SHOW_PARAMETER_DESCRIPTIONS = {
+  revision:
+    "Commit to show: a sha (>=4 hex chars), branch or tag name, or HEAD with ~ / ^ modifiers, e.g. HEAD, HEAD~2, main.",
+  path: "Optional relative path inside the repository. Limits the commit patch to this path; it does not read the file blob.",
+};
+
+export const GIT_DIFF_TOOL_DESCRIPTION =
+  "Show a git diff: between two revisions, a revision and the worktree, or staged changes. Read-only.";
+
+export const GIT_DIFF_PROMPT_SNIPPET =
+  "Compare git revisions or working-tree changes with git_diff.";
+
+export const GIT_DIFF_PROMPT_GUIDELINES = [
+  "Use git_diff (not git_show) when reviewing changes between refs or uncommitted work.",
+  "Set stat to true first for a broad overview, then drill into specific paths.",
+  "To review a pull request, diff its branch against the base, e.g. from: 'main', to: 'feature-branch'.",
+];
+
+export const GIT_DIFF_PARAMETER_DESCRIPTIONS = {
+  from: "Base revision. With to, compares from...to from their merge base (PR-style). Omit both revisions to diff the worktree against the index.",
+  to: "Compared revision. Requires from and uses the merge-base range from...to. Give from alone to diff that revision against the worktree.",
+  staged:
+    "Compare the index (staged changes) against HEAD instead of the worktree.",
+  stat: "Show a diffstat (files and line counts) instead of the full patch.",
+  path: "Only diff this relative path inside the repository.",
+};
+
+export const GIT_LOG_TOOL_DESCRIPTION =
+  "List commit history with sha, author, date, and first line. Filter by revision or file. Read-only.";
+
+export const GIT_LOG_PROMPT_SNIPPET = "Browse git history with git_log.";
+
+export const GIT_LOG_PROMPT_GUIDELINES = [
+  "Use git_log with a file to find who last touched a piece of code before changing it.",
+  "Keep oneline true unless the full commit message of every entry is needed.",
+];
+
+export const GIT_LOG_PARAMETER_DESCRIPTIONS = {
+  revision: "History starting from this revision. Defaults to HEAD.",
+  file: "Only commits touching this relative path.",
+  limit: "Maximum commits to list (1-1000). Defaults to 100.",
+  oneline: "One line per commit (default true); false adds full messages.",
+};