@trim21/personal-pi-extensions 0.1.690 → 0.1.691

package/README.md

@@ -461,20 +461,20 @@ pi -e ./src/aft/index.ts
 
 ## gh-readonly
 
-GitHub 只读工具集。取数走 octokit REST（`src/lib/github-reads.ts`）；只有「当前仓库」解析（`gh repo view`）与 token 获取（`gh auth token`）还用系统 [`gh`](https://cli.github.com/)，因此 `gh` 不在 PATH 时整组不注册并在 session_start 报错；Windows 禁用。
+GitHub 只读工具集。取数全部走 octokit REST（`src/lib/github-reads.ts` 的读取层 + `src/lib/github.ts` 的 accessor）；只有「当前仓库」解析（`gh repo view`）与 token 获取（`gh auth token`）还用系统 [`gh`](https://cli.github.com/)，因此 `gh` 不在 PATH 时整组不注册并在 session_start 报错；Windows 禁用。一个会话只 spawn 一次 `gh auth token`：三个子客户端（search / checks / reads）共用同一个 accessor。
 
 - **Issue / PR**：`read-github-issue`、`list-github-issues`、`read-github-issue-comments`、`read-github-pr`、`list-github-prs`、`read-github-pr-diff`、`read-github-pr-status`、`read-github-pr-comments`
 - **CI**：`read-github-ci-logs`、`list-github-workflow-runs`、`get-github-workflow-jobs`、`wait-github-pr-checks`、`wait-github-commit-checks`、`watch-github-run`
 - **仓库 / 发布**：`read-github-repo`、`list-github-releases`、`read-github-release`、`download-github-release-assets`
 
-`list-github-issues` / `list-github-prs` 带 `keywords` 时走 GitHub search API（state 缺省只搜 open，`state: "all"` 不加 state qualifier 覆盖 open + closed），输出 TSV，默认列 `number,state,title,labels,updatedAt`，可用 `fields` 白名单指定列。`wait-github-pr-checks` / `wait-github-commit-checks` 30 秒轮询、600 秒截止：任一 fail 即返回，全部 pass / skipped 才算通过，超时返回快照不抛错。
+`list-github-issues` / `list-github-prs` 带 `keywords` 时走 GitHub search API，不带 `keywords` 时走 REST 列表端点（state 缺省只搜 open，`state: "all"` 不加 state qualifier 覆盖 open + closed），输出 TSV，默认列 `number,state,title,labels,updatedAt`，可用 `fields` 白名单指定列。`wait-github-pr-checks` / `wait-github-commit-checks` 30 秒轮询、600 秒截止：任一 fail 即返回，全部 pass / skipped 才算通过，超时返回快照不抛错。
 
 出网代理：`~/.pi/agent/proxy.json`（`{ "proxy": "http://127.0.0.1:7890", "noProxy": "localhost" }`），缺省字段回退 `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` / `NO_PROXY` 环境变量。
 
 ### 使用
 
 ```bash
-pi -e ./src/gh-readonly.ts
+pi -e ./src/gh/index.ts
 ```
 
 ---

package/package.json

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

package/src/bwrap/dcg-scan.ts

@@ -7,6 +7,8 @@
  */
 import { spawn } from "node:child_process";
 
+import { escapeHtml } from "./html.js";
+
 /** `dcg test --format json` 输出中我们关心的字段。 */
 interface DcgTestOutput {
   decision?: "allow" | "deny" | "indeterminate";
@@ -30,14 +32,6 @@ export type DcgScanOutcome =
 /** dcg 扫描的超时预算：超时视为无建议，不让审批弹窗被拖住。 */
 const DCG_SCAN_TIMEOUT_MS = 2000;
 
-function escapeHtml(text: string): string {
-  return text
-    .replaceAll("&", "&")
-    .replaceAll("<", "&lt;")
-    .replaceAll(">", "&gt;")
-    .replaceAll('"', "&quot;");
-}
-
 /**
  * 对命令做 dcg 扫描。返回三种结果：
  * - `suggestion`：正常判定，携带建议文本

package/src/bwrap/html.ts

@@ -0,0 +1,13 @@
+/**
+ * UI 文本的 HTML 转义。
+ *
+ * bwrap 的审批弹窗把外部文本（dcg 建议、命令、路径）直接拼进 HTML description，
+ * 这些文本必须先转义，否则会成为弹窗里的标签/属性。
+ */
+export function escapeHtml(text: string): string {
+  return text
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}

package/src/bwrap/runtime.ts

@@ -43,6 +43,7 @@ import {
   type ResolvedBwrap,
 } from "./core.js";
 import { dcgSuggestion } from "./dcg-scan.js";
+import { escapeHtml } from "./html.js";
 import { loadSandboxConfig, runInSandbox } from "./sandbox.js";
 
 /** 全权限审批对话框的选项 label（也作为 switch 匹配键与测试引用）。 */
@@ -155,14 +156,6 @@ export function formatElapsedSeconds(elapsedMs: number): string {
   return `${(elapsedMs / 1000).toFixed(1)} seconds`;
 }
 
-function escapeHtml(text: string): string {
-  return text
-    .replaceAll("&", "&")
-    .replaceAll("<", "&lt;")
-    .replaceAll(">", "&gt;")
-    .replaceAll('"', "&quot;");
-}
-
 /** 进度推送的节流间隔（对齐 pi 内置 bash 工具的 100ms）。 */
 const BASH_UPDATE_THROTTLE_MS = 100;
 /** 进度快照只保留尾部内容，避免大输出每 100ms 全量推给 TUI。 */

package/src/claude-code/shell.ts

@@ -16,12 +16,15 @@ import {
   formatElapsedSeconds,
   sandboxHintBlock,
 } from "../bwrap/runtime.js";
+import {
+  BASH_DEFAULT_TIMEOUT_MS,
+  BASH_MAX_TIMEOUT_MS,
+  bashStructuredSchema,
+  spilledOutput,
+} from "../lib/bash-tool.js";
 import { resolveWorkdir } from "../lib/path.js";
 import { defineStructuredTool, type ToolBus } from "../lib/tool-bus.js";
 
-const DEFAULT_TIMEOUT_MS = 120_000;
-const MAX_TIMEOUT_MS = 7_200_000;
-
 /** 对齐 Claude Code formatError：错误文本超过该长度时头尾各保留一半。 */
 const MAX_ERROR_CHARS = 10_000;
 
@@ -66,39 +69,6 @@ function appendTruncationNotice(
   return `${text}\n\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines} (${formatSize(truncation.maxBytes)} limit). Full output: ${fullOutputPath}]`;
 }
 
-/**
- * `Bash` 的结构化结果：只有退出码与完整输出——命令非零退出不是失败，所以载荷里没有成败
- * 标志，脚本直接读 `exitCode` 分支；超时/中止时 `exitCode` 为 `null`（原因在模型侧文本里）。
- */
-const bashStructuredSchema = Type.Object({
-  exitCode: Type.Union([Type.Number(), Type.Null()], {
-    description: "Exit code of the command; null when it was killed (timeout or abort)",
-  }),
-  output: Type.String({
-    description:
-      "Complete output of the command (stdout and stderr merged). Never truncated, never mixed with tool-added notices.",
-  }),
-});
-
-/**
- * 载荷里的输出：文本被截断时读回落盘的完整输出（读不到就退回那份截断文本），
- * 因此脚本拿到的永远是命令真正输出的内容。
- */
-async function fullOutput(
-  output: string,
-  truncation: TruncationResult,
-  spillPath: string | undefined,
-): Promise<string> {
-  if (spillPath === undefined || !truncation.truncated) {
-    return output;
-  }
-  try {
-    return await readFile(spillPath, "utf8");
-  } catch {
-    return output;
-  }
-}
-
 /**
  * 成功路径：消费 runtime 的截断结果（输出已由 runtime 截断并落盘），
  * 截断时追加 `[Showing lines X-Y of N. Full output: path]` 提示。
@@ -158,9 +128,9 @@ export function registerShellTools(bus: ToolBus, pi: ExtensionAPI, runtime: Bwra
         { additionalProperties: false },
       ),
       async execute(id, params, signal, onUpdate, ctx) {
-        const timeout = params.timeout ?? DEFAULT_TIMEOUT_MS;
-        if (!Number.isFinite(timeout) || timeout <= 0 || timeout > MAX_TIMEOUT_MS) {
-          throw new Error(`timeout must be between 1 and ${MAX_TIMEOUT_MS} milliseconds`);
+        const timeout = params.timeout ?? BASH_DEFAULT_TIMEOUT_MS;
+        if (!Number.isFinite(timeout) || timeout <= 0 || timeout > BASH_MAX_TIMEOUT_MS) {
+          throw new Error(`timeout must be between 1 and ${BASH_MAX_TIMEOUT_MS} milliseconds`);
         }
 
         const cwd = params.workdir ? await resolveWorkdir(params.workdir, ctx.cwd) : ctx.cwd;
@@ -203,7 +173,7 @@ export function registerShellTools(bus: ToolBus, pi: ExtensionAPI, runtime: Bwra
                   ok: true as const,
                   value: {
                     exitCode: null,
-                    output: await fullOutput(
+                    output: await spilledOutput(
                       error.partial.output,
                       error.partial.truncation,
                       error.partial.fullOutputPath,
@@ -226,7 +196,7 @@ export function registerShellTools(bus: ToolBus, pi: ExtensionAPI, runtime: Bwra
                 ok: true as const,
                 value: {
                   exitCode: null,
-                  output: await fullOutput(
+                  output: await spilledOutput(
                     error.partial.output,
                     error.partial.truncation,
                     error.partial.fullOutputPath,
@@ -264,7 +234,7 @@ export function registerShellTools(bus: ToolBus, pi: ExtensionAPI, runtime: Bwra
             ok: true as const,
             value: {
               exitCode: result.exitCode,
-              output: await fullOutput(result.output, result.truncation, result.fullOutputPath),
+              output: await spilledOutput(result.output, result.truncation, result.fullOutputPath),
             },
           },
         };

package/src/codemode/declarations.ts

@@ -6,6 +6,7 @@
  * const / union / enum），其余退化成 `unknown`——宁可少给类型，也不要编出错类型。
  */
 
+import { isRecord } from "../lib/narrow.js";
 import type { ScriptTool } from "./protocol.js";
 
 interface ToolLike {
@@ -16,12 +17,6 @@ interface ToolLike {
   structuredSchema: unknown;
 }
 
-type JsonSchema = Record<string, unknown>;
-
-function isSchema(value: unknown): value is JsonSchema {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function literal(value: unknown): string {
   return typeof value === "string" ? JSON.stringify(value) : String(value);
 }
@@ -32,7 +27,7 @@ function propertyName(name: string): string {
 }
 
 function renderType(schema: unknown, indent: string): string {
-  if (!isSchema(schema)) {
+  if (!isRecord(schema)) {
     return "unknown";
   }
   // TypeBox 的 Type.Literal / StringEnum 产出 const，而不是 enum
@@ -64,7 +59,7 @@ function renderType(schema: unknown, indent: string): string {
       return `Array<${renderType(schema.items, indent)}>`;
     }
     case "object": {
-      const properties = isSchema(schema.properties) ? schema.properties : {};
+      const properties = isRecord(schema.properties) ? schema.properties : {};
       const required = new Set(Array.isArray(schema.required) ? (schema.required as string[]) : []);
       const entries = Object.entries(properties);
       if (entries.length === 0) {

package/src/gh/base.ts

@@ -18,6 +18,7 @@ import {
   type ActionJob,
   type CheckRun,
   type CommitStatus,
+  createGithubApi,
   createGithubChecks,
   createGithubSearch,
   type GithubChecksClient,
@@ -31,7 +32,7 @@ import { createGithubReads, type GithubReads } from "../lib/github-reads.js";
 import { parseWithSchema } from "../lib/parse-with-schema.js";
 import { type ToolPendant } from "../lib/pendant.js";
 import { type StructuredResult } from "../lib/tool-bus.js";
-import type { checksVerdictSchema } from "./schemas.js";
+import { type checksVerdictSchema, ghRunSummarySchema } from "./schemas.js";
 
 /** A tool result: what the model sees plus the structured details payload. */
 export interface ToolResult {
@@ -178,6 +179,29 @@ export async function resolveRepo(
   return nameWithOwner;
 }
 
+/** 工具操作的仓库：`OWNER/REPO` 全名加拆分后的两段。 */
+export interface RepoTarget {
+  /** 规范化的 `OWNER/REPO`（参数缺省时来自当前目录解析）。 */
+  readonly fullName: string;
+  readonly owner: string;
+  readonly name: string;
+}
+
+/**
+ * 解析工具该操作的仓库并拆开 `OWNER/REPO`。取数工具都要走这一步，收成一个调用
+ * 后每个工具只剩一行，也不再需要各自 import `splitRepo`。
+ */
+export async function resolveRepoTarget(
+  repo: string | undefined,
+  signal: AbortSignal | undefined,
+  cwd: string | undefined,
+  input?: unknown,
+): Promise<RepoTarget> {
+  const fullName = await resolveRepo(repo, signal, cwd, input);
+  const { owner, repo: name } = splitRepo(fullName);
+  return { fullName, owner, name };
+}
+
 export function truncate(
   text: string,
   maxLines = 2000,
@@ -294,6 +318,58 @@ export function subtitlePendant<IdKey extends string = never>(
   return { subtitle: parts.join(" ") };
 }
 
+/**
+ * 给结果挂上 pendant subtitle 后原样返回：取数工具的固定收尾，省掉每个工具重复的
+ * `result.details.pendant = ...; return result;` 两行。
+ */
+export function withPendant<T extends ToolResult, IdKey extends string = never>(
+  result: T,
+  params: { repo?: string } & Partial<Record<IdKey, string | number>>,
+  idKey?: IdKey,
+): T {
+  result.details.pendant = subtitlePendant(params, idKey);
+  return result;
+}
+
+/**
+ * `list-github-issues` / `list-github-prs` 共用的一套过滤参数，只有 `state` 与 `fields`
+ * 的说明文案按 kind 不同。
+ */
+export function listFilterParameters(kind: "issue" | "pr") {
+  const isPr = kind === "pr";
+  return Type.Object({
+    repo: Type.Optional(Type.String({ description: "OWNER/REPO (defaults to current repo)" })),
+    keywords: Type.Optional(Type.String({ description: "Search keywords (free text)" })),
+    state: Type.Optional(
+      Type.String({
+        description: isPr
+          ? "open, closed, merged, all (default: open; all applies to keyword search and covers open + closed + merged)"
+          : "open, closed, all (default: open; all applies to keyword search and covers closed too)",
+      }),
+    ),
+    label: Type.Optional(Type.String({ description: "Filter by label" })),
+    // `@me` 只在关键词搜索分支可用：搜索 API 自己把它解析成当前登录用户。浏览分支走
+    // REST 列表端点，`@me` 按字面量转发，不会匹配到当前用户（本仓库不做展开）。
+    author: Type.Optional(
+      Type.String({
+        description: "Filter by author ('@me' works with keywords; browse takes it literally)",
+      }),
+    ),
+    assignee: Type.Optional(
+      Type.String({
+        description: "Filter by assignee ('@me' works with keywords; browse takes it literally)",
+      }),
+    ),
+    milestone: Type.Optional(Type.String({ description: "Filter by milestone" })),
+    limit: Type.Optional(Type.Number({ description: "Max results (default 30, max 100)" })),
+    fields: Type.Optional(
+      Type.String({
+        description: `Comma-separated columns for the rows (default: number,state,title,labels,updatedAt; adds repo when no repo given). Valid: number,state,title,url,author,labels,milestone,assignees,comments,repo,createdAt,updatedAt,closedAt${isPr ? ",mergedAt" : ""}`,
+      }),
+    ),
+  });
+}
+
 export interface ListFilters {
   repo?: string;
   keywords?: string;
@@ -317,8 +393,11 @@ export async function browseList(
   params: ListFilters,
   ctx: { cwd?: string; signal?: AbortSignal; input?: unknown },
 ): Promise<{ repo: string; hits: SearchHit[] }> {
-  const repo = params.repo ?? (await resolveRepo(undefined, ctx.signal, ctx.cwd, ctx.input));
-  const { owner, repo: repoName } = splitRepo(repo);
+  const {
+    fullName: repo,
+    owner,
+    name,
+  } = await resolveRepoTarget(params.repo, ctx.signal, ctx.cwd, ctx.input);
   const query = {
     state: params.state,
     label: params.label,
@@ -329,8 +408,8 @@ export async function browseList(
   };
   const items =
     kind === "issue"
-      ? await gh.reads.listIssues(owner, repoName, query, ctx.signal)
-      : await gh.reads.listPulls(owner, repoName, query, ctx.signal);
+      ? await gh.reads.listIssues(owner, name, query, ctx.signal)
+      : await gh.reads.listPulls(owner, name, query, ctx.signal);
   return { repo, hits: normalizeRestList(items, repo) };
 }
 
@@ -367,9 +446,12 @@ export class GhClient {
     options: Pick<GithubClientOptions, "token"> = {},
   ) {
     this.fetch = fetchImpl;
-    this.search = createGithubSearch({ fetch: fetchImpl, ...options });
-    this.checks = createGithubChecks({ fetch: fetchImpl, ...options });
-    this.reads = createGithubReads({ fetch: fetchImpl, ...options });
+    // 三个子客户端共用同一个 accessor，因此也共用同一份 octokit 与 token 缓存
+    // （各自 createGithubApi 会让一个会话最多 spawn 三次 `gh auth token`）。
+    const api = createGithubApi({ fetch: fetchImpl, ...options });
+    this.search = createGithubSearch(api);
+    this.checks = createGithubChecks(api);
+    this.reads = createGithubReads(api);
   }
 }
 
@@ -380,20 +462,6 @@ const CHECKS_POLL_INTERVAL_MS = 30_000;
 const RUN_WATCH_INTERVAL_MS = 30_000;
 const RUN_WATCH_DEADLINE_MS = 600_000;
 
-/** 运行快照：只声明我们渲染与载荷用到的字段，其余由 REST 原样带过。 */
-const runSnapshotSchema = Type.Object({
-  id: Type.Number(),
-  name: Type.Optional(Type.Union([Type.String(), Type.Null()])),
-  display_title: Type.Optional(Type.String()),
-  status: Type.Optional(Type.Union([Type.String(), Type.Null()])),
-  conclusion: Type.Optional(Type.Union([Type.String(), Type.Null()])),
-  head_branch: Type.Optional(Type.Union([Type.String(), Type.Null()])),
-  event: Type.Optional(Type.String()),
-  created_at: Type.Optional(Type.String()),
-  updated_at: Type.Optional(Type.String()),
-  run_started_at: Type.Optional(Type.String()),
-  html_url: Type.Optional(Type.String()),
-});
 const CHECKS_WATCH_DEADLINE_MS = 600_000;
 
 export type CheckBucket = "pass" | "skipped" | "fail" | "pending";
@@ -688,7 +756,7 @@ export async function watchRun(options: WatchRunOptions): Promise<RunWatchResult
   const watchStart = Date.now();
   for (;;) {
     signal.throwIfAborted();
-    const run = parseWithSchema(runSnapshotSchema, await reads.run(owner, repo, runId, signal));
+    const run = parseWithSchema(ghRunSummarySchema, await reads.run(owner, repo, runId, signal));
     const elapsedMs = Date.now() - watchStart;
     onUpdate?.({
       content: [

package/src/gh/index.ts

@@ -1,11 +1,14 @@
 /**
  * GitHub Read-Only Tools Extension
  *
- * Provides individual read-only tools for GitHub operations using the system's `gh` CLI.
+ * Provides individual read-only tools for GitHub operations. 取数走 octokit REST；
+ * 只有「当前仓库」解析（`gh repo view`）与 token 获取（`gh auth token`）用系统 `gh`。
  *
  * Layout:
- *   - `base.ts`            shared helpers (gh subprocess, result shaping, REST client, checks watch)
- *   - `tools/<name>.ts`    one tool per file, each exporting `add<Name>Tool(gh, pi)`
+ *   - `base.ts`            shared helpers (result shaping, GhClient, repo resolution, checks watch)
+ *   - `schemas.ts`         structured-output schemas
+ *   - `render.ts`          text rendering of REST responses
+ *   - `tools/<name>.ts`    one tool per file, each exporting `add<Name>Tool(gh, bus)`
  *   - `index.ts`           this file: availability checks + tool registration
  *
  * Tools:
@@ -28,10 +31,10 @@
  *   - wait-github-commit-checks: Watch CI checks of a commit (no PR required)
  *   - watch-github-run: Watch a workflow run
  *
- * Proxy (for the gh CLI and for the octokit-backed search/checks requests):
+ * Proxy (shared by the `gh` subprocess and the octokit requests):
  *   ~/.pi/agent/proxy.json: { "proxy": "http://127.0.0.1:7890", "noProxy": "localhost" }
  *   HTTPS_PROXY / HTTP_PROXY / ALL_PROXY and NO_PROXY are used instead for the
- *   fields the config file leaves out. The config is read once per process.
+ *   fields the config file leaves out; the config is read through `src/lib/egress.ts`.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

package/src/gh/tools/download-release-assets.ts

@@ -9,7 +9,7 @@ import { type ToolPendant } from "../../lib/pendant.js";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  resolveRepo,
+  resolveRepoTarget,
   splitRepo,
   structuredFailure,
   type StructuredFailureResult,
@@ -114,8 +114,11 @@ export async function downloadReleaseAssets(
     );
   }
 
-  const effectiveRepo = await resolveRepo(params.repo, signal, ctx.cwd, params);
-  const { owner, repo: repoName } = splitRepo(effectiveRepo);
+  const {
+    fullName: effectiveRepo,
+    owner,
+    name: repoName,
+  } = await resolveRepoTarget(params.repo, signal, ctx.cwd, params);
   const view = Value.Parse(
     releaseViewSchema,
     await gh.reads.release(owner, repoName, params.tag, signal),

package/src/gh/tools/get-workflow-jobs.ts

@@ -3,13 +3,12 @@ import { Type } from "typebox";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  resolveRepo,
-  splitRepo,
+  resolveRepoTarget,
   type StructuredResultOf,
-  subtitlePendant,
   type ToolCall,
   toPositiveId,
   toStructuredJsonResult,
+  withPendant,
 } from "../base.js";
 import { workflowJobsSchema } from "../schemas.js";
 
@@ -25,8 +24,7 @@ async function workflowJobs(
 ): Promise<StructuredResultOf<typeof workflowJobsSchema>> {
   const { params, ctx, signal } = call;
   const runId = toPositiveId(params.run_id, "run_id");
-  const effectiveRepo = await resolveRepo(params.repo, signal, ctx.cwd, params);
-  const { owner, repo: name } = splitRepo(effectiveRepo);
+  const { owner, name } = await resolveRepoTarget(params.repo, signal, ctx.cwd, params);
 
   const jobs = await gh.checks.runJobs(owner, name, runId, signal);
   const result = toStructuredJsonResult(
@@ -34,8 +32,7 @@ async function workflowJobs(
     params,
     workflowJobsSchema,
   );
-  result.details.pendant = subtitlePendant(params, "run_id");
-  return result;
+  return withPendant(result, params, "run_id");
 }
 
 export function addGetWorkflowJobsTool(gh: GhClient, bus: ToolBus) {

package/src/gh/tools/list-issues.ts

@@ -1,20 +1,19 @@
 /**
- * `list-github-issues`：两条取数分支（关键词搜索走 octokit，浏览走 `gh issue list --json`）
- * 归一成同一套 `SearchHit`，因此文本渲染与结构化载荷只有一份实现。
+ * `list-github-issues`：两条取数分支（关键词搜索走 octokit 的 `/search/issues`，浏览走
+ * REST 列表端点）归一成同一套 `SearchHit`，因此文本渲染与结构化载荷只有一份实现。
  */
 
-import { Type } from "typebox";
-
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   browseList,
   type GhClient,
+  listFilterParameters,
   type ListFilters,
   renderHitList,
   type StructuredResultOf,
-  subtitlePendant,
   type ToolCall,
   toToolResult,
+  withPendant,
   withStructuredResult,
 } from "../base.js";
 import { ghHitListPayloadSchema } from "../schemas.js";
@@ -29,9 +28,8 @@ async function listIssues(
     : await browseList(gh, "issue", params, { cwd: ctx.cwd, signal, input: params });
   const text = renderHitList("issue", hits, { repo, fields: params.fields });
   const result = toToolResult(text, params);
-  result.details.pendant = subtitlePendant(params);
   // 文本可能被行数/字节预算截断，载荷给全部命中
-  return withStructuredResult(result, { text, items: hits });
+  return withStructuredResult(withPendant(result, params), { text, items: hits });
 }
 
 export function addListIssuesTool(gh: GhClient, bus: ToolBus) {
@@ -42,38 +40,7 @@ export function addListIssuesTool(gh: GhClient, bus: ToolBus) {
       description:
         'List GitHub issues with optional filters and keyword search. When repo is omitted, keyword search runs across GitHub. Keyword search defaults to open issues — pass state="all" to include closed ones. Set fields to choose the columns of each result row.',
       promptSnippet: "List or search GitHub issues",
-      parameters: Type.Object({
-        repo: Type.Optional(Type.String({ description: "OWNER/REPO (defaults to current repo)" })),
-        keywords: Type.Optional(Type.String({ description: "Search keywords (free text)" })),
-        state: Type.Optional(
-          Type.String({
-            description:
-              "open, closed, all (default: open; all applies to keyword search and covers closed too)",
-          }),
-        ),
-        label: Type.Optional(Type.String({ description: "Filter by label" })),
-        // `@me` 只在关键词搜索分支可用：搜索 API 自己把它解析成当前登录用户。浏览分支走
-        // REST 列表端点，`@me` 按字面量转发，不会匹配到当前用户（本仓库不做展开）。
-        author: Type.Optional(
-          Type.String({
-            description: "Filter by author ('@me' works with keywords; browse takes it literally)",
-          }),
-        ),
-        assignee: Type.Optional(
-          Type.String({
-            description:
-              "Filter by assignee ('@me' works with keywords; browse takes it literally)",
-          }),
-        ),
-        milestone: Type.Optional(Type.String({ description: "Filter by milestone" })),
-        limit: Type.Optional(Type.Number({ description: "Max results (default 30, max 100)" })),
-        fields: Type.Optional(
-          Type.String({
-            description:
-              "Comma-separated columns for the rows (default: number,state,title,labels,updatedAt; adds repo when no repo given). Valid: number,state,title,url,author,labels,milestone,assignees,comments,repo,createdAt,updatedAt,closedAt",
-          }),
-        ),
-      }),
+      parameters: listFilterParameters("issue"),
       structuredSchema: ghHitListPayloadSchema,
       async execute(_id, params, signal, onUpdate, ctx) {
         return listIssues(gh, { params, ctx, signal, onUpdate });

package/src/gh/tools/list-prs.ts

@@ -1,20 +1,19 @@
 /**
- * `list-github-prs`：与 `list-github-issues` 同一套两条分支（关键词搜索走 octokit，
- * 浏览走 `gh pr list --json`），归一成同一套 `SearchHit`。
+ * `list-github-prs`：与 `list-github-issues` 同一套两条分支（关键词搜索走 octokit 的
+ * `/search/issues`，浏览走 REST 列表端点），归一成同一套 `SearchHit`。
  */
 
-import { Type } from "typebox";
-
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   browseList,
   type GhClient,
+  listFilterParameters,
   type ListFilters,
   renderHitList,
   type StructuredResultOf,
-  subtitlePendant,
   type ToolCall,
   toToolResult,
+  withPendant,
   withStructuredResult,
 } from "../base.js";
 import { ghHitListPayloadSchema } from "../schemas.js";
@@ -29,9 +28,8 @@ async function listPrs(
     : await browseList(gh, "pr", params, { cwd: ctx.cwd, signal, input: params });
   const text = renderHitList("pr", hits, { repo, fields: params.fields });
   const result = toToolResult(text, params);
-  result.details.pendant = subtitlePendant(params);
   // 文本可能被行数/字节预算截断，载荷给全部命中
-  return withStructuredResult(result, { text, items: hits });
+  return withStructuredResult(withPendant(result, params), { text, items: hits });
 }
 
 export function addListPrsTool(gh: GhClient, bus: ToolBus) {
@@ -42,38 +40,7 @@ export function addListPrsTool(gh: GhClient, bus: ToolBus) {
       description:
         'List GitHub pull requests with optional filters and keyword search. When repo is omitted, keyword search runs across GitHub. Keyword search defaults to open PRs — pass state="merged", state="closed" (merged excluded) or state="all" to broaden. Set fields to choose the columns of each result row.',
       promptSnippet: "List or search GitHub PRs",
-      parameters: Type.Object({
-        repo: Type.Optional(Type.String({ description: "OWNER/REPO (defaults to current repo)" })),
-        keywords: Type.Optional(Type.String({ description: "Search keywords (free text)" })),
-        state: Type.Optional(
-          Type.String({
-            description:
-              "open, closed, merged, all (default: open; all applies to keyword search and covers open + closed + merged)",
-          }),
-        ),
-        label: Type.Optional(Type.String({ description: "Filter by label" })),
-        // `@me` 只在关键词搜索分支可用：搜索 API 自己把它解析成当前登录用户。浏览分支走
-        // REST 列表端点，`@me` 按字面量转发，不会匹配到当前用户（本仓库不做展开）。
-        author: Type.Optional(
-          Type.String({
-            description: "Filter by author ('@me' works with keywords; browse takes it literally)",
-          }),
-        ),
-        assignee: Type.Optional(
-          Type.String({
-            description:
-              "Filter by assignee ('@me' works with keywords; browse takes it literally)",
-          }),
-        ),
-        milestone: Type.Optional(Type.String({ description: "Filter by milestone" })),
-        limit: Type.Optional(Type.Number({ description: "Max results (default 30, max 100)" })),
-        fields: Type.Optional(
-          Type.String({
-            description:
-              "Comma-separated columns for the rows (default: number,state,title,labels,updatedAt; adds repo when no repo given). Valid: number,state,title,url,author,labels,milestone,assignees,comments,repo,createdAt,updatedAt,closedAt,mergedAt",
-          }),
-        ),
-      }),
+      parameters: listFilterParameters("pr"),
       structuredSchema: ghHitListPayloadSchema,
       async execute(_id, params, signal, onUpdate, ctx) {
         return listPrs(gh, { params, ctx, signal, onUpdate });