fix(github): constrain issue pagination size

Author: l1shen

src/providers/github/actions.ts

@@ -758,7 +758,7 @@ export const githubActions: ActionDefinition[] = [
   action({
     name: "list_repository_issues",
     description:
-      "List issues for a GitHub repository. Pull requests are filtered out of the response; pageInfo.fetched reports the raw page length before filtering, so paginating callers must continue while fetched equals the requested page size even when the issues array comes back short or empty.",
+      "List issues for a GitHub repository. Pull requests are filtered out of the response; pageInfo.fetched reports the raw page length before filtering, so paginating callers must continue while fetched equals perPage (30 by default) even when the issues array comes back short or empty.",
     requiredScopes: githubRepoScopes,
     inputSchema: s.object({
       owner: nonEmptyString,
@@ -768,7 +768,13 @@ export const githubActions: ActionDefinition[] = [
       sort: s.stringEnum(["created", "updated", "comments"]),
       direction: s.stringEnum(["asc", "desc"]),
       since: s.string(),
-      ...optionalPaginationFields,
+      perPage: s.integer({
+        minimum: 1,
+        maximum: 100,
+        default: 30,
+        description: "Number of results requested per page. Defaults to 30.",
+      }),
+      page: optionalPaginationFields.page,
     }),
     outputSchema: s.object({
       issues: s.array(githubIssueSchema),
@@ -778,7 +784,7 @@ export const githubActions: ActionDefinition[] = [
           fetched: s.integer({
             minimum: 0,
             description:
-              "Number of items GitHub returned on this page before filtering. Continue paginating while this equals the requested page size.",
+              "Number of items GitHub returned on this page before filtering. Continue paginating while this equals perPage, which defaults to 30.",
           }),
         },
       ),

src/providers/github/runtime-issue.test.ts

@@ -1,13 +1,17 @@
+import type { JsonSchema } from "../../core/types.ts";
+
 import { describe, expect, it } from "vitest";
 import { provider } from "./definition.ts";
 import { issueActionHandlers } from "./runtime-issue.ts";
 
-function pageFetcher(items: unknown[]): typeof fetch {
-  return async () =>
-    new Response(JSON.stringify(items), {
+function pageFetcher(items: unknown[], onRequest?: (url: string) => void): typeof fetch {
+  return async (url) => {
+    onRequest?.(String(url));
+    return new Response(JSON.stringify(items), {
       status: 200,
       headers: { "content-type": "application/json" },
     });
+  };
 }
 
 describe("list_repository_issues pagination signal", () => {
@@ -48,16 +52,31 @@ describe("list_repository_issues pagination signal", () => {
     expect(result.pageInfo.fetched).toBe(2);
   });
 
-  it("declares pageInfo.fetched in the action's output schema", () => {
-    interface ObjectSchema {
-      properties?: Record<string, ObjectSchema>;
-      required?: string[];
-      type?: string;
-    }
+  it("requests the documented default page size when perPage is omitted", async () => {
+    let requestedUrl = "";
+    await issueActionHandlers.list_repository_issues(
+      { owner: "acme", repo: "widgets" },
+      {
+        accessToken: "token",
+        fetcher: pageFetcher([], (url) => {
+          requestedUrl = url;
+        }),
+      },
+    );
+
+    expect(new URL(requestedUrl).searchParams.get("per_page")).toBe("30");
+  });
+
+  it("declares the pagination contract in the action schemas", () => {
     const action = provider.actions.find((entry) => entry.name === "list_repository_issues");
-    const pageInfo = (action?.outputSchema as ObjectSchema | undefined)?.properties?.pageInfo;
+    const inputProperties = action?.inputSchema.properties as Record<string, JsonSchema> | undefined;
+    const outputProperties = action?.outputSchema.properties as Record<string, JsonSchema> | undefined;
+    const perPage = inputProperties?.perPage;
+    const pageInfo = outputProperties?.pageInfo;
+    const pageInfoProperties = pageInfo?.properties as Record<string, JsonSchema> | undefined;
 
-    expect(pageInfo?.properties?.fetched?.type).toBe("integer");
-    expect(pageInfo?.required).toContain("fetched");
+    expect(perPage).toMatchObject({ type: "integer", minimum: 1, maximum: 100, default: 30 });
+    expect(pageInfoProperties?.fetched?.type).toBe("integer");
+    expect(pageInfo?.required as string[] | undefined).toContain("fetched");
   });
 });

src/providers/github/runtime-issue.ts

@@ -273,6 +273,7 @@ export const issueActionHandlers: Record<string, GitHubActionHandler> = {
 };
 
 async function listRepositoryIssues(input: Record<string, unknown>, accessToken: string, fetcher: typeof fetch) {
+  const perPage = optionalInteger(input.perPage) ?? 30;
   const issues = await githubRequestJson<Record<string, unknown>[]>({
     path: `/repos/${encodeURIComponent(String(input.owner))}/${encodeURIComponent(String(input.repo))}/issues`,
     query: compactObject({
@@ -281,7 +282,7 @@ async function listRepositoryIssues(input: Record<string, unknown>, accessToken:
       sort: optionalString(input.sort),
       direction: optionalString(input.direction),
       since: optionalString(input.since),
-      per_page: optionalInteger(input.perPage),
+      per_page: perPage,
       page: optionalInteger(input.page),
     }),
     accessToken,
@@ -292,8 +293,8 @@ async function listRepositoryIssues(input: Record<string, unknown>, accessToken:
     // The raw GitHub page mixes issues and pull requests; filtering PRs out
     // destroys the only pagination signal page-number callers have (the raw
     // page length). `pageInfo.fetched` preserves it: a caller must continue
-    // paginating while `fetched` equals the requested page size, even when
-    // `issues` comes back short or empty.
+    // paginating while `fetched` equals `perPage`, even when `issues` comes
+    // back short or empty.
     issues: issues.filter((issue) => issue.pull_request == null),
     pageInfo: { fetched: issues.length },
   };