deepline 0.3.461 → 0.3.462

package/dist/bundling-sources/sdk/src/http.ts

@@ -1,1235 +1,10 @@
-/**
- * HTTP transport layer for the Deepline SDK.
- *
- * Handles authentication, retries with exponential backoff, localhost failover
- * (tries both `localhost` and `127.0.0.1`), and structured error mapping.
- *
- * ## Retry behavior
- *
- * - **Max attempts**: `1 + maxRetries` (default: 4 total attempts)
- * - **Backoff**: exponential — 1s, 2s, 4s, 8s, ... capped at 30s
- * - **Total automatic retry wait**: 30s per request; a longer upstream
- *   `Retry-After` is returned to the caller instead of blocking the request
- * - **Retryable**: network errors, timeouts, HTTP 429 (rate limit)
- * - **Not retryable**: HTTP 401 (auth error), HTTP 403 and other 4xx API errors
- *
- * ## Localhost failover
- *
- * Local development hosts try loopback variants. This handles DNS resolution
- * differences across platforms.
- *
- * @module
- */
-import type { ResolvedConfig } from './types';
-import {
-  AuthError,
-  DeeplineError,
-  RateLimitError,
-  ToolExecutionError,
-  ToolRateLimitError,
-} from './errors';
-import {
-  deserializeToolExecutionFailure,
-  serializeToolExecutionFailure,
-  TOOL_EXECUTION_ERROR_SCHEMA_VERSION,
-} from '../../shared_libs/plays/tool-execution-error';
-import { SDK_API_CONTRACT, SDK_VERSION } from './version';
-import { apiErrorCodeFromResponse, apiErrorMessage } from './api-error';
-import type { LiveEventEnvelope } from './types';
-import {
-  agentSessionIdFromEnvironment,
-  detectAgentRuntime,
-  isCoworkLikeSandbox,
-} from './agent-runtime';
+/** HTTP transport with the local SDK skills diagnostic enabled. */
+import { HttpClient as HttpClientCore } from './http-core';
 import { readSdkSkillsLocalVersion } from './skills-version';
-import { deploymentProtectionHeaders } from './deployment-protection';
-import {
-  ABSURD_RELEASE_OVERRIDE_HEADER,
-  RETAINED_PIPELINE_RECEIVERS_HEADER,
-  COORDINATOR_INTERNAL_TOKEN_HEADER,
-  COORDINATOR_URL_OVERRIDE_HEADER,
-  PREFERRED_RECEIPT_GATEWAY_MACHINE_ID_HEADER,
-  RUNTIME_SCHEDULER_SCHEMA_OVERRIDE_HEADER,
-  SYNTHETIC_RUN_HEADER,
-  WORKER_CALLBACK_URL_OVERRIDE_HEADER,
-} from '../../shared_libs/play-runtime/coordinator-headers.js';
-import { PLAY_RUNTIME_TEST_FAULT_HEADER } from '../../shared_libs/play-runtime/test-runtime-seams.js';
-import {
-  EXECUTE_RETRY_POLICY_HEADER,
-  parseExecuteRetryPolicy,
-} from '../../shared_libs/integration-contracts/execute-retry-contract.js';
-
-const MAX_DIAGNOSTIC_HEADER_LENGTH = 120;
-const COWORK_NETWORK_HINT =
-  'Claude Cowork appears to be running Deepline in a network-restricted sandbox. In Claude Desktop, open Settings > Capabilities, turn on Allow network egress, and set Domain allowlist to All domains for the Cowork session.';
-const REQUEST_TIMEOUT_MARKER = Symbol('deeplineRequestTimeout');
-const REQUEST_ABORT_MARKER = Symbol('deeplineRequestAbort');
-const MAX_AUTOMATIC_RETRY_WAIT_MS = 30_000;
-
-interface RequestOptions {
-  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-  body?: unknown;
-  formData?: FormData | (() => FormData);
-  headers?: Record<string, string>;
-  /** Per-request timeout override in milliseconds. */
-  timeout?: number;
-  /** Cancel this request, including body reads, failover, and retry waits. */
-  signal?: AbortSignal;
-  /**
-   * Retry HTTP 408/425/5xx JSON API responses. Use only for idempotent requests;
-   * most mutating API calls must fail loudly after the first server response.
-   */
-  retryApiErrors?: boolean;
-  /**
-   * Only explicit server-authorized responses may retry; transport failures
-   * never retry unless `retryAmbiguousDelivery` is also set.
-   */
-  retryFromExecutePolicy?: boolean;
-  /**
-   * The server declared this tool safe to resend after a timeout or lost
-   * response, so those failures retry and stay retryable when exhausted.
-   */
-  retryAmbiguousDelivery?: boolean;
-  /** Retry budget enabled only by an explicit safe execute-policy response. */
-  executePolicyMaxRetries?: number;
-  /** Per-request retry override. Use 0 for possibly delivered mutating calls. */
-  maxRetries?: number;
-  /** Disable localhost/127.0.0.1 failover for non-idempotent requests. */
-  exactUrlOnly?: boolean;
-  /**
-   * Return a server-owned 429 envelope as a DeeplineError instead of replacing
-   * it with the transport's generic RateLimitError. Lifecycle mutations use
-   * this when their response explains whether the upstream change applied.
-   */
-  preserveRateLimitResponse?: boolean;
-  /** Enables endpoint-specific structured tool failure mapping. */
-  toolId?: string;
-  onResponse?: (response: Response) => void;
-  /** Observation after the entire response body arrives, before error mapping. */
-  onResponseBody?: (observation: {
-    receivedAtMs: number;
-    httpStatus: number;
-    body: unknown;
-  }) => void;
-  allowNotFound?: boolean;
-  idempotencyKey?: string;
-}
-
-interface StreamOptions {
-  method?: 'GET' | 'POST';
-  /** An unkeyed mutation must not try another URL after a lost response. */
-  exactUrlOnly?: boolean;
-  body?: unknown;
-  headers?: Record<string, string>;
-  signal?: AbortSignal;
-}
-
-type RequestAbortTaggedError = Error & {
-  [REQUEST_TIMEOUT_MARKER]?: number;
-  [REQUEST_ABORT_MARKER]?: true;
-};
-
-function requestCancelledError(signal: AbortSignal): RequestAbortTaggedError {
-  const error = withErrorCause(new Error('Request aborted'), signal.reason);
-  (error as RequestAbortTaggedError)[REQUEST_ABORT_MARKER] = true;
-  return error;
-}
-
-function normalizeRequestAbortError(
-  error: unknown,
-  input: { timeoutMs: number; timedOut: boolean },
-): Error {
-  const normalized = error instanceof Error ? error : new Error(String(error));
-  const tagged = normalized as RequestAbortTaggedError;
-  if (input.timedOut) {
-    tagged[REQUEST_TIMEOUT_MARKER] = input.timeoutMs;
-  } else if (isAbortLikeError(normalized)) {
-    tagged[REQUEST_ABORT_MARKER] = true;
-  }
-  return normalized;
-}
-
-/**
- * Merge caller-supplied headers over everything the transport already derived
- * from the environment, so an explicitly passed header always wins.
- *
- * HTTP header names are case-insensitive, so an existing header is removed by
- * case-insensitive match before the incoming name is set. Without
- * that, `Authorization` and `authorization` would both survive into the record
- * and `new Headers(record)` would concatenate the two values.
- */
-function applyExplicitHeaders(
-  headers: Record<string, string>,
-  explicit: Record<string, string> | undefined,
-): Record<string, string> {
-  if (!explicit) return headers;
-  for (const [rawName, value] of Object.entries(explicit)) {
-    const name = rawName.trim().toLowerCase();
-    if (!name) continue;
-    for (const existing of Object.keys(headers)) {
-      if (existing.toLowerCase() === name) delete headers[existing];
-    }
-    headers[rawName.trim()] = value;
-  }
-  return headers;
-}
-
-function isAbortLikeError(error: Error): boolean {
-  const name = error.name.toLowerCase();
-  const message = error.message.toLowerCase();
-  return (
-    name === 'aborterror' ||
-    message.includes('operation was aborted') ||
-    message === 'aborted'
-  );
-}
-
-function withErrorCause<T extends Error>(error: T, cause: unknown): T {
-  if (cause !== null && cause !== undefined) {
-    Object.defineProperty(error, 'cause', {
-      value: cause,
-      configurable: true,
-      writable: true,
-    });
-  }
-  return error;
-}
-
-function mapNetworkError(
-  baseUrl: string,
-  error: Error | null,
-  targetLabel: string,
-): {
-  message: string;
-  code: string;
-  details?: Record<string, unknown>;
-} {
-  const tagged = error as RequestAbortTaggedError | null;
-  const timeoutMs = tagged?.[REQUEST_TIMEOUT_MARKER];
-  if (typeof timeoutMs === 'number') {
-    return {
-      message: `Request to ${targetLabel} timed out after ${timeoutMs}ms while waiting for a response.`,
-      code: 'NETWORK_TIMEOUT',
-      details: { timeoutMs, target: targetLabel },
-    };
-  }
-  if (tagged?.[REQUEST_ABORT_MARKER]) {
-    return {
-      message: `Request to ${targetLabel} was aborted before it completed.`,
-      code: 'NETWORK_ABORTED',
-    };
-  }
-  return {
-    message: error?.message
-      ? `Unable to connect to ${baseUrl}. ${error.message}`
-      : `Unable to connect to ${baseUrl}. Is the computer able to access the url?`,
-    code: 'NETWORK_ERROR',
-  };
-}
-
-function describeRequestTarget(path: string): string {
-  const toolExecuteMatch = path.match(
-    /^\/api\/v2\/integrations\/([^/?#]+)\/execute(?:[/?#]|$)/,
-  );
-  if (toolExecuteMatch) {
-    return providerLabelFromToolId(decodeURIComponent(toolExecuteMatch[1]));
-  }
-  return 'Deepline';
-}
-
-function networkDiagnosticUrl(value: string): string | undefined {
-  try {
-    const url = new URL(value);
-    if (url.protocol !== 'https:' && url.protocol !== 'http:') return undefined;
-    // Diagnostics never retain URL credentials, query values, or fragments.
-    return `${url.origin}${url.pathname}`;
-  } catch {
-    // Preserve the original transport failure for malformed request URLs.
-    return undefined;
-  }
-}
-
-function providerLabelFromToolId(toolId: string): string {
-  const normalized = toolId.trim().toLowerCase();
-  const provider = normalized.split(/[_:./-]+/)[0];
-  return provider || normalized || 'provider';
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-
-/**
- * Low-level HTTP client used internally by {@link DeeplineClient}.
- *
- * You typically don't construct this directly — it's created automatically
- * when you instantiate `DeeplineClient` or call `Deepline.connect()`.
- *
- * @example
- * ```typescript
- * // Internal usage pattern:
- * const http = new HttpClient(resolvedConfig);
- * const tools = await http.get<{ tools: ToolDefinition[] }>('/api/v2/tools');
- * const result = await http.post('/api/v2/integrations/apollo/execute', { payload: input });
- * ```
- */
-export class HttpClient {
-  constructor(private config: ResolvedConfig) {}
-
-  private cleanDiagnosticHeader(
-    value: string | null | undefined,
-  ): string | null {
-    const normalized = String(value ?? '')
-      .replace(/[\u0000-\u001f\u007f]/g, ' ')
-      .trim()
-      .slice(0, MAX_DIAGNOSTIC_HEADER_LENGTH);
-    return normalized || null;
-  }
-
-  private environment(): Readonly<Record<string, string | undefined>> {
-    return (
-      this.config.environment ??
-      (typeof process !== 'undefined' ? process.env : {})
-    );
-  }
-
-  private readSkillsVersionHeader(): string | null {
-    const explicit = this.cleanDiagnosticHeader(
-      this.environment().DEEPLINE_SKILLS_VERSION,
-    );
-    if (explicit) return explicit;
-    try {
-      return this.cleanDiagnosticHeader(
-        readSdkSkillsLocalVersion(this.config.baseUrl),
-      );
-    } catch {
-      return null;
-    }
-  }
-
-  private authHeaders(extra?: Record<string, string>): Record<string, string> {
-    const env = this.environment();
-    const transportHeaders: Record<string, string> = {
-      Authorization: `Bearer ${this.config.apiKey}`,
-      'User-Agent': `deepline-ts-sdk/${SDK_VERSION}`,
-      'X-Deepline-Client-Family': 'sdk',
-      'X-Deepline-CLI-Family': 'sdk',
-      'X-Deepline-Agent-Runtime': detectAgentRuntime(
-        this.config.environment ? { env, detectCowork: false } : {},
-      ),
-      'X-Deepline-CLI-Version': SDK_VERSION,
-      'X-Deepline-SDK-Version': SDK_VERSION,
-      'X-Deepline-API-Contract': SDK_API_CONTRACT,
-      'X-Deepline-Run-Result-Shape': 'canonical',
-    };
-    const headers = deploymentProtectionHeaders(env);
-    const skillsVersion = this.readSkillsVersionHeader();
-    if (skillsVersion) {
-      headers['X-Deepline-Skills-Version'] = skillsVersion;
-    }
-    const agentSessionId = agentSessionIdFromEnvironment(env);
-    if (agentSessionId) {
-      headers['X-Deepline-Agent-Session-Id'] = agentSessionId;
-    }
-    const playArtifactR2Prefix = env.DEEPLINE_PLAY_ARTIFACT_R2_PREFIX;
-    if (playArtifactR2Prefix) {
-      headers['x-deepline-play-artifact-r2-prefix'] = playArtifactR2Prefix;
-    }
-    const coordinatorUrl = env.DEEPLINE_COORDINATOR_URL;
-    const coordinatorInternalToken = env.DEEPLINE_INTERNAL_TOKEN;
-    const absurdReleaseOverride = env.DEEPLINE_ABSURD_RELEASE;
-    const preferredReceiptGatewayMachineId =
-      env.DEEPLINE_PREFERRED_RECEIPT_GATEWAY_MACHINE_ID;
-    if (coordinatorUrl?.trim()) {
-      headers[COORDINATOR_URL_OVERRIDE_HEADER] = coordinatorUrl.trim();
-    }
-    const workerCallbackUrl = env.DEEPLINE_WORKER_CALLBACK_URL;
-    if (workerCallbackUrl?.trim()) {
-      headers[WORKER_CALLBACK_URL_OVERRIDE_HEADER] = workerCallbackUrl.trim();
-    }
-    const runtimeSchedulerSchema = env.DEEPLINE_RUNTIME_SCHEDULER_SCHEMA;
-    if (runtimeSchedulerSchema?.trim()) {
-      headers[RUNTIME_SCHEDULER_SCHEMA_OVERRIDE_HEADER] =
-        runtimeSchedulerSchema.trim();
-    }
-    // Automated test harnesses (e.g. tests/gauntlet-e2e-tests) set DEEPLINE_SYNTHETIC_RUN
-    // so their intentionally failing plays do not page the SDK CLI error
-    // channel. Honored server-side only in non-prod (see plays/run route).
-    const syntheticRun = env.DEEPLINE_SYNTHETIC_RUN;
-    if (syntheticRun && syntheticRun.trim() && syntheticRun.trim() !== '0') {
-      headers[SYNTHETIC_RUN_HEADER] = '1';
-    }
-    // Test-only runtime seam. The server validates both environment and value
-    // before honoring this header.
-    const runtimeTestFault = env.DEEPLINE_TEST_RUNTIME_FAULT;
-    if (runtimeTestFault?.trim()) {
-      headers[PLAY_RUNTIME_TEST_FAULT_HEADER] = runtimeTestFault.trim();
-    }
-    const retainedReceivers =
-      env.DEEPLINE_RUNTIME_RETAINED_PIPELINE_RECEIVERS?.trim();
-    if (retainedReceivers && coordinatorInternalToken?.trim()) {
-      headers[RETAINED_PIPELINE_RECEIVERS_HEADER] = retainedReceivers;
-      headers[COORDINATOR_INTERNAL_TOKEN_HEADER] =
-        coordinatorInternalToken.trim();
-    }
-    if (absurdReleaseOverride?.trim() && coordinatorInternalToken?.trim()) {
-      headers[ABSURD_RELEASE_OVERRIDE_HEADER] = absurdReleaseOverride.trim();
-    }
-    if (
-      preferredReceiptGatewayMachineId?.trim() &&
-      coordinatorInternalToken?.trim()
-    ) {
-      headers[PREFERRED_RECEIPT_GATEWAY_MACHINE_ID_HEADER] =
-        preferredReceiptGatewayMachineId.trim();
-    }
-    if (
-      coordinatorInternalToken?.trim() &&
-      (coordinatorUrl?.trim() ||
-        workerCallbackUrl?.trim() ||
-        runtimeTestFault?.trim() ||
-        absurdReleaseOverride?.trim() ||
-        preferredReceiptGatewayMachineId?.trim())
-    ) {
-      headers[COORDINATOR_INTERNAL_TOKEN_HEADER] =
-        coordinatorInternalToken.trim();
-    }
-    // Explicit client-option headers (e.g. `deepline plays run --header`) are
-    // applied last so an operator can override an env-derived header without
-    // rewriting the environment. Authorization of these headers stays
-    // server-side.
-    // Preserve layer precedence without leaving differently-cased duplicates
-    // for Fetch to concatenate. Environment-derived headers still supersede
-    // per-request headers, and explicit client-option headers remain last.
-    return applyExplicitHeaders(
-      applyExplicitHeaders(
-        applyExplicitHeaders(transportHeaders, extra),
-        headers,
-      ),
-      this.config.headers,
-    );
-  }
-
-  /**
-   * Send an HTTP request with automatic retries and error handling.
-   *
-   * @typeParam T - Expected response body type
-   * @param path - API path (e.g. `"/api/v2/tools"`)
-   * @param options - HTTP method, body, headers, and timeout
-   * @returns Parsed JSON response body
-   * @throws {@link AuthError} on Deepline-auth HTTP 401/403 (immediate, no retry)
-   * @throws {@link RateLimitError} on HTTP 429 after all retries exhausted
-   * @throws {@link DeeplineError} on other API errors or connection failures
-   */
-  async request<T = unknown>(
-    path: string,
-    options?: RequestOptions,
-  ): Promise<T> {
-    const baseUrl = this.config.baseUrl;
-    const url = `${baseUrl}${path}`;
-    const method = options?.method ?? 'GET';
-    const requestStartedAt = Date.now();
-    let fetchAttempts = 0;
-    let lastRequestUrl = url;
-    let networkFailedAt: number | undefined;
-    let networkPhase:
-      | 'before_request'
-      | 'retry_wait'
-      | 'awaiting_headers'
-      | 'reading_body' = 'before_request';
-
-    const headers = this.authHeaders(options?.headers);
-
-    if (options?.body !== undefined) {
-      applyExplicitHeaders(headers, { 'Content-Type': 'application/json' });
-    }
-
-    let lastError: Error | null = null;
-    const candidateUrls = options?.exactUrlOnly
-      ? [url]
-      : buildCandidateUrls(url);
-    let retryAfterDelayMs: number | null = null;
-    let totalRetryWaitMs = 0;
-
-    let maxRetries = options?.maxRetries ?? this.config.maxRetries;
-
-    requestAttempts: for (let attempt = 0; attempt <= maxRetries; attempt++) {
-      if (options?.signal?.aborted) {
-        lastError = requestCancelledError(options.signal);
-        networkFailedAt = Date.now();
-        break;
-      }
-      if (attempt > 0) {
-        const backoffMs = Math.min(1000 * Math.pow(2, attempt - 1), 30_000);
-        const delayMs =
-          retryAfterDelayMs === null
-            ? backoffMs
-            : Math.max(backoffMs, retryAfterDelayMs);
-        retryAfterDelayMs = null;
-        if (totalRetryWaitMs + delayMs > MAX_AUTOMATIC_RETRY_WAIT_MS) {
-          // Honor the upstream delay by returning its original error. Never
-          // retry sooner than requested, and never let automatic retries hold
-          // the caller for an unbounded series of Retry-After sleeps.
-          break requestAttempts;
-        }
-        totalRetryWaitMs += delayMs;
-        networkPhase = 'retry_wait';
-        try {
-          await sleep(delayMs, options?.signal);
-        } catch (error) {
-          lastError = error instanceof Error ? error : new Error(String(error));
-          networkFailedAt = Date.now();
-          break;
-        }
-      }
-
-      for (const candidateUrl of candidateUrls) {
-        if (options?.signal?.aborted) {
-          lastError = requestCancelledError(options.signal);
-          networkFailedAt = Date.now();
-          break requestAttempts;
-        }
-        const controller = new AbortController();
-        const timeoutMs = options?.timeout ?? this.config.timeout;
-        let requestTimedOut = false;
-        const timeoutId = setTimeout(() => {
-          requestTimedOut = true;
-          controller.abort();
-        }, timeoutMs);
-        const abortRequest = () => controller.abort();
-        options?.signal?.addEventListener('abort', abortRequest, {
-          once: true,
-        });
-
-        networkPhase = 'before_request';
-        try {
-          const requestBody =
-            options?.formData !== undefined
-              ? typeof options.formData === 'function'
-                ? options.formData()
-                : options.formData
-              : options?.body !== undefined
-                ? JSON.stringify(options.body)
-                : undefined;
-          fetchAttempts += 1;
-          lastRequestUrl = candidateUrl;
-          networkPhase = 'awaiting_headers';
-          const response = await fetch(candidateUrl, {
-            method,
-            headers,
-            body: requestBody,
-            signal: controller.signal,
-          });
-
-          networkPhase = 'reading_body';
-          options?.onResponse?.(response);
-          if (response.status === 404 && options?.allowNotFound) {
-            clearTimeout(timeoutId);
-            return null as T;
-          }
-
-          // Receiving headers is not completion: a stalled response body must
-          // remain inside the same request deadline and abort its connection.
-          const body = await response.text();
-          const receivedAtMs = Date.now();
-          clearTimeout(timeoutId);
-          const parsed = parseResponseBody(body);
-          options?.onResponseBody?.({
-            receivedAtMs,
-            httpStatus: response.status,
-            body: parsed,
-          });
-          const responseRetryAllowed =
-            options?.retryFromExecutePolicy !== true ||
-            parseExecuteRetryPolicy(
-              response.headers.get(EXECUTE_RETRY_POLICY_HEADER),
-            ) === 'transient-http-safe';
-          if (
-            options?.retryFromExecutePolicy === true &&
-            responseRetryAllowed &&
-            options.executePolicyMaxRetries !== undefined
-          ) {
-            maxRetries = options.executePolicyMaxRetries;
-          }
-
-          const structuredToolError =
-            options?.toolId && !response.ok
-              ? deserializeToolExecutionFailure(
-                  apiErrorMessage(parsed, response.status),
-                  isRecord(parsed)
-                    ? (parsed as Record<string, unknown>).tool_error
-                    : null,
-                  TOOL_EXECUTION_ERROR_SCHEMA_VERSION,
-                )
-              : null;
-          if (structuredToolError) {
-            if (response.status === 429) {
-              const retryAfter = parseRetryAfter(response);
-              const failure =
-                serializeToolExecutionFailure(structuredToolError);
-              lastError =
-                failure === null
-                  ? structuredToolError
-                  : new ToolRateLimitError(structuredToolError.message, {
-                      ...failure,
-                      retryAfterMs:
-                        failure.retryAfterMs ?? Math.max(0, retryAfter),
-                    });
-              if (responseRetryAllowed && attempt < maxRetries) {
-                retryAfterDelayMs = retryAfter;
-                break;
-              }
-              throw lastError;
-            }
-            throw structuredToolError;
-          }
-
-          if (response.status === 429) {
-            if (
-              options?.preserveRateLimitResponse &&
-              isMonitorRateLimitEnvelope(parsed)
-            ) {
-              throw new DeeplineError(
-                apiErrorMessage(parsed, response.status),
-                response.status,
-                apiErrorCodeFromResponse(parsed),
-                { response: parsed },
-              );
-            }
-            const retryAfter = parseRetryAfter(response);
-            lastError = new RateLimitError(retryAfter);
-            if (responseRetryAllowed && attempt < maxRetries) {
-              retryAfterDelayMs = retryAfter;
-              break;
-            }
-            throw lastError;
-          }
-
-          if (
-            response.status === 401 &&
-            !isProviderOriginatedHttpError(parsed)
-          ) {
-            throw new AuthError(apiErrorMessage(parsed, response.status));
-          }
-          if (!response.ok) {
-            const retryableApiError =
-              options?.retryApiErrors === true &&
-              responseRetryAllowed &&
-              isRetryableApiErrorResponse(response.status);
-            // A 5xx that escaped a Worker can return Cloudflare's default HTML
-            // error page. Never surface raw HTML to CLI users: replace the
-            // message with a structured summary and store a short flag in
-            // details instead of the full HTML body. JSON-envelope handling
-            // below is unchanged.
-            const htmlError = detectHtmlErrorBody(
-              body,
-              response.headers.get('content-type'),
-            );
-            if (htmlError) {
-              lastError = new DeeplineError(
-                htmlError.message(response.status),
-                response.status,
-                'API_ERROR',
-                {
-                  htmlErrorPage: true,
-                  ...(htmlError.title ? { title: htmlError.title } : {}),
-                  ...(htmlError.workerThrewException
-                    ? { workerThrewException: true }
-                    : {}),
-                },
-              );
-              if (retryableApiError && attempt < maxRetries) {
-                retryAfterDelayMs = parseOptionalRetryAfter(response);
-                break;
-              }
-              throw lastError;
-            }
-            const errorValue =
-              typeof parsed === 'object' && parsed && 'error' in parsed
-                ? (parsed as Record<string, unknown>).error
-                : undefined;
-            const msg =
-              typeof errorValue === 'string'
-                ? errorValue
-                : errorValue &&
-                    typeof errorValue === 'object' &&
-                    'message' in errorValue &&
-                    typeof (errorValue as Record<string, unknown>).message ===
-                      'string'
-                  ? (errorValue as Record<string, string>).message
-                  : typeof parsed === 'object' &&
-                      parsed &&
-                      'message' in parsed &&
-                      typeof (parsed as Record<string, unknown>).message ===
-                        'string'
-                    ? (parsed as Record<string, string>).message
-                    : `HTTP ${response.status}`;
-            const apiErrorCode = apiErrorCodeFromResponse(parsed);
-            lastError = new DeeplineError(msg, response.status, apiErrorCode, {
-              response: parsed,
-            });
-            if (retryableApiError && attempt < maxRetries) {
-              retryAfterDelayMs = parseOptionalRetryAfter(response);
-              break;
-            }
-            throw lastError;
-          }
-
-          // Vercel's deployment-protection interstitial is served as a 2xx
-          // HTML page, so it never reaches the !ok branch above. Without this
-          // the caller receives a string where it expected JSON and reports
-          // whatever field it found missing — an expired `vercel login` shows
-          // up as an unrelated validation error several layers away.
-          if (typeof parsed === 'string') {
-            const interstitial = detectHtmlErrorBody(
-              body,
-              response.headers.get('content-type'),
-            );
-            if (interstitial) {
-              throw new DeeplineError(
-                `${this.config.baseUrl} returned a deployment-protection page ` +
-                  'instead of JSON. Set VERCEL_PROTECTION_BYPASS_TOKEN, or run ' +
-                  '`vercel login` if the CLI session expired.',
-                response.status,
-                'DEPLOYMENT_PROTECTED',
-                { htmlErrorPage: true },
-              );
-            }
-          }
-
-          return parsed as T;
-        } catch (error) {
-          clearTimeout(timeoutId);
-          networkFailedAt = Date.now();
-          if (options?.signal?.aborted) {
-            lastError = requestCancelledError(options.signal);
-            break requestAttempts;
-          }
-          if (error instanceof AuthError || error instanceof DeeplineError) {
-            throw error;
-          }
-          if (error instanceof RateLimitError) {
-            lastError = error;
-            break;
-          }
-          lastError = normalizeRequestAbortError(error, {
-            timeoutMs,
-            timedOut: requestTimedOut,
-          });
-          if (
-            options?.retryFromExecutePolicy &&
-            options.retryAmbiguousDelivery !== true
-          ) {
-            break requestAttempts;
-          }
-        } finally {
-          clearTimeout(timeoutId);
-          options?.signal?.removeEventListener('abort', abortRequest);
-        }
-      }
-
-      if (attempt < maxRetries) continue;
-    }
-
-    if (lastError instanceof DeeplineError) {
-      throw lastError;
-    }
-    const mappedNetworkError = mapNetworkError(
-      baseUrl,
-      lastError,
-      describeRequestTarget(path),
-    );
-    const failedAt = networkFailedAt ?? Date.now();
-    const diagnosticUrl = networkDiagnosticUrl(lastRequestUrl);
-    const networkDetails = {
-      ...mappedNetworkError.details,
-      request: {
-        method,
-        ...(diagnosticUrl === undefined ? {} : { url: diagnosticUrl }),
-        failedAtUtc: new Date(failedAt).toISOString(),
-        // Elapsed time covers the entire logical request, including retries.
-        elapsedMs: Math.max(0, failedAt - requestStartedAt),
-        attempts: fetchAttempts,
-        phase: networkPhase,
-      },
-    };
-    if (options?.toolId) {
-      const code = mappedNetworkError.code;
-      throw withErrorCause(
-        new ToolExecutionError(
-          withCoworkNetworkHint(mappedNetworkError.message),
-          {
-            toolId: options.toolId,
-            provider: providerLabelFromToolId(options.toolId),
-            operation: options.toolId,
-            code,
-            origin: 'deepline',
-            category: 'network',
-            // A direct client timeout has ambiguous delivery. Fail closed unless
-            // the server returns the authoritative action delivery contract.
-            retryable: options.retryAmbiguousDelivery === true,
-            statusCode: null,
-            requestId: null,
-            retryAfterMs: null,
-            networkKind:
-              code === 'NETWORK_TIMEOUT'
-                ? 'timeout'
-                : code === 'NETWORK_ABORTED'
-                  ? 'unknown'
-                  : 'unavailable',
-            networkScope: 'client_to_deepline',
-            details: networkDetails,
-            publicDetails: options.idempotencyKey
-              ? { idempotencyKey: options.idempotencyKey }
-              : null,
-          },
-        ),
-        lastError,
-      );
-    }
-    throw withErrorCause(
-      new DeeplineError(
-        withCoworkNetworkHint(mappedNetworkError.message),
-        undefined,
-        mappedNetworkError.code,
-        networkDetails,
-      ),
-      lastError,
-    );
-  }
-
-  /**
-   * Send a GET request.
-   *
-   * @typeParam T - Expected response body type
-   * @param path - API path (e.g. `"/api/v2/tools"`)
-   */
-  async get<T = unknown>(
-    path: string,
-    options?: Pick<
-      RequestOptions,
-      | 'retryApiErrors'
-      | 'timeout'
-      | 'signal'
-      | 'maxRetries'
-      | 'exactUrlOnly'
-      | 'toolId'
-      | 'onResponse'
-      | 'onResponseBody'
-      | 'allowNotFound'
-      | 'idempotencyKey'
-      | 'headers'
-    >,
-  ): Promise<T> {
-    return this.request<T>(path, {
-      method: 'GET',
-      retryApiErrors: true,
-      ...options,
-    });
-  }
-
-  async *streamSse<TEvent extends LiveEventEnvelope = LiveEventEnvelope>(
-    path: string,
-    options?: StreamOptions,
-  ): AsyncGenerator<TEvent> {
-    const url = `${this.config.baseUrl}${path}`;
-    const method = options?.method ?? 'GET';
-    const headers = this.authHeaders({
-      Accept: 'text/event-stream',
-      ...options?.headers,
-    });
-    if (options?.body !== undefined) {
-      applyExplicitHeaders(headers, { 'Content-Type': 'application/json' });
-    }
-    let lastError: Error | null = null;
-
-    const candidateUrls = options?.exactUrlOnly
-      ? [url]
-      : buildCandidateUrls(url);
-    for (const candidateUrl of candidateUrls) {
-      try {
-        const response = await fetch(candidateUrl, {
-          method,
-          headers,
-          body:
-            options?.body !== undefined
-              ? JSON.stringify(options.body)
-              : undefined,
-          signal: options?.signal,
-        });
-
-        if (!response.ok) {
-          const body = await response.text();
-          const parsed = parseResponseBody(body);
-          if (
-            response.status === 401 &&
-            !isProviderOriginatedHttpError(parsed)
-          ) {
-            throw new AuthError(apiErrorMessage(parsed, response.status));
-          }
-          const htmlError = detectHtmlErrorBody(
-            body,
-            response.headers.get('content-type'),
-          );
-          if (htmlError) {
-            throw new DeeplineError(
-              htmlError.message(response.status),
-              response.status,
-              'API_ERROR',
-              {
-                htmlErrorPage: true,
-                ...(htmlError.title ? { title: htmlError.title } : {}),
-                ...(htmlError.workerThrewException
-                  ? { workerThrewException: true }
-                  : {}),
-              },
-            );
-          }
-          throw new DeeplineError(
-            apiErrorMessage(parsed, response.status),
-            response.status,
-            apiErrorCodeFromResponse(parsed),
-            { response: parsed },
-          );
-        }
-        if (!response.body) {
-          throw new DeeplineError('SSE response did not include a body.');
-        }
-
-        yield* decodeSseStream<TEvent>(response.body);
-        return;
-      } catch (error) {
-        if (error instanceof AuthError || error instanceof DeeplineError) {
-          throw error;
-        }
-        const normalized =
-          error instanceof Error ? error : new Error(String(error));
-        if (isAbortLikeError(normalized) && options?.signal?.aborted) {
-          throw new DeeplineError(
-            `Stream from ${this.config.baseUrl} was aborted by the caller.`,
-            undefined,
-            'ABORTED',
-          );
-        }
-        lastError = normalized;
-      }
-    }
-
-    if (lastError && isAbortLikeError(lastError)) {
-      throw new DeeplineError(
-        withCoworkNetworkHint(
-          `Unable to stream from ${this.config.baseUrl}. The remote stream was interrupted.`,
-        ),
-        undefined,
-        'PLAY_STREAM_NETWORK_ABORTED',
-      );
-    }
-    throw new DeeplineError(
-      withCoworkNetworkHint(
-        lastError?.message
-          ? `Unable to stream from ${this.config.baseUrl}. ${lastError.message}`
-          : `Unable to stream from ${this.config.baseUrl}.`,
-      ),
-    );
-  }
-
-  /**
-   * Send a POST request with a JSON body.
-   *
-   * @typeParam T - Expected response body type
-   * @param path - API path
-   * @param body - Request body (will be JSON-serialized)
-   */
-  async post<T = unknown>(
-    path: string,
-    body: unknown,
-    headers?: Record<string, string>,
-    options?: Pick<
-      RequestOptions,
-      | 'retryApiErrors'
-      | 'retryFromExecutePolicy'
-      | 'retryAmbiguousDelivery'
-      | 'executePolicyMaxRetries'
-      | 'timeout'
-      | 'signal'
-      | 'maxRetries'
-      | 'exactUrlOnly'
-      | 'toolId'
-      | 'onResponse'
-      | 'onResponseBody'
-      | 'allowNotFound'
-      | 'idempotencyKey'
-    >,
-  ): Promise<T> {
-    return this.request<T>(path, {
-      method: 'POST',
-      body,
-      headers,
-      ...options,
-    });
-  }
-
-  async postFormData<T = unknown>(
-    path: string,
-    formData: FormData | (() => FormData),
-    headers?: Record<string, string>,
-  ): Promise<T> {
-    return this.request<T>(path, {
-      method: 'POST',
-      formData,
-      headers,
-    });
-  }
-
-  /**
-   * Send a PATCH request with a JSON body.
-   *
-   * @typeParam T - Expected response body type
-   * @param path - API path
-   * @param body - JSON-serializable request body
-   */
-  async patch<T = unknown>(
-    path: string,
-    body?: unknown,
-    headers?: Record<string, string>,
-  ): Promise<T> {
-    return this.request<T>(path, {
-      method: 'PATCH',
-      body,
-      headers,
-    });
-  }
-
-  async put<T = unknown>(
-    path: string,
-    body?: unknown,
-    headers?: Record<string, string>,
-  ): Promise<T> {
-    return this.request<T>(path, { method: 'PUT', body, headers });
-  }
-
-  /**
-   * Send a DELETE request.
-   *
-   * @typeParam T - Expected response body type
-   * @param path - API path
-   */
-  async delete<T = unknown>(path: string): Promise<T> {
-    return this.request<T>(path, { method: 'DELETE' });
-  }
-}
-
-function parseResponseBody(body: string): unknown {
-  try {
-    return JSON.parse(body);
-  } catch {
-    return body;
-  }
-}
-
-/**
- * A provider can reject its own credential with HTTP 401 while the caller's
- * Deepline API key remains valid. The API envelope is authoritative in that
- * case, so preserve it as a regular DeeplineError rather than prompting the
- * caller to replace DEEPLINE_API_KEY.
- */
-function isProviderOriginatedHttpError(parsed: unknown): boolean {
-  const response = asRecord(parsed);
-  const error = asRecord(response?.error);
-  const failureOrigin = error?.failure_origin ?? response?.failure_origin;
-  const code = error?.code ?? response?.code;
-  return failureOrigin === 'provider' || code === 'UPSTREAM_BLOCKED';
-}
-
-/**
- * A monitor deployment may receive a safe, actionable 429 from Deepline after
- * an upstream lifecycle attempt. Do not treat a CDN/WAF 429 as that envelope:
- * it can be arbitrary HTML or text and must retain normal RateLimitError
- * behavior.
- */
-function isMonitorRateLimitEnvelope(parsed: unknown): boolean {
-  const response = asRecord(parsed);
-  const error = asRecord(response?.error);
-  return (
-    (error?.code === 'monitor_upstream_rate_limited' ||
-      error?.code === 'monitor_preview_rate_limited') &&
-    typeof error.message === 'string'
-  );
-}
-
-function asRecord(value: unknown): Record<string, unknown> | null {
-  return typeof value === 'object' && value !== null
-    ? (value as Record<string, unknown>)
-    : null;
-}
-
-function isRetryableApiErrorResponse(status: number): boolean {
-  return status === 408 || status === 425 || (status >= 500 && status < 600);
-}
-
-/**
- * Detect a raw Cloudflare HTML error page in an error response body.
- *
- * A 5xx that escaped a Worker can return Cloudflare's default HTML error page
- * ("Worker threw exception" / error code 1042). We must never surface raw HTML
- * to CLI users — it lands verbatim in `DeeplineError.message`/`details`. When
- * detected, we synthesize a structured message (status + extracted <title>) and
- * preserve the literal token `Worker threw exception` when present, since SDK
- * retry classifiers (`isTransientPlayRunReadError`) regex-match on it.
- */
-function detectHtmlErrorBody(
-  body: string,
-  contentType?: string | null,
-): {
-  title?: string;
-  workerThrewException: boolean;
-  message: (status: number) => string;
-} | null {
-  const trimmed = body.trim();
-  const lower = trimmed.toLowerCase();
-  const isHtml =
-    (contentType ?? '').toLowerCase().includes('text/html') ||
-    lower.startsWith('<!doctype') ||
-    lower.startsWith('<html');
-  if (!isHtml) {
-    return null;
-  }
-  const titleMatch = trimmed.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
-  const title = titleMatch?.[1]?.replace(/\s+/g, ' ').trim() || undefined;
-  const workerThrewException = /worker threw exception/i.test(trimmed);
-  return {
-    title,
-    workerThrewException,
-    message: (status: number): string => {
-      // Detail segments joined with ': ', then the suppression note appended
-      // in parens so it never reads as another colon-delimited segment.
-      const segments = [`HTTP ${status}`];
-      if (workerThrewException) {
-        segments.push('Worker threw exception');
-      }
-      if (title) {
-        segments.push(title);
-      }
-      return `${segments.join(': ')} (Cloudflare HTML error page suppressed)`;
-    },
-  };
-}
-
-/** Parse the `Retry-After` header as milliseconds. Falls back to 5000ms. */
-function parseRetryAfter(response: Response): number {
-  return parseOptionalRetryAfter(response) ?? 5000;
-}
-
-function parseOptionalRetryAfter(response: Response): number | null {
-  const header = response.headers.get('retry-after');
-  if (header) {
-    const seconds = Number(header);
-    if (Number.isFinite(seconds) && seconds > 0) {
-      return seconds * 1000;
-    }
-  }
-  return null;
-}
-
-/**
- * For local development URLs, generate loopback variants to handle platform DNS
- * differences.
- */
-function buildCandidateUrls(url: string): string[] {
-  try {
-    const parsed = new URL(url);
-    const candidates = [url];
-    if (parsed.hostname === 'localhost') {
-      const loopback = new URL(url);
-      loopback.hostname = '127.0.0.1';
-      candidates.push(loopback.toString());
-    }
-    return [...new Set(candidates)];
-  } catch {
-    return [url];
-  }
-}
-
-async function* decodeSseStream<TEvent extends LiveEventEnvelope>(
-  body: ReadableStream<Uint8Array>,
-): AsyncGenerator<TEvent> {
-  const reader = body.getReader();
-  const decoder = new TextDecoder();
-  let buffered = '';
-
-  try {
-    while (true) {
-      const { value, done } = await reader.read();
-      if (done) break;
-      buffered += decoder.decode(value, { stream: true });
-      const frames = buffered.split(/\r?\n\r?\n/);
-      buffered = frames.pop() ?? '';
-      for (const frame of frames) {
-        const event = decodeSseFrame<TEvent>(frame);
-        if (event) {
-          yield event;
-        }
-      }
-    }
-
-    buffered += decoder.decode();
-    const event = decodeSseFrame<TEvent>(buffered);
-    if (event) {
-      yield event;
-    }
-  } finally {
-    reader.releaseLock();
-  }
-}
-
-function decodeSseFrame<TEvent extends LiveEventEnvelope>(
-  frame: string,
-): TEvent | null {
-  const data = frame
-    .split(/\r?\n/)
-    .filter((line) => line.startsWith('data:'))
-    .map((line) => line.slice('data:'.length).trimStart())
-    .join('\n')
-    .trim();
-  if (!data) {
-    return null;
-  }
-  const parsed = JSON.parse(data) as Partial<LiveEventEnvelope>;
-  if (
-    !parsed ||
-    typeof parsed !== 'object' ||
-    typeof parsed.cursor !== 'string' ||
-    typeof parsed.streamId !== 'string' ||
-    typeof parsed.scope !== 'string' ||
-    typeof parsed.type !== 'string' ||
-    typeof parsed.at !== 'string'
-  ) {
-    return null;
-  }
-  return parsed as TEvent;
-}
-
-function sleep(ms: number, signal?: AbortSignal): Promise<void> {
-  return new Promise((resolve, reject) => {
-    if (signal?.aborted) {
-      reject(requestCancelledError(signal));
-      return;
-    }
-    const timeoutId = setTimeout(() => {
-      signal?.removeEventListener('abort', abort);
-      resolve();
-    }, ms);
-    const abort = () => {
-      clearTimeout(timeoutId);
-      signal?.removeEventListener('abort', abort);
-      reject(requestCancelledError(signal!));
-    };
-    signal?.addEventListener('abort', abort, { once: true });
-  });
-}
+import type { ResolvedConfig } from './types';
 
-function withCoworkNetworkHint(message: string): string {
-  if (!isCoworkLikeSandbox() || message.includes(COWORK_NETWORK_HINT)) {
-    return message;
+export class HttpClient extends HttpClientCore {
+  constructor(config: ResolvedConfig) {
+    super(config, readSdkSkillsLocalVersion);
   }
-  return `${message}\n${COWORK_NETWORK_HINT}`;
 }