@trim21/personal-pi-extensions 0.1.678 → 0.1.680

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

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

@@ -1,22 +1,30 @@
 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 { issueViewSchema } from "../schemas.js";
 
 export function addReadIssueTool(_gh: GhClient, bus: ToolBus) {
-  bus.register({
-    name: "read-github-issue",
-    label: "GitHub Issue",
-    description: "Get details of a GitHub issue by number.",
-    promptSnippet: "Read a GitHub issue",
-    parameters: Type.Object({
-      number: Type.Union([Type.Number(), Type.String()], { description: "Issue number" }),
-      repo: Type.Optional(Type.String({ description: "OWNER/REPO (defaults to current repo)" })),
-    }),
-    async execute(_id, params, signal, _onUpdate, ctx) {
-      const { number, repo } = params;
-      const result = toToolResultJson(
-        await ghExec(
+  bus.register(
+    defineStructuredTool({
+      name: "read-github-issue",
+      label: "GitHub Issue",
+      description: "Get details of a GitHub issue by number.",
+      promptSnippet: "Read a GitHub issue",
+      parameters: Type.Object({
+        number: Type.Union([Type.Number(), Type.String()], { description: "Issue number" }),
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO (defaults to current repo)" })),
+      }),
+      structuredSchema: issueViewSchema,
+      async execute(_id, params, signal, _onUpdate, ctx) {
+        const { number, repo } = params;
+        const out = await ghExec(
           [
             "issue",
             "view",
@@ -26,11 +34,11 @@ export function addReadIssueTool(_gh: GhClient, bus: ToolBus) {
             "title,state,body,author,createdAt,updatedAt,closedAt,url,labels,assignees,comments,milestone,number",
           ],
           { cwd: ctx.cwd, signal, input: params },
-        ),
-        params,
-      );
-      result.details.pendant = subtitlePendant(params, "number");
-      return result;
-    },
-  });
+        );
+        const result = toStructuredJsonResult(out, params, issueViewSchema);
+        result.details.pendant = subtitlePendant(params, "number");
+        return result;
+      },
+    }),
+  );
 }

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

@@ -1,6 +1,6 @@
 import { Type } from "typebox";
 
-import type { ToolBus } from "../../lib/tool-bus.js";
+import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   ghApiList,
   type GhClient,
@@ -8,66 +8,70 @@ import {
   repoArgs,
   resolveRepo,
   subtitlePendant,
-  toToolResultJson,
+  toStructuredJsonResult,
 } from "../base.js";
+import { prCommentsSchema } from "../schemas.js";
 
 export function addReadPrCommentsTool(_gh: GhClient, bus: ToolBus) {
-  bus.register({
-    name: "read-github-pr-comments",
-    label: "GitHub PR Comments",
-    description:
-      "Get review comments on a GitHub pull request. Set reviews=true for inline code review comments with diff_hunk.",
-    promptSnippet: "Read GitHub PR comments",
-    parameters: Type.Object({
-      number: Type.Union([Type.Number(), Type.String()], { description: "PR number" }),
-      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
-      reviews: Type.Optional(
-        Type.Boolean({
-          description:
-            "If true, returns inline code review comments (with diff_hunk, path, line) via API. Default: false (returns issue comments).",
-        }),
-      ),
-    }),
-    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 [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,
+  bus.register(
+    defineStructuredTool({
+      name: "read-github-pr-comments",
+      label: "GitHub PR Comments",
+      description:
+        "Get review comments on a GitHub pull request. Set reviews=true for inline code review comments with diff_hunk.",
+      promptSnippet: "Read GitHub PR comments",
+      parameters: Type.Object({
+        number: Type.Union([Type.Number(), Type.String()], { description: "PR number" }),
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+        reviews: Type.Optional(
+          Type.Boolean({
+            description:
+              "If true, returns inline code review comments (with diff_hunk, path, line) via API. Default: false (returns issue comments).",
           }),
-        ]);
+        ),
+      }),
+      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);
 
-        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 = toToolResultJson(out, params);
-      result.details.pendant = subtitlePendant(params, "number");
-      return result;
-    },
-  });
+          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,
+            }),
+          ]);
+
+          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);
+        result.details.pendant = subtitlePendant(params, "number");
+        return result;
+      },
+    }),
+  );
 }