fix(deploy): expose operation pagination cursor

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: MajorTal

sdk/src/namespaces/deploy.test.ts

@@ -3555,6 +3555,22 @@ describe("Deploy.list", () => {
     assert.equal(w.requests[0].path, "/deploy/v2/operations?limit=5");
   });
 
+  it("forwards cursor as a query string", async () => {
+    const w = makeWiring();
+    w.setHandler(() => ({ operations: [], cursor: null }));
+    const deploy = new Deploy(w.client);
+    await deploy.list({ project: "prj_test", cursor: "op_cursor" });
+    assert.equal(w.requests[0].path, "/deploy/v2/operations?cursor=op_cursor");
+  });
+
+  it("forwards limit and cursor as query strings", async () => {
+    const w = makeWiring();
+    w.setHandler(() => ({ operations: [], cursor: null }));
+    const deploy = new Deploy(w.client);
+    await deploy.list({ project: "prj_test", limit: 5, cursor: "op_cursor" });
+    assert.equal(w.requests[0].path, "/deploy/v2/operations?limit=5&cursor=op_cursor");
+  });
+
   it("accepts a bare projectId string and issues the same request as the options form", async () => {
     const projectLookups: string[] = [];
     const wiringFor = (): FakeWiring => {

sdk/src/namespaces/deploy.ts

@@ -46,6 +46,7 @@ import type {
   DeployEvent,
   DeployEventsResponse,
   DeployDiff,
+  DeployListOptions,
   DeployListResponse,
   DeployOperation,
   DeployResult,
@@ -274,14 +275,15 @@ export class Deploy {
    * List recent deploy operations for a project. The endpoint requires
    * `apikey` auth, so a project id is required — accepted as a bare string
    * (matches `r.functions.list(projectId)` and friends) or as `{ project,
-   * limit? }`. `limit` is forwarded to the gateway as a query string when
-   * set; the gateway picks a default otherwise.
+   * limit?, cursor? }`. `limit` and `cursor` are forwarded to the gateway
+   * as query strings when set; the gateway picks a default page otherwise.
    */
   async list(
-    opts: string | { project: string; limit?: number },
+    opts: string | DeployListOptions,
   ): Promise<DeployListResponse> {
     const project = typeof opts === "string" ? opts : opts?.project;
     const limit = typeof opts === "string" ? undefined : opts?.limit;
+    const cursor = typeof opts === "string" ? undefined : opts?.cursor;
     if (!project) {
       throw new LocalError(
         "r.deploy.list requires a project id (as a string or { project: 'prj_...' })",
@@ -291,6 +293,7 @@ export class Deploy {
     const headers = await apikeyHeaders(this.client, project);
     const qs = new URLSearchParams();
     if (limit !== undefined) qs.set("limit", String(limit));
+    if (cursor !== undefined) qs.set("cursor", cursor);
     const path =
       qs.toString().length > 0
         ? `/deploy/v2/operations?${qs.toString()}`

sdk/src/namespaces/deploy.types.ts

@@ -1630,6 +1630,12 @@ export interface OperationSnapshot {
 /** Response from `GET /deploy/v2/operations`. The gateway may return a
  *  pagination cursor when there are more operations than the requested
  *  page size; clients pass it back as `?cursor=` to fetch the next page. */
+export interface DeployListOptions {
+  project: string;
+  limit?: number;
+  cursor?: string;
+}
+
 export interface DeployListResponse {
   operations: OperationSnapshot[];
   cursor?: string | null;

src/tools/deploy-list.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, beforeEach, mock } from "node:test";
+import assert from "node:assert/strict";
+import { z } from "zod";
+
+let calls: unknown[] = [];
+let nextListImpl: (opts: unknown) => Promise<unknown> = async () => ({
+  operations: [],
+  cursor: null,
+});
+
+mock.module("../allowance-auth.js", {
+  namedExports: {
+    requireAllowanceAuth: () => ({ headers: { "SIGN-IN-WITH-X": "dGVzdA==" } }),
+  },
+});
+
+mock.module("../sdk.js", {
+  namedExports: {
+    getSdk: () => ({
+      deploy: {
+        list: async (opts: unknown) => {
+          calls.push(opts);
+          return nextListImpl(opts);
+        },
+      },
+    }),
+    _resetSdk: () => {},
+  },
+});
+
+mock.module("../errors.js", {
+  namedExports: {
+    mapSdkError: () => ({
+      content: [{ type: "text", text: "mapped SDK error" }],
+      isError: true,
+    }),
+  },
+});
+
+const { deployListSchema, handleDeployList } = await import("./deploy-list.js");
+
+beforeEach(() => {
+  calls = [];
+  nextListImpl = async () => ({
+    operations: [],
+    cursor: null,
+  });
+});
+
+describe("deploy_list", () => {
+  it("accepts a pagination cursor in the schema", () => {
+    const parsed = z.object(deployListSchema).parse({
+      project_id: "prj_test",
+      limit: 5,
+      cursor: "op_cursor",
+    });
+
+    assert.equal(parsed.cursor, "op_cursor");
+  });
+
+  it("forwards cursor to SDK deploy.list and still renders the next cursor", async () => {
+    nextListImpl = async () => ({
+      operations: [
+        {
+          operation_id: "op_1",
+          status: "ready",
+          release_id: "rel_1",
+          updated_at: "2026-05-15T00:00:00Z",
+        },
+      ],
+      cursor: "op_next",
+    });
+
+    const result = await handleDeployList({
+      project_id: "prj_test",
+      limit: 5,
+      cursor: "op_cursor",
+    });
+
+    assert.equal(result.isError, undefined);
+    assert.deepEqual(calls, [
+      { project: "prj_test", limit: 5, cursor: "op_cursor" },
+    ]);
+    assert.match(result.content[0]!.text, /Next cursor: `op_next`/);
+  });
+});

src/tools/deploy-list.ts

@@ -23,11 +23,18 @@ export const deployListSchema = {
     .describe(
       "Maximum number of operations to return. Forwarded to the gateway as `?limit=`; the gateway picks a default when omitted.",
     ),
+  cursor: z
+    .string()
+    .optional()
+    .describe(
+      "Pagination cursor returned by a previous deploy_list response. Forwarded to the gateway as `?cursor=`.",
+    ),
 };
 
 export async function handleDeployList(args: {
   project_id: string;
   limit?: number;
+  cursor?: string;
 }): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
   const auth = requireAllowanceAuth("/deploy/v2/operations");
   if ("error" in auth) return auth.error;
@@ -36,6 +43,7 @@ export async function handleDeployList(args: {
     const result = await getSdk().deploy.list({
       project: args.project_id,
       limit: args.limit,
+      cursor: args.cursor,
     });
 
     const lines: string[] = [