@trim21/personal-pi-extensions 0.1.633 → 0.1.635

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.633",
+  "version": "0.1.635",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/gh/base.ts

@@ -1,17 +1,18 @@
 /**
- * Shared infrastructure of the GitHub read-only tools: the `gh` subprocess
- * layer, result shaping, the octokit-backed client, and the checks-wait
- * pipeline. Each tool lives in `tools/<tool-name>.ts`; anything used by more
- * than one tool belongs here.
+ * Shared infrastructure of the GitHub read-only tools: result shaping, the
+ * octokit-backed client, and the checks-wait pipeline (running a `gh` process
+ * itself lives in `lib/gh-process.ts`, which also owns the proxy env shared by
+ * the subprocess and octokit). Each tool lives in `tools/<tool-name>.ts`;
+ * anything used by more than one tool belongs here.
  */
 
-import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { delimiter, join } from "node:path";
 
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 
+import { type GhResult, httpProxy, runGh } from "../lib/gh-process.js";
 import {
   type ActionJob,
   type CheckRun,
@@ -19,17 +20,11 @@ import {
   createGithubChecks,
   createGithubSearch,
   type GithubChecksClient,
+  type GithubClientOptions,
   type GithubSearch,
   renderHits,
 } from "../lib/github.js";
 import { type ToolPendant } from "../lib/pendant.js";
-import { createHttpProxy } from "../lib/proxy.js";
-
-/**
- * 代理配置（~/.pi/agent/proxy.json，回退到 HTTP(S)_PROXY 环境变量）在本模块内共享：
- * `gh` 子进程与 octokit 请求都从这里取，配置只在首次使用时读一次。
- */
-export const httpProxy = createHttpProxy();
 
 /** A tool result: what the model sees plus the structured details payload. */
 export interface ToolResult {
@@ -46,18 +41,6 @@ export interface ToolCall<Params> {
   onUpdate?: (update: ToolResult) => void;
 }
 
-export interface GhResult {
-  stdout: string;
-  stderr: string;
-  code: number;
-  killed: boolean;
-  combined: string;
-  /** Why the process was killed, when `killed` is true. */
-  reason?: "timeout" | "abort";
-  /** When the process could not be started at all (e.g. `gh` not found in PATH). */
-  spawnError?: string;
-}
-
 /**
  * Check whether the `gh` CLI is on the system, scanning PATH like
  * `findDefaultBwrap`. The extension registers no tools when `gh` is missing, so
@@ -78,120 +61,6 @@ export function isGhAvailable(): boolean {
   return false;
 }
 
-export function runGh(
-  args: string[],
-  ctx: {
-    cwd?: string;
-    signal?: AbortSignal;
-    timeout?: number;
-    /** 追加到子进程环境变量（覆盖进程环境与代理配置），供测试或调用方定制。 */
-    env?: NodeJS.ProcessEnv;
-  },
-): Promise<GhResult> {
-  return new Promise((resolve) => {
-    const proc = spawn("gh", args, {
-      cwd: ctx.cwd,
-      shell: false,
-      stdio: ["ignore", "pipe", "pipe"],
-      // gh 是 Go 程序，只认环境变量形式的代理配置；ctx.env 最后合并，调用方可覆盖。
-      env: { ...process.env, ...httpProxy.env, ...ctx.env, GH_PAGER: "cat" },
-    });
-
-    let stdout = "";
-    let stderr = "";
-    const combined: string[] = [];
-    let killed = false;
-    let killReason: "timeout" | "abort" | undefined;
-    let timeoutId: ReturnType<typeof setTimeout> | undefined;
-    let onAbort: (() => void) | undefined;
-
-    const killProcess = (reason: "timeout" | "abort") => {
-      if (killed) {
-        return;
-      }
-
-      killed = true;
-      killReason = reason;
-      proc.kill("SIGTERM");
-      setTimeout(() => {
-        if (!proc.killed) {
-          proc.kill("SIGKILL");
-        }
-      }, 5000);
-    };
-
-    if (ctx.signal) {
-      onAbort = () => killProcess("abort");
-      if (ctx.signal.aborted) {
-        killProcess("abort");
-      } else {
-        ctx.signal.addEventListener("abort", onAbort, { once: true });
-      }
-    }
-
-    // Default timeout: 10 minutes. Long operations like downloading a CI job's
-    // full log routinely take well over 30s, so a short default would kill them
-    // mid-transfer; combined with `code ?? 0` that would silently cache a
-    // truncated log as success. A killed process must never look successful.
-    const timeout = ctx.timeout ?? 600_000;
-    if (timeout > 0) {
-      timeoutId = setTimeout(() => killProcess("timeout"), timeout);
-    }
-
-    proc.stdout.on("data", (data: Buffer) => {
-      const text = data.toString();
-      stdout += text;
-      combined.push(text);
-    });
-    proc.stderr.on("data", (data: Buffer) => {
-      const text = data.toString();
-      stderr += text;
-      combined.push(text);
-    });
-
-    proc.on("close", (code) => {
-      if (timeoutId) {
-        clearTimeout(timeoutId);
-      }
-      if (onAbort && ctx.signal) {
-        ctx.signal.removeEventListener("abort", onAbort);
-      }
-      resolve({
-        stdout,
-        stderr,
-        // When killed by a signal the close event's code is null — including
-        // kills we did not initiate. Report failure instead of pretending it
-        // succeeded. -1 is a sentinel for "did not exit normally" — distinct
-        // from a real gh failure exit code (1), which is always in 0-255.
-        code: code ?? -1,
-        killed,
-        combined: combined.join(""),
-        reason: killReason,
-      });
-    });
-
-    proc.on("error", (err: Error) => {
-      if (timeoutId) {
-        clearTimeout(timeoutId);
-      }
-      if (onAbort && ctx.signal) {
-        ctx.signal.removeEventListener("abort", onAbort);
-      }
-      // spawn 失败（如 gh 不在 PATH → ENOENT、cwd 不存在）时进程从未启动，
-      // 没有任何 stdout/stderr；把底层错误带上，否则会退化成无信息的 "exit code 1"。
-      resolve({
-        stdout,
-        stderr,
-        code: 1,
-        killed,
-        combined: combined.join(""),
-        reason: killReason,
-        spawnError: err.message,
-      });
-    });
-  });
-}
-
 /**
  * Error thrown by `ghExec` when the `gh` invocation exits non-zero.
  * The message carries the toolcall input (JSON) wrapped in `<input>` markers,
@@ -474,10 +343,13 @@ export class GhClient {
   readonly search: GithubSearch;
   readonly checks: GithubChecksClient;
 
-  constructor(fetchImpl: typeof globalThis.fetch = httpProxy.fetch) {
+  constructor(
+    fetchImpl: typeof globalThis.fetch = httpProxy.fetch,
+    options: Pick<GithubClientOptions, "token"> = {},
+  ) {
     this.fetch = fetchImpl;
-    this.search = createGithubSearch({ fetch: fetchImpl });
-    this.checks = createGithubChecks({ fetch: fetchImpl });
+    this.search = createGithubSearch({ fetch: fetchImpl, ...options });
+    this.checks = createGithubChecks({ fetch: fetchImpl, ...options });
   }
 }
 

package/src/gh/tools/watch-run.ts

@@ -1,7 +1,8 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { type GhClient, repoArgs, runGh, subtitlePendant } from "../base.js";
+import { runGh } from "../../lib/gh-process.js";
+import { type GhClient, repoArgs, subtitlePendant } from "../base.js";
 
 export function addWatchRunTool(_gh: GhClient, pi: ExtensionAPI) {
   pi.registerTool({

package/src/lib/gh-process.ts

@@ -0,0 +1,157 @@
+/**
+ * `gh` subprocess adapter: start a `gh` process, collect its output, apply the
+ * shared timeout / kill semantics, and expose the proxy layer the subprocess
+ * inherits. It lives in `lib/` so both the gh tool layer (`src/gh/`) and the
+ * octokit clients (`lib/github.ts`) can depend on it without a cycle.
+ */
+
+import { spawn } from "node:child_process";
+
+import { createHttpProxy } from "./proxy.js";
+
+/**
+ * 代理配置（~/.pi/agent/proxy.json，回退到 HTTP(S)_PROXY 环境变量）在本模块内共享：
+ * `gh` 子进程与 octokit 请求都从这里取，配置只在首次使用时读一次。
+ */
+export const httpProxy = createHttpProxy();
+
+export interface GhResult {
+  stdout: string;
+  stderr: string;
+  code: number;
+  killed: boolean;
+  combined: string;
+  /** Why the process was killed, when `killed` is true. */
+  reason?: "timeout" | "abort";
+  /** When the process could not be started at all (e.g. `gh` not found in PATH). */
+  spawnError?: string;
+}
+
+export interface GhRunContext {
+  cwd?: string;
+  signal?: AbortSignal;
+  timeout?: number;
+  /** 追加到子进程环境变量（覆盖进程环境与代理配置），供测试或调用方定制。 */
+  env?: NodeJS.ProcessEnv;
+}
+
+export function runGh(args: string[], ctx: GhRunContext): Promise<GhResult> {
+  return new Promise((resolve) => {
+    const proc = spawn("gh", args, {
+      cwd: ctx.cwd,
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+      // gh 是 Go 程序，只认环境变量形式的代理配置；ctx.env 最后合并，调用方可覆盖。
+      env: { ...process.env, ...httpProxy.env, ...ctx.env, GH_PAGER: "cat" },
+    });
+
+    let stdout = "";
+    let stderr = "";
+    const combined: string[] = [];
+    let killed = false;
+    let killReason: "timeout" | "abort" | undefined;
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+    let onAbort: (() => void) | undefined;
+
+    const killProcess = (reason: "timeout" | "abort") => {
+      if (killed) {
+        return;
+      }
+
+      killed = true;
+      killReason = reason;
+      proc.kill("SIGTERM");
+      setTimeout(() => {
+        if (!proc.killed) {
+          proc.kill("SIGKILL");
+        }
+      }, 5000);
+    };
+
+    if (ctx.signal) {
+      onAbort = () => killProcess("abort");
+      if (ctx.signal.aborted) {
+        killProcess("abort");
+      } else {
+        ctx.signal.addEventListener("abort", onAbort, { once: true });
+      }
+    }
+
+    // Default timeout: 10 minutes. Long operations like downloading a CI job's
+    // full log routinely take well over 30s, so a short default would kill them
+    // mid-transfer; combined with `code ?? 0` that would silently cache a
+    // truncated log as success. A killed process must never look successful.
+    const timeout = ctx.timeout ?? 600_000;
+    if (timeout > 0) {
+      timeoutId = setTimeout(() => killProcess("timeout"), timeout);
+    }
+
+    proc.stdout.on("data", (data: Buffer) => {
+      const text = data.toString();
+      stdout += text;
+      combined.push(text);
+    });
+    proc.stderr.on("data", (data: Buffer) => {
+      const text = data.toString();
+      stderr += text;
+      combined.push(text);
+    });
+
+    proc.on("close", (code) => {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+      if (onAbort && ctx.signal) {
+        ctx.signal.removeEventListener("abort", onAbort);
+      }
+      resolve({
+        stdout,
+        stderr,
+        // When killed by a signal the close event's code is null — including
+        // kills we did not initiate. Report failure instead of pretending it
+        // succeeded. -1 is a sentinel for "did not exit normally" — distinct
+        // from a real gh failure exit code (1), which is always in 0-255.
+        code: code ?? -1,
+        killed,
+        combined: combined.join(""),
+        reason: killReason,
+      });
+    });
+
+    proc.on("error", (err: Error) => {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+      if (onAbort && ctx.signal) {
+        ctx.signal.removeEventListener("abort", onAbort);
+      }
+      // spawn 失败（如 gh 不在 PATH → ENOENT、cwd 不存在）时进程从未启动，
+      // 没有任何 stdout/stderr；把底层错误带上，否则会退化成无信息的 "exit code 1"。
+      resolve({
+        stdout,
+        stderr,
+        code: 1,
+        killed,
+        combined: combined.join(""),
+        reason: killReason,
+        spawnError: err.message,
+      });
+    });
+  });
+}
+
+/** Read the logged-in token from the system `gh` CLI (`gh auth token`). */
+export async function ghAuthToken(): Promise<string> {
+  const result = await runGh(["auth", "token"], { timeout: 10_000 });
+  if (result.spawnError) {
+    throw new Error(`failed to start gh: ${result.spawnError}`);
+  }
+  const token = result.stdout.trim();
+  if (token && result.code === 0) {
+    return token;
+  }
+  throw new Error(
+    result.stderr.trim() ||
+      `gh auth token exited with code ${result.code} — run "gh auth login" first`,
+  );
+}

package/src/lib/github.ts

@@ -8,11 +8,10 @@
  * rendered state is derived from `pull_request.merged_at`.
  */
 
-import { spawn } from "node:child_process";
-
 import { Octokit } from "octokit";
 import { type Static, Type } from "typebox";
 
+import { ghAuthToken } from "./gh-process.js";
 import { parseWithSchema } from "./parse-with-schema.js";
 
 export type SearchKind = "issue" | "pr";
@@ -218,38 +217,6 @@ function normalize(raw: SearchItem): SearchHit {
   };
 }
 
-function ghAuthToken(): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const proc = spawn("gh", ["auth", "token"], { stdio: ["ignore", "pipe", "pipe"] });
-    let stdout = "";
-    let stderr = "";
-    const timer = setTimeout(() => proc.kill("SIGTERM"), 10_000);
-    proc.stdout.on("data", (d: Buffer) => {
-      stdout += String(d);
-    });
-    proc.stderr.on("data", (d: Buffer) => {
-      stderr += String(d);
-    });
-    proc.on("error", (err) => {
-      clearTimeout(timer);
-      reject(new Error(`failed to start gh: ${err.message}`));
-    });
-    proc.on("close", (code) => {
-      clearTimeout(timer);
-      const token = stdout.trim();
-      if (code === 0 && token) {
-        resolve(token);
-      } else {
-        reject(
-          new Error(
-            stderr.trim() || `gh auth token exited with code ${code} — run "gh auth login" first`,
-          ),
-        );
-      }
-    });
-  });
-}
-
 /**
  * Error thrown when the GitHub search API rejects the request. Carries the
  * original toolcall params so the model can see the exact input.
@@ -291,6 +258,8 @@ export interface GithubClientOptions {
    * proxy dispatcher attached. Defaults to the global fetch.
    */
   fetch?: typeof globalThis.fetch;
+  /** gh token provider；缺省读系统 `gh auth token`（见 lib/gh-process.ts）。 */
+  token?: () => Promise<string>;
 }
 
 /**
@@ -304,7 +273,7 @@ function createGithubApi(options: GithubClientOptions = {}): GithubApi {
 
   async function getClient(): Promise<Octokit> {
     client ??= new Octokit({
-      auth: await ghAuthToken(),
+      auth: await (options.token ?? ghAuthToken)(),
       ...(options.fetch && { request: { fetch: options.fetch } }),
     });
     return client;

package/src/spawn-agent-progress.ts

@@ -0,0 +1,214 @@
+/**
+ * Progress state machine for the `spawn_agent` tool.
+ *
+ * The parent sees a rolling log: `tool: <name>` lines for tool calls and
+ * `text: <content>` lines for completed text blocks, keeping the last
+ * `MAX_PROGRESS_LINES` lines. Consecutive tool calls are merged into a single
+ * `tool:` line (`read x 2, glob`) and the merged content is folded to the
+ * first/last 9 chars joined by `…`, so a burst of tool calls or a long text
+ * block does not flood the window. Only a text block starts a new line —
+ * thinking is a transient status line, so it does not break the merge across
+ * turn boundaries. Line content is sanitized first: markdown marker characters
+ * are stripped and whitespace (including newlines) is collapsed to single
+ * spaces, so one log entry is always exactly one rendered line.
+ *
+ * The rendered panel is the window, then an optional transient
+ * `thinking ( N chars )` line while the model is thinking, then a fixed footer
+ * line: the subagent name as a code span (`` `scout` ``) followed by the live
+ * usage stats when there are any. The thinking line and the footer ride
+ * outside the rolling window, so the footer is never trimmed. The model name
+ * on the footer is the model the session actually uses, which differs from the
+ * frontmatter string when the declared model resolved to nothing and the SDK
+ * fell back to a default.
+ *
+ * State is held in the closure of a `createSubagentProgress` instance, one per
+ * run. The `noteX` methods only mutate state and return nothing; pushing the
+ * rendered text to the host (`onUpdate`) is the caller's job, so the caller
+ * decides when a state change is worth a refresh.
+ */
+
+/**
+ * Progress log keeps only the most recent lines (rolling window).
+ * 展开后面板最多 6 行内容：4 行日志 + 可能的一行瞬态 thinking + 固定的 metadata 行。
+ */
+const MAX_PROGRESS_LINES = 4;
+/** Progress line content (without the `tool:` / `text:` prefix) is capped at 21 chars; longer text is folded to the first/last 9 chars joined by ` … `. */
+const MAX_PROGRESS_CHARS_PER_LINE = 21;
+/**
+ * 进度内容会被 pi 按 markdown 渲染，这些标记字符会改变显示效果（代码块、粗体、
+ * 链接、标题等），因此在进日志前统一删掉。
+ */
+const PROGRESS_MARKDOWN_MARKERS_RE = /[`*_~[\]<>#|]/g;
+
+/** 进度面板要展示的运行统计（`runAgent` 的 `result.usage`）。 */
+export interface ProgressUsage {
+  turns: number;
+  cost: number;
+  contextTokens: number;
+}
+
+/** 一次子代理运行的进度状态机：改状态用 `noteX`，取文本用 `render`。 */
+export interface SubagentProgress {
+  /** 工具调用开始：合并进当前 `tool:` 行。 */
+  noteToolCall(rawName: string): void;
+  /** 一个完成的 text 块：作为 `text:` 行写入并打断工具合并。 */
+  noteTextBlock(content: string): void;
+  /** thinking 开始：打开瞬态行（计数从 0 开始）。 */
+  thinkingStart(): void;
+  /** thinking 增量：累加字符数。 */
+  thinkingDelta(length: number): void;
+  /** thinking 结束：关闭瞬态行。 */
+  thinkingEnd(): void;
+  /** 渲染面板：滚动窗口 + 瞬态 thinking 行 + footer。 */
+  render(usage: ProgressUsage, model?: string): string;
+}
+
+/**
+ * Fold over-long progress line content: keep the first/last 9 chars joined by
+ * ` … ` (space, ellipsis, space), so the folded line never exceeds
+ * `MAX_PROGRESS_CHARS_PER_LINE` chars (9 + 3 + 9 = 21). Shorter text is
+ * returned as-is.
+ */
+function foldProgressLine(text: string): string {
+  if (text.length <= MAX_PROGRESS_CHARS_PER_LINE) {
+    return text;
+  }
+  const keep = Math.floor((MAX_PROGRESS_CHARS_PER_LINE - 3) / 2);
+  return `${text.slice(0, keep)} … ${text.slice(-keep)}`;
+}
+
+/**
+ * 进度行是「单行内容 + markdown 渲染」：内容里的换行会打乱按行滚动的窗口，
+ * markdown 标记会改变渲染效果。先删掉标记字符，再把换行/制表符/连续空格折成
+ * 单个空格并去掉首尾空白，保证一条日志恒为一行。
+ */
+function sanitizeProgressLine(text: string): string {
+  return text.replaceAll(PROGRESS_MARKDOWN_MARKERS_RE, "").replaceAll(/\s+/g, " ").trim();
+}
+
+/**
+ * token 计数的可读格式。进度面板 footer 与 spawn_agent 的输出截断提示共用，
+ * 改动会同时影响两处。
+ */
+export function formatTokens(count: number): string {
+  if (count < 1000) {
+    return count.toString();
+  }
+  if (count < 10_000) {
+    return `${(count / 1000).toFixed(1)}k`;
+  }
+  if (count < 1_000_000) {
+    return `${Math.round(count / 1000)}k`;
+  }
+  return `${(count / 1_000_000).toFixed(1)}M`;
+}
+
+function formatUsageStats(usage: ProgressUsage, model?: string): string {
+  const parts: string[] = [];
+  if (usage.turns) {
+    parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
+  }
+  if (usage.cost) {
+    parts.push(`$${usage.cost.toFixed(4)}`);
+  }
+  if (usage.contextTokens > 0) {
+    parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
+  }
+  if (model) {
+    parts.push(model);
+  }
+  return parts.join(" ");
+}
+
+function toolSegment(name: string, count: number): string {
+  return count > 1 ? `${name} x ${count}` : name;
+}
+
+/**
+ * Create the progress state machine for one subagent run.
+ *
+ * `maxLines` only controls the rolling window of log lines — the transient
+ * thinking line and the footer ride outside it. Defaults to
+ * `MAX_PROGRESS_LINES`.
+ */
+export function createSubagentProgress(options: {
+  /** 面板标题（子代理名）。 */
+  name: string;
+  /** 滚动窗口行数，缺省 4。 */
+  maxLines?: number;
+}): SubagentProgress {
+  const maxLines = options.maxLines ?? MAX_PROGRESS_LINES;
+  let logLines: string[] = [];
+  // 工具调用行合并:连续的 tool_execution_start 事件合并在同一 `tool:` 行
+  // (如 `tool: read x 2, glob`),相同工具名连续出现时计为 `name x N`,
+  // 不同名按调用顺序罗列;只有写入日志行的事件(text 块)打断合并,thinking
+  // 不写日志行、也不打断合并。
+  let toolLineSegments: string[] = [];
+  let toolLine: { name: string; count: number } | undefined;
+  // 思考中状态：thinkingStart 打开、thinkingDelta 累计字符数、thinkingEnd
+  // 关闭；非 undefined 时 render 在 footer 上方插一行瞬态 thinking 状态。
+  let thinkingChars: number | undefined;
+
+  function pushLogLine(line: string) {
+    logLines.push(line);
+    if (logLines.length > maxLines) {
+      logLines = logLines.slice(-maxLines);
+    }
+    // 写进日志的新行都会打断工具调用合并,下一批调用另起一行。
+    toolLine = undefined;
+  }
+
+  function appendToolLine(rawName: string) {
+    const name = sanitizeProgressLine(rawName);
+    const firstInBatch = toolLine === undefined;
+    if (toolLine === undefined) {
+      toolLineSegments = [];
+      toolLine = { name, count: 1 };
+    } else if (toolLine.name === name) {
+      toolLine.count++;
+    } else {
+      toolLineSegments.push(toolSegment(toolLine.name, toolLine.count));
+      toolLine = { name, count: 1 };
+    }
+    const parts = [...toolLineSegments, toolSegment(toolLine.name, toolLine.count)].join(", ");
+    const line = `tool: ${foldProgressLine(parts)}`;
+    if (firstInBatch) {
+      logLines.push(line);
+      if (logLines.length > maxLines) {
+        logLines = logLines.slice(-maxLines);
+      }
+    } else {
+      logLines[logLines.length - 1] = line;
+    }
+  }
+
+  return {
+    noteToolCall: appendToolLine,
+    noteTextBlock(content) {
+      pushLogLine(`text: ${foldProgressLine(sanitizeProgressLine(content))}`);
+    },
+    thinkingStart() {
+      thinkingChars = 0;
+    },
+    thinkingDelta(length) {
+      thinkingChars = (thinkingChars ?? 0) + length;
+    },
+    thinkingEnd() {
+      thinkingChars = undefined;
+    },
+    render(usage, model) {
+      // 最后一行固定是「子代理名 + 运行中统计」：名字用 code span 标出，进度流里
+      // 一眼能看出属于哪个 subagent；usage 与它同行，TUI 始终能看到实时 token 开销。
+      // 这行位于滚动窗口之外，因此永远不会被挤掉。
+      const usageLine = formatUsageStats(usage, model);
+      const name = sanitizeProgressLine(options.name);
+      const footer = usageLine ? `\`${name}\` ${usageLine}` : `\`${name}\``;
+      const lines = [...logLines];
+      if (thinkingChars !== undefined) {
+        lines.push(`thinking ( ${thinkingChars} chars )`);
+      }
+      lines.push(footer);
+      return lines.join("\n");
+    },
+  };
+}

package/src/spawn-agent.ts

@@ -12,8 +12,8 @@
  * returns its final output to the parent model. Progress is streamed through
  * `onUpdate`, the same channel the built-in bash tool uses for live output.
  * Progress is a rolling log: `tool: <name>` lines for tool calls and
- * `text: <content>` lines for completed text blocks, keeping the last
- * `MAX_PROGRESS_LINES` lines. Consecutive tool calls are merged into a
+ * `text: <content>` lines for completed text blocks, keeping only the last few
+ * lines (`MAX_PROGRESS_LINES` in spawn-agent-progress.ts). Consecutive tool calls are merged into a
  * single `tool:` line (`read x 2, glob`) and over-long line content is
  * folded to the first/last 9 chars joined by `…`, so a burst of tool calls
  * or a long text block does not flood the window; only a text block starts
@@ -79,6 +79,7 @@ import {
   formatAgentList,
   loadSpawnAgentConfig,
 } from "./spawn-agent-agents.js";
+import { createSubagentProgress, formatTokens } from "./spawn-agent-progress.js";
 
 // ── constants ────────────────────────────────────────────────────────────────
 
@@ -96,18 +97,6 @@ export const SUBAGENT_DEFAULT_SANDBOX: BwrapConfig = completeBwrapConfig({
   fs: { mode: "readonly" },
   network: { mode: "block" },
 });
-/**
- * Progress log keeps only the most recent lines (rolling window).
- * 展开后面板最多 6 行内容：4 行日志 + 可能的一行瞬态 thinking + 固定的 metadata 行。
- */
-const MAX_PROGRESS_LINES = 4;
-/** Progress line content (without the `tool:` / `text:` prefix) is capped at 21 chars; longer text is folded to the first/last 9 chars joined by ` … `. */
-const MAX_PROGRESS_CHARS_PER_LINE = 21;
-/**
- * 进度内容会被 pi 按 markdown 渲染，这些标记字符会改变显示效果（代码块、粗体、
- * 链接、标题等），因此在进日志前统一删掉。
- */
-const PROGRESS_MARKDOWN_MARKERS_RE = /[`*_~[\]<>#|]/g;
 /** 错误消息里 stderr 的展示上限。 */
 const MAX_STDERR_ERROR_BYTES = 4 * 1024;
 /** 全局默认配置：~/.pi/agent/spawn-agent.json，字段可被 frontmatter 覆盖。 */
@@ -231,59 +220,6 @@ export function formatSubagentError(result: SubagentResult): { reason: string; m
   return { reason, message: parts.length > 0 ? parts.join("\n") : "(no output)" };
 }
 
-/**
- * Fold over-long progress line content: keep the first/last 9 chars joined by
- * ` … ` (space, ellipsis, space), so the folded line never exceeds
- * `MAX_PROGRESS_CHARS_PER_LINE` chars (9 + 3 + 9 = 21). Shorter text is
- * returned as-is.
- */
-function foldProgressLine(text: string): string {
-  if (text.length <= MAX_PROGRESS_CHARS_PER_LINE) {
-    return text;
-  }
-  const keep = Math.floor((MAX_PROGRESS_CHARS_PER_LINE - 3) / 2);
-  return `${text.slice(0, keep)} … ${text.slice(-keep)}`;
-}
-
-/**
- * 进度行是「单行内容 + markdown 渲染」：内容里的换行会打乱按行滚动的窗口，
- * markdown 标记会改变渲染效果。先删掉标记字符，再把换行/制表符/连续空格折成
- * 单个空格并去掉首尾空白，保证一条日志恒为一行。
- */
-function sanitizeProgressLine(text: string): string {
-  return text.replaceAll(PROGRESS_MARKDOWN_MARKERS_RE, "").replaceAll(/\s+/g, " ").trim();
-}
-
-function formatTokens(count: number): string {
-  if (count < 1000) {
-    return count.toString();
-  }
-  if (count < 10_000) {
-    return `${(count / 1000).toFixed(1)}k`;
-  }
-  if (count < 1_000_000) {
-    return `${Math.round(count / 1000)}k`;
-  }
-  return `${(count / 1_000_000).toFixed(1)}M`;
-}
-
-function formatUsageStats(usage: UsageStats, model?: string): string {
-  const parts: string[] = [];
-  if (usage.turns) {
-    parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
-  }
-  if (usage.cost) {
-    parts.push(`$${usage.cost.toFixed(4)}`);
-  }
-  if (usage.contextTokens > 0) {
-    parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
-  }
-  if (model) {
-    parts.push(model);
-  }
-  return parts.join(" ");
-}
-
 /** 子 agent 结果的折叠面板 markdown：父 agent 的 prompt 与父 agent 看到的结果。 */
 function formatPendantMarkdown(task: string, response: string): string {
   return `# prompt:\n${task.trim()}\n# response\n${response.trim()}`;
@@ -375,10 +311,6 @@ export function resolveModel(
 
 type OnUpdateCallback = (partial: AgentToolResult<SubagentDetails>) => void;
 
-function toolSegment(name: string, count: number): string {
-  return count > 1 ? `${name} x ${count}` : name;
-}
-
 /** The subset of AgentSession runAgent relies on (injectable for tests). */
 export interface SubagentSession {
   agent: { state: { messages: AgentMessage[] } };
@@ -478,65 +410,11 @@ export async function runAgent(
   // fallback 到默认模型，回显配置原文会掩盖这次 fallback。
   result.model = session.model?.id;
 
-  let logLines: string[] = [];
-  // 工具调用行合并:连续的 tool_execution_start 事件合并在同一 `tool:` 行
-  // (如 `tool: read x 2, glob`),相同工具名连续出现时计为 `name x N`,
-  // 不同名按调用顺序罗列;只有写入日志行的事件(text 块)打断合并,thinking
-  // 不写日志行、也不打断合并。
-  let toolLineSegments: string[] = [];
-  let toolLine: { name: string; count: number } | undefined;
-  // 思考中状态：thinking_start 打开、thinking_delta 累计字符数、thinking_end
-  // 关闭；非 undefined 时 emitUpdate 在 footer 上方插一行瞬态 thinking 状态。
-  let thinkingChars: number | undefined;
-
-  const pushLogLine = (line: string) => {
-    logLines.push(line);
-    if (logLines.length > MAX_PROGRESS_LINES) {
-      logLines = logLines.slice(-MAX_PROGRESS_LINES);
-    }
-    // 写进日志的新行都会打断工具调用合并,下一批调用另起一行。
-    toolLine = undefined;
-  };
-
-  const appendToolLine = (rawName: string) => {
-    const name = sanitizeProgressLine(rawName);
-    const firstInBatch = toolLine === undefined;
-    if (toolLine === undefined) {
-      toolLineSegments = [];
-      toolLine = { name, count: 1 };
-    } else if (toolLine.name === name) {
-      toolLine.count++;
-    } else {
-      toolLineSegments.push(toolSegment(toolLine.name, toolLine.count));
-      toolLine = { name, count: 1 };
-    }
-    const parts = [...toolLineSegments, toolSegment(toolLine.name, toolLine.count)].join(", ");
-    const line = `tool: ${foldProgressLine(parts)}`;
-    if (firstInBatch) {
-      logLines.push(line);
-      if (logLines.length > MAX_PROGRESS_LINES) {
-        logLines = logLines.slice(-MAX_PROGRESS_LINES);
-      }
-    } else {
-      logLines[logLines.length - 1] = line;
-    }
-    emitUpdate();
-  };
+  const progress = createSubagentProgress({ name: result.agent });
 
   const emitUpdate = () => {
-    // 最后一行固定是「子代理名 + 运行中统计」：名字用 code span 标出，进度流里
-    // 一眼能看出属于哪个 subagent；usage 与它同行，TUI 始终能看到实时 token 开销。
-    // 这行位于滚动窗口之外，因此永远不会被挤掉。
-    const usageLine = formatUsageStats(result.usage, result.model);
-    const name = sanitizeProgressLine(result.agent);
-    const footer = usageLine ? `\`${name}\` ${usageLine}` : `\`${name}\``;
-    const lines = [...logLines];
-    if (thinkingChars !== undefined) {
-      lines.push(`thinking ( ${thinkingChars} chars )`);
-    }
-    lines.push(footer);
     onUpdate?.({
-      content: [{ type: "text", text: lines.join("\n") }],
+      content: [{ type: "text", text: progress.render(result.usage, result.model) }],
       details: {},
     });
   };
@@ -550,24 +428,24 @@ export async function runAgent(
         const delta = event.assistantMessageEvent;
         switch (delta.type) {
           case "text_end": {
-            pushLogLine(`text: ${foldProgressLine(sanitizeProgressLine(delta.content))}`);
+            progress.noteTextBlock(delta.content);
             emitUpdate();
             break;
           }
           case "thinking_start": {
             // thinking 不产生日志行，因此不打断工具行合并：跨轮次的连续工具调用
             // 仍累加到同一 `tool:` 行。
-            thinkingChars = 0;
+            progress.thinkingStart();
             emitUpdate();
             break;
           }
           case "thinking_delta": {
-            thinkingChars = (thinkingChars ?? 0) + delta.delta.length;
+            progress.thinkingDelta(delta.delta.length);
             emitUpdate();
             break;
           }
           case "thinking_end": {
-            thinkingChars = undefined;
+            progress.thinkingEnd();
             emitUpdate();
             break;
           }
@@ -577,7 +455,8 @@ export async function runAgent(
         break;
       }
       case "tool_execution_start": {
-        appendToolLine(event.toolName);
+        progress.noteToolCall(event.toolName);
+        emitUpdate();
         break;
       }
       case "message_end": {