refactor(http2): extract transport selection to src/lib and share the default pool

Addresses PR review:

- Move the HTTP/2 transport-selection logic and one-time warnings out of the
  generated `src/index.ts` into a handwritten `src/lib/http2-transport.ts`
  helper (`resolveHttp2Fetch`). The generated file keeps only a one-line
  call-site hook, following the existing `makeHttp2Fetch` / `H2FetchOptions`
  pattern, so regeneration stays clean.
- Share a single default HTTP/2 pool across all clients instead of building a
  new pool per `new Runloop()`. Short-lived clients no longer leak H2 sessions.
  Explicit `H2FetchOptions` still get a dedicated pool (intentional tuning).

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

Author: Reflex

src/index.ts

@@ -1,6 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { type Agent, makeHttp2Fetch } from './_shims/index';
+import { type Agent } from './_shims/index';
+import { resolveHttp2Fetch } from './lib/http2-transport';
 import * as Core from './core';
 import * as Errors from './error';
 import * as Pagination from './pagination';
@@ -347,16 +348,6 @@ export interface ClientOptions {
  * console.log(result.exitCode);
  * ```
  */
-// 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;
 
@@ -392,56 +383,15 @@ export class Runloop extends Core.APIClient {
       baseURL: baseURL || `https://api.runloop.ai`,
     };
 
-    // 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({
       baseURL: options.baseURL!,
       baseURLOverridden: baseURL ? baseURL !== 'https://api.runloop.ai' : false,
       timeout: options.timeout ?? 30000 /* 30 seconds */,
       httpAgent: options.httpAgent,
       maxRetries: options.maxRetries,
-      fetch:
-        options.fetch ??
-        (useHttp2 ?
-          makeHttp2Fetch(typeof options.http2 === 'object' ? options.http2 : undefined)
-        : undefined),
+      // HTTP/2 is the default transport on Node; a custom `fetch` always wins.
+      // See `resolveHttp2Fetch` for the `http2` / `httpAgent` resolution.
+      fetch: options.fetch ?? resolveHttp2Fetch(options),
     });
 
     const customHeadersEnv = Core.readEnv('RUNLOOP_CUSTOM_HEADERS');

src/lib/http2-transport.ts

@@ -0,0 +1,78 @@
+import { makeHttp2Fetch } from '../_shims/index';
+import { type Fetch } from '../core';
+import type { H2FetchOptions } from './h2-transport';
+
+/**
+ * Transport-selection logic for the client. Kept out of the generated
+ * `src/index.ts` so the generated file only holds a one-line call-site hook.
+ *
+ * HTTP/2 is the default on Node. The web/Deno shims make {@link makeHttp2Fetch}
+ * a no-op that returns the platform `fetch`, so this is effectively Node-only.
+ */
+
+// A single HTTP/2 transport shared by every client that uses the default pool,
+// so short-lived clients don't each open (and leak) their own H2 sessions.
+// Clients that pass explicit `H2FetchOptions` get a dedicated pool, since they
+// asked to tune it.
+let sharedDefaultFetch: Fetch | undefined;
+
+function getSharedDefaultFetch(): Fetch {
+  return (sharedDefaultFetch ??= makeHttp2Fetch());
+}
+
+// Each warning is emitted at most once per process. Module-scoped flags mirror
+// the `fileFromPathWarned` pattern in _shims/node-runtime.ts.
+let httpAgentIgnoredWarned = false;
+let httpAgentFallbackWarned = false;
+
+function warnHttpAgentIgnored(): void {
+  if (httpAgentIgnoredWarned) return;
+  httpAgentIgnoredWarned = 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 }`).',
+  );
+}
+
+function warnHttpAgentFallback(): void {
+  if (httpAgentFallbackWarned) return;
+  httpAgentFallbackWarned = 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.',
+  );
+}
+
+export interface Http2TransportOptions {
+  http2?: boolean | H2FetchOptions | undefined;
+  httpAgent?: unknown;
+}
+
+/**
+ * Resolve the `fetch` implementation for the transport, or `undefined` to fall
+ * back to the default HTTP/1.1 (`node-fetch`) transport. Only called when the
+ * caller did not supply a custom `fetch` (a custom `fetch` always wins).
+ *
+ * - `http2: false` → HTTP/1.1.
+ * - `http2: true` / omitted → the shared default HTTP/2 pool.
+ * - `http2: H2FetchOptions` → a dedicated HTTP/2 pool tuned with those options.
+ * - a bare `httpAgent` (no explicit `http2`) → HTTP/1.1, so existing agents keep
+ *   working; warns once since it overrides the HTTP/2 default.
+ */
+export function resolveHttp2Fetch(options: Http2TransportOptions): Fetch | undefined {
+  if (options.http2 === false) return undefined;
+
+  if (options.http2) {
+    if (options.httpAgent) warnHttpAgentIgnored();
+    return typeof options.http2 === 'object' ? makeHttp2Fetch(options.http2) : getSharedDefaultFetch();
+  }
+
+  if (options.httpAgent) {
+    warnHttpAgentFallback();
+    return undefined;
+  }
+
+  return getSharedDefaultFetch();
+}

tests/lib/http2-transport.test.ts

@@ -0,0 +1,48 @@
+import { resolveHttp2Fetch } from '../../src/lib/http2-transport';
+
+describe('resolveHttp2Fetch', () => {
+  test('defaults to HTTP/2 and shares a single pool across clients', () => {
+    const a = resolveHttp2Fetch({});
+    const b = resolveHttp2Fetch({});
+    const explicitTrue = resolveHttp2Fetch({ http2: true });
+    expect(a).toBeDefined();
+    // Same instance — short-lived clients must not each open their own pool.
+    expect(b).toBe(a);
+    expect(explicitTrue).toBe(a);
+  });
+
+  test('http2: false falls back to HTTP/1.1 (undefined fetch)', () => {
+    expect(resolveHttp2Fetch({ http2: false })).toBeUndefined();
+  });
+
+  test('H2FetchOptions gets a dedicated pool, not the shared default', () => {
+    const shared = resolveHttp2Fetch({});
+    const tuned = resolveHttp2Fetch({ http2: { maxConnections: 2 } });
+    expect(tuned).toBeDefined();
+    expect(tuned).not.toBe(shared);
+  });
+
+  test('bare httpAgent keeps HTTP/1.1 and warns once', () => {
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      expect(resolveHttp2Fetch({ httpAgent: {} })).toBeUndefined();
+      expect(resolveHttp2Fetch({ httpAgent: {} })).toBeUndefined();
+      expect(warn).toHaveBeenCalledTimes(1);
+      expect(String(warn.mock.calls[0]?.[0])).toContain('HTTP/1.1');
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  test('http2 + httpAgent uses H2 and warns that httpAgent is ignored', () => {
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const shared = resolveHttp2Fetch({});
+      expect(resolveHttp2Fetch({ http2: true, httpAgent: {} })).toBe(shared);
+      expect(warn).toHaveBeenCalledTimes(1);
+      expect(String(warn.mock.calls[0]?.[0])).toContain('httpAgent');
+    } finally {
+      warn.mockRestore();
+    }
+  });
+});