feat: default to HTTP/2 transport on Node

Flip the `http2` client option default from `false` to `true`, so the SDK
uses its native `node:http2` multiplexing transport by default on Node.js
instead of one HTTP/1.1 connection per request. Web/Deno/Bun are unaffected
(platform fetch already speaks h2), and a user-supplied `fetch` still wins.

Opting out: pass `http2: false` for the HTTP/1.1 `node-fetch` transport. To
keep existing `httpAgent` users working, a bare `httpAgent` (with no explicit
`http2`) keeps the client on HTTP/1.1 and emits a one-time warning; pass
`http2: false` to select HTTP/1.1 explicitly and silence it.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Reflex

README.md

@@ -357,29 +357,27 @@ await runloop.devboxes.create({...}, {
 
 ### HTTP/2 transport
 
-On Node.js, the SDK can send requests over HTTP/2, which multiplexes many concurrent requests over a small number of TLS connections instead of opening a connection per request. Enable it with the `http2` option:
+On Node.js, the SDK sends requests over HTTP/2 **by default**, multiplexing many concurrent requests over a small number of TLS connections instead of opening a connection per request. The transport is built on Node's native `node:http2` and manages a bounded pool of persistent H2 sessions per origin, auto-scaling with load. On the web, Deno, and other runtimes the platform `fetch` already speaks HTTP/2, so this option is a no-op there.
+
+To tune the pool — for example to raise the number of connections for a high-concurrency workload — pass options as `http2`:
 
 <!-- prettier-ignore -->
 ```ts
 const runloop = new RunloopSDK({
-  http2: true,
+  http2: { maxConnections: 20 },
 });
 ```
 
-Requests are routed through an [undici](https://github.com/nodejs/undici) connection pool with HTTP/2 enabled, falling back to HTTP/1.1 for origins that don't negotiate h2 via ALPN. It is intended for HTTP/2-capable origins such as the Runloop API. This transport uses undici and therefore **requires Node.js >= 20.18.1** (see Requirements).
-
-`http2: true` uses a default bounded pool. To control the pool yourself — for example to raise the number of connections or multiplexed streams for a high-concurrency workload — pass a configured undici `Dispatcher` (such as an `Agent`) instead. The SDK uses it verbatim and does not manage its lifecycle, the same way it treats a custom `httpAgent`:
+To opt out and use the HTTP/1.1 `node-fetch` transport, set `http2: false`:
 
 <!-- prettier-ignore -->
 ```ts
-import { Agent } from 'undici';
-
 const runloop = new RunloopSDK({
-  http2: new Agent({ allowH2: true, connections: 8, pipelining: 100 }),
+  http2: false,
 });
 ```
 
-The `httpAgent` option does not apply to the HTTP/2 transport (undici has no Node `http.Agent` concept); set `http2` to a `Dispatcher` to tune connections. A one-time warning is emitted if both `http2` and `httpAgent` are provided.
+The `httpAgent` option only applies to the HTTP/1.1 transport — the H2 pool manages its own connections. Passing an `httpAgent` without an explicit `http2` value keeps the client on HTTP/1.1 (with a one-time warning); pass `http2: false` to select HTTP/1.1 explicitly and silence the warning. A custom `fetch` always takes precedence over `http2`.
 
 ## Semantic versioning
 

src/index.ts

@@ -294,14 +294,20 @@ export interface ClientOptions {
   /**
    * Send requests over HTTP/2 using native `node:http2` connection pools.
    *
-   * - `true` uses the SDK's default bounded HTTP/2 pool.
+   * HTTP/2 is the default transport on Node.js: it multiplexes many concurrent
+   * requests over a small number of TLS connections instead of opening one
+   * connection per request.
+   *
+   * - `true` / omitted uses the SDK's default bounded HTTP/2 pool.
    * - Pass `H2FetchOptions` to tune pool size, timeouts, etc.
+   * - `false` opts out and uses the HTTP/1.1 `node-fetch` transport.
    *
    * On the HTTP/2 path the `httpAgent` option is not used — the H2 transport
-   * manages its own persistent connections. A one-time warning is emitted if
-   * both `http2` and `httpAgent` are set.
+   * manages its own persistent connections. Passing an `httpAgent` without an
+   * explicit `http2` value keeps the client on HTTP/1.1 (with a one-time
+   * warning); pass `http2: false` to opt out silently.
    *
-   * @default false
+   * @default true
    */
   http2?: boolean | import('./lib/h2-transport').H2FetchOptions | undefined;
 
@@ -341,10 +347,15 @@ export interface ClientOptions {
  * console.log(result.exitCode);
  * ```
  */
-// Emitted at most once per process when `http2` and `httpAgent` are combined (see
-// the constructor). Module-scoped flag mirrors the `fileFromPathWarned` pattern in
-// _shims/node-runtime.ts.
+// Emitted at most once per process each (see the constructor). Module-scoped flags
+// mirror the `fileFromPathWarned` pattern in _shims/node-runtime.ts.
+//
+// `http2HttpAgentWarned`   — user explicitly set `http2` *and* `httpAgent`; the agent
+//                            is ignored on the H2 path.
+// `http2DefaultAgentWarned`— user set `httpAgent` without an explicit `http2` value, so
+//                            the client stays on HTTP/1.1 rather than the H2 default.
 let http2HttpAgentWarned = false;
+let http2DefaultAgentWarned = false;
 
 export class Runloop extends Core.APIClient {
   bearerToken: string;
@@ -359,7 +370,7 @@ export class Runloop extends Core.APIClient {
    * @param {number} [opts.timeout=30 seconds] - The maximum amount of time (in milliseconds) the client will wait for a response before timing out.
    * @param {number} [opts.httpAgent] - An HTTP agent used to manage HTTP(s) connections.
    * @param {Core.Fetch} [opts.fetch] - Specify a custom `fetch` function implementation.
-   * @param {boolean | H2FetchOptions} [opts.http2=false] - Send requests over HTTP/2 (Node only; ignored when `fetch` is provided). `true` uses the default bounded pool; pass H2FetchOptions to tune.
+   * @param {boolean | H2FetchOptions} [opts.http2=true] - Send requests over HTTP/2 (Node only; ignored when `fetch` is provided). Enabled by default; pass `false` to use HTTP/1.1, or H2FetchOptions to tune the pool.
    * @param {number} [opts.maxRetries=5] - The maximum number of times the client will retry a request.
    * @param {Core.Headers} opts.defaultHeaders - Default headers to include with every request to the API.
    * @param {Core.DefaultQuery} opts.defaultQuery - Default query parameters to include with every request to the API.
@@ -381,15 +392,43 @@ export class Runloop extends Core.APIClient {
       baseURL: baseURL || `https://api.runloop.ai`,
     };
 
-    // `httpAgent` does not apply to the HTTP/2 transport — it manages its own
-    // persistent connections. Warn once instead of silently ignoring.
-    if (!options.fetch && options.http2 && options.httpAgent && !http2HttpAgentWarned) {
-      http2HttpAgentWarned = true;
-      console.warn(
-        '[runloop] `httpAgent` is ignored when `http2` is set: the HTTP/2 transport manages ' +
-          'its own connections. To tune the H2 pool, pass options as `http2` ' +
-          '(e.g. `http2: { maxConnections: 20 }`).',
-      );
+    // Resolve the transport. HTTP/2 is the default on Node; a user-supplied
+    // `fetch` always wins, `http2: false` opts out, and a bare `httpAgent`
+    // (no explicit `http2`) keeps the client on HTTP/1.1 so existing agents
+    // keep working. `httpAgent` never applies to the H2 path — it manages its
+    // own persistent connections.
+    let useHttp2: boolean;
+    if (options.fetch) {
+      // Custom fetch owns the transport entirely.
+      useHttp2 = false;
+    } else if (options.http2 === false) {
+      useHttp2 = false;
+    } else if (options.http2) {
+      // Explicit opt-in (`true` or H2FetchOptions).
+      useHttp2 = true;
+      if (options.httpAgent && !http2HttpAgentWarned) {
+        http2HttpAgentWarned = true;
+        console.warn(
+          '[runloop] `httpAgent` is ignored when `http2` is set: the HTTP/2 transport manages ' +
+            'its own connections. To tune the H2 pool, pass options as `http2` ' +
+            '(e.g. `http2: { maxConnections: 20 }`).',
+        );
+      }
+    } else if (options.httpAgent) {
+      // Default would be H2, but a `httpAgent` was provided — respect it and
+      // stay on HTTP/1.1, warning once so the fallback isn't silent.
+      useHttp2 = false;
+      if (!http2DefaultAgentWarned) {
+        http2DefaultAgentWarned = true;
+        console.warn(
+          '[runloop] HTTP/2 is the default transport, but `httpAgent` is set, so this client ' +
+            'uses HTTP/1.1. Remove `httpAgent` to use HTTP/2, or pass `http2: false` to select ' +
+            'HTTP/1.1 explicitly and silence this warning.',
+        );
+      }
+    } else {
+      // New default: HTTP/2.
+      useHttp2 = true;
     }
 
     super({
@@ -400,7 +439,7 @@ export class Runloop extends Core.APIClient {
       maxRetries: options.maxRetries,
       fetch:
         options.fetch ??
-        (options.http2 ?
+        (useHttp2 ?
           makeHttp2Fetch(typeof options.http2 === 'object' ? options.http2 : undefined)
         : undefined),
     });

tests/index.test.ts

@@ -99,8 +99,8 @@ describe('instantiate client', () => {
 
   test('custom fetch wins over http2', async () => {
     // When both `fetch` and `http2` are provided, the custom fetch must be used —
-    // the undici (h2) adapter should not run. Locks in src/index.ts:
-    //   fetch: options.fetch ?? (options.http2 ? makeHttp2Fetch(...) : undefined)
+    // the h2 adapter should not run. Locks in src/index.ts:
+    //   fetch: options.fetch ?? (useHttp2 ? makeHttp2Fetch(...) : undefined)
     const customFetch = jest.fn((url: RequestInfo) =>
       Promise.resolve(
         new Response(JSON.stringify({ url, custom: true }), {
@@ -135,13 +135,17 @@ describe('instantiate client', () => {
   test('warns once when http2 and httpAgent are combined', () => {
     const warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
     try {
-      // http2 alone (or httpAgent alone) does not warn.
+      // Explicit http2 alone does not warn.
       new Runloop({ baseURL: 'http://localhost:5000/', bearerToken: 'My Bearer Token', http2: true });
       expect(warn).not.toHaveBeenCalled();
 
       // Combining them warns — exactly once per process (module-scoped flag), so the
       // second construction is silent.
-      const opts = { baseURL: 'http://localhost:5000/', bearerToken: 'My Bearer Token', httpAgent: {} as any };
+      const opts = {
+        baseURL: 'http://localhost:5000/',
+        bearerToken: 'My Bearer Token',
+        httpAgent: {} as any,
+      };
       new Runloop({ ...opts, http2: true });
       new Runloop({ ...opts, http2: true });
       expect(warn).toHaveBeenCalledTimes(1);
@@ -151,6 +155,43 @@ describe('instantiate client', () => {
     }
   });
 
+  test('httpAgent without explicit http2 stays on HTTP/1.1 and warns once', () => {
+    // HTTP/2 is the default, but a bare `httpAgent` keeps the client on HTTP/1.1 so
+    // existing agents keep working. The fallback warns once (module-scoped flag).
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const opts = {
+        baseURL: 'http://localhost:5000/',
+        bearerToken: 'My Bearer Token',
+        httpAgent: {} as any,
+      };
+      new Runloop(opts);
+      new Runloop(opts);
+      expect(warn).toHaveBeenCalledTimes(1);
+      expect(String(warn.mock.calls[0]?.[0])).toContain('HTTP/1.1');
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  test('http2: false opts out of the default HTTP/2 transport without warning', () => {
+    // Explicit opt-out is silent even alongside an httpAgent — the user has chosen
+    // HTTP/1.1 deliberately.
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const client = new Runloop({
+        baseURL: 'http://localhost:5000/',
+        bearerToken: 'My Bearer Token',
+        httpAgent: {} as any,
+        http2: false,
+      });
+      expect(client).toBeDefined();
+      expect(warn).not.toHaveBeenCalled();
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
   test('explicit global fetch', async () => {
     // make sure the global fetch type is assignable to our Fetch type
     const client = new Runloop({