@tt-a1i/openpi 0.3.1 → 0.5.0

package/extensions/shared/text-projection.ts

@@ -0,0 +1,113 @@
+import {
+  formatSize,
+  truncateHead,
+  truncateTail,
+} from "@earendil-works/pi-coding-agent";
+
+const HEAD_SHARE = 0.75;
+const OMISSION_MARKER = "[... middle omitted ...]";
+// Three framing blanks, the omission marker, and the footer.
+const STATIC_PROJECTION_OVERHEAD_LINES = 5;
+
+function utf8Prefix(content: string, maxBytes: number) {
+  const bytes = Buffer.from(content, "utf8");
+  if (bytes.length <= maxBytes) return content;
+  let end = Math.max(0, maxBytes);
+  while (end > 0) {
+    const value = bytes.subarray(0, end).toString("utf8");
+    if (!value.endsWith("�")) return value;
+    end -= 1;
+  }
+  return "";
+}
+
+function boundedHead(content: string, maxBytes: number, maxLines: number) {
+  const result = truncateHead(content, { maxBytes, maxLines });
+  if (result.content || !result.firstLineExceedsLimit) return result.content;
+  return utf8Prefix(content, maxBytes);
+}
+
+function compactProjection(
+  content: string,
+  maxBytes: number,
+  maxLines: number,
+) {
+  const marker =
+    maxBytes >= OMISSION_MARKER.length
+      ? OMISSION_MARKER
+      : ".".repeat(Math.min(3, maxBytes));
+  if (!marker || maxLines <= 0) return "";
+  if (maxLines === 1) return marker;
+
+  const bodyLineBudget = maxLines - 1;
+  const keepTail = bodyLineBudget >= 2;
+  const separatorBytes = keepTail ? 2 : 1;
+  const bodyByteBudget = maxBytes - marker.length - separatorBytes;
+  if (bodyByteBudget <= 0 || (keepTail && bodyByteBudget < 2)) return marker;
+
+  const headLines = keepTail
+    ? Math.max(1, Math.floor(bodyLineBudget * HEAD_SHARE))
+    : bodyLineBudget;
+  const tailLines = keepTail ? Math.max(1, bodyLineBudget - headLines) : 0;
+  const headBytes = keepTail
+    ? Math.max(1, Math.floor(bodyByteBudget * HEAD_SHARE))
+    : bodyByteBudget;
+  const tailBytes = keepTail ? Math.max(1, bodyByteBudget - headBytes) : 0;
+  const head = boundedHead(content, headBytes, headLines);
+  const tail = keepTail
+    ? truncateTail(content, {
+        maxBytes: tailBytes,
+        maxLines: tailLines,
+      }).content
+    : "";
+  return [head, marker, tail].filter(Boolean).join("\n");
+}
+
+/** Keep decision context at the start and verdict/evidence at the end. */
+export function projectText(
+  content: string,
+  options: { maxBytes: number; maxLines: number; recovery: string },
+) {
+  if (options.maxBytes <= 0 || options.maxLines <= 0) return "";
+
+  const probe = truncateHead(content, {
+    maxBytes: options.maxBytes,
+    maxLines: options.maxLines,
+  });
+  if (!probe.truncated) return content;
+
+  const recoveryNewlines = options.recovery.split("\n").length - 1;
+  const bodyLineBudget =
+    options.maxLines - STATIC_PROJECTION_OVERHEAD_LINES - recoveryNewlines;
+  if (bodyLineBudget < 2) {
+    return compactProjection(content, options.maxBytes, options.maxLines);
+  }
+  const headLines = Math.max(1, Math.floor(bodyLineBudget * HEAD_SHARE));
+  const tailLines = Math.max(1, bodyLineBudget - headLines);
+
+  let bodyBudget = options.maxBytes;
+  let projected = "";
+  for (let attempt = 0; attempt < 8; attempt++) {
+    const headBytes = Math.max(1, Math.floor(bodyBudget * HEAD_SHARE));
+    const tailBytes = Math.max(1, bodyBudget - headBytes);
+    const head = boundedHead(content, headBytes, headLines);
+    const tail = truncateTail(content, {
+      maxBytes: tailBytes,
+      maxLines: tailLines,
+    }).content;
+    const shown =
+      Buffer.byteLength(head, "utf8") + Buffer.byteLength(tail, "utf8");
+    const footer = `[Projection bounded: showing ${formatSize(shown)} of ${formatSize(probe.totalBytes)} across the head and tail. ${options.recovery}]`;
+    projected = `${head}\n\n${OMISSION_MARKER}\n\n${tail}\n\n${footer}`;
+    const overflow = Buffer.byteLength(projected, "utf8") - options.maxBytes;
+    if (overflow <= 0 || bodyBudget <= overflow + 2) break;
+    bodyBudget -= overflow;
+  }
+  const projectedProbe = truncateHead(projected, {
+    maxBytes: options.maxBytes,
+    maxLines: options.maxLines,
+  });
+  return projectedProbe.truncated
+    ? compactProjection(content, options.maxBytes, options.maxLines)
+    : projected;
+}

package/extensions/shared/tool-activity.ts

@@ -0,0 +1,382 @@
+import { isAbsolute, relative } from "node:path";
+import { stripVTControlCharacters } from "node:util";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import { spinnerFrame } from "./spinner.ts";
+import { sanitizeTerminalText } from "./terminal-text.ts";
+
+export type ToolActivityStatus = "pending" | "success" | "error";
+
+export interface ToolActivity {
+  readonly name: string;
+  readonly args?: unknown;
+  readonly argsFallback?: string;
+  readonly output?: string;
+  readonly details?: unknown;
+  readonly status: ToolActivityStatus;
+  readonly cwd?: string;
+  readonly startedAt?: number;
+  readonly endedAt?: number;
+}
+
+interface ActivityRow {
+  readonly verb: string;
+  readonly target: string;
+  readonly detail?: string;
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function string(value: unknown) {
+  return typeof value === "string" ? sanitizeTerminalText(value) : "";
+}
+
+function number(value: unknown) {
+  return typeof value === "number" ? value : undefined;
+}
+
+function compact(value: string) {
+  return sanitizeTerminalText(value).replace(/\r?\n/g, " ↵ ").trim();
+}
+
+export function parseToolArgsPreview(preview?: string) {
+  const clean = sanitizeTerminalText(preview ?? "").trim();
+  const fallback = compact(clean);
+  if (!fallback) return { args: undefined, fallback: undefined };
+  try {
+    const args: unknown = JSON.parse(clean);
+    return { args, fallback };
+  } catch {
+    return { args: undefined, fallback };
+  }
+}
+
+function displayPath(value: string, cwd?: string) {
+  if (!isAbsolute(value) || !cwd) return value;
+  const local = relative(cwd, value);
+  if (local === "") return ".";
+  return local.startsWith("..") || isAbsolute(local) ? value : local;
+}
+
+function resultCount(output: string) {
+  return output
+    .split(/\r?\n/)
+    .filter((line) => line.trim().length > 0 && !line.trim().startsWith("["))
+    .length;
+}
+
+function grepMatchCount(output: string) {
+  const text = output.trim();
+  if (!text || text === "No matches found") return 0;
+  return text.split(/\r?\n/).filter((line) => /^.+:\d+:/.test(line)).length;
+}
+
+function itemCount(output: string, emptyMessage: string) {
+  const text = output.trim();
+  return !text || text === emptyMessage ? 0 : resultCount(output);
+}
+
+function plural(count: number, singular: string) {
+  const pluralForm =
+    singular === "match"
+      ? "matches"
+      : singular === "entry"
+        ? "entries"
+        : `${singular}s`;
+  return `${count} ${count === 1 ? singular : pluralForm}`;
+}
+
+function editStats(details: unknown) {
+  const diff = string(record(details).diff);
+  if (!diff) return undefined;
+  let additions = 0;
+  let removals = 0;
+  for (const line of diff.split(/\r?\n/)) {
+    if (line.startsWith("+") && !line.startsWith("+++")) additions += 1;
+    if (line.startsWith("-") && !line.startsWith("---")) removals += 1;
+  }
+  return { additions, removals };
+}
+
+function range(args: Record<string, unknown>) {
+  const offset = number(args.offset);
+  const limit = number(args.limit);
+  if (offset === undefined && limit === undefined) return "";
+  const start = offset ?? 1;
+  return limit === undefined ? `:${start}-` : `:${start}-${start + limit - 1}`;
+}
+
+function canonicalName(name: string) {
+  const lower = sanitizeTerminalText(name).toLowerCase();
+  if (lower === "rg") return "grep";
+  if (lower === "fd") return "find";
+  return lower;
+}
+
+function activityRow(activity: ToolActivity): ActivityRow {
+  const name = canonicalName(activity.name);
+  const args = record(activity.args);
+  const fallback = compact(activity.argsFallback ?? "");
+  const output = sanitizeTerminalText(activity.output ?? "");
+  const path = displayPath(string(args.path) || ".", activity.cwd);
+  switch (name) {
+    case "read":
+      return { verb: "Read", target: `${path}${range(args)}` };
+    case "bash":
+      return {
+        verb: "Ran",
+        target:
+          string(args.command).replace(/\s+/g, " ").trim() || fallback || name,
+      };
+    case "write": {
+      const content = string(args.content);
+      const lines =
+        content.length === 0
+          ? 0
+          : content.replace(/\r?\n$/, "").split(/\r?\n/).length;
+      return {
+        verb: "Wrote",
+        target: string(args.path) ? path : fallback,
+        ...(content ? { detail: plural(lines, "line") } : {}),
+      };
+    }
+    case "edit":
+      return { verb: "Edited", target: string(args.path) ? path : fallback };
+    case "grep": {
+      const pattern = string(args.pattern) || fallback;
+      return {
+        verb: "Searched",
+        target: pattern,
+        ...(output
+          ? { detail: `in ${path}  ${plural(grepMatchCount(output), "match")}` }
+          : string(args.path)
+            ? { detail: `in ${path}` }
+            : {}),
+      };
+    }
+    case "find": {
+      const pattern = string(args.pattern) || fallback;
+      return {
+        verb: "Searched",
+        target: pattern,
+        ...(output
+          ? {
+              detail: `in ${path}  ${plural(itemCount(output, "No files found matching pattern"), "result")}`,
+            }
+          : string(args.path)
+            ? { detail: `in ${path}` }
+            : {}),
+      };
+    }
+    case "ls":
+      return {
+        verb: "Listed",
+        target: string(args.path) ? path : fallback || ".",
+        ...(output
+          ? { detail: plural(itemCount(output, "(empty directory)"), "entry") }
+          : {}),
+      };
+    default:
+      return {
+        verb: sanitizeTerminalText(activity.name),
+        target: fallback || name,
+      };
+  }
+}
+
+function pendingVerb(name: string) {
+  switch (canonicalName(name)) {
+    case "read":
+      return "Reading";
+    case "bash":
+      return "Running";
+    case "write":
+      return "Writing";
+    case "edit":
+      return "Editing";
+    case "grep":
+    case "find":
+      return "Searching";
+    case "ls":
+      return "Listing";
+    default:
+      return "Running";
+  }
+}
+
+function activityIcon(name: string) {
+  switch (canonicalName(name)) {
+    case "read":
+      return "\ueaa4";
+    case "bash":
+      return "\uea85";
+    case "write":
+    case "edit":
+      return "\uea73";
+    case "grep":
+    case "find":
+      return "\uea6d";
+    case "ls":
+      return "\uea83";
+    default:
+      return "✓";
+  }
+}
+
+function errorSummary(output?: string) {
+  const lines = sanitizeTerminalText(output ?? "")
+    .split(/\r?\n/)
+    .map((line) => stripVTControlCharacters(line).trim())
+    .filter(Boolean);
+  return (
+    [...lines]
+      .reverse()
+      .find((line) =>
+        /(?:command (?:exited|timed out|aborted)|error|denied|failed)/i.test(
+          line,
+        ),
+      ) ?? lines[0]
+  );
+}
+
+function elapsed(activity: ToolActivity, now: number) {
+  if (activity.startedAt === undefined) return undefined;
+  const seconds = Math.floor(
+    ((activity.endedAt ?? now) - activity.startedAt) / 1000,
+  );
+  return seconds > 0 ? `${seconds}s` : undefined;
+}
+
+export function toolActivityText(
+  activity: ToolActivity,
+  theme: Theme,
+  now = Date.now(),
+) {
+  const row = activityRow(activity);
+  const duration = elapsed(activity, now);
+  const verbText = (
+    activity.status === "pending"
+      ? pendingVerb(activity.name)
+      : activity.status === "error"
+        ? "Failed"
+        : row.verb
+  ).padEnd(8);
+  const verb = theme.fg(
+    activity.status === "error"
+      ? "error"
+      : activity.status === "success"
+        ? "muted"
+        : "toolTitle",
+    verbText,
+  );
+
+  if (activity.status === "pending") {
+    const detail = duration ? ` · ${duration}` : "";
+    return `${theme.fg("warning", spinnerFrame(now))} ${verb} ${row.target}${theme.fg("dim", detail)}`;
+  }
+  if (activity.status === "error") {
+    const summary = errorSummary(activity.output);
+    const detail = [duration, summary].filter(Boolean).join(" · ");
+    return `${theme.fg("error", "✕")} ${verb} ${row.target}${detail ? theme.fg("dim", ` · ${detail}`) : ""}`;
+  }
+
+  const parts: string[] = [];
+  if (canonicalName(activity.name) === "edit") {
+    const stats = editStats(activity.details);
+    if (stats) {
+      parts.push(
+        `${theme.fg("success", `+${stats.additions}`)} ${theme.fg("error", `-${stats.removals}`)}`,
+      );
+    }
+  } else if (row.detail) {
+    parts.push(theme.fg("dim", row.detail));
+  }
+  if (duration) parts.push(theme.fg("dim", duration));
+  const detail = parts.join(theme.fg("dim", " · "));
+  return `${theme.fg("dim", activityIcon(activity.name))} ${verb} ${theme.fg("muted", row.target)}${detail ? `  ${detail}` : ""}`;
+}
+
+export function renderToolActivityLine(
+  activity: ToolActivity,
+  theme: Theme,
+  width: number,
+  now = Date.now(),
+) {
+  const ellipsis = activity.status === "success" ? theme.fg("muted", "…") : "…";
+  return truncateToWidth(
+    toolActivityText(activity, theme, now),
+    width,
+    ellipsis,
+  );
+}
+
+/**
+ * Match the horizontal shell used by Pi's collapsed tool component. Keeping
+ * this here lets persisted child transcripts and live parent tools share the
+ * exact same operator-facing row without pretending bounded previews contain
+ * the full native tool result.
+ */
+export function renderPaddedToolActivityLine(
+  activity: ToolActivity,
+  theme: Theme,
+  width: number,
+  now = Date.now(),
+) {
+  const padding = "  ";
+  const contentWidth = width - padding.length * 2;
+  if (contentWidth <= 0) return "";
+  return `${padding}${renderToolActivityLine(activity, theme, contentWidth, now)}${padding}`;
+}
+
+/** Historical Direct helper retained without owning a second formatter. */
+export function summarizeToolArgs(
+  name: string,
+  argsPreview?: string,
+  cwd?: string,
+) {
+  if (!argsPreview) return undefined;
+  const fallback = compact(argsPreview);
+  if (!fallback || fallback === "{}") return undefined;
+
+  let args: Record<string, unknown> | undefined;
+  try {
+    const parsed: unknown = JSON.parse(argsPreview);
+    if (
+      parsed !== null &&
+      typeof parsed === "object" &&
+      !Array.isArray(parsed)
+    ) {
+      args = parsed as Record<string, unknown>;
+    }
+  } catch {
+    return fallback;
+  }
+  if (!args) return fallback;
+
+  const field = (key: string) => {
+    const value = args[key];
+    return typeof value === "string" && value.length > 0
+      ? sanitizeTerminalText(value).replace(/\r?\n/g, " ↵ ")
+      : undefined;
+  };
+  const path = () => {
+    const value = field("path");
+    return value ? displayPath(value, cwd) : undefined;
+  };
+  const tool = canonicalName(name);
+  if (tool === "bash") return field("command") ?? fallback;
+  if (tool === "read" || tool === "write" || tool === "edit") {
+    return path() ?? fallback;
+  }
+  if (tool === "grep" || tool === "find") {
+    const pattern = field("pattern");
+    const searchPath = path();
+    if (pattern && searchPath) return `${pattern} · ${searchPath}`;
+    return pattern ?? searchPath ?? fallback;
+  }
+  return fallback;
+}

package/extensions/shared/tool-surface.ts

@@ -17,19 +17,24 @@ export const OPENPI_TOOL_SURFACE = {
     entry: ["fd", "rg"],
     deferred: [],
   },
+  gitRead: {
+    entry: ["git_show", "git_diff", "git_log"],
+    deferred: [],
+  },
   subagents: {
-    entry: ["subagent_spawn"],
-    deferred: [
+    entry: [
+      "subagent_spawn",
       "subagent_wait",
       "subagent_cancel",
       "subagent_send",
       "subagent_check",
       "subagent_list",
     ],
+    deferred: [],
   },
   workflows: {
-    entry: ["workflow"],
-    deferred: ["workflow_stop", "workflow_status"],
+    entry: ["workflow", "workflow_stop", "workflow_status"],
+    deferred: [],
   },
   background: {
     entry: ["bg_start"],
@@ -65,8 +70,9 @@ export type OpenPiToolOwner = keyof typeof OPENPI_TOOL_SURFACE;
 
 export const OPENPI_CAPABILITY_GROUPS = {
   search: {
-    owners: ["fileSearch"],
-    summary: "Fast structured file and content search with fd and rg.",
+    owners: ["fileSearch", "gitRead"],
+    summary:
+      "Fast structured file and content search (fd, rg) plus read-only git inspection (git_show, git_diff, git_log).",
   },
   delegate: {
     owners: ["subagents"],
@@ -129,13 +135,14 @@ interface ToolSurfaceState {
   subscribed: boolean;
 }
 
-const OWNER_SOURCE_PATHS = {
+export const OPENPI_OWNER_SOURCE_PATHS = {
   capabilities: fileURLToPath(
     new URL("../capabilities/index.ts", import.meta.url),
   ),
   fileSearch: fileURLToPath(
     new URL("../file-search/index.ts", import.meta.url),
   ),
+  gitRead: fileURLToPath(new URL("../git-read/index.ts", import.meta.url)),
   subagents: fileURLToPath(new URL("../subagents/index.ts", import.meta.url)),
   workflows: fileURLToPath(new URL("../workflows/index.ts", import.meta.url)),
   background: fileURLToPath(
@@ -261,7 +268,7 @@ function availableOwnedToolNames(
   }
 
   const expectedSource =
-    state.sourceByOwner.get(owner) ?? OWNER_SOURCE_PATHS[owner];
+    state.sourceByOwner.get(owner) ?? OPENPI_OWNER_SOURCE_PATHS[owner];
   return new Set(
     reportedTools
       .filter(
@@ -272,6 +279,33 @@ function availableOwnedToolNames(
   );
 }
 
+/** Verify that one active tool is the definition owned by this OpenPI source. */
+export function isOwnedToolActive(
+  pi: ActiveToolSurface,
+  owner: OpenPiToolOwner,
+  name: string,
+) {
+  if (!ownedToolNames(owner).includes(name)) {
+    throw new Error(`${owner} does not own tool ${JSON.stringify(name)}.`);
+  }
+  return (
+    pi.getActiveTools().includes(name) &&
+    availableOwnedToolNames(pi, stateFor(pi), owner).has(name)
+  );
+}
+
+/** Verify that one registered tool is available from this OpenPI source. */
+export function isOwnedToolAvailable(
+  pi: ActiveToolSurface,
+  owner: OpenPiToolOwner,
+  name: string,
+) {
+  if (!ownedToolNames(owner).includes(name)) {
+    throw new Error(`${owner} does not own tool ${JSON.stringify(name)}.`);
+  }
+  return availableOwnedToolNames(pi, stateFor(pi), owner).has(name);
+}
+
 function projectedOwnerTools(
   pi: ActiveToolSurface,
   state: ToolSurfaceState,

package/extensions/shared/transcript-viewport.ts

@@ -0,0 +1,46 @@
+function maxScrollTop(rowCount: number, viewportSize: number) {
+  return Math.max(0, rowCount - Math.max(1, viewportSize));
+}
+
+function clamp(value: number, maximum: number) {
+  return Math.max(0, Math.min(value, maximum));
+}
+
+/**
+ * Pure transcript viewport state with the same follow-to-end contract as Pi's
+ * ScrollView. Operators may pause following without new rows moving their
+ * absolute reading anchor; reaching the end explicitly resumes following.
+ */
+export class TranscriptViewport {
+  scrollTop = 0;
+  followingEnd = true;
+
+  reconcile(rowCount: number, viewportSize: number) {
+    const maximum = maxScrollTop(rowCount, viewportSize);
+    this.scrollTop = this.followingEnd
+      ? maximum
+      : clamp(this.scrollTop, maximum);
+  }
+
+  scrollBy(delta: number, rowCount: number, viewportSize: number) {
+    this.reconcile(rowCount, viewportSize);
+    const maximum = maxScrollTop(rowCount, viewportSize);
+    this.scrollTop = clamp(this.scrollTop + delta, maximum);
+    this.followingEnd = this.scrollTop === maximum && delta > 0;
+  }
+
+  scrollToTop(rowCount: number, viewportSize: number) {
+    this.scrollTop = 0;
+    this.followingEnd = false;
+    this.reconcile(rowCount, viewportSize);
+  }
+
+  scrollToEnd(rowCount: number, viewportSize: number) {
+    this.followingEnd = true;
+    this.reconcile(rowCount, viewportSize);
+  }
+
+  linesBelow(rowCount: number, viewportSize: number) {
+    return maxScrollTop(rowCount, viewportSize) - this.scrollTop;
+  }
+}