@the-open-engine/zeroshot 6.25.1 → 6.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-open-engine/zeroshot",
-  "version": "6.25.1",
+  "version": "6.26.0",
   "description": "Multi-agent orchestration engine for Claude, Codex, and Gemini",
   "main": "src/orchestrator.js",
   "bin": {
@@ -40,8 +40,10 @@
     "test:coverage:report": "c8 --reporter=html npm run test:unit && echo 'Coverage report generated at coverage/index.html'",
     "postinstall": "node scripts/fix-node-pty-permissions.js && node scripts/check-path.js",
     "start": "node cli/index.js",
-    "typecheck": "tsc --noEmit && npm run typecheck:cluster",
+    "typecheck": "tsc --noEmit && npm run typecheck:cluster && npm run typecheck:hosted-target",
     "typecheck:agent-cli-provider": "tsc --project tsconfig.agent-cli-provider.json",
+    "typecheck:hosted-target": "tsc --project tsconfig.hosted-target.json",
+    "test:hosted-target": "node --test tests/hosted-target/*.test.ts",
     "typecheck:cluster": "tsc --project tsconfig.cluster.json",
     "lint:agent-cli-provider": "eslint \"src/agent-cli-provider/**/*.ts\" \"tests/agent-cli-provider/**/*.ts\"",
     "build:agent-cli-provider": "tsc --project tsconfig.agent-cli-provider.build.json",

package/src/hosted-target/bounds.ts

@@ -0,0 +1,6 @@
+export const MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+export const MAX_PAGINATION_PAGES = 100;
+export const MAX_RETRY_ATTEMPTS = 3;
+export const MAX_RETRY_ELAPSED_MS = 30_000;
+export const MAX_ERROR_BODY_BYTES = 8192;
+export const IDEMPOTENCY_KEY_PATTERN = /^[a-zA-Z0-9_-]{1,128}$/;

package/src/hosted-target/errors.ts

@@ -0,0 +1,90 @@
+function sanitize(text: string): string {
+  return text
+    .replace(/Authorization:\s*Bearer\s+\S+/gi, 'Authorization: Bearer [REDACTED]')
+    .replace(/token["']?\s*[:=]\s*["'][^"']+["']/gi, 'token: "[REDACTED]"')
+    .replace(/https?:\/\/[^\s]*(?:token|key|secret|credential|auth)[^\s]*/gi, '[REDACTED_URL]');
+}
+
+function sanitizeCause(cause: unknown): unknown {
+  if (!cause) return cause;
+  if (cause instanceof Error) {
+    const cleaned = new Error(sanitize(cause.message));
+    cleaned.name = cause.name;
+    if (cause.cause) cleaned.cause = sanitizeCause(cause.cause);
+    return cleaned;
+  }
+  if (typeof cause === 'string') return sanitize(cause);
+  return cause;
+}
+
+export class TargetAdapterError extends Error {
+  readonly code: string;
+  readonly retryable: boolean;
+
+  constructor(code: string, message: string, retryable: boolean, cause?: unknown) {
+    super(sanitize(message), { cause: sanitizeCause(cause) });
+    this.name = 'TargetAdapterError';
+    this.code = code;
+    this.retryable = retryable;
+  }
+}
+
+export class TargetAuthError extends TargetAdapterError {
+  constructor(message: string, cause?: unknown) {
+    super('AUTH_FAILED', message, false, cause);
+    this.name = 'TargetAuthError';
+  }
+}
+
+export class TargetConflictError extends TargetAdapterError {
+  readonly idempotencyKey: string;
+
+  constructor(idempotencyKey: string, message: string, cause?: unknown) {
+    super('CONFLICT', message, true, cause);
+    this.name = 'TargetConflictError';
+    this.idempotencyKey = idempotencyKey;
+  }
+}
+
+export class TargetRateLimitError extends TargetAdapterError {
+  readonly retryAfterMs: number | undefined;
+
+  constructor(message: string, retryAfterMs?: number, cause?: unknown) {
+    super('RATE_LIMITED', message, true, cause);
+    this.name = 'TargetRateLimitError';
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
+export class TargetTransportError extends TargetAdapterError {
+  constructor(message: string, cause?: unknown) {
+    super('TRANSPORT', message, true, cause);
+    this.name = 'TargetTransportError';
+  }
+}
+
+export class TargetProtocolError extends TargetAdapterError {
+  constructor(message: string, cause?: unknown) {
+    super('PROTOCOL', message, false, cause);
+    this.name = 'TargetProtocolError';
+  }
+}
+
+export class TargetCapacityError extends TargetAdapterError {
+  constructor(message: string, cause?: unknown) {
+    super('CAPACITY', message, false, cause);
+    this.name = 'TargetCapacityError';
+  }
+}
+
+export class TargetNotFoundError extends TargetAdapterError {
+  constructor(message: string, cause?: unknown) {
+    super('NOT_FOUND', message, false, cause);
+    this.name = 'TargetNotFoundError';
+  }
+}
+
+export function isRetryable(error: unknown): boolean {
+  if (error instanceof TargetAdapterError) return error.retryable;
+  return false;
+}

package/src/hosted-target/index.ts

@@ -0,0 +1,44 @@
+export type { TargetAdapter } from './target-adapter.ts';
+export { ZeroCloudV1TargetAdapter } from './zero-cloud-v1-adapter.ts';
+export {
+  TargetAdapterError,
+  TargetAuthError,
+  TargetConflictError,
+  TargetRateLimitError,
+  TargetTransportError,
+  TargetProtocolError,
+  TargetCapacityError,
+  TargetNotFoundError,
+  isRetryable,
+} from './errors.ts';
+export type {
+  TargetAccessTokenProvider,
+  CapsuleState,
+  Capsule,
+  CapsuleAccess,
+  CapsuleListPage,
+  CapsuleLimits,
+  AllocateRequest,
+  HttpTransport,
+  Clock,
+  RetryPolicy,
+  TargetDiscovery,
+} from './types.ts';
+export { KNOWN_CAPSULE_STATES } from './types.ts';
+export {
+  MAX_RESPONSE_BYTES,
+  MAX_PAGINATION_PAGES,
+  MAX_RETRY_ATTEMPTS,
+  MAX_RETRY_ELAPSED_MS,
+  MAX_ERROR_BODY_BYTES,
+  IDEMPOTENCY_KEY_PATTERN,
+} from './bounds.ts';
+export { DefaultRetryPolicy, parseRetryAfter } from './retry.ts';
+export {
+  assertRequiredFields,
+  assertKnownEnum,
+  assertCapsule,
+  assertCapsuleAccess,
+  assertCapsuleLimits,
+  assertCapsuleListPage,
+} from './response-validation.ts';

package/src/hosted-target/response-validation.ts

@@ -0,0 +1,86 @@
+import { TargetProtocolError } from './errors.ts';
+import { KNOWN_CAPSULE_STATES } from './types.ts';
+import type { Capsule, CapsuleAccess, CapsuleLimits, CapsuleListPage } from './types.ts';
+
+export function assertRequiredFields(
+  body: unknown,
+  fields: readonly string[],
+  context: string,
+): asserts body is Record<string, unknown> {
+  if (body === null || typeof body !== 'object') {
+    throw new TargetProtocolError(`${context}: expected object, got ${typeof body}`);
+  }
+  const record = body as Record<string, unknown>;
+  for (const field of fields) {
+    if (record[field] === undefined || record[field] === null) {
+      throw new TargetProtocolError(`${context}: missing required field "${field}"`);
+    }
+  }
+}
+
+export function assertKnownEnum(value: string, known: readonly string[], field: string): void {
+  if (!known.includes(value)) {
+    // eslint-disable-next-line no-console
+    console.warn(`Unknown ${field} value: "${value}". Known values: ${known.join(', ')}`);
+  }
+}
+
+export function assertCapsule(body: unknown): Capsule {
+  assertRequiredFields(body, ['id', 'state', 'createdAt'], 'Capsule');
+  const record = body as Record<string, unknown>;
+  if (typeof record['id'] !== 'string') {
+    throw new TargetProtocolError('Capsule: "id" must be a string');
+  }
+  if (typeof record['state'] !== 'string') {
+    throw new TargetProtocolError('Capsule: "state" must be a string');
+  }
+  if (typeof record['createdAt'] !== 'string') {
+    throw new TargetProtocolError('Capsule: "createdAt" must be a string');
+  }
+  assertKnownEnum(record['state'] as string, KNOWN_CAPSULE_STATES, 'CapsuleState');
+  return record as unknown as Capsule;
+}
+
+export function assertCapsuleAccess(body: unknown): CapsuleAccess {
+  assertRequiredFields(body, ['endpoint', 'token', 'expiresAt'], 'CapsuleAccess');
+  const record = body as Record<string, unknown>;
+  if (typeof record['endpoint'] !== 'string') {
+    throw new TargetProtocolError('CapsuleAccess: "endpoint" must be a string');
+  }
+  if (typeof record['token'] !== 'string') {
+    throw new TargetProtocolError('CapsuleAccess: "token" must be a string');
+  }
+  if (typeof record['expiresAt'] !== 'string') {
+    throw new TargetProtocolError('CapsuleAccess: "expiresAt" must be a string');
+  }
+  return record as unknown as CapsuleAccess;
+}
+
+export function assertCapsuleLimits(body: unknown): CapsuleLimits {
+  assertRequiredFields(body, ['maxConcurrent', 'maxPerHour'], 'CapsuleLimits');
+  const record = body as Record<string, unknown>;
+  if (typeof record['maxConcurrent'] !== 'number') {
+    throw new TargetProtocolError('CapsuleLimits: "maxConcurrent" must be a number');
+  }
+  if (typeof record['maxPerHour'] !== 'number') {
+    throw new TargetProtocolError('CapsuleLimits: "maxPerHour" must be a number');
+  }
+  return record as unknown as CapsuleLimits;
+}
+
+export function assertCapsuleListPage(body: unknown): CapsuleListPage {
+  assertRequiredFields(body, ['items'], 'CapsuleListPage');
+  const record = body as Record<string, unknown>;
+  if (!Array.isArray(record['items'])) {
+    throw new TargetProtocolError('CapsuleListPage: "items" must be an array');
+  }
+  const items = (record['items'] as unknown[]).map((item) => assertCapsule(item));
+  const cursor = record['cursor'];
+  if (cursor !== undefined && cursor !== null && typeof cursor !== 'string') {
+    throw new TargetProtocolError('CapsuleListPage: "cursor" must be a string if present');
+  }
+  if (typeof cursor === 'string') {
+    return { items, cursor };
+  }
+  return { items };
+}

package/src/hosted-target/retry.ts

@@ -0,0 +1,46 @@
+import { MAX_RETRY_ATTEMPTS, MAX_RETRY_ELAPSED_MS } from './bounds.ts';
+import type { TargetAdapterError } from './errors.ts';
+import { TargetAuthError, TargetRateLimitError } from './errors.ts';
+import type { Clock, RetryPolicy } from './types.ts';
+
+export class DefaultRetryPolicy implements RetryPolicy {
+  shouldRetry(
+    attempt: number,
+    elapsed: number,
+    error: TargetAdapterError,
+  ): { retry: boolean; delayMs: number } {
+    if (error instanceof TargetAuthError) return { retry: false, delayMs: 0 };
+    if (!error.retryable) return { retry: false, delayMs: 0 };
+    if (attempt >= MAX_RETRY_ATTEMPTS) return { retry: false, delayMs: 0 };
+    if (elapsed >= MAX_RETRY_ELAPSED_MS) return { retry: false, delayMs: 0 };
+
+    const requestedDelay =
+      error instanceof TargetRateLimitError && error.retryAfterMs !== undefined
+        ? Math.max(0, error.retryAfterMs)
+        : Math.min(1000 * Math.pow(2, attempt), 10_000);
+    const remaining = MAX_RETRY_ELAPSED_MS - elapsed;
+    if (!Number.isFinite(requestedDelay) || requestedDelay >= remaining) {
+      return { retry: false, delayMs: 0 };
+    }
+
+    return { retry: true, delayMs: requestedDelay };
+  }
+}
+
+export function parseRetryAfter(header: string | null, clock: Clock): number | null {
+  if (header === null) return null;
+
+  const trimmed = header.trim();
+  if (trimmed.length === 0) return null;
+
+  const numericSeconds = Number(trimmed);
+  if (Number.isFinite(numericSeconds) && numericSeconds >= 0) {
+    return Math.ceil(numericSeconds * 1000);
+  }
+
+  const date = Date.parse(trimmed);
+  if (Number.isNaN(date)) return null;
+
+  const delayMs = date - clock.now();
+  return delayMs > 0 ? Math.ceil(delayMs) : 0;
+}

package/src/hosted-target/target-adapter.ts

@@ -0,0 +1,10 @@
+import type { AllocateRequest, Capsule, CapsuleAccess, CapsuleLimits, CapsuleListPage } from './types.ts';
+
+export interface TargetAdapter {
+  allocate(req: AllocateRequest, signal?: AbortSignal): Promise<Capsule>;
+  list(cursor?: string, signal?: AbortSignal): Promise<CapsuleListPage>;
+  inspect(capsuleId: string, signal?: AbortSignal): Promise<Capsule>;
+  terminate(capsuleId: string, signal?: AbortSignal): Promise<void>;
+  limits(signal?: AbortSignal): Promise<CapsuleLimits>;
+  access(capsuleId: string, signal?: AbortSignal): Promise<CapsuleAccess>;
+}

package/src/hosted-target/types.ts

@@ -0,0 +1,58 @@
+import type { TargetAdapterError } from './errors.ts';
+
+export interface TargetAccessTokenProvider {
+  getAccessToken(signal?: AbortSignal): Promise<string>;
+}
+
+export type CapsuleState = 'provisioning' | 'running' | 'stopping' | 'terminated' | 'failed' | (string & {});
+
+export const KNOWN_CAPSULE_STATES = ['provisioning', 'running', 'stopping', 'terminated', 'failed'] as const;
+
+export interface Capsule {
+  readonly id: string;
+  readonly state: CapsuleState;
+  readonly createdAt: string;
+  readonly [key: string]: unknown;
+}
+
+export interface CapsuleAccess {
+  readonly endpoint: string;
+  readonly token: string;
+  readonly expiresAt: string;
+}
+
+export interface CapsuleListPage {
+  readonly items: readonly Capsule[];
+  readonly cursor?: string;
+}
+
+export interface CapsuleLimits {
+  readonly maxConcurrent: number;
+  readonly maxPerHour: number;
+  readonly [key: string]: unknown;
+}
+
+export interface AllocateRequest {
+  readonly idempotencyKey: string;
+  readonly profile: string;
+}
+
+export interface HttpTransport {
+  fetch(url: string, init: RequestInit & { redirect: 'error' }): Promise<Response>;
+}
+
+export interface Clock {
+  now(): number;
+}
+
+export interface RetryPolicy {
+  shouldRetry(
+    attempt: number,
+    elapsed: number,
+    error: TargetAdapterError,
+  ): { retry: boolean; delayMs: number };
+}
+
+export interface TargetDiscovery {
+  readonly capsuleV1: string;
+}

package/src/hosted-target/zero-cloud-v1-adapter.ts

@@ -0,0 +1,386 @@
+import { MAX_ERROR_BODY_BYTES, MAX_RESPONSE_BYTES, MAX_RETRY_ELAPSED_MS, IDEMPOTENCY_KEY_PATTERN } from './bounds.ts';
+import {
+  TargetAuthError,
+  TargetConflictError,
+  TargetNotFoundError,
+  TargetProtocolError,
+  TargetRateLimitError,
+  TargetTransportError,
+} from './errors.ts';
+import { TargetAdapterError } from './errors.ts';
+import { DefaultRetryPolicy, parseRetryAfter } from './retry.ts';
+import {
+  assertCapsule,
+  assertCapsuleAccess,
+  assertCapsuleLimits,
+  assertCapsuleListPage,
+} from './response-validation.ts';
+import type { TargetAdapter } from './target-adapter.ts';
+import type {
+  AllocateRequest,
+  Capsule,
+  CapsuleAccess,
+  CapsuleLimits,
+  CapsuleListPage,
+  Clock,
+  HttpTransport,
+  RetryPolicy,
+  TargetAccessTokenProvider,
+  TargetDiscovery,
+} from './types.ts';
+
+interface ZeroCloudV1Options {
+  readonly discovery: TargetDiscovery;
+  readonly organization: string;
+  readonly tokenProvider: TargetAccessTokenProvider;
+  readonly transport?: HttpTransport;
+  readonly clock?: Clock;
+  readonly retryPolicy?: RetryPolicy;
+}
+
+const DEFAULT_TRANSPORT: HttpTransport = {
+  fetch(url: string, init: RequestInit & { redirect: 'error' }): Promise<Response> {
+    return globalThis.fetch(url, init);
+  },
+};
+
+const DEFAULT_CLOCK: Clock = { now: () => Date.now() };
+
+function throwIfAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) {
+    throw signal.reason === undefined
+      ? new DOMException('The operation was aborted', 'AbortError')
+      : signal.reason;
+  }
+}
+
+async function waitForRetryDelay(delayMs: number, signal?: AbortSignal): Promise<void> {
+  throwIfAborted(signal);
+  if (delayMs <= 0) return;
+
+  await new Promise<void>((resolve, reject) => {
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      reject(
+        signal!.reason === undefined
+          ? new DOMException('The operation was aborted', 'AbortError')
+          : signal!.reason,
+      );
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, delayMs);
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+function originOf(url: string): string {
+  try {
+    const u = new URL(url);
+    return u.origin;
+  } catch {
+    throw new TargetProtocolError(`Invalid URL: ${url}`);
+  }
+}
+
+export class ZeroCloudV1TargetAdapter implements TargetAdapter {
+  private readonly discovery: TargetDiscovery;
+  private readonly organization: string;
+  private readonly tokenProvider: TargetAccessTokenProvider;
+  private readonly transport: HttpTransport;
+  private readonly clock: Clock;
+  private readonly retryPolicy: RetryPolicy;
+  private readonly expectedOrigin: string;
+
+  constructor(opts: ZeroCloudV1Options) {
+    this.discovery = opts.discovery;
+    this.organization = opts.organization;
+    this.tokenProvider = opts.tokenProvider;
+    this.transport = opts.transport ?? DEFAULT_TRANSPORT;
+    this.clock = opts.clock ?? DEFAULT_CLOCK;
+    this.retryPolicy = opts.retryPolicy ?? new DefaultRetryPolicy();
+    this.expectedOrigin = originOf(opts.discovery.capsuleV1);
+  }
+
+  async allocate(req: AllocateRequest, signal?: AbortSignal): Promise<Capsule> {
+    if (!IDEMPOTENCY_KEY_PATTERN.test(req.idempotencyKey)) {
+      throw new TargetProtocolError(
+        `Invalid idempotency key: must match ${IDEMPOTENCY_KEY_PATTERN}`,
+      );
+    }
+
+    const body = JSON.stringify({ profile: req.profile, organization: this.organization });
+
+    return this._withRetry(async () => {
+      const resp = await this._request('POST', '/capsules', {
+        signal,
+        body,
+        headers: { 'Idempotency-Key': req.idempotencyKey },
+      });
+      const json = await this._readJson(resp);
+      return assertCapsule(json);
+    }, signal);
+  }
+
+  async list(cursor?: string, signal?: AbortSignal): Promise<CapsuleListPage> {
+    return this._withRetry(async () => {
+      const params = new URLSearchParams({ organization: this.organization });
+      if (cursor) params.set('cursor', cursor);
+      const resp = await this._request('GET', `/capsules?${params.toString()}`, { signal });
+      const json = await this._readJson(resp);
+      const page = assertCapsuleListPage(json);
+      if (page.cursor !== undefined && page.cursor === cursor) {
+        throw new TargetProtocolError(
+          `Pagination loop detected: server returned the same cursor "${cursor}"`,
+        );
+      }
+      return page;
+    }, signal);
+  }
+
+  async inspect(capsuleId: string, signal?: AbortSignal): Promise<Capsule> {
+    return this._withRetry(async () => {
+      const resp = await this._request('GET', `/capsules/${encodeURIComponent(capsuleId)}`, {
+        signal,
+      });
+      const json = await this._readJson(resp);
+      return assertCapsule(json);
+    }, signal);
+  }
+
+  async terminate(capsuleId: string, signal?: AbortSignal): Promise<void> {
+    await this._withRetry(async () => {
+      const resp = await this._request(
+        'DELETE',
+        `/capsules/${encodeURIComponent(capsuleId)}`,
+        { signal },
+      );
+      if (resp.status !== 204) {
+        const json = await this._readJson(resp);
+        throw new TargetProtocolError(`Unexpected terminate response: ${JSON.stringify(json)}`);
+      }
+    }, signal);
+  }
+
+  async limits(signal?: AbortSignal): Promise<CapsuleLimits> {
+    return this._withRetry(async () => {
+      const params = new URLSearchParams({ organization: this.organization });
+      const resp = await this._request('GET', `/limits?${params.toString()}`, { signal });
+      const json = await this._readJson(resp);
+      return assertCapsuleLimits(json);
+    }, signal);
+  }
+
+  async access(capsuleId: string, signal?: AbortSignal): Promise<CapsuleAccess> {
+    return this._withRetry(async () => {
+      const resp = await this._request(
+        'POST',
+        `/capsules/${encodeURIComponent(capsuleId)}/access`,
+        { signal },
+      );
+      const json = await this._readJson(resp);
+      return assertCapsuleAccess(json);
+    }, signal);
+  }
+
+  private async _request(
+    method: string,
+    path: string,
+    opts: { signal?: AbortSignal | undefined; body?: string | undefined; headers?: Record<string, string> | undefined },
+  ): Promise<Response> {
+    const url = `${this.discovery.capsuleV1}${path}`;
+
+    const responseOrigin = originOf(url);
+    if (responseOrigin !== this.expectedOrigin) {
+      throw new TargetProtocolError(
+        `Origin mismatch: expected ${this.expectedOrigin}, got ${responseOrigin}`,
+      );
+    }
+
+    let token: string;
+    try {
+      token = await this.tokenProvider.getAccessToken(opts.signal);
+    } catch (err) {
+      throw new TargetTransportError('Failed to acquire access token', err);
+    }
+
+    const headers: Record<string, string> = {
+      'Authorization': `Bearer ${token}`,
+      'Content-Type': 'application/json',
+      'Accept': 'application/json',
+      ...opts.headers,
+    };
+
+    let response: Response;
+    const fetchInit: RequestInit & { redirect: 'error' } = {
+      method,
+      headers,
+      redirect: 'error',
+    };
+    if (opts.body !== undefined) fetchInit.body = opts.body;
+    if (opts.signal !== undefined) fetchInit.signal = opts.signal;
+
+    try {
+      response = await this.transport.fetch(url, fetchInit);
+    } catch (err) {
+      if (err instanceof TargetAdapterError) throw err;
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes('redirect')) {
+        throw new TargetProtocolError(`Redirect rejected for ${method} ${path}`, err);
+      }
+      throw new TargetTransportError(`Network error during ${method} ${path}`, err);
+    }
+
+    if (response.status < 200 || response.status >= 300) {
+      await this._mapStatusError(response, method, path, opts.headers);
+    }
+
+    return response;
+  }
+
+  private async _mapStatusError(
+    response: Response,
+    method: string,
+    path: string,
+    headers?: Record<string, string>,
+  ): Promise<never> {
+    const status = response.status;
+    const errorBody = await this._readErrorBody(response);
+    const context = `${status} ${method} ${path}: ${errorBody}`;
+
+    if (status === 401 || status === 403) throw new TargetAuthError(context);
+    if (status === 404) throw new TargetNotFoundError(context);
+    if (status === 409) {
+      const idempotencyKey = headers?.['Idempotency-Key'] ?? 'unknown';
+      throw new TargetConflictError(idempotencyKey, context);
+    }
+    if (status === 429) {
+      const retryAfterMs = parseRetryAfter(response.headers.get('Retry-After'), this.clock);
+      throw new TargetRateLimitError(context, retryAfterMs ?? undefined);
+    }
+    if (status >= 500) throw new TargetTransportError(context);
+    throw new TargetProtocolError(`Unexpected status ${context}`);
+  }
+
+  private async _readJson(response: Response): Promise<unknown> {
+    const contentLength = response.headers.get('Content-Length');
+    if (contentLength !== null) {
+      const len = parseInt(contentLength, 10);
+      if (Number.isFinite(len) && len > MAX_RESPONSE_BYTES) {
+        throw new TargetProtocolError(
+          `Response too large: ${len} bytes exceeds limit of ${MAX_RESPONSE_BYTES}`,
+        );
+      }
+    }
+
+    let text: string;
+    try {
+      const reader = response.body?.getReader();
+      if (!reader) {
+        text = await response.text();
+      } else {
+        const chunks: Uint8Array[] = [];
+        let totalBytes = 0;
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          totalBytes += value.byteLength;
+          if (totalBytes > MAX_RESPONSE_BYTES) {
+            reader.cancel();
+            throw new TargetProtocolError(
+              `Response body exceeds limit of ${MAX_RESPONSE_BYTES} bytes`,
+            );
+          }
+          chunks.push(value);
+        }
+        const combined = new Uint8Array(totalBytes);
+        let offset = 0;
+        for (const chunk of chunks) {
+          combined.set(chunk, offset);
+          offset += chunk.byteLength;
+        }
+        text = new TextDecoder().decode(combined);
+      }
+    } catch (err) {
+      if (err instanceof TargetProtocolError) throw err;
+      throw new TargetProtocolError('Failed to read response body', err);
+    }
+
+    try {
+      return JSON.parse(text);
+    } catch (err) {
+      throw new TargetProtocolError('Invalid JSON in response body', err);
+    }
+  }
+
+  private async _readErrorBody(response: Response): Promise<string> {
+    const reader = response.body?.getReader();
+    if (!reader) return '';
+
+    const chunks: Uint8Array[] = [];
+    let totalBytes = 0;
+    try {
+      while (totalBytes < MAX_ERROR_BODY_BYTES) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        const remaining = MAX_ERROR_BODY_BYTES - totalBytes;
+        const retained = value.byteLength > remaining ? value.slice(0, remaining) : value;
+        chunks.push(retained);
+        totalBytes += retained.byteLength;
+        if (retained.byteLength !== value.byteLength || totalBytes === MAX_ERROR_BODY_BYTES) {
+          void reader.cancel().catch(() => undefined);
+          break;
+        }
+      }
+    } catch {
+      void reader.cancel().catch(() => undefined);
+      return '<unreadable>';
+    }
+
+    const combined = new Uint8Array(totalBytes);
+    let offset = 0;
+    for (const chunk of chunks) {
+      combined.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    return new TextDecoder().decode(combined);
+  }
+
+  private async _withRetry<T>(
+    fn: () => Promise<T>,
+    signal?: AbortSignal,
+  ): Promise<T> {
+    const startTime = this.clock.now();
+    let attempt = 0;
+
+    while (true) {
+      throwIfAborted(signal);
+      try {
+        return await fn();
+      } catch (err) {
+        throwIfAborted(signal);
+        if (!(err instanceof TargetAdapterError)) throw err;
+        if (err instanceof TargetAuthError) throw err;
+
+        attempt++;
+        const elapsed = this.clock.now() - startTime;
+        const decision = this.retryPolicy.shouldRetry(attempt, elapsed, err);
+        const remaining = MAX_RETRY_ELAPSED_MS - elapsed;
+
+        if (
+          !decision.retry ||
+          !Number.isFinite(decision.delayMs) ||
+          decision.delayMs < 0 ||
+          decision.delayMs >= remaining
+        ) {
+          throw err;
+        }
+
+        await waitForRetryDelay(decision.delayMs, signal);
+        if (this.clock.now() - startTime >= MAX_RETRY_ELAPSED_MS) throw err;
+      }
+    }
+  }
+}