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

package/dist/esm/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/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/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/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/common/h2fetch.js

@@ -97,64 +97,44 @@ export 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).
  */
-export 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;
-        }
-    };
-}
-export 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;
                     },
@@ -162,21 +142,44 @@ export 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.
+ */
+export 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.
+ */
+export 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/esm/common/settings.js

@@ -1,12 +1,29 @@
 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.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
@@ -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/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(() => {
@@ -15,6 +16,14 @@ describe('Settings.apiVersion', () => {
     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-16');
+        }
+        finally {
+            settings.credentials = previous;
+        }
     });
 });