@trim21/personal-pi-extensions 0.1.678 → 0.1.679

package/src/gh/schemas.ts

@@ -0,0 +1,230 @@
+/**
+ * gh-readonly 工具的结构化结果 schema（TypeBox）。
+ *
+ * 两个用途：codemode 脚本侧据此渲染 `call()` 的返回类型；工具总线在运行期用它复核
+ * `structuredResult.value`。因此 schema 必须**允许额外字段**（GitHub 的 JSON 只多不少，
+ * 多出来的字段不该让工具失败），只对工具本身已经依赖的字段设 required。
+ *
+ * 字段名取自 GitHub 的两种传输：`gh ... view --json`（GraphQL，actor 叫 `author` /
+ * `user`）与 REST（`/pulls/:n/comments` 等，用了 `diff_hunk` / `submitted_at` 这类
+ * 下划线命名）。评论与评审条目因此放宽成两者的并集。
+ */
+
+import { Type } from "typebox";
+
+// ── 共享片段 ─────────────────────────────────────────────────────────────────
+
+/** GitHub 的 actor（author / assignee / mergedBy / review 作者）。 */
+export const ghActorSchema = Type.Object({
+  login: Type.Optional(Type.String()),
+  name: Type.Optional(Type.String()),
+  is_bot: Type.Optional(Type.Boolean()),
+});
+
+export const ghLabelSchema = Type.Object({
+  name: Type.String(),
+  color: Type.Optional(Type.String()),
+  description: Type.Optional(Type.String()),
+});
+
+export const ghMilestoneSchema = Type.Object({
+  title: Type.String(),
+  number: Type.Optional(Type.Number()),
+  dueOn: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+});
+
+/** 评论条目：GraphQL 的 `author`/`createdAt` 与 REST 的 `user`/`diff_hunk` 并集。 */
+export const ghCommentSchema = Type.Object({
+  id: Type.Optional(Type.Union([Type.String(), Type.Number()])),
+  body: Type.Optional(Type.String()),
+  author: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
+  user: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
+  path: Type.Optional(Type.String()),
+  line: Type.Optional(Type.Union([Type.Number(), Type.Null()])),
+  diff_hunk: Type.Optional(Type.String()),
+  createdAt: Type.Optional(Type.String()),
+  url: Type.Optional(Type.String()),
+});
+
+/** 评审条目：GraphQL 的 `reviews` 与 REST 的 `/pulls/:n/reviews` 并集。 */
+export const ghReviewSchema = Type.Object({
+  id: Type.Optional(Type.Union([Type.String(), Type.Number()])),
+  body: Type.Optional(Type.String()),
+  author: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
+  user: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
+  state: Type.Optional(Type.String()),
+  createdAt: Type.Optional(Type.String()),
+  submitted_at: Type.Optional(Type.String()),
+  url: Type.Optional(Type.String()),
+});
+
+/** 待评审人：可能是用户（login）也可能是团队（slug）。 */
+export const ghReviewRequestSchema = Type.Object({
+  login: Type.Optional(Type.String()),
+  name: Type.Optional(Type.String()),
+  slug: Type.Optional(Type.String()),
+});
+
+/** `read-github-pr-status` / 两个 wait 工具共用的检查桶。 */
+export const checkBucketSchema = Type.Union([
+  Type.Literal("pass"),
+  Type.Literal("fail"),
+  Type.Literal("pending"),
+  Type.Literal("skipped"),
+]);
+
+// ── 各工具的输出 ─────────────────────────────────────────────────────────────
+
+/** `read-github-issue`：`gh issue view --json` 的输出。 */
+export const issueViewSchema = Type.Object({
+  number: Type.Number(),
+  title: Type.String(),
+  state: Type.String(),
+  body: Type.Optional(Type.String()),
+  author: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
+  createdAt: Type.Optional(Type.String()),
+  updatedAt: Type.Optional(Type.String()),
+  closedAt: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  url: Type.Optional(Type.String()),
+  labels: Type.Optional(Type.Array(ghLabelSchema)),
+  assignees: Type.Optional(Type.Array(ghActorSchema)),
+  comments: Type.Optional(Type.Array(ghCommentSchema)),
+  milestone: Type.Optional(Type.Union([ghMilestoneSchema, Type.Null()])),
+});
+
+/** `read-github-pr`：`gh pr view --json` 的输出，比 issue 多出合并与 diff 统计。 */
+export const prViewSchema = Type.Object({
+  number: Type.Number(),
+  title: Type.String(),
+  state: Type.String(),
+  body: Type.Optional(Type.String()),
+  author: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
+  createdAt: Type.Optional(Type.String()),
+  updatedAt: Type.Optional(Type.String()),
+  closedAt: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  mergedAt: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  mergedBy: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
+  headRefName: Type.Optional(Type.String()),
+  baseRefName: Type.Optional(Type.String()),
+  url: Type.Optional(Type.String()),
+  additions: Type.Optional(Type.Number()),
+  deletions: Type.Optional(Type.Number()),
+  changedFiles: Type.Optional(Type.Number()),
+  labels: Type.Optional(Type.Array(ghLabelSchema)),
+  assignees: Type.Optional(Type.Array(ghActorSchema)),
+  reviewRequests: Type.Optional(Type.Array(ghReviewRequestSchema)),
+  reviews: Type.Optional(Type.Array(ghReviewSchema)),
+  comments: Type.Optional(Type.Array(ghCommentSchema)),
+  milestone: Type.Optional(Type.Union([ghMilestoneSchema, Type.Null()])),
+});
+
+/** `read-github-issue-comments`：`gh issue view --json comments`。 */
+export const issueCommentsSchema = Type.Object({
+  comments: Type.Array(ghCommentSchema),
+});
+
+/**
+ * `read-github-pr-comments`：默认模式是 `gh pr view --json comments`（只有 comments），
+ * `reviews: true` 时走 REST 同时给出 reviews 与行内评论。两个字段都可选。
+ */
+export const prCommentsSchema = Type.Object({
+  comments: Type.Optional(Type.Array(ghCommentSchema)),
+  reviews: Type.Optional(Type.Array(ghReviewSchema)),
+});
+
+/** `read-github-pr-status`：工具自己拼的 `{pr, repo, head_sha, checks}`。 */
+export const prStatusSchema = Type.Object({
+  pr: Type.Number(),
+  repo: Type.String(),
+  head_sha: Type.String(),
+  checks: Type.Array(
+    Type.Object({
+      name: Type.String(),
+      bucket: checkBucketSchema,
+      event: Type.Union([Type.String(), Type.Null()]),
+      run_id: Type.Union([Type.Number(), Type.Null()]),
+      job_id: Type.Union([Type.Number(), Type.Null()]),
+      url: Type.Union([Type.String(), Type.Null()]),
+    }),
+  ),
+});
+
+export const workflowJobsSchema = Type.Object({
+  total_count: Type.Number(),
+  jobs: Type.Array(
+    Type.Object({
+      id: Type.Number(),
+      run_id: Type.Number(),
+      run_url: Type.String(),
+      name: Type.String(),
+      status: Type.String(),
+      conclusion: Type.Union([Type.String(), Type.Null()]),
+      html_url: Type.Union([Type.String(), Type.Null()]),
+      steps: Type.Array(
+        Type.Object({
+          name: Type.String(),
+          number: Type.Number(),
+          status: Type.String(),
+          conclusion: Type.Union([Type.String(), Type.Null()]),
+          started_at: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+        }),
+      ),
+    }),
+  ),
+});
+
+/** `read-github-ci-logs`：`CiLogsJobIndex`（步骤带它在原始日志里的行号范围）。 */
+export const ciLogsSchema = Type.Object({
+  name: Type.String(),
+  id: Type.Number(),
+  status: Type.String(),
+  conclusion: Type.Union([Type.String(), Type.Null()]),
+  log_file: Type.String(),
+  steps: Type.Array(
+    Type.Object({
+      number: Type.Number(),
+      name: Type.String(),
+      conclusion: Type.Union([Type.String(), Type.Null()]),
+      start_line: Type.Optional(Type.Number()),
+      end_line: Type.Optional(Type.Number()),
+    }),
+  ),
+});
+
+/** `download-github-release-assets`：下载目录里此刻的文件清单。 */
+export const releaseDownloadSchema = Type.Object({
+  repo: Type.String(),
+  tag: Type.String(),
+  dir: Type.String(),
+  files: Type.Array(
+    Type.Object({ name: Type.String(), path: Type.String(), bytes: Type.Number() }),
+  ),
+});
+
+/** 两个 wait 工具共享的判定结果（`waitChecksReport` 的 payload）。 */
+export const checksVerdictSchema = Type.Object({
+  status: Type.Union([Type.Literal("success"), Type.Literal("failure"), Type.Literal("pending")]),
+  totalChecks: Type.Number(),
+  checks: Type.Array(
+    Type.Object({
+      name: Type.String(),
+      bucket: checkBucketSchema,
+      startedAt: Type.Union([Type.String(), Type.Null()]),
+      link: Type.Union([Type.String(), Type.Null()]),
+      event: Type.Union([Type.String(), Type.Null()]),
+      runId: Type.Union([Type.Number(), Type.Null()]),
+      jobId: Type.Union([Type.Number(), Type.Null()]),
+    }),
+  ),
+  failedJobs: Type.Array(
+    Type.Object({
+      runId: Type.Number(),
+      runName: Type.String(),
+      runUrl: Type.String(),
+      jobId: Type.Number(),
+      jobName: Type.String(),
+      conclusion: Type.String(),
+      jobUrl: Type.Optional(Type.String()),
+    }),
+  ),
+});

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

@@ -6,7 +6,7 @@ import { Type } from "typebox";
 import { Value } from "typebox/value";
 
 import { type ToolPendant } from "../../lib/pendant.js";
-import type { ToolBus } from "../../lib/tool-bus.js";
+import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
   GhError,
@@ -14,10 +14,14 @@ import {
   repoArgs,
   resolveRepo,
   splitRepo,
+  structuredFailure,
+  type StructuredFailureResult,
+  type StructuredResultOf,
   subtitlePendant,
   type ToolCall,
-  type ToolResult,
+  withStructuredResult,
 } from "../base.js";
+import { releaseDownloadSchema } from "../schemas.js";
 
 interface ReleaseDownloadParams {
   repo?: string;
@@ -120,7 +124,7 @@ const GH_NO_ASSET_MATCH = "no assets match the file pattern";
  */
 export async function downloadReleaseAssets(
   call: ToolCall<ReleaseDownloadParams>,
-): Promise<ToolResult> {
+): Promise<StructuredResultOf<typeof releaseDownloadSchema> | StructuredFailureResult> {
   const { params, ctx, signal } = call;
   const patterns = releasePatterns(params.pattern);
   if (params.archive !== undefined && patterns.length > 0) {
@@ -181,59 +185,62 @@ export async function downloadReleaseAssets(
   );
 
   if (files.length === 0 && params.archive === undefined) {
+    const text = `Nothing to download from ${effectiveRepo}@${view.tagName}: the release has no assets (try archive for the source tarball)`;
     return {
-      content: [
-        {
-          type: "text",
-          text: `Nothing to download from ${effectiveRepo}@${view.tagName}: the release has no assets (try archive for the source tarball)`,
-        },
-      ],
+      content: [{ type: "text", text }],
       details: {
         ...payload,
         available_assets: assetNames,
         input: params,
         ...(pendant && { pendant }),
       },
+      structuredResult: structuredFailure(text),
     };
   }
 
-  return {
-    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
-    details: { ...payload, input: params, ...(pendant && { pendant }) },
-  };
+  return withStructuredResult(
+    {
+      content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+      details: { ...payload, input: params, ...(pendant && { pendant }) },
+    },
+    payload,
+  );
 }
 
 export function addDownloadReleaseAssetsTool(_gh: GhClient, bus: ToolBus) {
-  bus.register({
-    name: "download-github-release-assets",
-    label: "GitHub Release Download",
-    description:
-      "Download a GitHub release's assets (or its source archive) into " +
-      "~/.cache/pi/github/releases/<owner>/<repo>/<tag>/ using the gh CLI's credentials, " +
-      "so private repositories and large binaries work where a plain HTTP fetch cannot. " +
-      "Files already in that directory are kept, never re-fetched. The result is the JSON " +
-      "summary {repo, tag, dir, files:[{name, path, bytes}]} listing everything now in the " +
-      "directory; file contents are not echoed. Read the entries you need from `path`.",
-    promptSnippet: "Download GitHub release assets",
-    parameters: Type.Object({
-      repo: Type.Optional(Type.String({ description: "OWNER/REPO (defaults to current repo)" })),
-      tag: Type.Optional(
-        Type.String({ description: "Release tag (defaults to the latest release)" }),
-      ),
-      pattern: Type.Optional(
-        Type.String({
-          description:
-            'Comma-separated glob patterns for asset names, e.g. "*.tar.gz,*.deb" (default: every asset)',
-        }),
-      ),
-      archive: Type.Optional(
-        Type.Union([Type.Literal("zip"), Type.Literal("tar.gz")], {
-          description: "Download the release's source archive instead of its assets",
-        }),
-      ),
+  bus.register(
+    defineStructuredTool({
+      name: "download-github-release-assets",
+      label: "GitHub Release Download",
+      description:
+        "Download a GitHub release's assets (or its source archive) into " +
+        "~/.cache/pi/github/releases/<owner>/<repo>/<tag>/ using the gh CLI's credentials, " +
+        "so private repositories and large binaries work where a plain HTTP fetch cannot. " +
+        "Files already in that directory are kept, never re-fetched. The result is the JSON " +
+        "summary {repo, tag, dir, files:[{name, path, bytes}]} listing everything now in the " +
+        "directory; file contents are not echoed. Read the entries you need from `path`.",
+      promptSnippet: "Download GitHub release assets",
+      parameters: Type.Object({
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO (defaults to current repo)" })),
+        tag: Type.Optional(
+          Type.String({ description: "Release tag (defaults to the latest release)" }),
+        ),
+        pattern: Type.Optional(
+          Type.String({
+            description:
+              'Comma-separated glob patterns for asset names, e.g. "*.tar.gz,*.deb" (default: every asset)',
+          }),
+        ),
+        archive: Type.Optional(
+          Type.Union([Type.Literal("zip"), Type.Literal("tar.gz")], {
+            description: "Download the release's source archive instead of its assets",
+          }),
+        ),
+      }),
+      structuredSchema: releaseDownloadSchema,
+      async execute(_id, params, signal, _onUpdate, ctx) {
+        return downloadReleaseAssets({ params, ctx, signal });
+      },
     }),
-    async execute(_id, params, signal, _onUpdate, ctx) {
-      return downloadReleaseAssets({ params, ctx, signal });
-    },
-  });
+  );
 }

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

@@ -1,16 +1,17 @@
 import { Type } from "typebox";
 
-import type { ToolBus } from "../../lib/tool-bus.js";
+import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
   resolveRepo,
   splitRepo,
+  type StructuredResultOf,
   subtitlePendant,
   type ToolCall,
-  type ToolResult,
   toPositiveId,
-  toToolResultJson,
+  toStructuredJsonResult,
 } from "../base.js";
+import { workflowJobsSchema } from "../schemas.js";
 
 interface RunIdParams {
   run_id: number | string;
@@ -18,31 +19,41 @@ interface RunIdParams {
 }
 
 /** The toolcall handler behind `get-github-workflow-jobs`: every job of a run, all pages. */
-async function workflowJobs(gh: GhClient, call: ToolCall<RunIdParams>): Promise<ToolResult> {
+async function workflowJobs(
+  gh: GhClient,
+  call: ToolCall<RunIdParams>,
+): 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 jobs = await gh.checks.runJobs(owner, name, runId, signal);
-  const result = toToolResultJson(JSON.stringify({ total_count: jobs.length, jobs }), params);
+  const result = toStructuredJsonResult(
+    JSON.stringify({ total_count: jobs.length, jobs }),
+    params,
+    workflowJobsSchema,
+  );
   result.details.pendant = subtitlePendant(params, "run_id");
   return result;
 }
 
 export function addGetWorkflowJobsTool(gh: GhClient, bus: ToolBus) {
-  bus.register({
-    name: "get-github-workflow-jobs",
-    label: "GitHub Workflow Jobs",
-    description:
-      "Get every job of a workflow run as JSON {total_count, jobs:[{id, run_id, run_url, name, status, conclusion, html_url, steps:[{name, number, status, conclusion, started_at}]}]}. Paginated server-side, so runs with more than 30 jobs return all of them. Use the `id` with read-github-ci-logs after read-github-pr-status / wait-github-commit-checks did not already give you a job id.",
-    promptSnippet: "Get GitHub workflow run jobs",
-    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: "get-github-workflow-jobs",
+      label: "GitHub Workflow Jobs",
+      description:
+        "Get every job of a workflow run as JSON {total_count, jobs:[{id, run_id, run_url, name, status, conclusion, html_url, steps:[{name, number, status, conclusion, started_at}]}]}. Paginated server-side, so runs with more than 30 jobs return all of them. Use the `id` with read-github-ci-logs after read-github-pr-status / wait-github-commit-checks did not already give you a job id.",
+      promptSnippet: "Get GitHub workflow run jobs",
+      parameters: Type.Object({
+        run_id: Type.Union([Type.Number(), Type.String()], { description: "Workflow run ID" }),
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+      }),
+      structuredSchema: workflowJobsSchema,
+      async execute(_id, params, signal, onUpdate, ctx) {
+        return workflowJobs(gh, { params, ctx, signal, onUpdate });
+      },
     }),
-    async execute(_id, params, signal, onUpdate, ctx) {
-      return workflowJobs(gh, { params, ctx, signal, onUpdate });
-    },
-  });
+  );
 }

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

@@ -11,17 +11,21 @@ import { Type } from "typebox";
 
 import type { RunJob } from "../../lib/github.js";
 import { createSeqState } from "../../lib/seq-state.js";
-import type { ToolBus } from "../../lib/tool-bus.js";
+import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
   ghExec,
   resolveRepo,
   splitRepo,
+  structuredFailure,
+  type StructuredFailureResult,
+  type StructuredResultOf,
   subtitlePendant,
   type ToolCall,
-  type ToolResult,
   toPositiveId,
+  withStructuredResult,
 } from "../base.js";
+import { ciLogsSchema } from "../schemas.js";
 
 // 模块级串行状态：同一资源（如 CI 日志）的请求排队执行，配合函数内部的
 // 缓存检查避免重复网络请求。闭包状态不与其他扩展共享，key 无需全局前缀。
@@ -373,8 +377,11 @@ interface JobIdParams {
   repo?: string;
 }
 
+/** 「没找到 / 还没日志」是结构化失败，不是异常：脚本能按 ok === false 分辨。 */
+type CiLogsResult = StructuredResultOf<typeof ciLogsSchema> | StructuredFailureResult;
+
 /** The toolcall handler behind `read-github-ci-logs`. */
-async function ciLogs(gh: GhClient, call: ToolCall<JobIdParams>): Promise<ToolResult> {
+async function ciLogs(gh: GhClient, call: ToolCall<JobIdParams>): Promise<CiLogsResult> {
   const { params, ctx, signal, onUpdate } = call;
   const { job_id, repo } = params;
   const jobId = toPositiveId(job_id, "job_id");
@@ -383,9 +390,10 @@ async function ciLogs(gh: GhClient, call: ToolCall<JobIdParams>): Promise<ToolRe
   const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
   const { owner, repo: name } = splitRepo(effectiveRepo);
 
-  const failure = (text: string): ToolResult => ({
+  const failure = (text: string): StructuredFailureResult => ({
     content: [{ type: "text", text }],
     details: { input: params, ...(pendant && { pendant }) },
+    structuredResult: structuredFailure(text),
   });
 
   let target: RunJob;
@@ -415,28 +423,34 @@ async function ciLogs(gh: GhClient, call: ToolCall<JobIdParams>): Promise<ToolRe
   const rawLog = await getJobLog(target, signal, ctx.cwd, params);
   const index = jobLogIndex(target, rawLog);
 
-  return {
-    content: [{ type: "text", text: JSON.stringify(index, null, 2) }],
-    details: { ...index, input: params, ...(pendant && { pendant }) },
-  };
+  return withStructuredResult(
+    {
+      content: [{ type: "text", text: JSON.stringify(index, null, 2) }],
+      details: { ...index, input: params, ...(pendant && { pendant }) },
+    },
+    index,
+  );
 }
 
 export function addReadCiLogsTool(gh: GhClient, bus: ToolBus) {
-  bus.register({
-    name: "read-github-ci-logs",
-    label: "GitHub CI Logs",
-    description:
-      "Download one GitHub Actions job's CI log by job ID and index its steps. Returns JSON {name, id, status, conclusion, log_file, steps:[{number, name, conclusion, start_line?, end_line?}]}: `log_file` is the job's complete raw log on disk (runner timestamps and ANSI kept, exactly as GitHub delivers it) and each step carries the 1-based inclusive line range of its block inside that file. Read the content out of the file yourself (read/grep with offset/limit) — it is not echoed back. Get the job IDs from get-github-workflow-jobs, then call this once per job you need." +
-      " Note: queued jobs have no logs yet; use watch-github-run to wait for completion.",
-    promptSnippet: "Read GitHub CI logs",
-    parameters: Type.Object({
-      job_id: Type.Union([Type.Number(), Type.String()], {
-        description: "Job ID, from get-github-workflow-jobs.",
+  bus.register(
+    defineStructuredTool({
+      name: "read-github-ci-logs",
+      label: "GitHub CI Logs",
+      description:
+        "Download one GitHub Actions job's CI log by job ID and index its steps. Returns JSON {name, id, status, conclusion, log_file, steps:[{number, name, conclusion, start_line?, end_line?}]}: `log_file` is the job's complete raw log on disk (runner timestamps and ANSI kept, exactly as GitHub delivers it) and each step carries the 1-based inclusive line range of its block inside that file. Read the content out of the file yourself (read/grep with offset/limit) — it is not echoed back. Get the job IDs from get-github-workflow-jobs, then call this once per job you need." +
+        " Note: queued jobs have no logs yet; use watch-github-run to wait for completion.",
+      promptSnippet: "Read GitHub CI logs",
+      parameters: Type.Object({
+        job_id: Type.Union([Type.Number(), Type.String()], {
+          description: "Job ID, from get-github-workflow-jobs.",
+        }),
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
       }),
-      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+      structuredSchema: ciLogsSchema,
+      async execute(_id, params, signal, onUpdate, ctx) {
+        return ciLogs(gh, { params, ctx, signal, onUpdate });
+      },
     }),
-    async execute(_id, params, signal, onUpdate, ctx) {
-      return ciLogs(gh, { params, ctx, signal, onUpdate });
-    },
-  });
+  );
 }

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

@@ -1,30 +1,37 @@
 import { Type } from "typebox";
 
-import type { ToolBus } from "../../lib/tool-bus.js";
-import { type GhClient, ghExec, repoArgs, subtitlePendant, toToolResultJson } from "../base.js";
+import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
+import {
+  type GhClient,
+  ghExec,
+  repoArgs,
+  subtitlePendant,
+  toStructuredJsonResult,
+} from "../base.js";
+import { issueCommentsSchema } from "../schemas.js";
 
 export function addReadIssueCommentsTool(_gh: GhClient, bus: ToolBus) {
-  bus.register({
-    name: "read-github-issue-comments",
-    label: "GitHub Issue Comments",
-    description: "Get comments on a GitHub issue.",
-    promptSnippet: "Read GitHub issue comments",
-    parameters: Type.Object({
-      number: Type.Union([Type.Number(), Type.String()], { description: "Issue number" }),
-      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+  bus.register(
+    defineStructuredTool({
+      name: "read-github-issue-comments",
+      label: "GitHub Issue Comments",
+      description: "Get comments on a GitHub issue.",
+      promptSnippet: "Read GitHub issue comments",
+      parameters: Type.Object({
+        number: Type.Union([Type.Number(), Type.String()], { description: "Issue number" }),
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+      }),
+      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 result = toStructuredJsonResult(out, params, issueCommentsSchema);
+        result.details.pendant = subtitlePendant(params, "number");
+        return result;
+      },
     }),
-    async execute(_id, params, signal, _onUpdate, ctx) {
-      const { number, repo } = params;
-      const result = toToolResultJson(
-        await ghExec(["issue", "view", String(number), ...repoArgs(repo), "--json", "comments"], {
-          cwd: ctx.cwd,
-          signal,
-          input: params,
-        }),
-        params,
-      );
-      result.details.pendant = subtitlePendant(params, "number");
-      return result;
-    },
-  });
+  );
 }