@trim21/personal-pi-extensions 0.1.690 → 0.1.692

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 });

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

@@ -4,10 +4,9 @@ import { parseWithSchema } from "../../lib/parse-with-schema.js";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  resolveRepo,
-  splitRepo,
-  subtitlePendant,
+  resolveRepoTarget,
   toToolResult,
+  withPendant,
   withStructuredResult,
 } from "../base.js";
 import { renderReleaseList } from "../render.js";
@@ -27,10 +26,9 @@ export function addListReleasesTool(gh: GhClient, bus: ToolBus) {
       }),
       structuredSchema: ghReleaseListPayloadSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
-        const { repo, limit } = params;
-        const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-        const { owner, repo: repoName } = splitRepo(effectiveRepo);
-        const items = await gh.reads.listReleases(owner, repoName, limit, signal);
+        const { limit } = params;
+        const { owner, name } = await resolveRepoTarget(params.repo, signal, ctx.cwd, params);
+        const items = await gh.reads.listReleases(owner, name, limit, signal);
         const releases = parseWithSchema(Type.Array(ghReleaseSummarySchema), items);
         // REST 没有 isLatest：按列表顺序取第一个非 draft / prerelease 的条目
         const latestIndex = releases.findIndex(
@@ -40,8 +38,7 @@ export function addListReleasesTool(gh: GhClient, bus: ToolBus) {
           releases.map((release, index) => ({ ...release, latest: index === latestIndex })),
         );
         const result = toToolResult(text, params);
-        result.details.pendant = subtitlePendant(params);
-        return withStructuredResult(result, { text, releases });
+        return withStructuredResult(withPendant(result, params), { text, releases });
       },
     }),
   );

package/src/gh/tools/list-workflow-runs.ts

@@ -4,10 +4,9 @@ import { parseWithSchema } from "../../lib/parse-with-schema.js";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  resolveRepo,
-  splitRepo,
-  subtitlePendant,
+  resolveRepoTarget,
   toToolResult,
+  withPendant,
   withStructuredResult,
 } from "../base.js";
 import { renderRunList } from "../render.js";
@@ -31,15 +30,13 @@ export function addListWorkflowRunsTool(gh: GhClient, bus: ToolBus) {
       }),
       structuredSchema: ghRunListPayloadSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
-        const { repo, limit, status, workflow } = params;
-        const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-        const { owner, repo: repoName } = splitRepo(effectiveRepo);
-        const items = await gh.reads.listRuns(owner, repoName, { workflow, status, limit }, signal);
+        const { limit, status, workflow } = params;
+        const { owner, name } = await resolveRepoTarget(params.repo, signal, ctx.cwd, params);
+        const items = await gh.reads.listRuns(owner, name, { workflow, status, limit }, signal);
         const runs = parseWithSchema(Type.Array(ghRunSummarySchema), items);
         const text = renderRunList(runs);
         const result = toToolResult(text, params);
-        result.details.pendant = subtitlePendant(params);
-        return withStructuredResult(result, { text, runs });
+        return withStructuredResult(withPendant(result, params), { text, runs });
       },
     }),
   );

package/src/gh/tools/read-ci-logs.ts

@@ -9,12 +9,12 @@ import { dirname, join } from "node:path";
 
 import { Type } from "typebox";
 
-import type { RunJob } from "../../lib/github.js";
+import { isNotFound, type RunJob } from "../../lib/github.js";
 import { createSeqState } from "../../lib/seq-state.js";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  resolveRepo,
+  resolveRepoTarget,
   splitRepo,
   structuredFailure,
   type StructuredFailureResult,
@@ -299,19 +299,6 @@ export function stepLineSpans(log: string, apiSteps: readonly StepRef[]): Map<nu
   return spans;
 }
 
-/** Text of `stepNumber` in its raw log, or null when the step never ran. */
-export function extractStepFromLog(
-  log: string,
-  stepNumber: number,
-  apiSteps: readonly { number: number; name: string }[],
-): string | null {
-  const span = stepLineSpans(log, apiSteps).get(stepNumber);
-  if (span === undefined) {
-    return null;
-  }
-  return log.split("\n").slice(span.start, span.end).join("\n").trimEnd();
-}
-
 /** One step of a job, indexed into the job's raw log file. */
 export interface CiLogsStepIndex {
   number: number;
@@ -374,8 +361,11 @@ async function ciLogs(gh: GhClient, call: ToolCall<JobIdParams>): Promise<CiLogs
   const jobId = toPositiveId(job_id, "job_id");
 
   const pendant = subtitlePendant(params, "job_id");
-  const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-  const { owner, repo: name } = splitRepo(effectiveRepo);
+  const {
+    fullName: effectiveRepo,
+    owner,
+    name,
+  } = await resolveRepoTarget(repo, signal, ctx.cwd, params);
 
   const failure = (text: string): StructuredFailureResult => ({
     content: [{ type: "text", text }],
@@ -387,8 +377,7 @@ async function ciLogs(gh: GhClient, call: ToolCall<JobIdParams>): Promise<CiLogs
   try {
     target = await gh.checks.job(owner, name, jobId, signal);
   } catch (error) {
-    const status = (error as { status?: number }).status;
-    if (status !== 404) {
+    if (!isNotFound(error)) {
       throw error;
     }
     return failure(

package/src/gh/tools/read-issue-comments.ts

@@ -1,13 +1,7 @@
 import { Type } from "typebox";
 
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
-import {
-  type GhClient,
-  resolveRepo,
-  splitRepo,
-  subtitlePendant,
-  toStructuredJsonResult,
-} from "../base.js";
+import { type GhClient, resolveRepoTarget, toStructuredJsonResult, withPendant } from "../base.js";
 import { issueCommentsSchema } from "../schemas.js";
 
 export function addReadIssueCommentsTool(gh: GhClient, bus: ToolBus) {
@@ -24,16 +18,14 @@ export function addReadIssueCommentsTool(gh: GhClient, bus: ToolBus) {
       structuredSchema: issueCommentsSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
         const { number, repo } = params;
-        const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-        const { owner, repo: repoName } = splitRepo(effectiveRepo);
-        const comments = await gh.reads.issueComments(owner, repoName, Number(number), signal);
+        const { owner, name } = await resolveRepoTarget(repo, signal, ctx.cwd, params);
+        const comments = await gh.reads.issueComments(owner, name, Number(number), signal);
         const result = toStructuredJsonResult(
           JSON.stringify({ comments }, null, 2),
           params,
           issueCommentsSchema,
         );
-        result.details.pendant = subtitlePendant(params, "number");
-        return result;
+        return withPendant(result, params, "number");
       },
     }),
   );

package/src/gh/tools/read-issue.ts

@@ -1,13 +1,7 @@
 import { Type } from "typebox";
 
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
-import {
-  type GhClient,
-  resolveRepo,
-  splitRepo,
-  subtitlePendant,
-  toStructuredJsonResult,
-} from "../base.js";
+import { type GhClient, resolveRepoTarget, toStructuredJsonResult, withPendant } from "../base.js";
 import { issueViewSchema } from "../schemas.js";
 
 export function addReadIssueTool(gh: GhClient, bus: ToolBus) {
@@ -24,16 +18,14 @@ export function addReadIssueTool(gh: GhClient, bus: ToolBus) {
       structuredSchema: issueViewSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
         const { number, repo } = params;
-        const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-        const { owner, repo: repoName } = splitRepo(effectiveRepo);
-        const data = await gh.reads.issue(owner, repoName, Number(number), signal);
+        const { owner, name } = await resolveRepoTarget(repo, signal, ctx.cwd, params);
+        const data = await gh.reads.issue(owner, name, Number(number), signal);
         const result = toStructuredJsonResult(
           JSON.stringify(data, null, 2),
           params,
           issueViewSchema,
         );
-        result.details.pendant = subtitlePendant(params, "number");
-        return result;
+        return withPendant(result, params, "number");
       },
     }),
   );

package/src/gh/tools/read-pr-comments.ts

@@ -1,13 +1,7 @@
 import { Type } from "typebox";
 
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
-import {
-  type GhClient,
-  resolveRepo,
-  splitRepo,
-  subtitlePendant,
-  toStructuredJsonResult,
-} from "../base.js";
+import { type GhClient, resolveRepoTarget, toStructuredJsonResult, withPendant } from "../base.js";
 import { prCommentsSchema } from "../schemas.js";
 
 export function addReadPrCommentsTool(gh: GhClient, bus: ToolBus) {
@@ -31,18 +25,17 @@ export function addReadPrCommentsTool(gh: GhClient, bus: ToolBus) {
       structuredSchema: prCommentsSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
         const { number, repo, reviews } = params;
-        const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-        const { owner, repo: repoName } = splitRepo(effectiveRepo);
+        const { owner, name } = await resolveRepoTarget(repo, signal, ctx.cwd, params);
         const pullNumber = Number(number);
 
         // reviews=true 给行内评审评论 + 评审摘要；缺省给 PR 上的普通（issue）评论
         const payload = reviews
           ? {
-              reviews: await gh.reads.pullReviews(owner, repoName, pullNumber, signal),
-              comments: await gh.reads.pullReviewComments(owner, repoName, pullNumber, signal),
+              reviews: await gh.reads.pullReviews(owner, name, pullNumber, signal),
+              comments: await gh.reads.pullReviewComments(owner, name, pullNumber, signal),
             }
           : {
-              comments: await gh.reads.issueComments(owner, repoName, pullNumber, signal),
+              comments: await gh.reads.issueComments(owner, name, pullNumber, signal),
             };
 
         const result = toStructuredJsonResult(
@@ -50,8 +43,7 @@ export function addReadPrCommentsTool(gh: GhClient, bus: ToolBus) {
           params,
           prCommentsSchema,
         );
-        result.details.pendant = subtitlePendant(params, "number");
-        return result;
+        return withPendant(result, params, "number");
       },
     }),
   );

package/src/gh/tools/read-pr-diff.ts

@@ -3,10 +3,9 @@ import { Type } from "typebox";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  resolveRepo,
-  splitRepo,
-  subtitlePendant,
+  resolveRepoTarget,
   toToolResult,
+  withPendant,
   withStructuredResult,
 } from "../base.js";
 import { parseDiffStats } from "../render.js";
@@ -26,13 +25,14 @@ export function addReadPrDiffTool(gh: GhClient, bus: ToolBus) {
       structuredSchema: ghDiffPayloadSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
         const { number, repo } = params;
-        const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-        const { owner, repo: repoName } = splitRepo(effectiveRepo);
-        const diff = await gh.reads.pullDiff(owner, repoName, Number(number), signal);
+        const { owner, name } = await resolveRepoTarget(repo, signal, ctx.cwd, params);
+        const diff = await gh.reads.pullDiff(owner, name, Number(number), signal);
         const result = toToolResult(diff, params);
-        result.details.pendant = subtitlePendant(params, "number");
         // 文本是原始 diff（没有 JSON 形式），载荷从同一份 diff 解析出变更统计
-        return withStructuredResult(result, { text: diff, ...parseDiffStats(diff) });
+        return withStructuredResult(withPendant(result, params, "number"), {
+          text: diff,
+          ...parseDiffStats(diff),
+        });
       },
     }),
   );

package/src/gh/tools/read-pr-status.ts

@@ -4,8 +4,7 @@ import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
   mergeChecks,
-  resolveRepo,
-  splitRepo,
+  resolveRepoTarget,
   type StructuredResultOf,
   subtitlePendant,
   type ToolCall,
@@ -32,8 +31,11 @@ export async function prStatus(
   const { number, repo } = params;
   const pullNumber = toPositiveId(number, "number");
   const pendant = subtitlePendant(params, "number");
-  const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-  const { owner, repo: name } = splitRepo(effectiveRepo);
+  const {
+    fullName: effectiveRepo,
+    owner,
+    name,
+  } = await resolveRepoTarget(repo, signal, ctx.cwd, params);
 
   const pollSignal = signal ?? new AbortController().signal;
   const headSha = await gh.checks.pullHead(owner, name, pullNumber, pollSignal);

package/src/gh/tools/read-pr.ts

@@ -1,13 +1,7 @@
 import { Type } from "typebox";
 
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
-import {
-  type GhClient,
-  resolveRepo,
-  splitRepo,
-  subtitlePendant,
-  toStructuredJsonResult,
-} from "../base.js";
+import { type GhClient, resolveRepoTarget, toStructuredJsonResult, withPendant } from "../base.js";
 import { prViewSchema } from "../schemas.js";
 
 export function addReadPrTool(gh: GhClient, bus: ToolBus) {
@@ -24,12 +18,10 @@ export function addReadPrTool(gh: GhClient, bus: ToolBus) {
       structuredSchema: prViewSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
         const { number, repo } = params;
-        const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-        const { owner, repo: repoName } = splitRepo(effectiveRepo);
-        const data = await gh.reads.pull(owner, repoName, Number(number), signal);
+        const { owner, name } = await resolveRepoTarget(repo, signal, ctx.cwd, params);
+        const data = await gh.reads.pull(owner, name, Number(number), signal);
         const result = toStructuredJsonResult(JSON.stringify(data, null, 2), params, prViewSchema);
-        result.details.pendant = subtitlePendant(params, "number");
-        return result;
+        return withPendant(result, params, "number");
       },
     }),
   );

package/src/gh/tools/read-release.ts

@@ -4,10 +4,9 @@ import { parseWithSchema } from "../../lib/parse-with-schema.js";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  resolveRepo,
-  splitRepo,
-  subtitlePendant,
+  resolveRepoTarget,
   toToolResult,
+  withPendant,
   withStructuredResult,
 } from "../base.js";
 import { renderReleaseView } from "../render.js";
@@ -28,14 +27,12 @@ export function addReadReleaseTool(gh: GhClient, bus: ToolBus) {
       structuredSchema: ghReleaseViewPayloadSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
         const { tag, repo } = params;
-        const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-        const { owner, repo: repoName } = splitRepo(effectiveRepo);
-        const data = await gh.reads.release(owner, repoName, tag, signal);
+        const { owner, name } = await resolveRepoTarget(repo, signal, ctx.cwd, params);
+        const data = await gh.reads.release(owner, name, tag, signal);
         const view = parseWithSchema(ghReleaseViewSchema, data);
         const text = renderReleaseView(view);
         const result = toToolResult(text, params);
-        result.details.pendant = subtitlePendant(params, "tag");
-        return withStructuredResult(result, { text, release: view });
+        return withStructuredResult(withPendant(result, params, "tag"), { text, release: view });
       },
     }),
   );

package/src/gh/tools/read-repo.ts

@@ -4,10 +4,9 @@ import { parseWithSchema } from "../../lib/parse-with-schema.js";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  resolveRepo,
-  splitRepo,
-  subtitlePendant,
+  resolveRepoTarget,
   toToolResult,
+  withPendant,
   withStructuredResult,
 } from "../base.js";
 import { renderRepoView } from "../render.js";
@@ -25,15 +24,12 @@ export function addReadRepoTool(gh: GhClient, bus: ToolBus) {
       }),
       structuredSchema: ghRepoPayloadSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
-        const { repo } = params;
-        const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-        const { owner, repo: repoName } = splitRepo(effectiveRepo);
-        const data = await gh.reads.repository(owner, repoName, signal);
+        const { owner, name } = await resolveRepoTarget(params.repo, signal, ctx.cwd, params);
+        const data = await gh.reads.repository(owner, name, signal);
         const view = parseWithSchema(ghRepoViewSchema, data);
         const text = renderRepoView(view);
         const result = toToolResult(text, params);
-        result.details.pendant = subtitlePendant(params);
-        return withStructuredResult(result, { text, repo: view });
+        return withStructuredResult(withPendant(result, params), { text, repo: view });
       },
     }),
   );

package/src/gh/tools/wait-commit-checks.ts

@@ -3,8 +3,7 @@ import { Type } from "typebox";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  resolveRepo,
-  splitRepo,
+  resolveRepoTarget,
   type StructuredResultOf,
   subtitlePendant,
   type ToolCall,
@@ -33,8 +32,7 @@ async function waitCommitChecks(
     details: {},
   });
 
-  const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-  const { owner, repo: repoName } = splitRepo(effectiveRepo);
+  const { owner, name: repoName } = await resolveRepoTarget(repo, signal, ctx.cwd, params);
 
   const pollSignal = signal ?? new AbortController().signal;
   const sha = await gh.checks.headSha(owner, repoName, String(commit), pollSignal);

package/src/gh/tools/wait-pr-checks.ts

@@ -4,8 +4,7 @@ import { Value } from "typebox/value";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  resolveRepo,
-  splitRepo,
+  resolveRepoTarget,
   type StructuredResultOf,
   subtitlePendant,
   type ToolCall,
@@ -36,8 +35,7 @@ async function waitPrChecks(
     details: {},
   });
 
-  const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-  const { owner, repo: repoName } = splitRepo(effectiveRepo);
+  const { owner, name: repoName } = await resolveRepoTarget(repo, signal, ctx.cwd, params);
 
   const pull = Value.Parse(
     pullHeadSchema,

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

@@ -4,8 +4,7 @@ import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
   renderRunStatus,
-  resolveRepo,
-  splitRepo,
+  resolveRepoTarget,
   subtitlePendant,
   type ToolResult,
   watchRun,
@@ -38,8 +37,12 @@ export function addWatchRunTool(gh: GhClient, bus: ToolBus) {
 
         // 轮询循环要求非空 signal（与两个 wait 工具一致：没有就自建一个）
         const pollSignal = signal ?? new AbortController().signal;
-        const effectiveRepo = await resolveRepo(repo, pollSignal, ctx.cwd, params);
-        const { owner, repo: repoName } = splitRepo(effectiveRepo);
+        const { owner, name: repoName } = await resolveRepoTarget(
+          repo,
+          pollSignal,
+          ctx.cwd,
+          params,
+        );
         const outcome = await watchRun({
           owner,
           repo: repoName,

package/src/index.ts

@@ -126,6 +126,9 @@ export default function personalExtensions(pi: ExtensionAPI): void {
       codemode.register(bus, { policy: services.policy, reads: fileToolset.reads }),
     );
 
+    // 注册期的可诊断问题（例如 codemode-only 命中但没有结构化输出的工具）与其它警告一起上报。
+    warnings.push(...registration.diagnostics());
+
     for (const warning of warnings) {
       ctx.ui.notify(warning, "warning");
     }

package/src/lib/abort.ts

@@ -0,0 +1,10 @@
+/**
+ * 把调用方的取消信号与一个本地超时合并成单个 AbortSignal。
+ *
+ * 调用方可能不传 signal（例如 agent 空闲时的 `ctx.signal`），那时仍然要有超时兜底，
+ * 所以本地 `AbortSignal.timeout` 始终生效，两者都触发时以先到者为准。
+ */
+export function withTimeoutSignal(signal: AbortSignal | undefined, ms: number): AbortSignal {
+  const timeout = AbortSignal.timeout(ms);
+  return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}

package/src/lib/bash-tool.ts

@@ -0,0 +1,48 @@
+/**
+ * claude-code 与 opencode 两套 Bash 工具共用的部分：超时上下限、结构化结果 schema、
+ * 以及截断后从落盘文件读回完整输出。
+ *
+ * 只放两边逐字相同的部分。两套工具的截断提示文案、失败判定与 details 是刻意的差异，
+ * 留在各自的工具里，不在这里统一。
+ */
+
+import { readFile } from "node:fs/promises";
+
+import type { TruncationResult } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+export const BASH_DEFAULT_TIMEOUT_MS = 120_000;
+export const BASH_MAX_TIMEOUT_MS = 7_200_000;
+
+/**
+ * `Bash` 的结构化结果：只有退出码与完整输出——命令非零退出不是失败，所以载荷里没有成败
+ * 标志，脚本直接读 `exitCode` 分支；超时/中止时 `exitCode` 为 `null`（原因在模型侧文本里）。
+ */
+export 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.",
+  }),
+});
+
+/**
+ * 载荷里的输出：文本被截断时读回落盘的完整输出（读不到就退回那份截断文本），
+ * 因此脚本拿到的永远是命令真正输出的内容。
+ */
+export async function spilledOutput(
+  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;
+  }
+}