@blaxel/core 0.2.87-preview.169 → 0.2.87-preview.171

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/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

@@ -103,64 +103,44 @@ 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) => {
-        // Acquire 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. Paths that
-        // never open a stream on the shared session (fetch fallbacks go over a
-        // different connection) release it immediately so they do not count against
-        // the open-stream budget. `rel` is idempotent, so the explicit releases
-        // below are safe even though the send path may also release.
-        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;
-                        },
-                        releaseSlot: rel,
-                    });
-                }
-                catch (err) {
-                    if (h2RequestCreated) {
-                        pool.evictSession(domain, session);
-                    }
-                    throw err;
-                }
-            }
-            // No usable session: this fetch does not open a stream on the shared
-            // session, so free the slot before falling back.
-            rel();
-            return await globalThis.fetch(input);
-        }
-        catch (err) {
-            // Pre-send throw (e.g. pool.get() or Request body read): release the slot
-            // so a failed request never pins it. Idempotent if already released.
-            rel();
-            throw err;
-        }
-    };
-}
-async function h2RequestDirectFromPool(pool, domain, url, init) {
-    // See createPoolBackedH2Fetch: the slot is held for the OPEN-STREAM lifetime
-    // and released by the send path on the stream terminal; non-stream fallbacks
-    // release it immediately. `rel` is idempotent.
+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;
                     },
@@ -168,21 +148,44 @@ async function h2RequestDirectFromPool(pool, domain, url, init) {
                 });
             }
             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;
             }
         }
-        // No usable session: fetch over a different connection, no stream opened.
+        // No usable session: free the slot before falling back over a different
+        // connection (no stream opens on the shared session).
         rel();
-        return await globalThis.fetch(url, init);
+        return await fallback();
     }
     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.

package/dist/cjs/common/settings.js

@@ -7,12 +7,29 @@ exports.settings = void 0;
 const yaml_1 = __importDefault(require("yaml"));
 const apikey_js_1 = require("../authentication/apikey.js");
 const clientcredentials_js_1 = require("../authentication/clientcredentials.js");
+const credentials_js_1 = require("../authentication/credentials.js");
 const index_js_1 = require("../authentication/index.js");
 const env_js_1 = require("../common/env.js");
+const errors_js_1 = require("../common/errors.js");
 const node_js_1 = require("../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_js_1.env.BL_WORKSPACE;
+    const hasApiKey = !!env_js_1.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.87-preview.169";
-const BUILD_COMMIT = "5357b12d98548db2b306537be7d96d2888ac8cb1";
+const BUILD_VERSION = "0.2.87-preview.171";
+const BUILD_COMMIT = "06530fbea3b8ff89d51d0b834de6725ad5ad80ee";
 const BUILD_SENTRY_DSN = "https://fd5e60e1c9820e1eef5ccebb84a07127@o4508714045276160.ingest.us.sentry.io/4510465864564736";
 const BLAXEL_API_VERSION = "2026-04-16";
 // Cache for config.yaml tracking value
@@ -173,6 +190,7 @@ class Settings {
         return env_js_1.env.BL_API_VERSION || BLAXEL_API_VERSION;
     }
     get headers() {
+        this.assertCredentials();
         const osArch = getOsArch();
         return {
             "x-blaxel-authorization": this.authorization,
@@ -258,7 +276,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 credentials_js_1.MissingCredentials) {
+            throw new errors_js_1.CredentialsError(missingCredentialsMessage());
+        }
+        if (!this.workspace) {
+            throw new errors_js_1.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/cjs/common/settings.test.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 const vitest_1 = require("vitest");
+const apikey_js_1 = require("../authentication/apikey.js");
 const env_js_1 = require("./env.js");
 (0, vitest_1.describe)('Settings.apiVersion', () => {
     (0, vitest_1.beforeEach)(() => {
@@ -50,6 +51,14 @@ const env_js_1 = require("./env.js");
     (0, vitest_1.it)('headers include Blaxel-Version set to the default', async () => {
         delete env_js_1.env.BL_API_VERSION;
         const { settings } = await Promise.resolve().then(() => __importStar(require('./settings.js')));
-        (0, vitest_1.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_js_1.ApiKey({ apiKey: 'test-key', workspace: 'test-ws' });
+        try {
+            (0, vitest_1.expect)(settings.headers['Blaxel-Version']).toBe('2026-04-16');
+        }
+        finally {
+            settings.credentials = previous;
+        }
     });
 });

package/dist/cjs/types/authentication/credentials.d.ts

@@ -4,3 +4,12 @@ export declare class Credentials {
     get authorization(): string;
     get token(): string;
 }
+/**
+ * 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 declare class MissingCredentials extends Credentials {
+}

package/dist/cjs/types/common/credentials.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cjs/types/common/errors.d.ts

@@ -1 +1,11 @@
+/**
+ * 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 declare class CredentialsError extends Error {
+    constructor(message: string);
+}
 export declare function handleDynamicImportError(err: any): void;

package/dist/cjs/types/common/h2fetch.d.ts

@@ -10,13 +10,18 @@ import type { H2Pool } from "./h2pool.js";
  */
 export declare function createH2Fetch(session: http2.ClientHttp2Session): (input: Request) => Promise<Response>;
 /**
- * Creates a fetch()-compatible function backed by the H2 session pool.
+ * Creates a fetch()-compatible function backed by the H2 session pool, routed
+ * through the single gateway. Used as the generated client's `fetch`.
  *
- * 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.
+ * If no usable H2 session is available, the request falls back to regular fetch
+ * before any H2 frames are sent.
  */
 export declare function createPoolBackedH2Fetch(pool: H2Pool, domain: string): (input: Request) => Promise<Response>;
+/**
+ * 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.
+ */
 export declare function h2RequestDirectFromPool(pool: H2Pool, domain: string, url: string, init?: RequestInit): Promise<Response>;
 /**
  * Low-level H2 request that takes raw URL + init, skipping Request construction.

package/dist/cjs/types/common/settings.d.ts

@@ -63,6 +63,15 @@ declare class Settings {
     get disableH2(): boolean;
     get maxConcurrentH2Requests(): number;
     get fsPartRetries(): number;
+    /**
+     * 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.
+     */
+    private assertCredentials;
     authenticate(): Promise<void>;
 }
 export declare const settings: Settings;