@blaxel/core 0.2.82-preview.146 → 0.2.82

package/dist/cjs/common/h2fetch.js

@@ -2,7 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createH2Fetch = createH2Fetch;
 exports.createPoolBackedH2Fetch = createPoolBackedH2Fetch;
+exports.h2RequestDirectFromPool = h2RequestDirectFromPool;
 exports.h2RequestDirect = h2RequestDirect;
+const MIN_H2_SESSION_MAX_LISTENERS = 64;
+const sessionsWithListenerBudget = new WeakSet();
 /**
  * Creates a fetch()-compatible function that sends requests over an existing
  * HTTP/2 session. Falls back to globalThis.fetch() only when the session is
@@ -22,25 +25,60 @@ function createH2Fetch(session) {
 /**
  * Creates a fetch()-compatible function backed by the H2 session pool.
  *
- * Non-blocking: checks the pool cache synchronously. If a warm session is
- * available it's used immediately; otherwise the request goes through
- * regular fetch with zero delay (the pool keeps warming in the background
- * so subsequent calls get H2).
+ * 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.
  */
 function createPoolBackedH2Fetch(pool, domain) {
-    return (input) => {
-        const session = pool.tryGet(domain);
+    return async (input) => {
+        const session = await pool.get(domain);
         if (session) {
-            return _h2Request(session, input);
+            let h2RequestCreated = false;
+            try {
+                return await _h2Request(session, input, {
+                    onH2RequestCreated: () => {
+                        h2RequestCreated = true;
+                    },
+                });
+            }
+            catch (err) {
+                if (h2RequestCreated) {
+                    pool.evictSession(domain, session);
+                }
+                throw err;
+            }
         }
         return globalThis.fetch(input);
     };
 }
+async function h2RequestDirectFromPool(pool, domain, url, init) {
+    const session = await pool.get(domain);
+    if (session) {
+        let h2RequestCreated = false;
+        try {
+            return await h2RequestDirectInternal(session, url, init, {
+                onH2RequestCreated: () => {
+                    h2RequestCreated = true;
+                },
+            });
+        }
+        catch (err) {
+            if (h2RequestCreated) {
+                pool.evictSession(domain, session);
+            }
+            throw err;
+        }
+    }
+    return 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.
  */
 function h2RequestDirect(session, url, init) {
+    return h2RequestDirectInternal(session, url, init);
+}
+function h2RequestDirectInternal(session, url, init, options) {
     if (session.closed || session.destroyed) {
         return globalThis.fetch(url, init);
     }
@@ -88,9 +126,9 @@ function h2RequestDirect(session, url, init) {
             h2Headers["content-length"] = body.byteLength;
         }
     }
-    return _h2Send(session, h2Headers, body, init?.signal ?? null, url, init);
+    return _h2Send(session, h2Headers, body, init?.signal ?? null, url, init, options);
 }
-async function _h2Request(session, input) {
+async function _h2Request(session, input, options) {
     const url = new URL(input.url);
     const method = input.method || "GET";
     const h2Headers = {
@@ -115,15 +153,15 @@ async function _h2Request(session, input) {
         headers: input.headers,
         body,
         signal: input.signal,
-    });
+    }, options);
 }
-function _h2Send(session, h2Headers, body, signal, fallbackUrl, fallbackInit) {
+function _h2Send(session, h2Headers, body, signal, fallbackUrl, fallbackInit, options) {
     return new Promise((resolve, reject) => {
         let settled = false;
         let responded = false;
         let streamController = null;
         let streamClosed = false;
-        let req;
+        let req = null;
         try {
             req = session.request(h2Headers);
         }
@@ -133,12 +171,40 @@ function _h2Send(session, h2Headers, body, signal, fallbackUrl, fallbackInit) {
             globalThis.fetch(fallbackUrl, fallbackInit).then(resolve, reject);
             return;
         }
+        options?.onH2RequestCreated?.();
+        ensureH2SessionListenerBudget(session);
+        const cleanupBeforeResponseListeners = () => {
+            session.off("close", onSessionClose);
+            session.off("goaway", onSessionGoaway);
+            session.off("error", onSessionError);
+        };
+        const rejectBeforeResponse = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanupBeforeResponseListeners();
+            req?.close();
+            reject(err);
+        };
+        const onSessionClose = () => {
+            rejectBeforeResponse(new Error("HTTP/2 session closed before response"));
+        };
+        const onSessionGoaway = () => {
+            rejectBeforeResponse(new Error("HTTP/2 session sent GOAWAY before response"));
+        };
+        const onSessionError = (err) => {
+            rejectBeforeResponse(err);
+        };
+        session.once("close", onSessionClose);
+        session.once("goaway", onSessionGoaway);
+        session.once("error", onSessionError);
         const abort = () => {
-            req.close();
+            req?.close();
             const abortError = new DOMException("The operation was aborted.", "AbortError");
             if (!responded) {
                 if (!settled) {
                     settled = true;
+                    cleanupBeforeResponseListeners();
                     reject(abortError);
                 }
                 return;
@@ -151,6 +217,7 @@ function _h2Send(session, h2Headers, body, signal, fallbackUrl, fallbackInit) {
         if (signal) {
             if (signal.aborted) {
                 req.close();
+                cleanupBeforeResponseListeners();
                 settled = true;
                 reject(new DOMException("The operation was aborted.", "AbortError"));
                 return;
@@ -162,6 +229,7 @@ function _h2Send(session, h2Headers, body, signal, fallbackUrl, fallbackInit) {
                 return;
             settled = true;
             responded = true;
+            cleanupBeforeResponseListeners();
             const status = headers[":status"] ?? 200;
             const resHeaders = new Headers();
             for (const [k, v] of Object.entries(headers)) {
@@ -181,12 +249,14 @@ function _h2Send(session, h2Headers, body, signal, fallbackUrl, fallbackInit) {
                     req.on("end", () => {
                         if (!streamClosed) {
                             streamClosed = true;
+                            signal?.removeEventListener("abort", abort);
                             controller.close();
                         }
                     });
                     req.on("error", (err) => {
                         if (!streamClosed) {
                             streamClosed = true;
+                            signal?.removeEventListener("abort", abort);
                             controller.error(err);
                         }
                     });
@@ -198,6 +268,7 @@ function _h2Send(session, h2Headers, body, signal, fallbackUrl, fallbackInit) {
             if (settled)
                 return;
             settled = true;
+            cleanupBeforeResponseListeners();
             reject(err);
         });
         if (body) {
@@ -208,3 +279,12 @@ function _h2Send(session, h2Headers, body, signal, fallbackUrl, fallbackInit) {
         }
     });
 }
+function ensureH2SessionListenerBudget(session) {
+    if (sessionsWithListenerBudget.has(session))
+        return;
+    sessionsWithListenerBudget.add(session);
+    const currentMax = session.getMaxListeners();
+    if (currentMax > 0 && currentMax < MIN_H2_SESSION_MAX_LISTENERS) {
+        session.setMaxListeners(MIN_H2_SESSION_MAX_LISTENERS);
+    }
+}

package/dist/cjs/common/h2pool.js

@@ -34,6 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.h2Pool = exports.H2Pool = void 0;
+const DEFAULT_MAX_IDLE_MS = 5_000;
+const DEFAULT_PING_TIMEOUT_MS = 500;
 /**
  * Singleton H2 session pool keyed by edge domain.
  *
@@ -46,6 +48,14 @@ class H2Pool {
     sessions = new Map();
     inflight = new Map();
     _establish = null;
+    maxIdleMs;
+    pingTimeoutMs;
+    now;
+    constructor(options = {}) {
+        this.maxIdleMs = options.maxIdleMs ?? DEFAULT_MAX_IDLE_MS;
+        this.pingTimeoutMs = options.pingTimeoutMs ?? DEFAULT_PING_TIMEOUT_MS;
+        this.now = options.now ?? Date.now;
+    }
     /**
      * Lazily resolve the establish function so the http2 / tls / dns modules
      * are only imported in Node.js environments.
@@ -68,7 +78,7 @@ class H2Pool {
         const evict = () => {
             // Only evict if this specific session is still the cached one.
             // A newer session may have taken its place after reconnect.
-            if (this.sessions.get(domain) === session) {
+            if (this.sessions.get(domain)?.session === session) {
                 this.sessions.delete(domain);
             }
         };
@@ -76,19 +86,92 @@ class H2Pool {
         session.on("error", evict);
         session.on("close", evict);
     }
+    isClosed(session) {
+        return session.closed || session.destroyed;
+    }
+    isIdle(entry) {
+        return this.now() - entry.lastUsedAt > this.maxIdleMs;
+    }
+    cache(domain, session) {
+        this.sessions.set(domain, {
+            session,
+            lastUsedAt: this.now(),
+        });
+    }
+    markUsed(domain, session) {
+        const entry = this.sessions.get(domain);
+        if (entry?.session === session) {
+            entry.lastUsedAt = this.now();
+        }
+    }
+    evict(domain, session) {
+        const entry = this.sessions.get(domain);
+        if (!entry)
+            return;
+        if (session && entry.session !== session)
+            return;
+        this.sessions.delete(domain);
+        if (!entry.session.closed && !entry.session.destroyed) {
+            entry.session.close();
+        }
+    }
+    ping(session) {
+        if (this.isClosed(session))
+            return Promise.resolve(false);
+        return new Promise((resolve) => {
+            let settled = false;
+            const finish = (ok) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve(ok);
+            };
+            const timer = setTimeout(() => finish(false), this.pingTimeoutMs);
+            try {
+                const sent = session.ping((err) => {
+                    finish(!err && !this.isClosed(session));
+                });
+                if (!sent)
+                    finish(false);
+            }
+            catch {
+                finish(false);
+            }
+        });
+    }
+    async validateEntry(domain, entry) {
+        if (!entry)
+            return null;
+        const { session } = entry;
+        if (this.isClosed(session)) {
+            this.evict(domain, session);
+            return null;
+        }
+        if (!this.isIdle(entry)) {
+            this.markUsed(domain, session);
+            return session;
+        }
+        if (await this.ping(session)) {
+            this.markUsed(domain, session);
+            return session;
+        }
+        this.evict(domain, session);
+        return null;
+    }
     /**
      * Fire-and-forget background warming. Safe to call multiple times for
      * the same domain — only one connection attempt per domain at a time.
      */
     warm(domain) {
-        const existing = this.sessions.get(domain);
-        if (existing && !existing.closed && !existing.destroyed)
+        const existing = this.tryGet(domain);
+        if (existing)
             return;
         if (this.inflight.has(domain))
             return;
         const p = this.establish(domain)
             .then((session) => {
-            this.sessions.set(domain, session);
+            this.cache(domain, session);
             return session;
         })
             .catch(() => null)
@@ -103,25 +186,37 @@ class H2Pool {
      */
     tryGet(domain) {
         const cached = this.sessions.get(domain);
-        if (cached && !cached.closed && !cached.destroyed)
-            return cached;
-        this.sessions.delete(domain);
-        return null;
+        if (!cached)
+            return null;
+        if (this.isClosed(cached.session) || this.isIdle(cached)) {
+            this.evict(domain, cached.session);
+            return null;
+        }
+        this.markUsed(domain, cached.session);
+        return cached.session;
+    }
+    isUsable(session) {
+        return !this.isClosed(session);
+    }
+    evictSession(domain, session) {
+        this.evict(domain, session);
     }
     /**
      * Get a live H2 session for `domain`. Returns immediately from cache,
      * joins an in-flight warming, or starts a new one.
      */
     async get(domain) {
-        const fast = this.tryGet(domain);
+        const fast = await this.validateEntry(domain, this.sessions.get(domain));
         if (fast)
             return fast;
         // Join in-flight warming if one exists
         const pending = this.inflight.get(domain);
         if (pending) {
             const session = await pending;
-            if (session && !session.closed && !session.destroyed)
+            if (session && this.isUsable(session)) {
+                this.markUsed(domain, session);
                 return session;
+            }
         }
         // Start fresh, deduplicating concurrent callers via inflight
         // Re-check: another caller may have started a fresh one while we awaited
@@ -133,7 +228,7 @@ class H2Pool {
             return freshCached;
         const p = this.establish(domain)
             .then((session) => {
-            this.sessions.set(domain, session);
+            this.cache(domain, session);
             return session;
         })
             .catch(() => null)
@@ -145,9 +240,9 @@ class H2Pool {
     }
     /** Close all sessions (for cleanup). */
     closeAll() {
-        for (const [, session] of this.sessions) {
-            if (!session.closed && !session.destroyed)
-                session.close();
+        for (const [, entry] of this.sessions) {
+            if (!entry.session.closed && !entry.session.destroyed)
+                entry.session.close();
         }
         this.sessions.clear();
         this.inflight.clear();

package/dist/cjs/common/lazyInit.js

@@ -77,7 +77,7 @@ function ensureAutoloaded() {
     const isNode = typeof process !== "undefined" && process.versions != null && process.versions.node != null;
     /* eslint-disable */
     const isBrowser = typeof globalThis !== "undefined" && globalThis?.window !== undefined;
-    if (isNode && !isBrowser) {
+    if (isNode && !isBrowser && !settings_js_1.settings.disableH2) {
         try {
             // Pre-warm edge H2 for the configured region so the first
             // SandboxInstance.create() gets an instant session via the pool.

package/dist/cjs/common/settings.js

@@ -11,8 +11,8 @@ const index_js_1 = require("../authentication/index.js");
 const env_js_1 = require("../common/env.js");
 const node_js_1 = require("../common/node.js");
 // Build info - these placeholders are replaced at build time by build:replace-imports
-const BUILD_VERSION = "0.2.82-preview.146";
-const BUILD_COMMIT = "bd1f2f080c52d701b0dcbcccd73d139be5740ef2";
+const BUILD_VERSION = "0.2.82";
+const BUILD_COMMIT = "4d2b3531bdb9d8a065f6d83822343840ae0b8d65";
 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
@@ -218,6 +218,15 @@ class Settings {
     get region() {
         return env_js_1.env.BL_REGION || undefined;
     }
+    get disableH2() {
+        if (typeof this.config.disableH2 === "boolean") {
+            return this.config.disableH2;
+        }
+        const value = env_js_1.env.BL_DISABLE_H2;
+        if (!value)
+            return false;
+        return ["1", "true", "yes", "on"].includes(value.toLowerCase());
+    }
     async authenticate() {
         await this.credentials.authenticate();
     }

package/dist/cjs/sandbox/action.js

@@ -5,6 +5,7 @@ const client_fetch_1 = require("@hey-api/client-fetch");
 const interceptors_js_1 = require("../client/interceptors.js");
 const responseInterceptor_js_1 = require("../client/responseInterceptor.js");
 const h2fetch_js_1 = require("../common/h2fetch.js");
+const h2pool_js_1 = require("../common/h2pool.js");
 const internal_js_1 = require("../common/internal.js");
 const settings_js_1 = require("../common/settings.js");
 const client_gen_js_1 = require("./client/client.gen.js");
@@ -36,6 +37,7 @@ exports.ResponseError = ResponseError;
 class SandboxAction {
     sandbox;
     _h2Client = null;
+    _h2ClientDomain = null;
     constructor(sandbox) {
         this.sandbox = sandbox;
     }
@@ -62,12 +64,13 @@ class SandboxAction {
                 headers: this.sandbox.headers,
             });
         }
-        const session = this.sandbox.h2Session;
-        if (session && !session.closed && !session.destroyed) {
-            if (!this._h2Client) {
+        const h2Domain = this.sandbox.h2Domain;
+        if (h2Domain) {
+            if (!this._h2Client || this._h2ClientDomain !== h2Domain) {
                 this._h2Client = (0, client_fetch_1.createClient)({
-                    fetch: (0, h2fetch_js_1.createH2Fetch)(session),
+                    fetch: (0, h2fetch_js_1.createPoolBackedH2Fetch)(h2pool_js_1.h2Pool, h2Domain),
                 });
+                this._h2ClientDomain = h2Domain;
                 for (const interceptor of interceptors_js_1.interceptors) {
                     // @ts-expect-error - Interceptor is not typed
                     this._h2Client.interceptors.request.use(interceptor);
@@ -78,8 +81,9 @@ class SandboxAction {
             }
             return this._h2Client;
         }
-        // Invalidate cached H2 client when session is no longer usable
+        // Invalidate cached H2 client when the sandbox no longer has an H2 domain.
         this._h2Client = null;
+        this._h2ClientDomain = null;
         return client_gen_js_1.client;
     }
     /**
@@ -87,9 +91,9 @@ class SandboxAction {
      * globalThis.fetch. Uses a direct H2 path that avoids Request allocation.
      */
     h2Fetch(input, init) {
-        const session = this.sandbox.h2Session;
-        if (session && !session.closed && !session.destroyed) {
-            return (0, h2fetch_js_1.h2RequestDirect)(session, input.toString(), init);
+        const h2Domain = this.sandbox.h2Domain;
+        if (h2Domain) {
+            return (0, h2fetch_js_1.h2RequestDirectFromPool)(h2pool_js_1.h2Pool, h2Domain, input.toString(), init);
         }
         return globalThis.fetch(input, init);
     }

package/dist/cjs/sandbox/interpreter.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CodeInterpreter = void 0;
 const h2fetch_js_1 = require("../common/h2fetch.js");
+const h2pool_js_1 = require("../common/h2pool.js");
 const logger_js_1 = require("../common/logger.js");
 const settings_js_1 = require("../common/settings.js");
 const sandbox_js_1 = require("./sandbox.js");
@@ -28,6 +29,7 @@ class CodeInterpreter extends sandbox_js_1.SandboxInstance {
             status: base.status,
             events: base.events,
             h2Session: base.h2Session,
+            h2Domain: base.h2Domain,
         };
         return new CodeInterpreter(config);
     }
@@ -72,6 +74,7 @@ class CodeInterpreter extends sandbox_js_1.SandboxInstance {
             status: baseInstance.status,
             events: baseInstance.events,
             h2Session: baseInstance.h2Session,
+            h2Domain: baseInstance.h2Domain,
         };
         // Preserve forceUrl, headers, and params from input if provided
         if (sandbox && typeof sandbox === "object" && !Array.isArray(sandbox)) {
@@ -94,9 +97,9 @@ class CodeInterpreter extends sandbox_js_1.SandboxInstance {
         return this.process.url;
     }
     _fetch(input, init) {
-        const session = this._sandboxConfig.h2Session;
-        if (session && !session.closed && !session.destroyed) {
-            return (0, h2fetch_js_1.h2RequestDirect)(session, input.toString(), init);
+        const h2Domain = this._sandboxConfig.h2Domain;
+        if (h2Domain) {
+            return (0, h2fetch_js_1.h2RequestDirectFromPool)(h2pool_js_1.h2Pool, h2Domain, input.toString(), init);
         }
         return globalThis.fetch(input, init);
     }

package/dist/cjs/sandbox/sandbox.js

@@ -57,7 +57,6 @@ class SandboxInstance {
     codegen;
     system;
     drives;
-    /* eslint-disable @typescript-eslint/no-explicit-any */
     h2Session;
     constructor(sandbox) {
         this.sandbox = sandbox;
@@ -86,27 +85,35 @@ class SandboxInstance {
     get lastUsedAt() {
         return this.sandbox.lastUsedAt;
     }
+    get h2Domain() {
+        return this.sandbox.h2Domain ?? null;
+    }
     /**
      * Warm and attach an H2 session based on the sandbox's region.
      * Shared by create(), get(), list(), and update helpers.
      */
     static async attachH2Session(instance) {
-        const region = instance.spec?.region;
-        if (!region)
+        const edgeDomain = SandboxInstance.edgeDomainForRegion(instance.spec?.region);
+        if (!edgeDomain || settings_js_1.settings.disableH2)
             return instance;
-        const edgeSuffix = settings_js_1.settings.env === "prod" ? "bl.run" : "runv2.blaxel.dev";
-        const edgeDomain = `any.${region}.${edgeSuffix}`;
         try {
             const { h2Pool } = await Promise.resolve().then(() => __importStar(require("../common/h2pool.js")));
             const h2Session = await h2Pool.get(edgeDomain);
             instance.h2Session = h2Session;
             instance.sandbox.h2Session = h2Session;
+            instance.sandbox.h2Domain = edgeDomain;
         }
         catch {
             // H2 warming is best-effort; fall back to regular fetch
         }
         return instance;
     }
+    static edgeDomainForRegion(region) {
+        if (!region)
+            return null;
+        const edgeSuffix = settings_js_1.settings.env === "prod" ? "bl.run" : "runv2.blaxel.dev";
+        return `any.${region}.${edgeSuffix}`;
+    }
     get expiresIn() {
         return this.sandbox.expiresIn;
     }
@@ -201,10 +208,9 @@ class SandboxInstance {
         }
         sandbox.spec.runtime.image = sandbox.spec.runtime.image || defaultImage;
         sandbox.spec.runtime.memory = sandbox.spec.runtime.memory || defaultMemory;
-        const edgeSuffix = settings_js_1.settings.env === "prod" ? "bl.run" : "runv2.blaxel.dev";
-        const edgeDomain = sandbox.spec?.region ? `any.${sandbox.spec.region}.${edgeSuffix}` : null;
+        const edgeDomain = SandboxInstance.edgeDomainForRegion(sandbox.spec?.region);
         // Kick off warming so h2Pool.get() can join it during the API call
-        if (edgeDomain) {
+        if (edgeDomain && !settings_js_1.settings.disableH2) {
             Promise.resolve().then(() => __importStar(require("../common/h2pool.js"))).then(({ h2Pool }) => h2Pool.warm(edgeDomain)).catch(() => { });
         }
         const [{ data }, h2Session] = await Promise.all([
@@ -212,10 +218,10 @@ class SandboxInstance {
                 body: sandbox,
                 throwOnError: true,
             }),
-            edgeDomain ? Promise.resolve().then(() => __importStar(require("../common/h2pool.js"))).then(({ h2Pool }) => h2Pool.get(edgeDomain)).catch(() => null) : Promise.resolve(null),
+            edgeDomain && !settings_js_1.settings.disableH2 ? Promise.resolve().then(() => __importStar(require("../common/h2pool.js"))).then(({ h2Pool }) => h2Pool.get(edgeDomain)).catch(() => null) : Promise.resolve(null),
         ]);
         // Inject the H2 session into the config so subsystems can use it
-        const config = { ...data, h2Session };
+        const config = { ...data, h2Session, h2Domain: settings_js_1.settings.disableH2 ? null : edgeDomain };
         const instance = new SandboxInstance(config);
         instance.h2Session = h2Session;
         // Note: H2 session already attached via Promise.all above, no need for attachH2Session()
@@ -224,7 +230,10 @@ class SandboxInstance {
             try {
                 await instance.fs.ls('/');
             }
-            catch { }
+            catch (err) {
+                await SandboxInstance.delete(instance.metadata.name).catch(() => { });
+                throw err;
+            }
         }
         return instance;
     }
@@ -255,6 +264,8 @@ class SandboxInstance {
     async delete() {
         // Don't close the H2 session — it's shared via h2Pool
         this.h2Session = null;
+        this.sandbox.h2Session = null;
+        this.sandbox.h2Domain = null;
         return await SandboxInstance.delete(this.metadata.name);
     }
     static async updateMetadata(sandboxName, metadata) {

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

@@ -1,5 +1,5 @@
 import http2 from "http2";
-import type { h2Pool as H2PoolType } from "./h2pool.js";
+import type { H2Pool } from "./h2pool.js";
 /**
  * Creates a fetch()-compatible function that sends requests over an existing
  * HTTP/2 session. Falls back to globalThis.fetch() only when the session is
@@ -12,12 +12,12 @@ export declare function createH2Fetch(session: http2.ClientHttp2Session): (input
 /**
  * Creates a fetch()-compatible function backed by the H2 session pool.
  *
- * Non-blocking: checks the pool cache synchronously. If a warm session is
- * available it's used immediately; otherwise the request goes through
- * regular fetch with zero delay (the pool keeps warming in the background
- * so subsequent calls get H2).
+ * 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.
  */
-export declare function createPoolBackedH2Fetch(pool: typeof H2PoolType, domain: string): (input: Request) => Promise<Response>;
+export declare function createPoolBackedH2Fetch(pool: H2Pool, domain: string): (input: Request) => Promise<Response>;
+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.
  * Used by SandboxAction.h2Fetch() for direct calls from subsystems.