@tt-a1i/openpi 0.3.0 → 0.4.0

package/extensions/shared/below-editor-navigation.ts

@@ -1,6 +1,7 @@
 import type {
   AppKeybinding,
   KeybindingsManager,
+  Theme,
 } from "@earendil-works/pi-coding-agent";
 import type {
   AutocompleteProvider,
@@ -328,6 +329,31 @@ export class BelowEditorNavigationEditor implements EditorComponent, Focusable {
   }
 }
 
+/**
+ * Metrics tail for a below-editor strip: quiet values, quieter separators, and
+ * a hint that recedes furthest.
+ *
+ * The whole tail used to be painted in the status colour, which made a routine
+ * "1 running · 9m51s · ↓ to manage" shout as loudly as a failure. The status
+ * already has a coloured glyph on the left edge, so the tail only borrows that
+ * colour for the one count that carries the outcome — and only once the run has
+ * settled, where the colour means something.
+ */
+export function renderNavigationMetrics(
+  theme: Theme,
+  parts: readonly (string | undefined)[],
+  hint: string,
+  emphasis?: Parameters<Theme["fg"]>[0],
+) {
+  const present = parts.filter((part): part is string => Boolean(part));
+  const styled = present.map((part, index) =>
+    index === 0 && emphasis
+      ? theme.fg(emphasis, part)
+      : theme.fg("muted", part),
+  );
+  return [...styled, theme.fg("dim", hint)].join(theme.fg("dim", " · "));
+}
+
 /** Fit a left label and right metrics into exactly one bounded terminal row. */
 export function fitNavigationSides(left: string, right: string, width: number) {
   const boundedRight = truncateToWidth(right, Math.max(0, width - 4), "…");

package/extensions/shared/capability-intent.ts

@@ -0,0 +1,53 @@
+import {
+  OPENPI_CAPABILITY_NAMES,
+  type OpenPiCapability,
+} from "./tool-surface.ts";
+
+const CAPABILITY_INTENT = {
+  search:
+    /\b(?:use|run)\s+(?:fd|rg)\b|\buse\s+(?:structured\s+)?(?:(?:file|code|content)\s+)?search\b|\b(?:structured|fast)\s+(?:file|code|content)\s+search\b|(?:使用|用|运行).{0,8}(?:fd|rg|git\s+(?:show|diff|log))|结构化(?:文件|代码|内容)搜索/iu,
+  delegate:
+    /\bsubagents?\b|(?:^|[.!?]\s+)(?:please\s+)?(?:delegate|parallelize)\s+(?:this|the)\s+(?:task|work)\b|\b(?:can|could|would)\s+you\s+(?:please\s+)?(?:delegate|parallelize)\s+(?:this|the)\s+(?:task|work)\b|\bparallel\s+agents?\b|(?:使用|用|启动|调用|来|开).{0,8}子代理|(?:多个?|多路)子代理|并行.{0,8}(?:代理|agent)|委派.{0,6}(?:任务|给|出去)/iu,
+  workflow: /\bworkflows?\b|(?:使用|用|运行|创建|构建).{0,8}工作流/iu,
+  background:
+    /\b(?:run|start|keep)\b.{0,40}\b(?:in the background|background\s+(?:process|terminal|job))\b|后台.{0,8}(?:运行|启动|进程|终端|任务)/iu,
+  session:
+    /\b(?:create|set|update|track)\s+(?:an?\s+)?(?:session\s+)?(?:goal|task list|tasks)\b|(?:设置|创建|更新|跟踪|追踪).{0,8}(?:目标|任务)/iu,
+} as const satisfies Record<OpenPiCapability, RegExp>;
+
+const CAPABILITY_GATEWAY_INTENT =
+  /\bopenpi\s+(?:capabilit(?:y|ies)|tools?|features?)\b|openpi.{0,8}(?:能力|工具|功能)/iu;
+
+const CONDITIONAL_OR_NEGATED_INTENT =
+  /^(?:\s*(?:only\s+)?(?:if|when|unless|before|in case)\b)|\b(?:do not|don't|cannot|can't|not|no|never|avoid)\b|\b(?:if|unless)\b|\bwhen\s+(?:needed|required|necessary)\b|(?:如果|若|假如|除非|仅当|需要时|不要|不能|不用|不必|无需|避免|请勿|禁止)/iu;
+
+function clauses(prompt: string) {
+  return prompt.split(/[\n.!?。！？;；]+/u);
+}
+
+function isExplicitClause(clause: string) {
+  return !CONDITIONAL_OR_NEGATED_INTENT.test(clause);
+}
+
+/**
+ * One fail-closed interpretation of explicit user capability intent. The
+ * English names `subagent` and `workflow` are reserved authorization words;
+ * negated or conditional clauses remain inert. Runtime activation and
+ * pre-submit UI feedback both cross this seam, so they cannot drift.
+ */
+export function capabilitiesRequestedByPrompt(prompt: string) {
+  const promptClauses = clauses(prompt);
+  return OPENPI_CAPABILITY_NAMES.filter((capability) =>
+    promptClauses.some(
+      (clause) =>
+        isExplicitClause(clause) && CAPABILITY_INTENT[capability].test(clause),
+    ),
+  );
+}
+
+export function requestsCapabilityGateway(prompt: string) {
+  return clauses(prompt).some(
+    (clause) =>
+      isExplicitClause(clause) && CAPABILITY_GATEWAY_INTENT.test(clause),
+  );
+}

package/extensions/shared/child-session.ts

@@ -22,7 +22,13 @@ export const CHILD_SHUTDOWN_TIMEOUT_MS = 5_000;
  * `registerTool(createEditToolDefinition(...))`); an unrecognized factory
  * registration fails the guard rather than escaping it.
  */
-export const CHILD_SAFE_PACKAGE_TOOL_NAMES = ["fd", "rg"] as const;
+export const CHILD_SAFE_PACKAGE_TOOL_NAMES = [
+  "fd",
+  "rg",
+  "git_show",
+  "git_diff",
+  "git_log",
+] as const;
 
 /**
  * pi-intercom resources are unsafe inside concurrent in-process child sessions.

package/extensions/shared/result-budget.ts

@@ -0,0 +1,134 @@
+export interface ParentContextUsage {
+  readonly tokens: number | null;
+  readonly contextWindow: number;
+}
+
+export interface ResultBudgetPolicy {
+  readonly maxBatchBytes: number;
+  readonly maxResultBytes: number;
+  readonly minResultBytes: number;
+  readonly headroomShare: number;
+  readonly estimatedBytesPerToken: number;
+  /** Batch metadata that consumes the same parent-context headroom. */
+  readonly fixedBytes?: number;
+}
+
+export interface ResultBudgetAllocation {
+  readonly budgets: readonly number[];
+  readonly batchBytes: number;
+  readonly source: "static" | "dynamic";
+}
+
+function validUsage(
+  usage: ParentContextUsage | null | undefined,
+): usage is { readonly tokens: number; readonly contextWindow: number } {
+  return Boolean(
+    usage &&
+      typeof usage.tokens === "number" &&
+      Number.isFinite(usage.tokens) &&
+      usage.tokens >= 0 &&
+      Number.isFinite(usage.contextWindow) &&
+      usage.contextWindow > 0,
+  );
+}
+
+function distribute(
+  desired: readonly number[],
+  batchBytes: number,
+  minResultBytes: number,
+) {
+  const budgets = desired.map((bytes) => Math.min(bytes, minResultBytes));
+  let remaining = Math.max(
+    0,
+    batchBytes - budgets.reduce((sum, bytes) => sum + bytes, 0),
+  );
+  let active = desired
+    .map((bytes, index) => ({ bytes, index }))
+    .filter(({ bytes, index }) => bytes > budgets[index]!);
+
+  while (remaining > 0 && active.length > 0) {
+    const share = Math.floor(remaining / active.length);
+    if (share === 0) {
+      for (const { bytes, index } of active) {
+        if (remaining === 0) break;
+        if (budgets[index]! >= bytes) continue;
+        budgets[index]! += 1;
+        remaining--;
+      }
+      break;
+    }
+
+    const satisfied = active.filter(
+      ({ bytes, index }) => bytes - budgets[index]! <= share,
+    );
+    if (satisfied.length > 0) {
+      for (const { bytes, index } of satisfied) {
+        const addition = bytes - budgets[index]!;
+        budgets[index]! = bytes;
+        remaining -= addition;
+      }
+      const settled = new Set(satisfied.map(({ index }) => index));
+      active = active.filter(({ index }) => !settled.has(index));
+      continue;
+    }
+
+    for (const { index } of active) budgets[index]! += share;
+    remaining -= share * active.length;
+  }
+
+  return budgets;
+}
+
+/**
+ * Allocate one bounded projection budget per result. Small results yield their
+ * unused share to larger siblings. Parent context usage is optional: Pi marks
+ * it unknown after compaction until a fresh response, in which case the
+ * deterministic static batch cap remains the source of truth.
+ */
+export function allocateResultBudgets(
+  resultBytes: readonly number[],
+  usage: ParentContextUsage | null | undefined,
+  policy: ResultBudgetPolicy,
+): ResultBudgetAllocation {
+  if (resultBytes.length === 0) {
+    return { budgets: [], batchBytes: 0, source: "static" };
+  }
+
+  const desired = resultBytes.map((bytes) =>
+    Math.min(policy.maxResultBytes, Math.max(0, Math.floor(bytes))),
+  );
+  const perResultFloor = Math.min(
+    policy.minResultBytes,
+    Math.floor(policy.maxBatchBytes / resultBytes.length),
+  );
+  const desiredTotal = desired.reduce((sum, bytes) => sum + bytes, 0);
+  const staticBatchBytes = Math.min(policy.maxBatchBytes, desiredTotal);
+  const minimumBatchBytes = desired.reduce(
+    (sum, bytes) => sum + Math.min(bytes, perResultFloor),
+    0,
+  );
+
+  let batchBytes = staticBatchBytes;
+  let source: ResultBudgetAllocation["source"] = "static";
+  if (validUsage(usage)) {
+    const headroomTokens = Math.max(0, usage.contextWindow - usage.tokens);
+    const dynamicBytes = Math.max(
+      0,
+      Math.floor(
+        headroomTokens * policy.headroomShare * policy.estimatedBytesPerToken,
+      ) - Math.max(0, policy.fixedBytes ?? 0),
+    );
+    const narrowed = Math.max(
+      minimumBatchBytes,
+      Math.min(staticBatchBytes, dynamicBytes),
+    );
+    if (narrowed < staticBatchBytes) source = "dynamic";
+    batchBytes = narrowed;
+  }
+
+  return {
+    budgets: distribute(desired, batchBytes, perResultFloor),
+    batchBytes,
+    source,
+  };
+}

package/extensions/shared/screen-chrome.ts

@@ -0,0 +1,133 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+/**
+ * Only the two paint calls this chrome makes, following the footer's precedent:
+ * views that carry a narrowed theme object can use it without a cast.
+ */
+type Theme = Pick<ExtensionContext["ui"]["theme"], "fg" | "bold">;
+
+/**
+ * Some labels arrive already styled (a task census colours each state). Painting
+ * a colour over them would apply only up to their first inner reset, leaving the
+ * rest a different shade than the caller asked for, so pre-styled text is passed
+ * through untouched.
+ */
+const isStyled = (text: string) => text.includes("\u001b");
+
+/**
+ * The chrome every full-screen OpenPI view shares: a title line, one bordered
+ * panel, a hint line, and one way to say "there is more above/below".
+ *
+ * Three views had grown their own copy of this (`/subagents`, `/ps`,
+ * `/workflows`), and they had drifted apart in the details you notice without
+ * being able to name: one framed the body in `border`, another in
+ * `borderMuted`; one wrote `... 3 more` and another `… 3 more`; hints were a
+ * single dim run in which the keys you are supposed to press read exactly as
+ * faint as the prose describing them. Fixing that in one place is also the only
+ * way it stays fixed.
+ */
+
+/** Title left, quiet census right, with the same one-column inset as the panel. */
+export function screenTitleLine(
+  theme: Theme,
+  title: string,
+  meta: string,
+  width: number,
+) {
+  const left = ` ${theme.bold(theme.fg("accent", title))}`;
+  const right = meta ? `${isStyled(meta) ? meta : theme.fg("dim", meta)} ` : "";
+  const rightWidth = visibleWidth(right);
+  const fittedLeft = truncateToWidth(
+    left,
+    Math.max(0, width - rightWidth - 1),
+    "…",
+  );
+  const pad = Math.max(1, width - visibleWidth(fittedLeft) - rightWidth);
+  return truncateToWidth(fittedLeft + " ".repeat(pad) + right, width, "");
+}
+
+/**
+ * Bordered panel with an optional label set into the top edge, padded to an
+ * exact height so a view's overlay never changes size as content streams in.
+ */
+export function panelFrame(
+  theme: Theme,
+  options: {
+    label?: string;
+    rows: readonly string[];
+    width: number;
+    height: number;
+  },
+) {
+  const { label = "", rows, width, height } = options;
+  const inner = Math.max(0, width - 2);
+  const border = (text: string) => theme.fg("borderMuted", text);
+  // The label rides the border rather than sitting above it, so it reads as
+  // this panel's name instead of competing with the screen title.
+  const clippedLabel = label
+    ? truncateToWidth(` ${label} `, Math.max(0, inner - 2))
+    : "";
+  const labelText = clippedLabel
+    ? isStyled(clippedLabel)
+      ? clippedLabel
+      : theme.fg("muted", clippedLabel)
+    : "";
+  const dashes = Math.max(0, inner - visibleWidth(labelText) - 1);
+  const lines = [border("╭─") + labelText + border("─".repeat(dashes) + "╮")];
+  const bodyHeight = Math.max(0, height - 2);
+  for (let index = 0; index < bodyHeight; index += 1) {
+    const clipped = truncateToWidth(rows[index] ?? "", inner, "…");
+    const pad = Math.max(0, inner - visibleWidth(clipped));
+    lines.push(border("│") + clipped + " ".repeat(pad) + border("│"));
+  }
+  lines.push(border("╰" + "─".repeat(inner) + "╯"));
+  return lines;
+}
+
+/** One `keys label` pair of a hint line. */
+export type ScreenHint = readonly [keys: string, label: string];
+
+/**
+ * Keys read one step brighter than what they do, so the line scans as a
+ * keyboard legend instead of a sentence. A notice takes the whole line when
+ * there is one: it is the answer to what you just pressed, and the legend can
+ * wait a beat.
+ */
+export function hintLine(
+  theme: Theme,
+  hints: readonly (ScreenHint | undefined)[],
+  width: number,
+  notice?: string,
+) {
+  if (notice) {
+    return truncateToWidth(theme.fg("accent", ` ${notice}`), width, "…");
+  }
+  const parts = hints
+    .filter((hint): hint is ScreenHint => Boolean(hint))
+    .map(([keys, label]) => {
+      // An empty key slot is a plain status segment (a scroll position, say);
+      // an empty label is a bare key. Both stay dimmer than a real key.
+      if (!keys) return theme.fg("dim", label);
+      if (!label) return theme.fg("muted", keys);
+      return `${theme.fg("muted", keys)} ${theme.fg("dim", label)}`;
+    });
+  return truncateToWidth(
+    ` ${parts.join(theme.fg("dim", " · "))}`,
+    width,
+    theme.fg("dim", "…"),
+  );
+}
+
+/** Single vocabulary for a clipped list: `… 3 more agents`. */
+export function overflowNote(
+  theme: Theme,
+  count: number,
+  width: number,
+  noun = "",
+) {
+  return truncateToWidth(
+    theme.fg("dim", `   … ${count} more${noun ? ` ${noun}` : ""}`),
+    width,
+  );
+}

package/extensions/shared/setup-config.ts

@@ -69,7 +69,12 @@ export type CapabilityDiscoveryMode =
 
 /** Canonical default layout: one-line plain footer with flex alignment. */
 export const DEFAULT_FOOTER_LINES: FooterLines = [
-  ["cwd", "git", "pr", "flex", "model", "context", "cost"],
+  ["model", "context", "flex", "git", "pr", "cwd"],
+];
+
+/** The persisted canonical default before model/context moved to the left. */
+const LEGACY_DEFAULT_FOOTER_LINES: FooterLines = [
+  ["cwd", "git", "pr", "flex", "model", "context"],
 ];
 
 export const DEFAULT_FOOTER_STYLE: FooterStyle = "plain";
@@ -88,7 +93,7 @@ export const FOOTER_PRESET_DEFINITIONS: Record<
 > = {
   compact: {
     style: "plain",
-    lines: [["cwd", "model", "thinking", "context", "flex", "git", "pr"]],
+    lines: DEFAULT_FOOTER_LINES,
   },
   powerline: {
     style: "powerline",
@@ -340,6 +345,17 @@ function parseFooterItems(value: unknown): readonly FooterItem[] {
   return items.length > 0 ? items : DEFAULT_FOOTER_ITEMS;
 }
 
+function sameFooterLines(left: FooterLines, right: FooterLines) {
+  return (
+    left.length === right.length &&
+    left.every(
+      (line, lineIndex) =>
+        line.length === right[lineIndex]?.length &&
+        line.every((item, itemIndex) => item === right[lineIndex]?.[itemIndex]),
+    )
+  );
+}
+
 function parseUiFooter(
   ui: Record<string, unknown>,
 ): Pick<MyPiSetupConfig["ui"], "footerStyle" | "footerLines" | "footerItems"> {
@@ -348,7 +364,10 @@ function parseUiFooter(
     : DEFAULT_FOOTER_STYLE;
 
   if (ui.footerLines !== undefined) {
-    const lines = normalizeFooterLines(ui.footerLines);
+    const normalized = normalizeFooterLines(ui.footerLines);
+    const lines = sameFooterLines(normalized, LEGACY_DEFAULT_FOOTER_LINES)
+      ? DEFAULT_FOOTER_LINES
+      : normalized;
     return {
       footerStyle: style,
       footerLines: lines,
@@ -957,8 +976,8 @@ export function formatSetupConfig(
     `Workflows: ${config.workflows.concurrency} concurrent agents · ${config.workflows.maxAgentCalls} total calls`,
     `UI: large header ${config.ui.showHeader ? "on" : "off"} · custom footer ${footer}`,
     `Subagent results: ${config.ui.subagentResultDisplay === "full" ? "full by default" : "compact status summary (Ctrl+O expands full output)"}`,
-    `Bash operations: ${config.ui.bashToolDisplay === "full" ? "expanded by default" : "folded preview (Ctrl+O expands all)"}`,
-    `Write/Edit operations: ${config.ui.fileMutationDisplay === "full" ? "expanded by default" : "folded preview (Ctrl+O expands all)"}`,
+    `Bash operations: ${config.ui.bashToolDisplay === "full" ? "expanded by default" : "one-line activity summary (Ctrl+O restores native evidence)"}`,
+    `Write/Edit operations: ${config.ui.fileMutationDisplay === "full" ? "expanded by default" : "one-line activity summary (Ctrl+O restores native evidence)"}`,
     `Post-edit command: ${config.postEdit.command ? config.postEdit.command : "off"}`,
     `Agent role models (Subagents + Workflows): ${SUBAGENT_ROLE_NAMES.map((role) => `${role} ${config.subagents.roleModels[role] ? `${config.subagents.roleModels[role].provider}/${config.subagents.roleModels[role].model}` : "inherit"}`).join(" · ")}`,
     ...integrationLines,

package/extensions/shared/spinner.ts

@@ -0,0 +1,28 @@
+/**
+ * One braille spinner for every running-state indicator in the package:
+ * transcripts, takeover and dashboard headers, and the below-editor strips all
+ * advance on the same cadence so concurrent views animate in step.
+ */
+
+export const SPINNER_FRAMES = [
+  "⠋",
+  "⠙",
+  "⠹",
+  "⠸",
+  "⠼",
+  "⠴",
+  "⠦",
+  "⠧",
+  "⠇",
+  "⠏",
+] as const;
+
+/** Frame cadence, shared with the dashboard and takeover headers. */
+export const SPINNER_INTERVAL_MS = 120;
+
+export function spinnerFrame(now: number) {
+  const frame = Math.floor(now / SPINNER_INTERVAL_MS) % SPINNER_FRAMES.length;
+  return SPINNER_FRAMES[
+    (frame + SPINNER_FRAMES.length) % SPINNER_FRAMES.length
+  ];
+}

package/extensions/shared/text-projection.ts

@@ -0,0 +1,56 @@
+import { formatSize, truncateHead } from "@earendil-works/pi-coding-agent";
+
+const HEAD_SHARE = 0.75;
+
+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 utf8Suffix(content: string, maxBytes: number) {
+  const bytes = Buffer.from(content, "utf8");
+  if (bytes.length <= maxBytes) return content;
+  let start = Math.max(0, bytes.length - maxBytes);
+  while (start < bytes.length) {
+    const value = bytes.subarray(start).toString("utf8");
+    if (!value.startsWith("�")) return value;
+    start += 1;
+  }
+  return "";
+}
+
+/** Keep decision context at the start and verdict/evidence at the end. */
+export function projectText(
+  content: string,
+  options: { maxBytes: number; maxLines: number; recovery: string },
+) {
+  const probe = truncateHead(content, {
+    maxBytes: options.maxBytes,
+    maxLines: options.maxLines,
+  });
+  if (!probe.truncated) return content;
+
+  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 = utf8Prefix(content, headBytes);
+    const tail = utf8Suffix(content, tailBytes);
+    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[... middle omitted ...]\n\n${tail}\n\n${footer}`;
+    const overflow = Buffer.byteLength(projected, "utf8") - options.maxBytes;
+    if (overflow <= 0 || bodyBudget <= overflow + 2) break;
+    bodyBudget -= overflow;
+  }
+  return projected;
+}

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"],
@@ -136,6 +142,7 @@ const OWNER_SOURCE_PATHS = {
   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(