@trim21/personal-pi-extensions 0.1.683 → 0.1.685

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

@@ -1,64 +1,79 @@
+/**
+ * `list-github-prs`：与 `list-github-issues` 同一套两条分支（关键词搜索走 octokit，
+ * 浏览走 `gh pr list --json`），归一成同一套 `SearchHit`。
+ */
+
 import { Type } from "typebox";
 
-import type { ToolBus } from "../../lib/tool-bus.js";
+import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
+  browseList,
   type GhClient,
   type ListFilters,
-  listGithub,
-  searchList,
+  renderHitList,
+  type StructuredResultOf,
   subtitlePendant,
   type ToolCall,
-  type ToolResult,
   toToolResult,
+  withStructuredResult,
 } from "../base.js";
+import { ghHitListPayloadSchema } from "../schemas.js";
 
-async function listPrs(gh: GhClient, call: ToolCall<ListFilters>): Promise<ToolResult> {
+async function listPrs(
+  gh: GhClient,
+  call: ToolCall<ListFilters>,
+): Promise<StructuredResultOf<typeof ghHitListPayloadSchema>> {
   const { params, ctx, signal } = call;
-  const result = toToolResult(
-    params.keywords
-      ? await searchList("pr", params, gh.search)
-      : await listGithub("pr", params, { cwd: ctx.cwd, signal, input: params }),
-    params,
-  );
+  const { repo, hits } = params.keywords
+    ? { repo: params.repo, hits: await gh.search.search("pr", params) }
+    : await browseList("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 result;
+  // 文本可能被行数/字节预算截断，载荷给全部命中
+  return withStructuredResult(result, { text, items: hits });
 }
 
 export function addListPrsTool(gh: GhClient, bus: ToolBus) {
-  bus.register({
-    name: "list-github-prs",
-    label: "GitHub PRs List",
-    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` 由 GitHub 的搜索 / 过滤 API 解析：不带 keywords 时 gh 自行展开（GraphQL 过滤分支）
-      // 或按字面量转发（搜索分支），带 keywords 时我们直接把 `assignee:@me` 交给搜索 API。
-      // 两条传输都支持，因此本仓库不要再实现一次展开。
-      author: Type.Optional(Type.String({ description: "Filter by author ('@me' for yourself)" })),
-      assignee: Type.Optional(
-        Type.String({ description: "Filter by assignee ('@me' for yourself)" }),
-      ),
-      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 keyword-search 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",
-        }),
-      ),
+  bus.register(
+    defineStructuredTool({
+      name: "list-github-prs",
+      label: "GitHub PRs List",
+      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` 由 GitHub 的搜索 / 过滤 API 解析：不带 keywords 时 gh 自行展开（GraphQL 过滤分支）
+        // 或按字面量转发（搜索分支），带 keywords 时我们直接把 `assignee:@me` 交给搜索 API。
+        // 两条传输都支持，因此本仓库不要再实现一次展开。
+        author: Type.Optional(
+          Type.String({ description: "Filter by author ('@me' for yourself)" }),
+        ),
+        assignee: Type.Optional(
+          Type.String({ description: "Filter by assignee ('@me' for yourself)" }),
+        ),
+        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",
+          }),
+        ),
+      }),
+      structuredSchema: ghHitListPayloadSchema,
+      async execute(_id, params, signal, onUpdate, ctx) {
+        return listPrs(gh, { params, ctx, signal, onUpdate });
+      },
     }),
-    async execute(_id, params, signal, onUpdate, ctx) {
-      return listPrs(gh, { params, ctx, signal, onUpdate });
-    },
-  });
+  );
 }

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

@@ -1,30 +1,47 @@
 import { Type } from "typebox";
 
-import type { ToolBus } from "../../lib/tool-bus.js";
-import { type GhClient, ghExec, repoArgs, subtitlePendant, toToolResult } from "../base.js";
+import { parseWithSchema } from "../../lib/parse-with-schema.js";
+import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
+import {
+  type GhClient,
+  ghExec,
+  repoArgs,
+  subtitlePendant,
+  toToolResult,
+  withStructuredResult,
+} from "../base.js";
+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) {
-  bus.register({
-    name: "list-github-releases",
-    label: "GitHub Releases List",
-    description: "List GitHub releases.",
-    promptSnippet: "List GitHub releases",
-    parameters: Type.Object({
-      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
-      limit: Type.Optional(Type.Number({ description: "Max results (default 10)" })),
+  bus.register(
+    defineStructuredTool({
+      name: "list-github-releases",
+      label: "GitHub Releases List",
+      description:
+        "List GitHub releases. Each row is: tag, flags (latest/prerelease/draft), published date, name.",
+      promptSnippet: "List GitHub releases",
+      parameters: Type.Object({
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+        limit: Type.Optional(Type.Number({ description: "Max results (default 10)" })),
+      }),
+      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 result = toToolResult(text, params);
+        result.details.pendant = subtitlePendant(params);
+        return withStructuredResult(result, { text, releases });
+      },
     }),
-    async execute(_id, params, signal, _onUpdate, ctx) {
-      const { repo, limit } = params;
-      const args = ["release", "list", ...repoArgs(repo)];
-      if (limit) {
-        args.push("--limit", String(limit));
-      }
-      const result = toToolResult(
-        await ghExec(args, { cwd: ctx.cwd, signal, input: params }),
-        params,
-      );
-      result.details.pendant = subtitlePendant(params);
-      return result;
-    },
-  });
+  );
 }

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

@@ -1,40 +1,58 @@
 import { Type } from "typebox";
 
-import type { ToolBus } from "../../lib/tool-bus.js";
-import { type GhClient, ghExec, repoArgs, subtitlePendant, toToolResult } from "../base.js";
+import { parseWithSchema } from "../../lib/parse-with-schema.js";
+import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
+import {
+  type GhClient,
+  ghExec,
+  repoArgs,
+  subtitlePendant,
+  toToolResult,
+  withStructuredResult,
+} from "../base.js";
+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) {
-  bus.register({
-    name: "list-github-workflow-runs",
-    label: "GitHub Workflow Runs",
-    description: "List GitHub Actions workflow runs.",
-    promptSnippet: "List GitHub workflow runs",
-    parameters: Type.Object({
-      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
-      limit: Type.Optional(Type.Number({ description: "Max results (default 20)" })),
-      status: Type.Optional(
-        Type.String({ description: "Filter by status: success, failure, cancelled, etc." }),
-      ),
-      workflow: Type.Optional(Type.String({ description: "Filter by workflow name or file" })),
+  bus.register(
+    defineStructuredTool({
+      name: "list-github-workflow-runs",
+      label: "GitHub Workflow Runs",
+      description:
+        "List GitHub Actions workflow runs. Each row is: id, status, conclusion, workflow, branch, event, created date, url.",
+      promptSnippet: "List GitHub workflow runs",
+      parameters: Type.Object({
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+        limit: Type.Optional(Type.Number({ description: "Max results (default 20)" })),
+        status: Type.Optional(
+          Type.String({ description: "Filter by status: success, failure, cancelled, etc." }),
+        ),
+        workflow: Type.Optional(Type.String({ description: "Filter by workflow name or file" })),
+      }),
+      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 text = renderRunList(runs);
+        const result = toToolResult(text, params);
+        result.details.pendant = subtitlePendant(params);
+        return withStructuredResult(result, { text, runs });
+      },
     }),
-    async execute(_id, params, signal, _onUpdate, ctx) {
-      const { repo, limit, status, workflow } = params;
-      const args = ["run", "list", ...repoArgs(repo)];
-      if (limit) {
-        args.push("--limit", String(limit));
-      }
-      if (status) {
-        args.push("--status", status);
-      }
-      if (workflow) {
-        args.push("--workflow", workflow);
-      }
-      const result = toToolResult(
-        await ghExec(args, { cwd: ctx.cwd, signal, input: params }),
-        params,
-      );
-      result.details.pendant = subtitlePendant(params);
-      return result;
-    },
-  });
+  );
 }

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

@@ -1,27 +1,38 @@
 import { Type } from "typebox";
 
-import type { ToolBus } from "../../lib/tool-bus.js";
-import { type GhClient, ghExec, repoArgs, subtitlePendant, toToolResult } from "../base.js";
+import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
+import {
+  type GhClient,
+  ghExec,
+  repoArgs,
+  subtitlePendant,
+  toToolResult,
+  withStructuredResult,
+} from "../base.js";
+import { parseDiffStats } from "../render.js";
+import { ghDiffPayloadSchema } from "../schemas.js";
 
 export function addReadPrDiffTool(_gh: GhClient, bus: ToolBus) {
-  bus.register({
-    name: "read-github-pr-diff",
-    label: "GitHub PR Diff",
-    description: "Get the diff of a GitHub pull request.",
-    promptSnippet: "Read a GitHub PR diff",
-    parameters: Type.Object({
-      number: Type.Union([Type.Number(), Type.String()], { description: "PR number" }),
-      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+  bus.register(
+    defineStructuredTool({
+      name: "read-github-pr-diff",
+      label: "GitHub PR Diff",
+      description: "Get the diff of a GitHub pull request.",
+      promptSnippet: "Read a GitHub PR diff",
+      parameters: Type.Object({
+        number: Type.Union([Type.Number(), Type.String()], { description: "PR number" }),
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+      }),
+      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);
+        result.details.pendant = subtitlePendant(params, "number");
+        // 文本仍是原始 diff（`gh pr diff` 没有 --json），载荷从同一份 diff 解析出变更统计
+        return withStructuredResult(result, { text: stdout, ...parseDiffStats(stdout) });
+      },
     }),
-    async execute(_id, params, signal, _onUpdate, ctx) {
-      const { number, repo } = params;
-      const args = ["pr", "diff", String(number), ...repoArgs(repo)];
-      const result = toToolResult(
-        await ghExec(args, { cwd: ctx.cwd, signal, input: params }),
-        params,
-      );
-      result.details.pendant = subtitlePendant(params, "number");
-      return result;
-    },
-  });
+  );
 }

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

@@ -1,30 +1,58 @@
 import { Type } from "typebox";
 
-import type { ToolBus } from "../../lib/tool-bus.js";
-import { type GhClient, ghExec, repoArgs, subtitlePendant, toToolResult } from "../base.js";
+import { parseWithSchema } from "../../lib/parse-with-schema.js";
+import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
+import {
+  type GhClient,
+  ghExec,
+  repoArgs,
+  subtitlePendant,
+  toToolResult,
+  withStructuredResult,
+} from "../base.js";
+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) {
-  bus.register({
-    name: "read-github-release",
-    label: "GitHub Release",
-    description: "Get details of a specific GitHub release by tag.",
-    promptSnippet: "Read a GitHub release",
-    parameters: Type.Object({
-      tag: Type.String({ description: "Release tag name" }),
-      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+  bus.register(
+    defineStructuredTool({
+      name: "read-github-release",
+      label: "GitHub Release",
+      description:
+        "Get details of a specific GitHub release by tag: metadata, asset list and release notes.",
+      promptSnippet: "Read a GitHub release",
+      parameters: Type.Object({
+        tag: Type.String({ description: "Release tag name" }),
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+      }),
+      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 text = renderReleaseView(view);
+        const result = toToolResult(text, params);
+        result.details.pendant = subtitlePendant(params, "tag");
+        return withStructuredResult(result, { text, release: view });
+      },
     }),
-    async execute(_id, params, signal, _onUpdate, ctx) {
-      const { tag, repo } = params;
-      const result = toToolResult(
-        await ghExec(["release", "view", tag, ...repoArgs(repo)], {
-          cwd: ctx.cwd,
-          signal,
-          input: params,
-        }),
-        params,
-      );
-      result.details.pendant = subtitlePendant(params, "tag");
-      return result;
-    },
-  });
+  );
 }

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

@@ -1,29 +1,65 @@
 import { Type } from "typebox";
 
-import type { ToolBus } from "../../lib/tool-bus.js";
-import { type GhClient, ghExec, subtitlePendant, toToolResult } from "../base.js";
+import { parseWithSchema } from "../../lib/parse-with-schema.js";
+import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
+import {
+  type GhClient,
+  ghExec,
+  subtitlePendant,
+  toToolResult,
+  withStructuredResult,
+} from "../base.js";
+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) {
-  bus.register({
-    name: "read-github-repo",
-    label: "GitHub Repo",
-    description: "Get repository information.",
-    promptSnippet: "Read GitHub repo info",
-    parameters: Type.Object({
-      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+  bus.register(
+    defineStructuredTool({
+      name: "read-github-repo",
+      label: "GitHub Repo",
+      description: "Get repository information.",
+      promptSnippet: "Read GitHub repo info",
+      parameters: Type.Object({
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+      }),
+      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 text = renderRepoView(view);
+        const result = toToolResult(text, params);
+        result.details.pendant = subtitlePendant(params);
+        return withStructuredResult(result, { text, repo: view });
+      },
     }),
-    async execute(_id, params, signal, _onUpdate, ctx) {
-      const { repo } = params;
-      const args = ["repo", "view"];
-      if (repo) {
-        args.push(repo);
-      }
-      const result = toToolResult(
-        await ghExec(args, { cwd: ctx.cwd, signal, input: params }),
-        params,
-      );
-      result.details.pendant = subtitlePendant(params);
-      return result;
-    },
-  });
+  );
 }

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

@@ -1,46 +1,62 @@
 import { Type } from "typebox";
 
 import { runGh } from "../../lib/gh-process.js";
-import type { ToolBus } from "../../lib/tool-bus.js";
-import { type GhClient, repoArgs, subtitlePendant } from "../base.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";
+
+/** 收尾时查运行状态要的字段（`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) {
-  bus.register({
-    name: "watch-github-run",
-    label: "Watch GitHub Workflow Run",
-    description:
-      "Watch a GitHub Actions workflow run until it completes. " +
-      "Blocks until the run finishes and shows the final status.",
-    promptSnippet: "Watch and wait for a GitHub Actions run to complete",
-    parameters: Type.Object({
-      run_id: Type.Union([Type.Number(), Type.String()], { description: "Workflow run ID" }),
-      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+  bus.register(
+    defineStructuredTool({
+      name: "watch-github-run",
+      label: "Watch GitHub Workflow Run",
+      description:
+        "Watch a GitHub Actions workflow run until it completes. " +
+        "Blocks until the run finishes and shows the final status.",
+      promptSnippet: "Watch and wait for a GitHub Actions run to complete",
+      parameters: Type.Object({
+        run_id: Type.Union([Type.Number(), Type.String()], { description: "Workflow run ID" }),
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+      }),
+      structuredSchema: ghRunPayloadSchema,
+      async execute(_id, params, signal, onUpdate, ctx) {
+        const { run_id, repo } = params;
+
+        const pendant = subtitlePendant(params, "run_id");
+        onUpdate?.({
+          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,
+        });
+
+        if (result.code !== 0) {
+          throw new Error(`gh run watch failed: ${result.stderr || `exit code ${result.code}`}`);
+        }
+
+        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));
+
+        return {
+          content: [{ type: "text" as const, text }],
+          details: { exitCode: 0, input: params, ...(pendant && { pendant }) },
+          structuredResult: { ok: true as const, value: { text, run } },
+        };
+      },
     }),
-    async execute(_id, params, signal, onUpdate, ctx) {
-      const { run_id, repo } = params;
-
-      const pendant = subtitlePendant(params, "run_id");
-      onUpdate?.({
-        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,
-      });
-
-      if (result.code !== 0) {
-        throw new Error(`gh run watch failed: ${result.stderr || `exit code ${result.code}`}`);
-      }
-
-      return {
-        content: [
-          { type: "text", text: `## Workflow Run ${run_id} Completed\n\n${result.stdout}` },
-        ],
-        details: { exitCode: 0, input: params, ...(pendant && { pendant }) },
-      };
-    },
-  });
+  );
 }