@trim21/personal-pi-extensions 0.1.685 → 0.1.687

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

@@ -4,8 +4,8 @@ import { parseWithSchema } from "../../lib/parse-with-schema.js";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  ghExec,
-  repoArgs,
+  resolveRepo,
+  splitRepo,
   subtitlePendant,
   toToolResult,
   withStructuredResult,
@@ -13,10 +13,7 @@ import {
 import { renderReleaseList } from "../render.js";
 import { ghReleaseListPayloadSchema, ghReleaseSummarySchema } from "../schemas.js";
 
-/** 我们向 gh 要的 release 字段，与渲染和载荷一一对应。 */
-const RELEASE_FIELDS = "tagName,name,isLatest,isPrerelease,isDraft,publishedAt,createdAt";
-
-export function addListReleasesTool(_gh: GhClient, bus: ToolBus) {
+export function addListReleasesTool(gh: GhClient, bus: ToolBus) {
   bus.register(
     defineStructuredTool({
       name: "list-github-releases",
@@ -31,13 +28,17 @@ export function addListReleasesTool(_gh: GhClient, bus: ToolBus) {
       structuredSchema: ghReleaseListPayloadSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
         const { repo, limit } = params;
-        const args = ["release", "list", ...repoArgs(repo), "--json", RELEASE_FIELDS];
-        if (limit) {
-          args.push("--limit", String(limit));
-        }
-        const stdout = await ghExec(args, { cwd: ctx.cwd, signal, input: params });
-        const releases = parseWithSchema(Type.Array(ghReleaseSummarySchema), JSON.parse(stdout));
-        const text = renderReleaseList(releases);
+        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 releases = parseWithSchema(Type.Array(ghReleaseSummarySchema), items);
+        // REST 没有 isLatest：按列表顺序取第一个非 draft / prerelease 的条目
+        const latestIndex = releases.findIndex(
+          (release) => release.draft !== true && release.prerelease !== true,
+        );
+        const text = renderReleaseList(
+          releases.map((release, index) => ({ ...release, latest: index === latestIndex })),
+        );
         const result = toToolResult(text, params);
         result.details.pendant = subtitlePendant(params);
         return withStructuredResult(result, { text, releases });

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

@@ -4,8 +4,8 @@ import { parseWithSchema } from "../../lib/parse-with-schema.js";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  ghExec,
-  repoArgs,
+  resolveRepo,
+  splitRepo,
   subtitlePendant,
   toToolResult,
   withStructuredResult,
@@ -13,11 +13,7 @@ import {
 import { renderRunList } from "../render.js";
 import { ghRunListPayloadSchema, ghRunSummarySchema } from "../schemas.js";
 
-/** 我们向 gh 要的运行字段，与渲染和载荷一一对应。 */
-const RUN_FIELDS =
-  "databaseId,displayTitle,status,conclusion,workflowName,headBranch,event,createdAt,url";
-
-export function addListWorkflowRunsTool(_gh: GhClient, bus: ToolBus) {
+export function addListWorkflowRunsTool(gh: GhClient, bus: ToolBus) {
   bus.register(
     defineStructuredTool({
       name: "list-github-workflow-runs",
@@ -36,18 +32,10 @@ export function addListWorkflowRunsTool(_gh: GhClient, bus: ToolBus) {
       structuredSchema: ghRunListPayloadSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
         const { repo, limit, status, workflow } = params;
-        const args = ["run", "list", ...repoArgs(repo), "--json", RUN_FIELDS];
-        if (limit) {
-          args.push("--limit", String(limit));
-        }
-        if (status) {
-          args.push("--status", status);
-        }
-        if (workflow) {
-          args.push("--workflow", workflow);
-        }
-        const stdout = await ghExec(args, { cwd: ctx.cwd, signal, input: params });
-        const runs = parseWithSchema(Type.Array(ghRunSummarySchema), JSON.parse(stdout));
+        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 runs = parseWithSchema(Type.Array(ghRunSummarySchema), items);
         const text = renderRunList(runs);
         const result = toToolResult(text, params);
         result.details.pendant = subtitlePendant(params);

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

@@ -14,7 +14,6 @@ import { createSeqState } from "../../lib/seq-state.js";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  ghExec,
   resolveRepo,
   splitRepo,
   structuredFailure,
@@ -55,10 +54,9 @@ export function jobLogPath(repo: string, runId: string, jobId: number): string {
 }
 
 async function getJobLog(
+  gh: GhClient,
   job: RunJob,
   signal: AbortSignal | undefined,
-  cwd: string | undefined,
-  input?: unknown,
 ): Promise<string> {
   // The log download only accepts a job id, and the cache is keyed on the
   // canonical repo/run from the job itself, not on the caller's `repo` string.
@@ -76,21 +74,10 @@ async function getJobLog(
       // Not cached, fetch from GitHub
     }
 
-    // `gh api` refuses to print responses that contain terminal escape
-    // sequences unless `--allow-escape-sequences` is passed. Job logs carry
-    // ANSI color codes, so without this flag the download always fails with
-    // "the response contains terminal escape sequences; pass
-    // --allow-escape-sequences to output it anyway". The raw bytes are kept
-    // as-is (the file is the log exactly as GitHub delivers it); the tool never
-    // echoes them, and the TUI strips ANSI when rendering tool results.
-    const log = await ghExec(
-      ["api", "--allow-escape-sequences", `/repos/${repo}/actions/jobs/${job.id}/logs`],
-      {
-        cwd,
-        signal,
-        input,
-      },
-    );
+    // 日志原样落盘（GitHub 返回什么就是什么，含 ANSI 转义与 runner 时间戳）；工具从不回显
+    // 它，模型自己读文件，TUI 渲染工具结果时会自己剥 ANSI。
+    const { owner, repo: name } = splitRepo(repo);
+    const log = await gh.reads.jobLogs(owner, name, job.id, signal);
 
     // Write to cache
     await mkdir(cacheDir, { recursive: true });
@@ -420,7 +407,7 @@ async function ciLogs(gh: GhClient, call: ToolCall<JobIdParams>): Promise<CiLogs
     details: {},
   });
 
-  const rawLog = await getJobLog(target, signal, ctx.cwd, params);
+  const rawLog = await getJobLog(gh, target, signal);
   const index = jobLogIndex(target, rawLog);
 
   return withStructuredResult(

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

@@ -3,14 +3,14 @@ import { Type } from "typebox";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  ghExec,
-  repoArgs,
+  resolveRepo,
+  splitRepo,
   subtitlePendant,
   toStructuredJsonResult,
 } from "../base.js";
 import { issueCommentsSchema } from "../schemas.js";
 
-export function addReadIssueCommentsTool(_gh: GhClient, bus: ToolBus) {
+export function addReadIssueCommentsTool(gh: GhClient, bus: ToolBus) {
   bus.register(
     defineStructuredTool({
       name: "read-github-issue-comments",
@@ -24,11 +24,14 @@ export function addReadIssueCommentsTool(_gh: GhClient, bus: ToolBus) {
       structuredSchema: issueCommentsSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
         const { number, repo } = params;
-        const out = await ghExec(
-          ["issue", "view", String(number), ...repoArgs(repo), "--json", "comments"],
-          { cwd: ctx.cwd, signal, input: 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 result = toStructuredJsonResult(
+          JSON.stringify({ comments }, null, 2),
+          params,
+          issueCommentsSchema,
         );
-        const result = toStructuredJsonResult(out, params, issueCommentsSchema);
         result.details.pendant = subtitlePendant(params, "number");
         return result;
       },

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

@@ -3,14 +3,14 @@ import { Type } from "typebox";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  ghExec,
-  repoArgs,
+  resolveRepo,
+  splitRepo,
   subtitlePendant,
   toStructuredJsonResult,
 } from "../base.js";
 import { issueViewSchema } from "../schemas.js";
 
-export function addReadIssueTool(_gh: GhClient, bus: ToolBus) {
+export function addReadIssueTool(gh: GhClient, bus: ToolBus) {
   bus.register(
     defineStructuredTool({
       name: "read-github-issue",
@@ -24,18 +24,14 @@ export function addReadIssueTool(_gh: GhClient, bus: ToolBus) {
       structuredSchema: issueViewSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
         const { number, repo } = params;
-        const out = await ghExec(
-          [
-            "issue",
-            "view",
-            String(number),
-            ...repoArgs(repo),
-            "--json",
-            "title,state,body,author,createdAt,updatedAt,closedAt,url,labels,assignees,comments,milestone,number",
-          ],
-          { cwd: ctx.cwd, signal, input: 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 result = toStructuredJsonResult(
+          JSON.stringify(data, null, 2),
+          params,
+          issueViewSchema,
         );
-        const result = toStructuredJsonResult(out, params, issueViewSchema);
         result.details.pendant = subtitlePendant(params, "number");
         return result;
       },

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

@@ -2,17 +2,15 @@ import { Type } from "typebox";
 
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
-  ghApiList,
   type GhClient,
-  ghExec,
-  repoArgs,
   resolveRepo,
+  splitRepo,
   subtitlePendant,
   toStructuredJsonResult,
 } from "../base.js";
 import { prCommentsSchema } from "../schemas.js";
 
-export function addReadPrCommentsTool(_gh: GhClient, bus: ToolBus) {
+export function addReadPrCommentsTool(gh: GhClient, bus: ToolBus) {
   bus.register(
     defineStructuredTool({
       name: "read-github-pr-comments",
@@ -33,42 +31,25 @@ export function addReadPrCommentsTool(_gh: GhClient, bus: ToolBus) {
       structuredSchema: prCommentsSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
         const { number, repo, reviews } = params;
-        let out: string;
-        if (reviews) {
-          const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
+        const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
+        const { owner, repo: repoName } = splitRepo(effectiveRepo);
+        const pullNumber = Number(number);
 
-          const [reviewComments, reviewSummaries] = await Promise.all([
-            ghApiList(`/repos/${effectiveRepo}/pulls/${String(number)}/comments`, {
-              cwd: ctx.cwd,
-              signal,
-              input: params,
-            }),
-            ghApiList(`/repos/${effectiveRepo}/pulls/${String(number)}/reviews`, {
-              cwd: ctx.cwd,
-              signal,
-              input: params,
-            }),
-          ]);
+        // 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),
+            }
+          : {
+              comments: await gh.reads.issueComments(owner, repoName, pullNumber, signal),
+            };
 
-          out = JSON.stringify(
-            {
-              reviews: reviewSummaries,
-              comments: reviewComments,
-            },
-            null,
-            2,
-          );
-        } else {
-          out = await ghExec(
-            ["pr", "view", String(number), ...repoArgs(repo), "--json", "comments"],
-            {
-              cwd: ctx.cwd,
-              signal,
-              input: params,
-            },
-          );
-        }
-        const result = toStructuredJsonResult(out, params, prCommentsSchema);
+        const result = toStructuredJsonResult(
+          JSON.stringify(payload, null, 2),
+          params,
+          prCommentsSchema,
+        );
         result.details.pendant = subtitlePendant(params, "number");
         return result;
       },

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

@@ -3,8 +3,8 @@ import { Type } from "typebox";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  ghExec,
-  repoArgs,
+  resolveRepo,
+  splitRepo,
   subtitlePendant,
   toToolResult,
   withStructuredResult,
@@ -12,7 +12,7 @@ import {
 import { parseDiffStats } from "../render.js";
 import { ghDiffPayloadSchema } from "../schemas.js";
 
-export function addReadPrDiffTool(_gh: GhClient, bus: ToolBus) {
+export function addReadPrDiffTool(gh: GhClient, bus: ToolBus) {
   bus.register(
     defineStructuredTool({
       name: "read-github-pr-diff",
@@ -26,12 +26,13 @@ export function addReadPrDiffTool(_gh: GhClient, bus: ToolBus) {
       structuredSchema: ghDiffPayloadSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
         const { number, repo } = params;
-        const args = ["pr", "diff", String(number), ...repoArgs(repo)];
-        const stdout = await ghExec(args, { cwd: ctx.cwd, signal, input: params });
-        const result = toToolResult(stdout, 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 result = toToolResult(diff, params);
         result.details.pendant = subtitlePendant(params, "number");
-        // 文本仍是原始 diff（`gh pr diff` 没有 --json），载荷从同一份 diff 解析出变更统计
-        return withStructuredResult(result, { text: stdout, ...parseDiffStats(stdout) });
+        // 文本是原始 diff（没有 JSON 形式），载荷从同一份 diff 解析出变更统计
+        return withStructuredResult(result, { text: diff, ...parseDiffStats(diff) });
       },
     }),
   );

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

@@ -3,14 +3,14 @@ import { Type } from "typebox";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  ghExec,
-  repoArgs,
+  resolveRepo,
+  splitRepo,
   subtitlePendant,
   toStructuredJsonResult,
 } from "../base.js";
 import { prViewSchema } from "../schemas.js";
 
-export function addReadPrTool(_gh: GhClient, bus: ToolBus) {
+export function addReadPrTool(gh: GhClient, bus: ToolBus) {
   bus.register(
     defineStructuredTool({
       name: "read-github-pr",
@@ -24,18 +24,10 @@ export function addReadPrTool(_gh: GhClient, bus: ToolBus) {
       structuredSchema: prViewSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
         const { number, repo } = params;
-        const out = await ghExec(
-          [
-            "pr",
-            "view",
-            String(number),
-            ...repoArgs(repo),
-            "--json",
-            "title,state,body,author,createdAt,updatedAt,mergedAt,mergedBy,headRefName,baseRefName,url,additions,deletions,changedFiles,labels,assignees,reviewRequests,reviews,comments,number",
-          ],
-          { cwd: ctx.cwd, signal, input: params },
-        );
-        const result = toStructuredJsonResult(out, params, prViewSchema);
+        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 result = toStructuredJsonResult(JSON.stringify(data, null, 2), params, prViewSchema);
         result.details.pendant = subtitlePendant(params, "number");
         return result;
       },

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

@@ -4,8 +4,8 @@ import { parseWithSchema } from "../../lib/parse-with-schema.js";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  ghExec,
-  repoArgs,
+  resolveRepo,
+  splitRepo,
   subtitlePendant,
   toToolResult,
   withStructuredResult,
@@ -13,22 +13,7 @@ import {
 import { renderReleaseView } from "../render.js";
 import { ghReleaseViewPayloadSchema, ghReleaseViewSchema } from "../schemas.js";
 
-/** 我们向 gh 要的 release 字段，与渲染和载荷一一对应。 */
-const RELEASE_FIELDS = [
-  "tagName",
-  "name",
-  "body",
-  "url",
-  "isDraft",
-  "isPrerelease",
-  "createdAt",
-  "publishedAt",
-  "targetCommitish",
-  "author",
-  "assets",
-].join(",");
-
-export function addReadReleaseTool(_gh: GhClient, bus: ToolBus) {
+export function addReadReleaseTool(gh: GhClient, bus: ToolBus) {
   bus.register(
     defineStructuredTool({
       name: "read-github-release",
@@ -43,11 +28,10 @@ export function addReadReleaseTool(_gh: GhClient, bus: ToolBus) {
       structuredSchema: ghReleaseViewPayloadSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
         const { tag, repo } = params;
-        const stdout = await ghExec(
-          ["release", "view", tag, ...repoArgs(repo), "--json", RELEASE_FIELDS],
-          { cwd: ctx.cwd, signal, input: params },
-        );
-        const view = parseWithSchema(ghReleaseViewSchema, JSON.parse(stdout));
+        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 view = parseWithSchema(ghReleaseViewSchema, data);
         const text = renderReleaseView(view);
         const result = toToolResult(text, params);
         result.details.pendant = subtitlePendant(params, "tag");

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

@@ -4,7 +4,8 @@ import { parseWithSchema } from "../../lib/parse-with-schema.js";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  ghExec,
+  resolveRepo,
+  splitRepo,
   subtitlePendant,
   toToolResult,
   withStructuredResult,
@@ -12,30 +13,7 @@ import {
 import { renderRepoView } from "../render.js";
 import { ghRepoPayloadSchema, ghRepoViewSchema } from "../schemas.js";
 
-/** 我们向 gh 要的仓库字段，与渲染和载荷一一对应。 */
-const REPO_FIELDS = [
-  "name",
-  "nameWithOwner",
-  "description",
-  "url",
-  "homepageUrl",
-  "visibility",
-  "isPrivate",
-  "isFork",
-  "isArchived",
-  "stargazerCount",
-  "forkCount",
-  "primaryLanguage",
-  "defaultBranchRef",
-  "licenseInfo",
-  "issues",
-  "pullRequests",
-  "pushedAt",
-  "createdAt",
-  "updatedAt",
-].join(",");
-
-export function addReadRepoTool(_gh: GhClient, bus: ToolBus) {
+export function addReadRepoTool(gh: GhClient, bus: ToolBus) {
   bus.register(
     defineStructuredTool({
       name: "read-github-repo",
@@ -48,13 +26,10 @@ export function addReadRepoTool(_gh: GhClient, bus: ToolBus) {
       structuredSchema: ghRepoPayloadSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
         const { repo } = params;
-        const args = ["repo", "view"];
-        if (repo) {
-          args.push(repo);
-        }
-        args.push("--json", REPO_FIELDS);
-        const stdout = await ghExec(args, { cwd: ctx.cwd, signal, input: params });
-        const view = parseWithSchema(ghRepoViewSchema, JSON.parse(stdout));
+        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 view = parseWithSchema(ghRepoViewSchema, data);
         const text = renderRepoView(view);
         const result = toToolResult(text, params);
         result.details.pendant = subtitlePendant(params);

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

@@ -4,7 +4,6 @@ import { Value } from "typebox/value";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  ghExec,
   resolveRepo,
   splitRepo,
   type StructuredResultOf,
@@ -20,7 +19,8 @@ interface PrChecksWaitParams {
   fail_fast?: boolean;
 }
 
-const prHeadSchema = Type.Object({ headRefOid: Type.String() });
+/** pulls.get 里我们只需要 head commit 的 SHA（它决定查哪个 commit 的 checks）。 */
+const pullHeadSchema = Type.Object({ head: Type.Object({ sha: Type.String() }) });
 
 /** The toolcall handler behind `wait-github-pr-checks`. */
 async function waitPrChecks(
@@ -39,18 +39,17 @@ async function waitPrChecks(
   const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
   const { owner, repo: repoName } = splitRepo(effectiveRepo);
 
-  const prOut = await ghExec(
-    ["pr", "view", String(number), "--repo", effectiveRepo, "--json", "headRefOid"],
-    { cwd: ctx.cwd, signal, input: params },
+  const pull = Value.Parse(
+    pullHeadSchema,
+    await gh.reads.pull(owner, repoName, Number(number), signal),
   );
-  const { headRefOid } = Value.Parse(prHeadSchema, JSON.parse(prOut));
 
   return waitChecksReport({
     checks: gh.checks,
     subject: `PR #${number}`,
     owner,
     repo: repoName,
-    headSha: headRefOid,
+    headSha: pull.head.sha,
     failFast: fail_fast === true,
     signal,
     onUpdate,

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

@@ -1,16 +1,18 @@
 import { Type } from "typebox";
 
-import { runGh } from "../../lib/gh-process.js";
-import { parseWithSchema } from "../../lib/parse-with-schema.js";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
-import { type GhClient, ghExec, repoArgs, subtitlePendant } from "../base.js";
-import { ghRunPayloadSchema, ghRunSummarySchema } from "../schemas.js";
+import {
+  type GhClient,
+  renderRunStatus,
+  resolveRepo,
+  splitRepo,
+  subtitlePendant,
+  type ToolResult,
+  watchRun,
+} from "../base.js";
+import { ghRunPayloadSchema } from "../schemas.js";
 
-/** 收尾时查运行状态要的字段（`gh run watch` 自己没有 `--json`）。 */
-const RUN_FIELDS =
-  "databaseId,displayTitle,status,conclusion,workflowName,headBranch,event,createdAt,updatedAt,startedAt,url";
-
-export function addWatchRunTool(_gh: GhClient, bus: ToolBus) {
+export function addWatchRunTool(gh: GhClient, bus: ToolBus) {
   bus.register(
     defineStructuredTool({
       name: "watch-github-run",
@@ -28,33 +30,41 @@ export function addWatchRunTool(_gh: GhClient, bus: ToolBus) {
         const { run_id, repo } = params;
 
         const pendant = subtitlePendant(params, "run_id");
-        onUpdate?.({
+        const publish = (message: ToolResult) => onUpdate?.(message);
+        publish({
           content: [{ type: "text", text: `Watching workflow run ${run_id}...` }],
           details: {},
         });
 
-        const result = await runGh(["run", "watch", String(run_id), ...repoArgs(repo)], {
-          cwd: ctx.cwd,
-          signal,
-          timeout: 600_000,
+        // 轮询循环要求非空 signal（与两个 wait 工具一致：没有就自建一个）
+        const pollSignal = signal ?? new AbortController().signal;
+        const effectiveRepo = await resolveRepo(repo, pollSignal, ctx.cwd, params);
+        const { owner, repo: repoName } = splitRepo(effectiveRepo);
+        const outcome = await watchRun({
+          owner,
+          repo: repoName,
+          runId: Number(run_id),
+          reads: gh.reads,
+          signal: pollSignal,
+          onUpdate: publish,
         });
 
-        if (result.code !== 0) {
-          throw new Error(`gh run watch failed: ${result.stderr || `exit code ${result.code}`}`);
+        if (outcome.outcome === "timeout") {
+          throw new Error(
+            `workflow run ${run_id} did not finish within ${Math.round(outcome.elapsedMs / 1000)}s; last status: ${renderRunStatus(outcome.run)}`,
+          );
         }
 
-        const text = `## Workflow Run ${run_id} Completed\n\n${result.stdout}`;
-        // 监控的是状态变化，结论要另外查一次（watch 的文本里只有过程）
-        const stdout = await ghExec(
-          ["run", "view", String(run_id), ...repoArgs(repo), "--json", RUN_FIELDS],
-          { cwd: ctx.cwd, signal, input: params },
-        );
-        const run = parseWithSchema(ghRunSummarySchema, JSON.parse(stdout));
+        const heading =
+          outcome.run.conclusion === "success"
+            ? `## Workflow Run ${run_id} Completed`
+            : `## Workflow Run ${run_id} Finished (${outcome.run.conclusion ?? "unknown"})`;
+        const text = `${heading}\n\n${renderRunStatus(outcome.run)}`;
 
         return {
           content: [{ type: "text" as const, text }],
-          details: { exitCode: 0, input: params, ...(pendant && { pendant }) },
-          structuredResult: { ok: true as const, value: { text, run } },
+          details: { input: params, ...(pendant && { pendant }) },
+          structuredResult: { ok: true as const, value: { text, run: outcome.run } },
         };
       },
     }),