@trim21/personal-pi-extensions 0.1.674 → 0.1.679

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

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

@@ -1,16 +1,18 @@
 import { Type } from "typebox";
 
-import type { ToolBus } from "../../lib/tool-bus.js";
+import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
   mergeChecks,
   resolveRepo,
   splitRepo,
+  type StructuredResultOf,
   subtitlePendant,
   type ToolCall,
-  type ToolResult,
   toPositiveId,
+  withStructuredResult,
 } from "../base.js";
+import { prStatusSchema } from "../schemas.js";
 
 interface PrStatusParams {
   number: number | string;
@@ -22,7 +24,10 @@ interface PrStatusParams {
  * path as the wait tools (octokit), but it never polls — pending checks come
  * back as-is.
  */
-export async function prStatus(gh: GhClient, call: ToolCall<PrStatusParams>): Promise<ToolResult> {
+export async function prStatus(
+  gh: GhClient,
+  call: ToolCall<PrStatusParams>,
+): Promise<StructuredResultOf<typeof prStatusSchema>> {
   const { params, ctx, signal } = call;
   const { number, repo } = params;
   const pullNumber = toPositiveId(number, "number");
@@ -46,25 +51,31 @@ export async function prStatus(gh: GhClient, call: ToolCall<PrStatusParams>): Pr
   }));
 
   const payload = { pr: pullNumber, repo: effectiveRepo, head_sha: headSha, checks };
-  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 addReadPrStatusTool(gh: GhClient, bus: ToolBus) {
-  bus.register({
-    name: "read-github-pr-status",
-    label: "GitHub PR Status",
-    description:
-      "Get the current checks of a pull request's head commit as JSON {pr, repo, head_sha, checks:[{name, bucket, event, run_id, job_id, url}]}. `bucket` is pass / fail / pending / skipped; Actions checks carry the `run_id` and `job_id` behind them (null for other CI), which is what read-github-ci-logs and get-github-workflow-jobs take. Returns the snapshot immediately without waiting — use wait-github-pr-checks to block until the checks finish.",
-    promptSnippet: "Read GitHub PR status checks",
-    parameters: Type.Object({
-      number: Type.Union([Type.Number(), Type.String()], { description: "PR number" }),
-      repo: Type.Optional(Type.String({ description: "OWNER/REPO (defaults to current repo)" })),
+  bus.register(
+    defineStructuredTool({
+      name: "read-github-pr-status",
+      label: "GitHub PR Status",
+      description:
+        "Get the current checks of a pull request's head commit as JSON {pr, repo, head_sha, checks:[{name, bucket, event, run_id, job_id, url}]}. `bucket` is pass / fail / pending / skipped; Actions checks carry the `run_id` and `job_id` behind them (null for other CI), which is what read-github-ci-logs and get-github-workflow-jobs take. Returns the snapshot immediately without waiting — use wait-github-pr-checks to block until the checks finish.",
+      promptSnippet: "Read GitHub PR status checks",
+      parameters: Type.Object({
+        number: Type.Union([Type.Number(), Type.String()], { description: "PR number" }),
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO (defaults to current repo)" })),
+      }),
+      structuredSchema: prStatusSchema,
+      async execute(_id, params, signal, onUpdate, ctx) {
+        return prStatus(gh, { params, ctx, signal, onUpdate });
+      },
     }),
-    async execute(_id, params, signal, onUpdate, ctx) {
-      return prStatus(gh, { params, ctx, signal, onUpdate });
-    },
-  });
+  );
 }

package/src/gh/tools/read-pr.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 { prViewSchema } from "../schemas.js";
 
 export function addReadPrTool(_gh: GhClient, bus: ToolBus) {
-  bus.register({
-    name: "read-github-pr",
-    label: "GitHub PR",
-    description: "Get details of a GitHub pull request by number.",
-    promptSnippet: "Read a GitHub PR",
-    parameters: Type.Object({
-      number: Type.Union([Type.Number(), Type.String()], { description: "PR number" }),
-      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
-    }),
-    async execute(_id, params, signal, _onUpdate, ctx) {
-      const { number, repo } = params;
-      const result = toToolResultJson(
-        await ghExec(
+  bus.register(
+    defineStructuredTool({
+      name: "read-github-pr",
+      label: "GitHub PR",
+      description: "Get details of a GitHub pull request by number.",
+      promptSnippet: "Read a GitHub PR",
+      parameters: Type.Object({
+        number: Type.Union([Type.Number(), Type.String()], { description: "PR number" }),
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+      }),
+      structuredSchema: prViewSchema,
+      async execute(_id, params, signal, _onUpdate, ctx) {
+        const { number, repo } = params;
+        const out = await ghExec(
           [
             "pr",
             "view",
@@ -26,11 +34,11 @@ export function addReadPrTool(_gh: GhClient, bus: ToolBus) {
             "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 },
-        ),
-        params,
-      );
-      result.details.pendant = subtitlePendant(params, "number");
-      return result;
-    },
-  });
+        );
+        const result = toStructuredJsonResult(out, params, prViewSchema);
+        result.details.pendant = subtitlePendant(params, "number");
+        return result;
+      },
+    }),
+  );
 }

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

@@ -1,15 +1,16 @@
 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,
   waitChecksReport,
 } from "../base.js";
+import { checksVerdictSchema } from "../schemas.js";
 
 interface CommitChecksWaitParams {
   commit: number | string;
@@ -22,7 +23,7 @@ interface CommitChecksWaitParams {
 async function waitCommitChecks(
   gh: GhClient,
   call: ToolCall<CommitChecksWaitParams>,
-): Promise<ToolResult> {
+): Promise<StructuredResultOf<typeof checksVerdictSchema>> {
   const { params, ctx, signal, onUpdate } = call;
   const { commit, repo, event, fail_fast } = params;
 
@@ -54,35 +55,38 @@ async function waitCommitChecks(
 }
 
 export function addWaitCommitChecksTool(gh: GhClient, bus: ToolBus) {
-  bus.register({
-    name: "wait-github-commit-checks",
-    label: "Watch GitHub Commit Checks",
-    description:
-      "Watch CI status checks for a commit until they complete — no pull request required. " +
-      "Same semantics as wait-github-pr-checks: returns when any check fails (immediately under fail_fast) " +
-      "or all checks pass/skip; on timeout the still-in-flight snapshot is returned. " +
-      "With `event`, only check runs triggered by that workflow event (e.g. push) are judged; " +
-      "commit statuses have an unknown trigger event and are excluded under a filter. " +
-      "Use this to wait for the runs a commit's push triggered, or for checks on an arbitrary ref.",
-    promptSnippet: "Watch and wait for GitHub commit CI checks to complete",
-    parameters: Type.Object({
-      commit: Type.Union([Type.Number(), Type.String()], {
-        description:
-          "Commit to wait for: full or partial SHA, branch name, or tag name (resolved to the commit's SHA)",
-      }),
-      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
-      event: Type.Optional(
-        Type.String({
+  bus.register(
+    defineStructuredTool({
+      name: "wait-github-commit-checks",
+      label: "Watch GitHub Commit Checks",
+      description:
+        "Watch CI status checks for a commit until they complete — no pull request required. " +
+        "Same semantics as wait-github-pr-checks: returns when any check fails (immediately under fail_fast) " +
+        "or all checks pass/skip; on timeout the still-in-flight snapshot is returned. " +
+        "With `event`, only check runs triggered by that workflow event (e.g. push) are judged; " +
+        "commit statuses have an unknown trigger event and are excluded under a filter. " +
+        "Use this to wait for the runs a commit's push triggered, or for checks on an arbitrary ref.",
+      promptSnippet: "Watch and wait for GitHub commit CI checks to complete",
+      parameters: Type.Object({
+        commit: Type.Union([Type.Number(), Type.String()], {
           description:
-            "Only judge check runs triggered by this workflow event (e.g. push, pull_request)",
+            "Commit to wait for: full or partial SHA, branch name, or tag name (resolved to the commit's SHA)",
         }),
-      ),
-      fail_fast: Type.Optional(
-        Type.Boolean({ description: "Exit immediately when any check fails (default: false)" }),
-      ),
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+        event: Type.Optional(
+          Type.String({
+            description:
+              "Only judge check runs triggered by this workflow event (e.g. push, pull_request)",
+          }),
+        ),
+        fail_fast: Type.Optional(
+          Type.Boolean({ description: "Exit immediately when any check fails (default: false)" }),
+        ),
+      }),
+      structuredSchema: checksVerdictSchema,
+      async execute(_id, params, signal, onUpdate, ctx) {
+        return waitCommitChecks(gh, { params, ctx, signal, onUpdate });
+      },
     }),
-    async execute(_id, params, signal, onUpdate, ctx) {
-      return waitCommitChecks(gh, { params, ctx, signal, onUpdate });
-    },
-  });
+  );
 }

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

@@ -1,17 +1,18 @@
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 
-import type { ToolBus } from "../../lib/tool-bus.js";
+import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
   ghExec,
   resolveRepo,
   splitRepo,
+  type StructuredResultOf,
   subtitlePendant,
   type ToolCall,
-  type ToolResult,
   waitChecksReport,
 } from "../base.js";
+import { checksVerdictSchema } from "../schemas.js";
 
 interface PrChecksWaitParams {
   number: number | string;
@@ -22,7 +23,10 @@ interface PrChecksWaitParams {
 const prHeadSchema = Type.Object({ headRefOid: Type.String() });
 
 /** The toolcall handler behind `wait-github-pr-checks`. */
-async function waitPrChecks(gh: GhClient, call: ToolCall<PrChecksWaitParams>): Promise<ToolResult> {
+async function waitPrChecks(
+  gh: GhClient,
+  call: ToolCall<PrChecksWaitParams>,
+): Promise<StructuredResultOf<typeof checksVerdictSchema>> {
   const { params, ctx, signal, onUpdate } = call;
   const { number, repo, fail_fast } = params;
 
@@ -56,25 +60,28 @@ async function waitPrChecks(gh: GhClient, call: ToolCall<PrChecksWaitParams>): P
 }
 
 export function addWaitPrChecksTool(gh: GhClient, bus: ToolBus) {
-  bus.register({
-    name: "wait-github-pr-checks",
-    label: "Watch GitHub PR Checks",
-    description:
-      "Watch CI status checks for a PR until they complete. Blocks until all checks pass (or are skipped) or one fails. " +
-      "Covers both commit statuses (Azure DevOps, Jenkins, ...) and GitHub Actions check runs. " +
-      "Each polling round streams a compact bullet list of the checks still in flight via onUpdate; " +
-      "on timeout the still-in-flight snapshot is returned instead of a verdict. " +
-      "Use this when you need to wait for CI to complete and see the final result.",
-    promptSnippet: "Watch and wait for GitHub PR CI checks to complete",
-    parameters: Type.Object({
-      number: Type.Union([Type.Number(), Type.String()], { description: "PR number" }),
-      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
-      fail_fast: Type.Optional(
-        Type.Boolean({ description: "Exit immediately when any check fails (default: false)" }),
-      ),
+  bus.register(
+    defineStructuredTool({
+      name: "wait-github-pr-checks",
+      label: "Watch GitHub PR Checks",
+      description:
+        "Watch CI status checks for a PR until they complete. Blocks until all checks pass (or are skipped) or one fails. " +
+        "Covers both commit statuses (Azure DevOps, Jenkins, ...) and GitHub Actions check runs. " +
+        "Each polling round streams a compact bullet list of the checks still in flight via onUpdate; " +
+        "on timeout the still-in-flight snapshot is returned instead of a verdict. " +
+        "Use this when you need to wait for CI to complete and see the final result.",
+      promptSnippet: "Watch and wait for GitHub PR CI checks to complete",
+      parameters: Type.Object({
+        number: Type.Union([Type.Number(), Type.String()], { description: "PR number" }),
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+        fail_fast: Type.Optional(
+          Type.Boolean({ description: "Exit immediately when any check fails (default: false)" }),
+        ),
+      }),
+      structuredSchema: checksVerdictSchema,
+      async execute(_id, params, signal, onUpdate, ctx) {
+        return waitPrChecks(gh, { params, ctx, signal, onUpdate });
+      },
     }),
-    async execute(_id, params, signal, onUpdate, ctx) {
-      return waitPrChecks(gh, { params, ctx, signal, onUpdate });
-    },
-  });
+  );
 }