@blaxel/core 0.2.86-preview.165 → 0.2.87-dev.173

package/dist/esm-browser/authentication/credentials.js

@@ -11,3 +11,12 @@ export class Credentials {
         return "";
     }
 }
+/**
+ * Marker returned by `authentication()` when no usable Blaxel credentials were
+ * resolved (no env vars, no matching config workspace). Construction is
+ * side-effect free so importing `@blaxel/core` never fails; the actionable
+ * error is raised when an authenticated request is actually attempted
+ * (see `Settings.assertCredentials`).
+ */
+export class MissingCredentials extends Credentials {
+}

package/dist/esm-browser/authentication/index.js

@@ -3,7 +3,7 @@ import { env } from "../common/env.js";
 import { fs, os, path } from "../common/node.js";
 import { ApiKey } from "./apikey.js";
 import { ClientCredentials } from "./clientcredentials.js";
-import { Credentials } from "./credentials.js";
+import { Credentials, MissingCredentials } from "./credentials.js";
 import { DeviceMode } from "./deviceMode.js";
 function getCredentials() {
     if (env.BL_API_KEY) {
@@ -45,7 +45,9 @@ function getCredentials() {
 export function authentication() {
     const credentials = getCredentials();
     if (!credentials) {
-        return new Credentials();
+        // Never silently fall back to empty headers: a marker that triggers a
+        // clear CredentialsError when an authenticated request is attempted.
+        return new MissingCredentials();
     }
     if (credentials.apiKey) {
         return new ApiKey(credentials);

package/dist/esm-browser/client/sdk.gen.js

@@ -2,7 +2,7 @@
 import { client as _heyApiClient } from "./client.gen.js";
 /**
  * List all agents
- * Returns all AI agents deployed in the workspace. Each agent includes its deployment status, runtime configuration, and global inference endpoint URL.
+ * Returns AI agents deployed in the workspace. Each agent includes its deployment status, runtime configuration, and global inference endpoint URL. Starting with API version 2026-04-28 the response is wrapped in `{data, meta}` and supports cursor pagination via the `cursor` and `limit` query parameters; older versions keep returning a bare array with all agents.
  */
 export const listAgents = (options) => {
     return (options?.client ?? _heyApiClient).get({
@@ -221,7 +221,7 @@ export const verifyCustomDomain = (options) => {
 };
 /**
  * List drives
- * Returns all drives in the workspace. Drives provide persistent storage that can be attached to agents, functions, and sandboxes.
+ * Returns all drives in the workspace. Drives provide persistent storage that can be attached to agents, functions, and sandboxes. Starting with API version 2026-04-28, the response wraps items in `{data, meta}` and supports cursor pagination via the `cursor` and `limit` query parameters; older versions keep returning a bare array with all drives.
  */
 export const listDrives = (options) => {
     return (options?.client ?? _heyApiClient).get({
@@ -348,6 +348,22 @@ export const listAllEgressGateways = (options) => {
         ...options
     });
 };
+/**
+ * Egress gateway sandbox attachments
+ * Returns the inverse map (gateway → sandbox names) for the workspace. Used by the egress-IPs UI to render attachment counts without fetching the sandboxes listing full client-side.
+ */
+export const getEgressGatewayUsage = (options) => {
+    return (options?.client ?? _heyApiClient).get({
+        security: [
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/egressgateways/usage',
+        ...options
+    });
+};
 /**
  * List all egress IPs across all VPCs and gateways in the workspace
  */
@@ -397,7 +413,7 @@ export const testFeatureFlag = (options) => {
 };
 /**
  * List all MCP servers
- * Returns all MCP server functions deployed in the workspace. Each function includes its deployment status, transport protocol (websocket or http-stream), and endpoint URL.
+ * Returns MCP server functions deployed in the workspace. Each function includes its deployment status, transport protocol (websocket or http-stream), and endpoint URL. Starting with API version 2026-04-28 the response is wrapped in `{data, meta}` and supports cursor pagination via the `cursor` and `limit` query parameters; older versions keep returning a bare array with all functions.
  */
 export const listFunctions = (options) => {
     return (options?.client ?? _heyApiClient).get({
@@ -805,7 +821,7 @@ export const getIntegrationConnectionModel = (options) => {
 };
 /**
  * List batch jobs
- * Returns all batch job definitions in the workspace. Each job can be triggered to run multiple parallel tasks with configurable concurrency and retry settings.
+ * Returns batch job definitions in the workspace. Each job can be triggered to run multiple parallel tasks with configurable concurrency and retry settings. Starting with API version 2026-04-28 the response is wrapped in `{data, meta}` and supports cursor pagination via the `cursor` and `limit` query parameters; older versions keep returning a bare array with all jobs.
  */
 export const listJobs = (options) => {
     return (options?.client ?? _heyApiClient).get({
@@ -893,7 +909,7 @@ export const updateJob = (options) => {
 };
 /**
  * List job executions
- * Returns paginated list of executions for a batch job, sorted by creation time. Each execution contains status, task counts, and timing information.
+ * Returns executions for a batch job. Starting with API version 2026-04-28 the response is wrapped in `{data, meta}` and supports cursor pagination via the `cursor` and `limit` query parameters; older versions keep the legacy offset/limit contract and return a bare array.
  */
 export const listJobExecutions = (options) => {
     return (options.client ?? _heyApiClient).get({
@@ -959,6 +975,22 @@ export const getJobExecution = (options) => {
         ...options
     });
 };
+/**
+ * List execution tasks
+ * Returns one cursor-paginated page of an execution's tasks. Tasks are derived from event history each request; only the in-memory slicing is paginated, the events scan still fetches the whole event log behind the scenes. Available starting with API version 2026-04-28.
+ */
+export const listJobExecutionTasks = (options) => {
+    return (options.client ?? _heyApiClient).get({
+        security: [
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/jobs/{jobId}/executions/{executionId}/tasks',
+        ...options
+    });
+};
 /**
  * List job revisions
  * Returns revisions for a job by name.
@@ -1009,7 +1041,7 @@ export const listMcpHubDefinitions = (options) => {
 };
 /**
  * List model endpoints
- * Returns all model gateway endpoints configured in the workspace. Each model represents a proxy to an external LLM provider (OpenAI, Anthropic, etc.) with unified access control.
+ * Returns model gateway endpoints configured in the workspace. Each model represents a proxy to an external LLM provider (OpenAI, Anthropic, etc.) with unified access control. Starting with API version 2026-04-28 the response is wrapped in `{data, meta}` and supports cursor pagination via the `cursor` and `limit` query parameters; older versions keep returning a bare array with all models.
  */
 export const listModels = (options) => {
     return (options?.client ?? _heyApiClient).get({
@@ -1161,7 +1193,7 @@ export const declineImageShare = (options) => {
 };
 /**
  * List governance policies
- * Returns all governance policies in the workspace. Policies control deployment locations, hardware flavors, and token limits for agents, functions, and models.
+ * Returns governance policies in the workspace. Policies control deployment locations, hardware flavors, and token limits for agents, functions, and models. Starting with API version 2026-04-28 the response is wrapped in `{data, meta}` and supports cursor pagination via the `cursor` and `limit` query parameters; older versions keep returning a bare array with all policies.
  */
 export const listPolicies = (options) => {
     return (options?.client ?? _heyApiClient).get({
@@ -1247,6 +1279,22 @@ export const updatePolicy = (options) => {
         }
     });
 };
+/**
+ * List resources using a policy
+ * Returns the names of every resource (agent, function, model, sandbox, job) currently referencing the given policy. Replaces the client-side fan-out the policies UI used to do over the listings.
+ */
+export const getPolicyUsages = (options) => {
+    return (options.client ?? _heyApiClient).get({
+        security: [
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/policies/{policyName}/usages',
+        ...options
+    });
+};
 /**
  * List public ips
  * Returns a list of all public ips used in Blaxel..
@@ -1281,7 +1329,7 @@ export const listSandboxHubDefinitions = (options) => {
 };
 /**
  * List sandboxes
- * Returns all sandboxes in the workspace. Each sandbox includes its configuration, status, and endpoint URL.
+ * Returns sandboxes in the workspace. Each sandbox includes its configuration, status, and endpoint URL. Terminated sandboxes are hidden by default; pass `showTerminated=true` to include them. Starting with API version 2026-04-28 the response is wrapped in `{data, meta}` and supports cursor pagination via the `cursor` and `limit` query parameters; older versions keep returning a bare array of all sandboxes.
  */
 export const listSandboxes = (options) => {
     return (options?.client ?? _heyApiClient).get({
@@ -1841,7 +1889,7 @@ export const deleteVolumeTemplateVersion = (options) => {
 };
 /**
  * List persistent volumes
- * Returns all persistent storage volumes in the workspace. Volumes can be attached to sandboxes for durable file storage that persists across sessions and sandbox deletions.
+ * Returns persistent storage volumes in the workspace. Volumes can be attached to sandboxes for durable file storage that persists across sessions and sandbox deletions. Starting with API version 2026-04-28 the response is wrapped in `{data, meta}` and supports cursor pagination via the `cursor` and `limit` query parameters; older versions keep returning a bare array of volumes.
  */
 export const listVolumes = (options) => {
     return (options?.client ?? _heyApiClient).get({

package/dist/esm-browser/common/credentials.test.js

@@ -0,0 +1,69 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ApiKey } from '../authentication/apikey.js';
+import { MissingCredentials } from '../authentication/credentials.js';
+import { authentication } from '../authentication/index.js';
+import { CredentialsError } from './errors.js';
+import { settings } from './settings.js';
+/**
+ * ENG-2698: missing / partial BL_WORKSPACE / BL_API_KEY must fail fast with a
+ * clear, actionable error instead of silently sending empty headers and
+ * surfacing the server's misleading "workspace is required".
+ *
+ * `env` reads through to `process.env`, so env state is controlled there.
+ */
+describe('credential validation', () => {
+    const AUTH_ENV = ['BL_API_KEY', 'BL_WORKSPACE', 'BL_CLIENT_CREDENTIALS'];
+    let savedEnv;
+    let savedCredentials;
+    let savedConfig;
+    beforeEach(() => {
+        savedEnv = {};
+        for (const key of AUTH_ENV) {
+            savedEnv[key] = process.env[key];
+            delete process.env[key];
+        }
+        savedCredentials = settings.credentials;
+        savedConfig = settings.config;
+        settings.config = { proxy: '', apikey: '', workspace: '' };
+    });
+    afterEach(() => {
+        for (const key of AUTH_ENV) {
+            if (savedEnv[key] === undefined)
+                delete process.env[key];
+            else
+                process.env[key] = savedEnv[key];
+        }
+        settings.credentials = savedCredentials;
+        settings.config = savedConfig;
+    });
+    it('API key without workspace throws a clear BL_WORKSPACE error from headers', () => {
+        settings.credentials = new ApiKey({ apiKey: 'test-key' });
+        expect(() => settings.headers).toThrow(CredentialsError);
+        expect(() => settings.headers).toThrow(/BL_WORKSPACE/);
+    });
+    it('API key without workspace rejects from authenticate()', async () => {
+        settings.credentials = new ApiKey({ apiKey: 'test-key' });
+        await expect(settings.authenticate()).rejects.toThrow(/BL_WORKSPACE/);
+    });
+    it('workspace set but no API key names the missing API key', () => {
+        process.env.BL_WORKSPACE = 'my-workspace';
+        settings.credentials = new MissingCredentials();
+        expect(() => settings.headers).toThrow(/API key is missing/);
+    });
+    it('no credentials at all names both env vars', () => {
+        settings.credentials = new MissingCredentials();
+        expect(() => settings.headers).toThrow(CredentialsError);
+        expect(() => settings.headers).toThrow(/BL_API_KEY and BL_WORKSPACE/);
+    });
+    it('api key + workspace builds clean headers with no empty values', () => {
+        settings.credentials = new ApiKey({ apiKey: 'test-key', workspace: 'my-workspace' });
+        const headers = settings.headers;
+        expect(headers['x-blaxel-workspace']).toBe('my-workspace');
+        expect(headers['x-blaxel-authorization']).toBe('Bearer test-key');
+        expect(Object.values(headers)).not.toContain('');
+    });
+    it('authentication() returns a real ApiKey when BL_API_KEY is set', () => {
+        process.env.BL_API_KEY = 'test-key';
+        expect(authentication()).toBeInstanceOf(ApiKey);
+    });
+});

package/dist/esm-browser/common/errors.js

@@ -1,3 +1,16 @@
+/**
+ * Thrown when Blaxel credentials are missing or incomplete.
+ *
+ * Surfaced eagerly with an actionable message (which env var / login step is
+ * missing) instead of silently sending empty workspace/authorization headers
+ * and letting the user hit a misleading server-side "workspace is required".
+ */
+export class CredentialsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CredentialsError";
+    }
+}
 export function handleDynamicImportError(err) {
     if (err instanceof Error) {
         // We check if it's module import error and retrieve package name from the error message with a regex

package/dist/esm-browser/common/pagination.js

@@ -0,0 +1,83 @@
+export function unwrapListData(response) {
+    if (!response) {
+        return [];
+    }
+    if (Array.isArray(response)) {
+        return response;
+    }
+    return response.data ?? [];
+}
+function unwrapListMeta(response) {
+    if (!response || Array.isArray(response)) {
+        return { hasMore: false };
+    }
+    return response.meta ?? { hasMore: false };
+}
+export async function createPaginatedList({ response, fetchPage, mapItem, query, seenCursors, }) {
+    const meta = unwrapListMeta(response);
+    const data = await Promise.all(unwrapListData(response).map(mapItem));
+    const cursors = new Set(seenCursors);
+    if (query?.cursor) {
+        cursors.add(query.cursor);
+    }
+    const list = {
+        data,
+        meta,
+        get hasMore() {
+            return Boolean(meta.hasMore);
+        },
+        get nextCursor() {
+            return meta.nextCursor || undefined;
+        },
+        async nextPage() {
+            const cursor = list.nextCursor;
+            if (!cursor) {
+                return null;
+            }
+            if (cursors.has(cursor)) {
+                throw new Error("Pagination returned a repeated cursor");
+            }
+            const nextQuery = { ...(query ?? {}), cursor };
+            const nextSeenCursors = new Set(cursors);
+            nextSeenCursors.add(cursor);
+            return createPaginatedList({
+                response: await fetchPage(nextQuery),
+                fetchPage,
+                mapItem,
+                query: nextQuery,
+                seenCursors: nextSeenCursors,
+            });
+        },
+        async autoPagingEach(onItem) {
+            for await (const item of list) {
+                const shouldContinue = await onItem(item);
+                if (shouldContinue === false) {
+                    return;
+                }
+            }
+        },
+        async autoPagingToArray(options) {
+            if (!options || !Number.isFinite(options.limit) || options.limit <= 0) {
+                throw new Error("autoPagingToArray requires a positive limit");
+            }
+            const items = [];
+            for await (const item of list) {
+                items.push(item);
+                if (items.length >= options.limit) {
+                    return items;
+                }
+            }
+            return items;
+        },
+        async *[Symbol.asyncIterator]() {
+            let page = list;
+            while (page) {
+                for (const item of page.data) {
+                    yield item;
+                }
+                page = await page.nextPage();
+            }
+        },
+    };
+    return list;
+}

package/dist/esm-browser/common/pagination.test.js

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { createPaginatedList, unwrapListData } from "./pagination.js";
+describe("pagination helpers", () => {
+    it("unwraps legacy array and paginated list responses", () => {
+        expect(unwrapListData([{ name: "legacy" }])).toEqual([{ name: "legacy" }]);
+        expect(unwrapListData({
+            data: [{ name: "paginated" }],
+            meta: { hasMore: false },
+        })).toEqual([{ name: "paginated" }]);
+    });
+    it("returns page data and lets callers request the next page", async () => {
+        const cursors = [];
+        const fetchPage = async (query) => {
+            await Promise.resolve();
+            cursors.push(query?.cursor);
+            if (!query?.cursor) {
+                return {
+                    data: ["first"],
+                    meta: { hasMore: true, nextCursor: "next-page" },
+                };
+            }
+            return {
+                data: ["second"],
+                meta: { hasMore: false },
+            };
+        };
+        const page = await createPaginatedList({
+            response: await fetchPage(),
+            fetchPage,
+            mapItem: (item) => item.toUpperCase(),
+        });
+        expect(page.data).toEqual(["FIRST"]);
+        expect(page.hasMore).toBe(true);
+        expect(page.nextCursor).toBe("next-page");
+        const nextPage = await page.nextPage();
+        expect(nextPage?.data).toEqual(["SECOND"]);
+        expect(cursors).toEqual([undefined, "next-page"]);
+    });
+    it("supports auto paging with an explicit limit", async () => {
+        const fetchPage = async (query) => {
+            await Promise.resolve();
+            if (!query?.cursor) {
+                return {
+                    data: ["first"],
+                    meta: { hasMore: true, nextCursor: "next-page" },
+                };
+            }
+            return {
+                data: ["second"],
+                meta: { hasMore: false },
+            };
+        };
+        const page = await createPaginatedList({
+            response: await fetchPage(),
+            fetchPage,
+            mapItem: (item) => item,
+        });
+        await expect(page.autoPagingToArray({ limit: 2 })).resolves.toEqual(["first", "second"]);
+    });
+});

package/dist/esm-browser/common/settings.js

@@ -1,14 +1,31 @@
 import yaml from 'yaml';
 import { ApiKey } from "../authentication/apikey.js";
 import { ClientCredentials } from "../authentication/clientcredentials.js";
+import { MissingCredentials } from "../authentication/credentials.js";
 import { authentication } from "../authentication/index.js";
 import { env } from "../common/env.js";
+import { CredentialsError } from "../common/errors.js";
 import { fs, os, path } from "../common/node.js";
+/**
+ * Build an actionable "credentials missing" message naming exactly which piece
+ * is absent, based on the env vars currently set.
+ */
+function missingCredentialsMessage() {
+    const hasWorkspace = !!env.BL_WORKSPACE;
+    const hasApiKey = !!env.BL_API_KEY;
+    if (hasWorkspace && !hasApiKey) {
+        return "Blaxel API key is missing. Set the BL_API_KEY environment variable, or run `bl login`, to authenticate (BL_WORKSPACE is already set).";
+    }
+    if (hasApiKey && !hasWorkspace) {
+        return "Blaxel workspace is missing. Set the BL_WORKSPACE environment variable, or run `bl login`, to authenticate (BL_API_KEY is already set).";
+    }
+    return "No Blaxel credentials found. Set the BL_API_KEY and BL_WORKSPACE environment variables, or run `bl login`.";
+}
 // Build info - these placeholders are replaced at build time by build:replace-imports
-const BUILD_VERSION = "0.2.86-preview.165";
-const BUILD_COMMIT = "e53a861ff9a1ab4392f576a45a9ab18a3bdf47fe";
+const BUILD_VERSION = "0.2.87-dev.173";
+const BUILD_COMMIT = "43df206258fd8138bafddefa56333aadab2be731";
 const BUILD_SENTRY_DSN = "https://fd5e60e1c9820e1eef5ccebb84a07127@o4508714045276160.ingest.us.sentry.io/4510465864564736";
-const BLAXEL_API_VERSION = "2026-04-16";
+const BLAXEL_API_VERSION = "2026-04-28";
 // Cache for config.yaml tracking value
 let configTrackingValue = null;
 let configTrackingLoaded = false;
@@ -167,6 +184,7 @@ class Settings {
         return env.BL_API_VERSION || BLAXEL_API_VERSION;
     }
     get headers() {
+        this.assertCredentials();
         const osArch = getOsArch();
         return {
             "x-blaxel-authorization": this.authorization,
@@ -252,7 +270,27 @@ class Settings {
         }
         return 0;
     }
+    /**
+     * Fail fast with a clear, actionable error when credentials are missing or
+     * incomplete, instead of sending empty workspace/authorization headers and
+     * surfacing a misleading server-side "workspace is required". Skipped for
+     * `forceUrl` sandbox sessions, which carry their own headers and never read
+     * `settings.headers`. Leaves `workspace` itself non-throwing so telemetry
+     * tagging stays safe.
+     */
+    assertCredentials() {
+        const hasConfigCredentials = !!(this.config.apikey ||
+            this.config.apiKey ||
+            this.config.clientCredentials);
+        if (!hasConfigCredentials && this.credentials instanceof MissingCredentials) {
+            throw new CredentialsError(missingCredentialsMessage());
+        }
+        if (!this.workspace) {
+            throw new CredentialsError("Blaxel workspace is missing. Set the BL_WORKSPACE environment variable, or run `bl login`, to authenticate your requests.");
+        }
+    }
     async authenticate() {
+        this.assertCredentials();
         await this.credentials.authenticate();
     }
 }

package/dist/esm-browser/common/settings.test.js

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ApiKey } from '../authentication/apikey.js';
 import { env } from './env.js';
 describe('Settings.apiVersion', () => {
     beforeEach(() => {
@@ -7,14 +8,22 @@ describe('Settings.apiVersion', () => {
     afterEach(() => {
         delete env.BL_API_VERSION;
     });
-    it('defaults to 2026-04-16 when BL_API_VERSION is not set', async () => {
+    it('defaults to 2026-04-28 when BL_API_VERSION is not set', async () => {
         delete env.BL_API_VERSION;
         const { settings } = await import('./settings.js');
-        expect(settings.apiVersion).toBe('2026-04-16');
+        expect(settings.apiVersion).toBe('2026-04-28');
     });
     it('headers include Blaxel-Version set to the default', async () => {
         delete env.BL_API_VERSION;
         const { settings } = await import('./settings.js');
-        expect(settings.headers['Blaxel-Version']).toBe('2026-04-16');
+        // headers now requires resolvable credentials; run in an authenticated context
+        const previous = settings.credentials;
+        settings.credentials = new ApiKey({ apiKey: 'test-key', workspace: 'test-ws' });
+        try {
+            expect(settings.headers['Blaxel-Version']).toBe('2026-04-28');
+        }
+        finally {
+            settings.credentials = previous;
+        }
     });
 });

package/dist/esm-browser/drive/index.js

@@ -1,5 +1,6 @@
 import { v4 as uuidv4 } from "uuid";
 import { createDrive, deleteDrive, getDrive, listDrives, updateDrive } from "../client/index.js";
+import { createPaginatedList } from "../common/pagination.js";
 import { settings } from "../common/settings.js";
 export class DriveInstance {
     drive;
@@ -83,9 +84,44 @@ export class DriveInstance {
         });
         return new DriveInstance(data);
     }
-    static async list() {
-        const { data } = await listDrives({ throwOnError: true });
-        return data.map((drive) => new DriveInstance(drive));
+    /**
+     * List one page of drives.
+     *
+     * The returned page exposes `data` for the current page, `meta` for cursor
+     * metadata, and helpers to fetch more pages only when you need them.
+     *
+     * @example
+     * ```ts
+     * const page = await DriveInstance.list({ limit: 50 });
+     *
+     * for (const drive of page.data) {
+     *   console.log(drive.name);
+     * }
+     *
+     * const nextPage = await page.nextPage();
+     * ```
+     *
+     * @example
+     * ```ts
+     * const allDrives = await (await DriveInstance.list()).autoPagingToArray({
+     *   limit: 1000,
+     * });
+     * ```
+     */
+    static async list(query) {
+        const fetchPage = async (pageQuery) => {
+            const { data } = await listDrives({
+                query: pageQuery,
+                throwOnError: true,
+            });
+            return data;
+        };
+        return createPaginatedList({
+            response: await fetchPage(query),
+            fetchPage,
+            mapItem: (drive) => new DriveInstance(drive),
+            query,
+        });
     }
     static async delete(driveName) {
         const { data } = await deleteDrive({

package/dist/esm-browser/index.js

@@ -7,6 +7,7 @@ export * from "./common/node.js";
 export * from "./common/errors.js";
 export * from "./common/internal.js";
 export * from "./common/logger.js";
+export * from "./common/pagination.js";
 export * from "./common/settings.js";
 export * from "./common/webhook.js";
 export * from "./drive/index.js";

package/dist/esm-browser/jobs/jobs.js

@@ -1,5 +1,6 @@
 import { createJobExecution, deleteJobExecution, getJobExecution, listJobExecutions, } from "../client/index.js";
 import { logger } from "../common/logger.js";
+import { createPaginatedList } from "../common/pagination.js";
 import { settings } from "../common/settings.js";
 import { startSpan } from "../telemetry/telemetry.js";
 class BlJob {
@@ -75,18 +76,50 @@ class BlJob {
         return data;
     }
     /**
-     * List all executions for this job
+     * List one page of executions for this job.
+     *
+     * The returned page exposes `data` for the current page, `meta` for cursor
+     * metadata, and helpers to fetch more pages only when you need them.
+     *
+     * @example
+     * ```ts
+     * const job = blJob("daily-import");
+     * const page = await job.listExecutions({ limit: 50 });
+     *
+     * for (const execution of page.data) {
+     *   console.log(execution.status);
+     * }
+     *
+     * const nextPage = await page.nextPage();
+     * ```
+     *
+     * @example
+     * ```ts
+     * const job = blJob("daily-import");
+     * const executions = await (await job.listExecutions()).autoPagingToArray({
+     *   limit: 1000,
+     * });
+     * ```
      */
-    async listExecutions() {
+    async listExecutions(query) {
         logger.debug(`Listing executions for job: ${this.jobName}`);
-        const { data } = await listJobExecutions({
-            path: {
-                jobId: this.jobName,
-            },
-            headers: settings.headers,
-            throwOnError: true,
+        const fetchPage = async (pageQuery) => {
+            const { data } = await listJobExecutions({
+                path: {
+                    jobId: this.jobName,
+                },
+                query: pageQuery,
+                headers: settings.headers,
+                throwOnError: true,
+            });
+            return data;
+        };
+        return createPaginatedList({
+            response: await fetchPage(query),
+            fetchPage,
+            mapItem: (execution) => execution,
+            query,
         });
-        return data ?? [];
     }
     /**
      * Get the status of a specific execution

package/dist/esm-browser/sandbox/client/sdk.gen.js

@@ -86,7 +86,7 @@ export const getDrivesMount = (options) => {
 };
 /**
  * Attach a drive to a local path
- * Mounts an agent drive using the blfs binary to a local path, optionally mounting a subpath within the drive
+ * Mounts an agent drive using the blfs binary to a local path, optionally mounting a subpath within the drive. Supports optional UID/GID mapping to remap file ownership between the local sandbox and the filer (always mapped to filer UID/GID 0). Mapping values can be set per-request via uidMap/gidMap fields, or globally via BLFS_UID_MAP/BLFS_GID_MAP environment variables (request values take precedence).
  */
 export const postDrivesMount = (options) => {
     return (options.client ?? _heyApiClient).post({