@blaxel/core 0.2.86 → 0.2.87-dev.173

package/dist/cjs/authentication/credentials.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Credentials = void 0;
+exports.MissingCredentials = exports.Credentials = void 0;
 const env_js_1 = require("../common/env.js");
 class Credentials {
     async authenticate() { }
@@ -15,3 +15,13 @@ class Credentials {
     }
 }
 exports.Credentials = Credentials;
+/**
+ * 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`).
+ */
+class MissingCredentials extends Credentials {
+}
+exports.MissingCredentials = MissingCredentials;

package/dist/cjs/authentication/index.js

@@ -51,7 +51,9 @@ function getCredentials() {
 function authentication() {
     const credentials = getCredentials();
     if (!credentials) {
-        return new credentials_js_1.Credentials();
+        // Never silently fall back to empty headers: a marker that triggers a
+        // clear CredentialsError when an authenticated request is attempted.
+        return new credentials_js_1.MissingCredentials();
     }
     if (credentials.apiKey) {
         return new apikey_js_1.ApiKey(credentials);

package/dist/cjs/client/sdk.gen.js

@@ -1,13 +1,13 @@
 "use strict";
 // This file is auto-generated by @hey-api/openapi-ts
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createJob = exports.listJobs = exports.getIntegrationConnectionModel = exports.listIntegrationConnectionModels = exports.getIntegrationConnectionModelEndpointConfigurations = exports.updateIntegrationConnection = exports.getIntegrationConnection = exports.deleteIntegrationConnection = exports.createIntegrationConnection = exports.listIntegrationConnections = exports.getIntegration = exports.deleteImageTag = exports.unshareImage = exports.shareImage = exports.listImageShares = exports.getImage = exports.deleteImage = exports.createImage = exports.listImages = exports.cleanupImages = exports.listFunctionRevisions = exports.updateFunction = exports.getFunction = exports.deleteFunction = exports.createFunction = exports.listFunctions = exports.testFeatureFlag = exports.getWorkspaceFeatures = exports.listAllEgressIps = exports.listAllEgressGateways = exports.getDriveJwks = exports.createDriveAccessToken = exports.updateDrive = exports.getDrive = exports.deleteDrive = exports.createDrive = exports.listDrives = exports.verifyCustomDomain = exports.updateCustomDomain = exports.getCustomDomain = exports.deleteCustomDomain = exports.createCustomDomain = exports.listCustomDomains = exports.getConfiguration = exports.listAgentRevisions = exports.updateAgent = exports.getAgent = exports.deleteAgent = exports.createAgent = exports.listAgents = void 0;
-exports.inviteWorkspaceUser = exports.listWorkspaceUsers = exports.getTemplate = exports.listTemplates = exports.deleteApiKeyForServiceAccount = exports.createApiKeyForServiceAccount = exports.listApiKeysForServiceAccount = exports.updateWorkspaceServiceAccount = exports.deleteWorkspaceServiceAccount = exports.createWorkspaceServiceAccount = exports.getWorkspaceServiceAccounts = exports.deleteSandboxPreviewToken = exports.createSandboxPreviewToken = exports.listSandboxPreviewTokens = exports.updateSandboxPreview = exports.getSandboxPreview = exports.deleteSandboxPreview = exports.createSandboxPreview = exports.listSandboxPreviews = exports.updateSandbox = exports.getSandbox = exports.deleteSandbox = exports.createSandbox = exports.listSandboxes = exports.listSandboxHubDefinitions = exports.listPublicIps = exports.updatePolicy = exports.getPolicy = exports.deletePolicy = exports.createPolicy = exports.listPolicies = exports.declineImageShare = exports.acceptImageShare = exports.listPendingImageShares = exports.listModelRevisions = exports.updateModel = exports.getModel = exports.deleteModel = exports.createModel = exports.listModels = exports.listMcpHubDefinitions = exports.listLocations = exports.listJobRevisions = exports.getJobExecution = exports.deleteJobExecution = exports.createJobExecution = exports.listJobExecutions = exports.updateJob = exports.getJob = exports.deleteJob = void 0;
-exports.checkWorkspaceAvailability = exports.leaveWorkspace = exports.acceptWorkspaceInvitation = exports.declineWorkspaceInvitation = exports.updateWorkspace = exports.getWorkspace = exports.deleteWorkspace = exports.createWorkspace = exports.listWorkspaces = exports.getEgressIp = exports.deleteEgressIp = exports.createEgressIp = exports.listEgressIps = exports.getEgressGateway = exports.deleteEgressGateway = exports.createEgressGateway = exports.listEgressGateways = exports.getVpc = exports.deleteVpc = exports.createVpc = exports.listVpcs = exports.updateVolume = exports.getVolume = exports.deleteVolume = exports.createVolume = exports.listVolumes = exports.deleteVolumeTemplateVersion = exports.updateVolumeTemplate = exports.getVolumeTemplate = exports.deleteVolumeTemplate = exports.createVolumeTemplate = exports.listVolumeTemplates = exports.updateWorkspaceUserRole = exports.removeWorkspaceUser = void 0;
+exports.listJobs = exports.getIntegrationConnectionModel = exports.listIntegrationConnectionModels = exports.getIntegrationConnectionModelEndpointConfigurations = exports.updateIntegrationConnection = exports.getIntegrationConnection = exports.deleteIntegrationConnection = exports.createIntegrationConnection = exports.listIntegrationConnections = exports.getIntegration = exports.deleteImageTag = exports.unshareImage = exports.shareImage = exports.listImageShares = exports.getImage = exports.deleteImage = exports.createImage = exports.listImages = exports.cleanupImages = exports.listFunctionRevisions = exports.updateFunction = exports.getFunction = exports.deleteFunction = exports.createFunction = exports.listFunctions = exports.testFeatureFlag = exports.getWorkspaceFeatures = exports.listAllEgressIps = exports.getEgressGatewayUsage = exports.listAllEgressGateways = exports.getDriveJwks = exports.createDriveAccessToken = exports.updateDrive = exports.getDrive = exports.deleteDrive = exports.createDrive = exports.listDrives = exports.verifyCustomDomain = exports.updateCustomDomain = exports.getCustomDomain = exports.deleteCustomDomain = exports.createCustomDomain = exports.listCustomDomains = exports.getConfiguration = exports.listAgentRevisions = exports.updateAgent = exports.getAgent = exports.deleteAgent = exports.createAgent = exports.listAgents = void 0;
+exports.listTemplates = exports.deleteApiKeyForServiceAccount = exports.createApiKeyForServiceAccount = exports.listApiKeysForServiceAccount = exports.updateWorkspaceServiceAccount = exports.deleteWorkspaceServiceAccount = exports.createWorkspaceServiceAccount = exports.getWorkspaceServiceAccounts = exports.deleteSandboxPreviewToken = exports.createSandboxPreviewToken = exports.listSandboxPreviewTokens = exports.updateSandboxPreview = exports.getSandboxPreview = exports.deleteSandboxPreview = exports.createSandboxPreview = exports.listSandboxPreviews = exports.updateSandbox = exports.getSandbox = exports.deleteSandbox = exports.createSandbox = exports.listSandboxes = exports.listSandboxHubDefinitions = exports.listPublicIps = exports.getPolicyUsages = exports.updatePolicy = exports.getPolicy = exports.deletePolicy = exports.createPolicy = exports.listPolicies = exports.declineImageShare = exports.acceptImageShare = exports.listPendingImageShares = exports.listModelRevisions = exports.updateModel = exports.getModel = exports.deleteModel = exports.createModel = exports.listModels = exports.listMcpHubDefinitions = exports.listLocations = exports.listJobRevisions = exports.listJobExecutionTasks = exports.getJobExecution = exports.deleteJobExecution = exports.createJobExecution = exports.listJobExecutions = exports.updateJob = exports.getJob = exports.deleteJob = exports.createJob = void 0;
+exports.checkWorkspaceAvailability = exports.leaveWorkspace = exports.acceptWorkspaceInvitation = exports.declineWorkspaceInvitation = exports.updateWorkspace = exports.getWorkspace = exports.deleteWorkspace = exports.createWorkspace = exports.listWorkspaces = exports.getEgressIp = exports.deleteEgressIp = exports.createEgressIp = exports.listEgressIps = exports.getEgressGateway = exports.deleteEgressGateway = exports.createEgressGateway = exports.listEgressGateways = exports.getVpc = exports.deleteVpc = exports.createVpc = exports.listVpcs = exports.updateVolume = exports.getVolume = exports.deleteVolume = exports.createVolume = exports.listVolumes = exports.deleteVolumeTemplateVersion = exports.updateVolumeTemplate = exports.getVolumeTemplate = exports.deleteVolumeTemplate = exports.createVolumeTemplate = exports.listVolumeTemplates = exports.updateWorkspaceUserRole = exports.removeWorkspaceUser = exports.inviteWorkspaceUser = exports.listWorkspaceUsers = exports.getTemplate = void 0;
 const client_gen_1 = require("./client.gen");
 /**
  * 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.
  */
 const listAgents = (options) => {
     return (options?.client ?? client_gen_1.client).get({
@@ -239,7 +239,7 @@ const verifyCustomDomain = (options) => {
 exports.verifyCustomDomain = verifyCustomDomain;
 /**
  * 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.
  */
 const listDrives = (options) => {
     return (options?.client ?? client_gen_1.client).get({
@@ -374,6 +374,23 @@ const listAllEgressGateways = (options) => {
     });
 };
 exports.listAllEgressGateways = listAllEgressGateways;
+/**
+ * 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.
+ */
+const getEgressGatewayUsage = (options) => {
+    return (options?.client ?? client_gen_1.client).get({
+        security: [
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/egressgateways/usage',
+        ...options
+    });
+};
+exports.getEgressGatewayUsage = getEgressGatewayUsage;
 /**
  * List all egress IPs across all VPCs and gateways in the workspace
  */
@@ -426,7 +443,7 @@ const testFeatureFlag = (options) => {
 exports.testFeatureFlag = testFeatureFlag;
 /**
  * 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.
  */
 const listFunctions = (options) => {
     return (options?.client ?? client_gen_1.client).get({
@@ -858,7 +875,7 @@ const getIntegrationConnectionModel = (options) => {
 exports.getIntegrationConnectionModel = getIntegrationConnectionModel;
 /**
  * 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.
  */
 const listJobs = (options) => {
     return (options?.client ?? client_gen_1.client).get({
@@ -951,7 +968,7 @@ const updateJob = (options) => {
 exports.updateJob = updateJob;
 /**
  * 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.
  */
 const listJobExecutions = (options) => {
     return (options.client ?? client_gen_1.client).get({
@@ -1021,6 +1038,23 @@ const getJobExecution = (options) => {
     });
 };
 exports.getJobExecution = getJobExecution;
+/**
+ * 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.
+ */
+const listJobExecutionTasks = (options) => {
+    return (options.client ?? client_gen_1.client).get({
+        security: [
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/jobs/{jobId}/executions/{executionId}/tasks',
+        ...options
+    });
+};
+exports.listJobExecutionTasks = listJobExecutionTasks;
 /**
  * List job revisions
  * Returns revisions for a job by name.
@@ -1074,7 +1108,7 @@ const listMcpHubDefinitions = (options) => {
 exports.listMcpHubDefinitions = listMcpHubDefinitions;
 /**
  * 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.
  */
 const listModels = (options) => {
     return (options?.client ?? client_gen_1.client).get({
@@ -1235,7 +1269,7 @@ const declineImageShare = (options) => {
 exports.declineImageShare = declineImageShare;
 /**
  * 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.
  */
 const listPolicies = (options) => {
     return (options?.client ?? client_gen_1.client).get({
@@ -1326,6 +1360,23 @@ const updatePolicy = (options) => {
     });
 };
 exports.updatePolicy = updatePolicy;
+/**
+ * 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.
+ */
+const getPolicyUsages = (options) => {
+    return (options.client ?? client_gen_1.client).get({
+        security: [
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/policies/{policyName}/usages',
+        ...options
+    });
+};
+exports.getPolicyUsages = getPolicyUsages;
 /**
  * List public ips
  * Returns a list of all public ips used in Blaxel..
@@ -1362,7 +1413,7 @@ const listSandboxHubDefinitions = (options) => {
 exports.listSandboxHubDefinitions = listSandboxHubDefinitions;
 /**
  * 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.
  */
 const listSandboxes = (options) => {
     return (options?.client ?? client_gen_1.client).get({
@@ -1954,7 +2005,7 @@ const deleteVolumeTemplateVersion = (options) => {
 exports.deleteVolumeTemplateVersion = deleteVolumeTemplateVersion;
 /**
  * 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.
  */
 const listVolumes = (options) => {
     return (options?.client ?? client_gen_1.client).get({

package/dist/cjs/common/credentials.test.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const apikey_js_1 = require("../authentication/apikey.js");
+const credentials_js_1 = require("../authentication/credentials.js");
+const index_js_1 = require("../authentication/index.js");
+const errors_js_1 = require("./errors.js");
+const settings_js_1 = require("./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.
+ */
+(0, vitest_1.describe)('credential validation', () => {
+    const AUTH_ENV = ['BL_API_KEY', 'BL_WORKSPACE', 'BL_CLIENT_CREDENTIALS'];
+    let savedEnv;
+    let savedCredentials;
+    let savedConfig;
+    (0, vitest_1.beforeEach)(() => {
+        savedEnv = {};
+        for (const key of AUTH_ENV) {
+            savedEnv[key] = process.env[key];
+            delete process.env[key];
+        }
+        savedCredentials = settings_js_1.settings.credentials;
+        savedConfig = settings_js_1.settings.config;
+        settings_js_1.settings.config = { proxy: '', apikey: '', workspace: '' };
+    });
+    (0, vitest_1.afterEach)(() => {
+        for (const key of AUTH_ENV) {
+            if (savedEnv[key] === undefined)
+                delete process.env[key];
+            else
+                process.env[key] = savedEnv[key];
+        }
+        settings_js_1.settings.credentials = savedCredentials;
+        settings_js_1.settings.config = savedConfig;
+    });
+    (0, vitest_1.it)('API key without workspace throws a clear BL_WORKSPACE error from headers', () => {
+        settings_js_1.settings.credentials = new apikey_js_1.ApiKey({ apiKey: 'test-key' });
+        (0, vitest_1.expect)(() => settings_js_1.settings.headers).toThrow(errors_js_1.CredentialsError);
+        (0, vitest_1.expect)(() => settings_js_1.settings.headers).toThrow(/BL_WORKSPACE/);
+    });
+    (0, vitest_1.it)('API key without workspace rejects from authenticate()', async () => {
+        settings_js_1.settings.credentials = new apikey_js_1.ApiKey({ apiKey: 'test-key' });
+        await (0, vitest_1.expect)(settings_js_1.settings.authenticate()).rejects.toThrow(/BL_WORKSPACE/);
+    });
+    (0, vitest_1.it)('workspace set but no API key names the missing API key', () => {
+        process.env.BL_WORKSPACE = 'my-workspace';
+        settings_js_1.settings.credentials = new credentials_js_1.MissingCredentials();
+        (0, vitest_1.expect)(() => settings_js_1.settings.headers).toThrow(/API key is missing/);
+    });
+    (0, vitest_1.it)('no credentials at all names both env vars', () => {
+        settings_js_1.settings.credentials = new credentials_js_1.MissingCredentials();
+        (0, vitest_1.expect)(() => settings_js_1.settings.headers).toThrow(errors_js_1.CredentialsError);
+        (0, vitest_1.expect)(() => settings_js_1.settings.headers).toThrow(/BL_API_KEY and BL_WORKSPACE/);
+    });
+    (0, vitest_1.it)('api key + workspace builds clean headers with no empty values', () => {
+        settings_js_1.settings.credentials = new apikey_js_1.ApiKey({ apiKey: 'test-key', workspace: 'my-workspace' });
+        const headers = settings_js_1.settings.headers;
+        (0, vitest_1.expect)(headers['x-blaxel-workspace']).toBe('my-workspace');
+        (0, vitest_1.expect)(headers['x-blaxel-authorization']).toBe('Bearer test-key');
+        (0, vitest_1.expect)(Object.values(headers)).not.toContain('');
+    });
+    (0, vitest_1.it)('authentication() returns a real ApiKey when BL_API_KEY is set', () => {
+        process.env.BL_API_KEY = 'test-key';
+        (0, vitest_1.expect)((0, index_js_1.authentication)()).toBeInstanceOf(apikey_js_1.ApiKey);
+    });
+});

package/dist/cjs/common/errors.js

@@ -1,6 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CredentialsError = void 0;
 exports.handleDynamicImportError = handleDynamicImportError;
+/**
+ * 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".
+ */
+class CredentialsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CredentialsError";
+    }
+}
+exports.CredentialsError = CredentialsError;
 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/cjs/common/h2fetch.js

@@ -17,14 +17,21 @@ const sessionsWithListenerBudget = new WeakSet();
  * When `settings.maxConcurrentH2Requests` is `0`/unset the gate is a no-op
  * (current default behavior: unlimited concurrency).
  */
-// Safety timeout for a held slot. A request that never resolves (no response,
-// no error, no abort) would otherwise hold its slot forever and starve every
-// queued request for the same domain. After this window we release the slot
-// and let the underlying request continue or reject on its own; we never
-// cancel the in-flight request here, we only stop it from blocking the queue.
-// Kept deliberately conservative (well above any realistic part-upload time)
-// so it does not interfere with legitimately slow but healthy requests.
-const H2_SLOT_TIMEOUT_MS = 120_000;
+// Last-resort leak guard for a held slot. The slot is now released on the real
+// stream terminal (end / error / abort / cancel / pre-response reject), which
+// always fires, so this timer is a pure backstop for the one residual case: a
+// request that never opens a stream AND never settles (no response, no error,
+// no abort) — it must not pin a slot forever and starve the per-domain queue.
+//
+// When it fires it ONLY frees the queue slot. It NEVER aborts or cancels the
+// underlying request or its response stream: `release` does not touch `req` or
+// the body stream, so a long-lived streaming response keeps flowing. Raised
+// well beyond any legitimate stream lifetime so it cannot interfere with a
+// healthy long-open stream (process.streamLogs / execWithStreaming / port
+// proxy). RESIDUAL: a stream that outlives this backstop would have its slot
+// freed early (the queue could then admit one extra stream); acceptable as a
+// pure backstop, since the slot is otherwise tied to the true stream terminal.
+const H2_SLOT_TIMEOUT_MS = 1_800_000; // 30 minutes
 const h2GatesByDomain = new Map();
 function getH2Gate(domain) {
     let gate = h2GatesByDomain.get(domain);
@@ -35,10 +42,14 @@ function getH2Gate(domain) {
     return gate;
 }
 /**
- * Acquire an in-flight slot for `domain`. Resolves with a release function
- * that is idempotent and FIFO-fair: releasing wakes the longest-waiting
- * queued caller for the same domain. A safety timer also releases the slot
- * if the caller never does, preventing per-domain starvation.
+ * Acquire an OPEN-STREAM slot for `domain`. Resolves with a release function
+ * that is idempotent and FIFO-fair: releasing wakes the longest-waiting queued
+ * caller for the same domain. The slot is held for the lifetime of an OPEN H2
+ * stream — the send path releases it on the stream terminal — so the gate
+ * bounds true concurrent streams on the one shared session, not merely requests
+ * awaiting headers (ENG-2678). A backstop timer releases the slot if a request
+ * neither opens a stream nor ever settles, preventing per-domain starvation;
+ * it never aborts the underlying request (see `H2_SLOT_TIMEOUT_MS`).
  */
 async function acquireH2Slot(domain) {
     const max = settings_js_1.settings.maxConcurrentH2Requests; // 0/undefined = unlimited
@@ -92,66 +103,89 @@ function createH2Fetch(session) {
     };
 }
 /**
- * Creates a fetch()-compatible function backed by the H2 session pool.
+ * The single HTTP/2 request gateway (ENG-2679).
  *
- * The pool validates idle sessions before reuse. If no usable H2 session is
- * available, the request falls back to regular fetch before any H2 frames
- * are sent.
+ * Every pool-backed request funnels through here, no matter which entry point
+ * it came from: the generated client's fetch (`createPoolBackedH2Fetch`),
+ * `SandboxAction.h2Fetch`, and the interpreter's direct path (both via
+ * `h2RequestDirectFromPool`). It owns the shared request lifecycle in one place:
+ *   1. take a per-domain open-stream slot,
+ *   2. get a live session from the pool,
+ *   3. send the request on it,
+ *   4. evict the session if the send fails after a stream was opened,
+ *   5. fall back to globalThis.fetch when the pool has no usable session.
+ *
+ * This is the chokepoint where reliability behavior that must protect EVERY
+ * consumer belongs: the open-stream concurrency limit today, and retry,
+ * timeouts, typed errors, and observability in later phases. Adding it once here
+ * (instead of re-implementing it per entry point) is what stops the recurring
+ * "fixed on one path, still broken on another" regressions.
+ *
+ * `send` performs the actual wire send on a live session; the caller supplies it
+ * so the gateway stays agnostic to the `Request` vs `(url, init)` call shapes,
+ * and it receives the slot-release and request-created hooks. `fallback` runs
+ * only when the pool has no usable session (a fresh connection, no shared
+ * stream is opened).
  */
-function createPoolBackedH2Fetch(pool, domain) {
-    return async (input) => {
-        const rel = await acquireH2Slot(domain);
-        try {
-            const session = await pool.get(domain);
-            if (session) {
-                let h2RequestCreated = false;
-                try {
-                    return await _h2Request(session, input, {
-                        onH2RequestCreated: () => {
-                            h2RequestCreated = true;
-                        },
-                    });
-                }
-                catch (err) {
-                    if (h2RequestCreated) {
-                        pool.evictSession(domain, session);
-                    }
-                    throw err;
-                }
-            }
-            return await globalThis.fetch(input);
-        }
-        finally {
-            rel();
-        }
-    };
-}
-async function h2RequestDirectFromPool(pool, domain, url, init) {
+async function h2GatewayRequest(pool, domain, send, fallback) {
+    // Take the slot here, but hand its release to the send path: it is held for
+    // the OPEN-STREAM lifetime and freed on the stream terminal (ENG-2678). A
+    // request that never opens a stream on the shared session (the fallback goes
+    // over a different connection) releases it immediately so it does not count
+    // against the open-stream budget. `rel` is idempotent, so releasing here when
+    // the send path may also release is safe.
     const rel = await acquireH2Slot(domain);
     try {
         const session = await pool.get(domain);
         if (session) {
             let h2RequestCreated = false;
             try {
-                return await h2RequestDirectInternal(session, url, init, {
+                return await send(session, {
                     onH2RequestCreated: () => {
                         h2RequestCreated = true;
                     },
+                    releaseSlot: rel,
                 });
             }
             catch (err) {
+                // A failure AFTER a stream opened means the session is suspect: drop it
+                // so the next caller gets a fresh one.
                 if (h2RequestCreated) {
                     pool.evictSession(domain, session);
                 }
                 throw err;
             }
         }
-        return await globalThis.fetch(url, init);
+        // No usable session: free the slot before falling back over a different
+        // connection (no stream opens on the shared session).
+        rel();
+        return await fallback();
     }
-    finally {
+    catch (err) {
+        // Pre-send throw (pool.get(), Request body read, or the fallback itself):
+        // release the slot so a failed request never pins it. Idempotent.
         rel();
+        throw err;
     }
 }
+/**
+ * Creates a fetch()-compatible function backed by the H2 session pool, routed
+ * through the single gateway. Used as the generated client's `fetch`.
+ *
+ * If no usable H2 session is available, the request falls back to regular fetch
+ * before any H2 frames are sent.
+ */
+function createPoolBackedH2Fetch(pool, domain) {
+    return (input) => h2GatewayRequest(pool, domain, (session, options) => _h2Request(session, input, options), () => globalThis.fetch(input));
+}
+/**
+ * Pool-backed H2 request taking raw url + init (skips Request allocation),
+ * routed through the same single gateway. Used by `SandboxAction.h2Fetch` and
+ * the code interpreter.
+ */
+function h2RequestDirectFromPool(pool, domain, url, init) {
+    return h2GatewayRequest(pool, domain, (session, options) => h2RequestDirectInternal(session, url, init, options), () => globalThis.fetch(url, init));
+}
 /**
  * Low-level H2 request that takes raw URL + init, skipping Request construction.
  * Used by SandboxAction.h2Fetch() for direct calls from subsystems.
@@ -161,6 +195,9 @@ function h2RequestDirect(session, url, init) {
 }
 function h2RequestDirectInternal(session, url, init, options) {
     if (session.closed || session.destroyed) {
+        // Pre-flight fallback (session unusable): no stream opens on the shared
+        // session, so free any held slot before going over globalThis.fetch.
+        options?.releaseSlot?.();
         return globalThis.fetch(url, init);
     }
     const parsed = new URL(url);
@@ -200,7 +237,9 @@ function h2RequestDirectInternal(session, url, init, options) {
         else {
             // FormData, ReadableStream, Blob, etc. can't be serialized to Buffer
             // for manual H2 framing — fall back to regular fetch (pre-flight,
-            // nothing has been sent on the wire yet).
+            // nothing has been sent on the wire yet). No stream opens on the shared
+            // session, so free any held slot before falling back.
+            options?.releaseSlot?.();
             return globalThis.fetch(url, init);
         }
         if (!h2Headers["content-length"]) {
@@ -244,13 +283,19 @@ function _h2Send(session, h2Headers, body, signal, fallbackUrl, fallbackInit, op
         let streamClosed = false;
         let req = null;
         let releaseSessionRef = () => { };
+        // The per-domain open-stream slot (idempotent; no-op for the non-pool
+        // transports). Held for the OPEN-STREAM lifetime and released alongside the
+        // session ref from cleanupActiveRequest() on every terminal path.
+        const releaseSlot = options?.releaseSlot ?? (() => { });
         let abort = null;
         try {
             req = session.request(h2Headers);
         }
         catch {
             // Pre-flight fallback: session.request() threw synchronously, so no
-            // H2 frames were sent. Safe to retry over globalThis.fetch.
+            // H2 frames were sent. No stream opened on the shared session, so free
+            // the slot before retrying over globalThis.fetch.
+            releaseSlot();
             globalThis.fetch(fallbackUrl, fallbackInit).then(resolve, reject);
             return;
         }
@@ -265,7 +310,13 @@ function _h2Send(session, h2Headers, body, signal, fallbackUrl, fallbackInit, op
         const cleanupActiveRequest = () => {
             if (abort)
                 signal?.removeEventListener("abort", abort);
+            // Slot and session-ref share the OPEN-STREAM lifetime but stay
+            // independent and each idempotent (PM-2160). Every terminal path funnels
+            // through here exactly once: pre-response reject (close/goaway/error),
+            // abort-before-response, abort-during-stream, stream end, stream error,
+            // and ReadableStream cancel — so the slot is freed once on each.
             releaseSessionRef();
+            releaseSlot();
         };
         const rejectBeforeResponse = (err) => {
             if (settled)

package/dist/cjs/common/h2pool.js

@@ -153,6 +153,15 @@ class H2Pool {
             return session;
         }
         if (await this.ping(session)) {
+            // ENG-2676 generation/identity pin: `await this.ping` yields, and during
+            // that await an eviction listener (goaway/error/close ->
+            // attachEvictionListeners, see above) may have deleted or replaced this
+            // entry. `entry` is the exact object held in the map, so if it is no
+            // longer the cached generation, refuse the now-stale session instead of
+            // handing back a zombie — the ENG-2422 failure re-entering through the
+            // validate race. The caller falls through to establish a fresh session.
+            if (this.sessions.get(domain) !== entry)
+                return null;
             this.markUsed(domain, session);
             return session;
         }

package/dist/cjs/common/pagination.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unwrapListData = unwrapListData;
+exports.createPaginatedList = createPaginatedList;
+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 };
+}
+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;
+}