Skip to content

Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors

43.7 KB
Raw Blame
import { hasTrustedEmptyTurn } from "./emptyTurnPolicy.ts";
import { createCompletionDrain } from "./streamCompletionDrain.ts";
import type { StreamControllerOptions } from "./streamControllerTypes.ts";
import { trackPendingRequest } from "@/lib/usageDb";
import { STREAM_ACTIVE_TIMEOUT_MS, STREAM_IDLE_TIMEOUT_MS } from "../config/constants.ts";
import { FORMATS } from "../translator/formats.ts";
import { buildErrorBody } from "./error.ts";
import { PENDING_REQUEST_CLEARED_MARKER } from "./stream.ts";
import { createCompletedResponsesToolHandoffWatcher } from "./responsesToolHandoff.ts";
import { createStreamContentWatcher, type StreamContentWatcher } from "./streamReadiness.ts";
import { hasOpenReasoning } from "./emptyTurnRetry.ts";
import { createStallWatchdog } from "./streamStallWatchdog.ts";
import {
  buildSyntheticResponsesFailureId,
  SYNTHETIC_RESPONSES_SEQUENCE_NUMBER,
} from "./responsesSequence.ts";

// Stream handler with disconnect detection - shared for all providers

// Default budget for the pipeWithDisconnect raw-upstream stall watchdog.
// Inherits STREAM_IDLE_TIMEOUT_MS so a single env knob still governs the
// max time we tolerate silence from upstream. Reasoning models (Claude
// thinking, Kiro EventStream binary frames) emit zero post-transform
// output for long stretches while raw bytes keep arriving — measuring
// stall on the transform output false-positives on those streams, so
// the watchdog must track upstream byte activity instead. Ported from
// decolua/9router#1243.
const DEFAULT_STREAM_STALL_TIMEOUT_MS = STREAM_IDLE_TIMEOUT_MS;

type StreamController = ReturnType<typeof createStreamController>;

type StreamErrorStatusKind = "rate_limit" | "authentication" | "permission" | "client" | "server";

type StreamErrorStatusMapping = {
  responses: {
    type: string;
    code: string;
  };
  claude: {
    type: string;
  };
};

function isResponsesClientFormat(clientResponseFormat?: string | null): boolean {
  return (
    clientResponseFormat === FORMATS.OPENAI_RESPONSES ||
    clientResponseFormat === FORMATS.OPENAI_RESPONSE
  );
}

function getStreamErrorStatusKind(statusCode: number): StreamErrorStatusKind {
  if (statusCode === 429) return "rate_limit";
  if (statusCode === 401) return "authentication";
  if (statusCode === 403) return "permission";
  if (statusCode >= 400 && statusCode < 500) return "client";
  return "server";
}

function getStreamErrorStatusMapping(statusCode: number): StreamErrorStatusMapping {
  switch (getStreamErrorStatusKind(statusCode)) {
    case "rate_limit":
      return {
        responses: { type: "rate_limit_error", code: "rate_limit_exceeded" },
        claude: { type: "rate_limit_error" },
      };
    case "authentication":
      return {
        responses: { type: "authentication_error", code: "invalid_authentication" },
        claude: { type: "authentication_error" },
      };
    case "permission":
      return {
        responses: { type: "authentication_error", code: "permission_denied" },
        claude: { type: "permission_error" },
      };
    case "client":
      return {
        responses: { type: "invalid_request_error", code: "bad_request" },
        claude: { type: "invalid_request_error" },
      };
    case "server":
      return {
        responses: { type: "server_error", code: "server_error" },
        claude: { type: "api_error" },
      };
    default:
      return {
        responses: { type: "server_error", code: "server_error" },
        claude: { type: "api_error" },
      };
  }
}

function encodeSseEvent(
  data: unknown,
  {
    event,
    includeDone = false,
  }: {
    event?: string;
    includeDone?: boolean;
  } = {}
) {
  if (event && /[\r\n]/.test(event)) {
    throw new Error("SSE event names must not contain newlines");
  }

  const encoder = new TextEncoder();
  const prefix = event ? `event: ${event}\n` : "";
  const chunks = [encoder.encode(`${prefix}data: ${JSON.stringify(data)}\n\n`)];
  if (includeDone) {
    chunks.push(encoder.encode("data: [DONE]\n\n"));
  }
  return chunks;
}

// Get HH:MM:SS timestamp
function getTimeString() {
  return new Date().toLocaleTimeString("en-US", {
    hour12: false,
    hour: "2-digit",
    minute: "2-digit",
    second: "2-digit",
  });
}

function isPendingRequestClearedError(error: unknown): boolean {
  return (
    !!error &&
    typeof error === "object" &&
    (error as Record<string, unknown>)[PENDING_REQUEST_CLEARED_MARKER] === true
  );
}

/**
 * A client disconnect — the caller aborted the request or closed the SSE
 * connection — is NOT a provider failure. It surfaces either as an
 * AbortError/ResponseAborted, or, when OmniRoute then tries to enqueue another
 * chunk into the now-closed response stream, as a "Controller is already closed"
 * TypeError. Treating any of these as an upstream error wrongly cools down the
 * account/connection, so the stream error path uses this to skip the provider
 * failover/cooldown (the Codex / Antigravity executors already
 * guard client aborts the same way).
 */
export function isClientDisconnectError(error: unknown): boolean {
  if (!error || typeof error !== "object") return false;
  const name = (error as { name?: unknown }).name;
  if (name === "AbortError" || name === "ResponseAborted") return true;
  const message = (error as { message?: unknown }).message;
  return typeof message === "string" && /Controller is already closed/i.test(message);
}

function getErrorMessage(error: unknown): string {
  if (error instanceof Error && error.message) return error.message;
  if (typeof error === "string" && error.trim().length > 0) return error;
  return "Upstream stream error";
}

function getErrorStatusCode(error: unknown): number {
  const errorName =
    error && typeof error === "object" && typeof (error as { name?: unknown }).name === "string"
      ? (error as { name: string }).name
      : "";
  if (errorName === "TimeoutError" || errorName === "BodyTimeoutError") {
    return 504;
  }
  if (error && typeof error === "object" && "statusCode" in error) {
    const statusCode = Number((error as { statusCode?: unknown }).statusCode);
    if (Number.isFinite(statusCode) && statusCode >= 400 && statusCode <= 599) {
      return statusCode;
    }
  }
  return 502;
}

function getPublicErrorMessage(errorMsg: string, statusCode: number): string {
  return buildErrorBody(statusCode, errorMsg).error.message;
}

function isDeadlineAbortReason(reason: unknown): reason is Error {
  return (
    reason instanceof Error &&
    (reason.name === "TimeoutError" || reason.name === "BodyTimeoutError")
  );
}

function hasClientTerminalSseMarker(text: string, clientResponseFormat?: string | null): boolean {
  if (/(?:^|\r?\n)data:\s*\[DONE\]\s*(?:\r?\n|$)/.test(text)) {
    return true;
  }

  if (isResponsesClientFormat(clientResponseFormat)) {
    return (
      /(?:^|\r?\n)event:\s*response\.completed\s*(?:\r?\n|$)/.test(text) ||
      /"type"\s*:\s*"response\.completed"/.test(text)
    );
  }

  if (clientResponseFormat === FORMATS.CLAUDE) {
    return (
      /(?:^|\r?\n)event:\s*message_stop\s*(?:\r?\n|$)/.test(text) ||
      /"type"\s*:\s*"message_stop"/.test(text)
    );
  }

  // OpenAI chat completions: some providers omit `data: [DONE]` (already
  // matched above) and terminate with a finish_reason chunk instead. A
  // non-null finish_reason value is that terminal signal — a bare
  // `finish_reason: null` delta chunk must NOT count (#10443).
  if (clientResponseFormat === FORMATS.OPENAI) {
    return /"finish_reason"\s*:\s*"[^"]+"/.test(text);
  }

  return false;
}

/**
 * Create stream controller with abort and disconnect detection
 * @param {object} options
 * @param {function} options.onDisconnect - Callback when client disconnects
 * @param {object} options.log - Logger instance
 * @param {string} options.provider - Provider name
 * @param {string} options.model - Model name
 */
/** @param {StreamControllerOptions} options */
export function createStreamController({
  onDisconnect,
  onError,
  provider,
  model,
  connectionId,
  pendingRequestId = null,
  clientResponseFormat,
  clientAbortSignal,
  allowCompletedToolHandoffGrace = false,
  clientDisconnectGracePeriodMs = 0,
}: StreamControllerOptions = {}) {
  const abortController = new AbortController();
  const startTime = Date.now();
  let disconnected = false;
  let clientTerminalSeen = false;
  let completedToolHandoffSeen = false;
  let completedToolHandoffDrain: (() => void) | null = null;
  let pendingRequestCleared = false;
  let cleanupClientAbortSignal: (() => void) | null = null;

  const logStream = (status) => {
    const duration = Date.now() - startTime;
    const p = provider?.toUpperCase() || "UNKNOWN";
    console.log(
      `[${getTimeString()}] 🌊 [STREAM] ${p} | ${model || "unknown"} | ${duration}ms | ${status}`
    );
  };

  const clearPendingRequest = (error?: unknown) => {
    if (pendingRequestCleared) return;
    if (
      error &&
      typeof error === "object" &&
      (error as Record<string, unknown>)[PENDING_REQUEST_CLEARED_MARKER] === true
    ) {
      pendingRequestCleared = true;
      return;
    }

    pendingRequestCleared = true;
    if (!model && !provider && !connectionId) return;
    try {
      trackPendingRequest(
        model || "",
        provider || "",
        connectionId ?? null,
        false,
        undefined,
        pendingRequestId ?? undefined
      );
    } catch (e) {
      console.error(
        `[${getTimeString()}] [streamHandler] trackPendingRequest decrement failed — counter may drift`,
        e
      );
    }
  };

  const cleanupClientAbortListener = () => {
    if (!cleanupClientAbortSignal) return;
    cleanupClientAbortSignal();
    cleanupClientAbortSignal = null;
  };

  const releaseRequestCallbacks = (preserveHandoffDrain = false) => {
    // A completed Response may outlive its request. These callbacks capture
    // chatCore's provider wire body and multimodal input through their context.
    onDisconnect = undefined;
    onError = undefined;
    if (!preserveHandoffDrain) completedToolHandoffDrain = null;
  };

  const getClientAbortReason = () => {
    const reason = clientAbortSignal?.reason;
    if (typeof reason === "string" && reason.trim().length > 0) {
      return reason;
    }
    if (reason instanceof Error && reason.message) {
      return reason.message;
    }
    return "request_signal_aborted";
  };

  const controller = {
    signal: abortController.signal,
    startTime,

    isConnected: () => !disconnected,

    // Call when client disconnects
    handleDisconnect: (reason = "client_closed") => {
      if (disconnected) return;
      if (clientTerminalSeen) {
        // Start the drain before completion releases its registered callback.
        if (clientDisconnectGracePeriodMs > 0) completedToolHandoffDrain?.();
        controller.handleComplete();
        return;
      }
      disconnected = true;
      cleanupClientAbortListener();

      logStream(`disconnect: ${reason}`);

      // Decrement pending request counter — the TransformStream flush() won't
      // fire when the client aborts mid-stream, so we must clean up here.
      clearPendingRequest();

      const deferUpstreamAbort =
        allowCompletedToolHandoffGrace &&
        clientDisconnectGracePeriodMs > 0 &&
        completedToolHandoffSeen &&
        completedToolHandoffDrain !== null;
      if (deferUpstreamAbort) {
        completedToolHandoffDrain?.();
      } else {
        abortController.abort(reason);
      }

      try {
        onDisconnect?.({ reason, duration: Date.now() - startTime });
      } finally {
        releaseRequestCallbacks(deferUpstreamAbort);
      }
    },

    // Call when stream completes normally
    handleComplete: () => {
      releaseRequestCallbacks();
      if (disconnected) return;
      disconnected = true;
      cleanupClientAbortListener();

      logStream("complete");
    },

    markClientTerminalSeen: () => {
      clientTerminalSeen = true;
    },

    markCompletedToolHandoffSeen: () => {
      completedToolHandoffSeen = true;
    },

    registerCompletedToolHandoffDrain: (drain: () => void) => {
      if (!disconnected && !abortController.signal.aborted) completedToolHandoffDrain = drain;
    },

    shouldDeferCompletedToolHandoff: () =>
      allowCompletedToolHandoffGrace &&
      clientDisconnectGracePeriodMs > 0 &&
      completedToolHandoffSeen &&
      completedToolHandoffDrain !== null,

    // Call on error
    handleError: (error: unknown) => {
      cleanupClientAbortListener();

      // A client disconnect is not a provider failure. If the client already went away
      // (disconnected) or the error is a client abort / "Controller is already closed",
      // skip the onError failover/cooldown path — otherwise one cancelled request marks
      // the upstream connection unavailable.
      if (disconnected || isClientDisconnectError(error)) {
        clearPendingRequest(error);
        releaseRequestCallbacks();
        logStream(disconnected ? "client_disconnect (post-abort)" : "client_disconnect");
        return;
      }

      const alreadyCleared = isPendingRequestClearedError(error);
      let handled = false;
      if (!alreadyCleared) {
        try {
          handled =
            onError?.({
              error,
              message: getErrorMessage(error),
              statusCode: getErrorStatusCode(error),
              duration: Date.now() - startTime,
            }) === true;
        } catch (e) {
          console.debug(`[STREAM-HANDLER] onError callback error:`, e);
        }
      }

      if (!handled) {
        clearPendingRequest(error);
      } else {
        pendingRequestCleared = true;
      }
      releaseRequestCallbacks();

      if (error instanceof Error && error.name === "AbortError") {
        logStream("aborted");
        return;
      }

      if (error instanceof Error) {
        logStream(`error: ${getPublicErrorMessage(error.message, getErrorStatusCode(error))}`);
        return;
      }
      logStream("error: unknown");
    },

    abort: () => {
      cleanupClientAbortListener();
      abortController.abort();
      releaseRequestCallbacks();
    },
    clientResponseFormat,
    clientDisconnectGracePeriodMs,
  };

  if (clientAbortSignal && typeof clientAbortSignal.addEventListener === "function") {
    const handleClientAbort = () => {
      const reason = clientAbortSignal.reason;
      if (isDeadlineAbortReason(reason)) {
        // An AbortSignal can represent an OmniRoute-owned deadline as well as
        // a caller disconnect. Preserve deadline failures as 504; classifying
        // them as client disconnects writes a misleading 499 to the call log.
        abortController.abort(reason);
        controller.handleError(reason);
        return;
      }
      controller.handleDisconnect(getClientAbortReason());
    };
    if (clientAbortSignal.aborted) {
      queueMicrotask(handleClientAbort);
    } else {
      clientAbortSignal.addEventListener("abort", handleClientAbort, { once: true });
      cleanupClientAbortSignal = () => {
        clientAbortSignal.removeEventListener("abort", handleClientAbort);
      };
    }
  }

  return controller;
}

export function buildStreamErrorChunks(
  errorMsg: string,
  statusCode: number,
  clientResponseFormat?: string | null
) {
  const statusMapping = getStreamErrorStatusMapping(statusCode);
  const publicErrorMessage = getPublicErrorMessage(errorMsg, statusCode);

  if (isResponsesClientFormat(clientResponseFormat)) {
    const errorEvent = {
      type: "response.failed",
      // #15202: synthesized response.failed frames must satisfy the Responses event
      // union — a string `response.id` and a numeric `sequence_number`. The 3.8.51
      // fix set both fields on the other synthetic sites but left this one as
      // `id: null` with no sequence, so a strict decoder aborts here too.
      sequence_number: SYNTHETIC_RESPONSES_SEQUENCE_NUMBER,
      response: {
        id: buildSyntheticResponsesFailureId(),
        status: "failed",
        error: {
          message: publicErrorMessage,
          type: statusMapping.responses.type,
          code: statusMapping.responses.code,
        },
      },
    };

    return encodeSseEvent(errorEvent, { event: "response.failed" });
  }

  if (clientResponseFormat === FORMATS.CLAUDE) {
    const errorEvent = {
      type: "error",
      error: {
        type: statusMapping.claude.type,
        message: publicErrorMessage,
      },
    };

    // #7699 — emit message_stop after event:error so Anthropic SDK / Claude Code
    // see a proper terminal frame instead of a silent mid-response close.
    // Without message_stop, clients report "Connection closed mid-response."
    return [
      ...encodeSseEvent(errorEvent, { event: "error" }),
      ...encodeSseEvent({ type: "message_stop" }, { event: "message_stop" }),
    ];
  }

  const errorEvent = {
    object: "chat.completion.chunk",
    choices: [
      {
        index: 0,
        delta: {},
        finish_reason: "error",
      },
    ],
    error: {
      message: publicErrorMessage,
      type: statusMapping.responses.type,
      code: statusMapping.responses.code,
    },
  };

  return encodeSseEvent(errorEvent, { includeDone: true });
}

/**
 * Synthesized terminal frames for a graceful truncation (#7699): the upstream
 * ended without a terminal marker AFTER content was already forwarded to the
 * client. Instead of an `event: error` frame (which would discard the partial
 * content and report a mid-response failure), emit a clean Claude completion —
 * `message_delta` carrying `stop_reason: "max_tokens"` followed by
 * `message_stop` — so Anthropic SDK / Claude Code treat the response as a
 * budget-limited finish and keep everything already received.
 */
export function buildGracefulTruncationChunks(clientResponseFormat?: string | null): Uint8Array[] {
  if (clientResponseFormat !== FORMATS.CLAUDE) return [];

  return [
    ...encodeSseEvent(
      {
        type: "message_delta",
        delta: { stop_reason: "max_tokens", stop_sequence: null },
        usage: { input_tokens: 0, output_tokens: 0 },
      },
      { event: "message_delta" }
    ),
    ...encodeSseEvent({ type: "message_stop" }, { event: "message_stop" }),
  ];
}

/**
 * Minimal `writable` half used by `pipeWithDisconnect`. The real writable is
 * driven entirely by the upstream-piped readable, so the writer only needs an
 * `abort()` hook for `createDisconnectAwareStream`'s `cancel()` path.
 *
 * `abort()` returns `Promise<void>` to match the native
 * `WritableStreamDefaultWriter.abort()` contract — `cancel()` (and any caller
 * that awaits the writer) gets a real thenable instead of `undefined`, which
 * keeps abort/error handling clean. Ported from decolua/9router@6b624af4.
 */
export function createNoopAbortWritable(): {
  getWriter: () => { abort: () => Promise<void> };
} {
  return { getWriter: () => ({ abort: () => Promise.resolve() }) };
}

/**
 * Create transform stream with disconnect detection
 * Wraps existing transform stream and adds abort capability
 */
/**
 * Why a finished upstream stream should still be reported as a failure, or null
 * when the close was clean. Two distinct silent-close shapes:
 *
 * - **#7699, no terminal marker.** Scoped to Claude (`/v1/messages`), which is
 *   the issue's real scope: Anthropic's SSE spec permits a mid-stream
 *   `event: error`, and Claude clients treat a stream ending without
 *   `message_stop` as an error. When content already reached the client this is
 *   NOT a provider failure — the partial response is valid and must be kept — so
 *   it resolves to a graceful truncation (`stop_reason: max_tokens`). For every
 *   other format (plain OpenAI chat completions included) a
 *   done-without-recognized-marker close is NOT necessarily a drop — many
 *   formats have no `[DONE]` equivalent — so synthesising an error there would
 *   be a false positive.
 *
 * - **#8649, no content at all.** The stream terminated properly and carried no
 *   model output. Unlike the marker case this is not format-dependent: a
 *   completed stream with zero content is a failure everywhere, and it is the
 *   streaming twin of the non-streaming `isEmptyContentResponse` check. Only
 *   applies to bodies that actually looked like SSE, and terminal states where
 *   emptiness is legitimate (length / tool_calls / content_filter / max_tokens /
 *   tool_use) are excluded by the watcher. If the stream already carried a
 *   substantive SSE `error` / `response.failed` / Claude `event:error`, stand
 *   down — same spirit as Claude #3685 `lifecycle.hasError` and readiness #8972
 *   (do not invent empty content on top of an actionable error).
 */
type SilentCloseOutcome = { kind: "truncated" } | { kind: "error"; reason: string };

function resolveSilentCloseOutcome(input: {
  bytesWereForwarded: boolean;
  clientTerminalSeen: boolean;
  clientResponseFormat?: string | null;
  contentWatcher: StreamContentWatcher;
  permitsEmptyTurn?: () => boolean;
}): SilentCloseOutcome | null {
  if (!input.bytesWereForwarded) return null;

  if (!input.clientTerminalSeen) {
    if (input.clientResponseFormat === FORMATS.CLAUDE && input.contentWatcher.sawContent()) {
      // #7699 — upstream dropped after content reached the client on a Claude
      // stream. Keep the partial response: emit a clean max_tokens completion
      // instead of an error frame so Anthropic SDK / Claude Code don't report
      // a mid-response break.
      return { kind: "truncated" };
    }
    // #10443: every known path that produces OpenAI chat chunks emits a
    // terminal — the response translators (gemini/claude/kiro/cursor-to-openai)
    // all emit a finish_reason chunk, the non-standard executors (kiro, cursor,
    // nlpcloud, poe-web, copilot-m365-web, gitlab)
    // enqueue `data: [DONE]` themselves, and standard OpenAI-compatible
    // upstreams end with finish_reason + [DONE] per spec. So a close that
    // forwarded content but no terminal marker is an upstream drop, not a
    // legitimate end. Guard on sawContent() so the #8649 empty-content
    // verdict below keeps its more precise shape for content-free closes.
    if (input.clientResponseFormat === FORMATS.OPENAI && input.contentWatcher.sawContent()) {
      return { kind: "error", reason: "Upstream stream ended without a terminal marker" };
    }
    // Responses-format clients (Codex CLI and other /v1/responses consumers):
    // a healthy OpenAI Responses stream ALWAYS terminates with an explicit
    // `response.completed` event — it is the format's only terminal marker and
    // carries the final status/usage. Content forwarded without it is an
    // upstream drop, the same class as #10443 for chat completions; surface a
    // synthetic response.failed instead of a silent close so clients report
    // the break instead of waiting on a completion event that never comes.
    if (isResponsesClientFormat(input.clientResponseFormat) && input.contentWatcher.sawContent()) {
      return { kind: "error", reason: "Upstream stream ended without a terminal marker" };
    }
  }

  const watcher = input.contentWatcher;
  if (watcher.sawError()) return null;
  if (watcher.sawSseFrame() && !watcher.sawContent() && !watcher.sawLegitEmptyTerminal()) {
    // A translated/client stop is insufficient: the executed native protocol
    // must also have supplied an ordinary terminal on a trusted origin.
    if (!(input.clientTerminalSeen && input.permitsEmptyTurn?.())) {
      return { kind: "error", reason: "Provider returned empty content" };
    }
  }

  return null;
}

export function createDisconnectAwareStream(
  transformStream,
  streamController,
  options: { highWaterMark?: number; permitsEmptyTurn?: () => boolean } = {}
) {
  const reader = transformStream.readable.getReader();
  const writer = transformStream.writable.getWriter();
  const terminalDecoder = new TextDecoder();
  const contentDecoder = new TextDecoder();
  const contentWatcher = createStreamContentWatcher();
  const completedToolHandoffWatcher = createCompletedResponsesToolHandoffWatcher();
  const toolHandoffDecoder = new TextDecoder();
  let terminalTail = "";
  let clientTerminalSeen = false;
  let bytesWereForwarded = false;
  const completionDrain = createCompletionDrain(reader, writer, streamController, () =>
    clientTerminalSeen ? "terminal_stream_grace_expired" : "completed_tool_handoff_grace_expired"
  );
  streamController.registerCompletedToolHandoffDrain?.(completionDrain.start);

  const noteClientChunk = (chunk: unknown) => {
    if (!(chunk instanceof Uint8Array)) return;
    bytesWereForwarded = true;
    // Runs past clientTerminalSeen: the frame that carries the terminal marker
    // can carry the only content too, and #8649 needs the whole stream scanned.
    contentWatcher.note(contentDecoder.decode(chunk, { stream: true }));
    if (
      isResponsesClientFormat(streamController.clientResponseFormat) &&
      completedToolHandoffWatcher.note(toolHandoffDecoder.decode(chunk, { stream: true }))
    ) {
      streamController.markCompletedToolHandoffSeen?.();
    }
    if (clientTerminalSeen) return;

    terminalTail += terminalDecoder.decode(chunk, { stream: true });
    // Scan before bounding retained state: a compaction terminal frame can
    // exceed the tail budget because encrypted_content is carried inline.
    clientTerminalSeen = hasClientTerminalSseMarker(
      terminalTail,
      streamController.clientResponseFormat
    );
    if (terminalTail.length > 4096) {
      terminalTail = terminalTail.slice(-4096);
    }
    if (clientTerminalSeen) {
      streamController.markClientTerminalSeen?.();
    }
  };

  const highWaterMark = options.highWaterMark ?? 16384;

  return new ReadableStream(
    {
      async pull(controller) {
        if (!streamController.isConnected()) {
          // Closing our side alone leaves the upstream body being pulled by the
          // transform pipe. Cancel it so the provider stops generating for a
          // client that is gone. A completed terminal stream with a grace window
          // hands the inner reader to the bounded drain so late usage can flush.
          if (clientTerminalSeen) {
            if (Number(streamController.clientDisconnectGracePeriodMs) > 0) {
              completionDrain.start();
            }
          } else if (streamController.shouldDeferCompletedToolHandoff?.() !== true) {
            const reason = "client_disconnected";
            void Promise.allSettled([reader.cancel(reason), writer.abort(reason)]);
          }
          controller.close();
          return;
        }

        try {
          const { done, value } = await reader.read();
          if (done) {
            contentWatcher.finish();
            const silentClose = resolveSilentCloseOutcome({
              bytesWereForwarded,
              clientTerminalSeen,
              clientResponseFormat: streamController.clientResponseFormat,
              contentWatcher,
              permitsEmptyTurn: options.permitsEmptyTurn,
            });

            if (silentClose?.kind === "truncated") {
              // #7699 — the upstream dropped without a terminal marker after
              // content reached the client. Keep the partial response: emit a
              // clean `max_tokens` completion instead of an error frame so
              // Anthropic SDK / Claude Code don't report a mid-response break.
              streamController.handleComplete();
              try {
                for (const chunk of buildGracefulTruncationChunks(
                  streamController.clientResponseFormat
                )) {
                  controller.enqueue(chunk);
                }
              } catch {
                // downstream may have closed; stream already marked complete
              }
            } else if (silentClose) {
              streamController.handleError(
                Object.assign(new Error(silentClose.reason), { statusCode: 502 })
              );
              try {
                for (const chunk of buildStreamErrorChunks(
                  silentClose.reason,
                  502,
                  streamController.clientResponseFormat
                )) {
                  controller.enqueue(chunk);
                }
              } catch {
                // downstream may have closed; original error already recorded
              }
            } else {
              streamController.handleComplete();
            }
            try {
              controller.close();
            } catch {
              // Expected: downstream may have already closed
            }
            return;
          }
          controller.enqueue(value);
          noteClientChunk(value);
        } catch (error) {
          if (!streamController.isConnected()) {
            // A pending pull can lose enqueue to cancellation after the drain takes ownership.
            if (!completionDrain.isStarted()) {
              reader.cancel(new Error("Downstream disconnected")).catch(() => {});
            }
            try {
              controller.close();
            } catch {
              // Expected: downstream may have already closed
            }
            return;
          }

          if (clientTerminalSeen) {
            streamController.handleComplete();
            reader.cancel(new Error("Client terminal seen")).catch(() => {});
            try {
              controller.close();
            } catch {
              // Expected: downstream may have already closed
            }
            return;
          }

          streamController.handleError(error);

          // T35: Encapsulate mid-stream errors as SSE events instead of abruptly aborting
          const errorMsg = getErrorMessage(error);
          const statusCode = getErrorStatusCode(error);

          try {
            for (const chunk of buildStreamErrorChunks(
              errorMsg,
              statusCode,
              streamController.clientResponseFormat
            )) {
              controller.enqueue(chunk);
            }
          } catch {
            // The downstream may have closed while we were formatting the in-band
            // error event. The original stream error has already been recorded.
          }

          try {
            controller.close();
          } catch {
            // Closing an already-closed/aborted controller after client disconnect is expected.
          }
        }
      },

      async cancel(reason) {
        const deferCompletedToolHandoff =
          streamController.shouldDeferCompletedToolHandoff?.() === true;
        if (clientTerminalSeen) {
          if (Number(streamController.clientDisconnectGracePeriodMs) > 0) {
            completionDrain.start();
            streamController.handleComplete();
            return;
          }
          streamController.handleComplete();
        } else {
          streamController.handleDisconnect(reason || "cancelled");
        }
        if (deferCompletedToolHandoff) return;
        await Promise.allSettled([reader.cancel(reason), writer.abort(reason)]);
      },
    },
    { highWaterMark }
  );
}

/**
 * Pipe provider response through transform with disconnect detection.
 *
 * Stall watchdog tracks raw upstream byte activity, not transform output.
 * Reasoning models (Claude thinking via Kiro, etc.) can produce zero SSE
 * output for long stretches while partial EventStream frames keep arriving;
 * measuring stall on the transform output caused false stalls. Any upstream
 * chunk resets the timer. If no bytes arrive for `stallTimeoutMs`, the
 * stream surfaces a "stream stall timeout" error and aborts. A separate
 * active lifetime budget never resets on bytes and surfaces
 * "stream active timeout" when exceeded.
 *
 * Ported from decolua/9router#1243 by @zakirkun.
 *
 * @param providerResponse - Response from provider
 * @param transformStream - Transform stream for SSE
 * @param streamController - Stream controller from createStreamController
 * @param opts.stallTimeoutMs - Override the stall budget (defaults to
 *   STREAM_IDLE_TIMEOUT_MS / DEFAULT_STREAM_STALL_TIMEOUT_MS). `0` disables
 *   the stall watchdog.
 * @param opts.activeTimeoutMs - Override the total active-stream budget
 *   (defaults to STREAM_ACTIVE_TIMEOUT_MS). `0` disables the active watchdog.
 */
export function pipeWithDisconnect(
  providerResponse: Response,
  transformStream: TransformStream<Uint8Array, Uint8Array>,
  streamController: StreamController,
  opts: {
    stallTimeoutMs?: number;
    activeTimeoutMs?: number;
    contentStallTimeoutMs?: number;
    highWaterMark?: number;
  } = {}
) {
  const stallTimeoutMs = opts.stallTimeoutMs ?? DEFAULT_STREAM_STALL_TIMEOUT_MS;
  const activeTimeoutMs = opts.activeTimeoutMs ?? STREAM_ACTIVE_TIMEOUT_MS;
  const stallEnabled = Number.isFinite(stallTimeoutMs) && stallTimeoutMs > 0;
  const activeEnabled = Number.isFinite(activeTimeoutMs) && activeTimeoutMs > 0;
  // Disabled unless a caller opts in with an explicit budget (chatCore wires
  // the adaptive streamReadinessPolicy.timeoutMs — see its own doc comment).
  // No blanket default here: an arbitrary constant picked at this layer,
  // without the request's actual model/provider/payload context, would risk
  // false-stalling the exact slow-first-content reasoning models the
  // readiness policy already knows to grant more patience.
  const contentStallTimeoutMs = opts.contentStallTimeoutMs ?? 0;

  // Watchdogs disabled — preserve legacy behavior verbatim.
  if (!stallEnabled && !activeEnabled && contentStallTimeoutMs <= 0) {
    const transformedBody = providerResponse.body.pipeThrough(transformStream);
    return createDisconnectAwareStream(
      { readable: transformedBody, writable: createNoopAbortWritable() },
      streamController,
      {
        highWaterMark: opts.highWaterMark,
        permitsEmptyTurn: () => hasTrustedEmptyTurn(providerResponse),
      }
    );
  }

  let activeTimer: ReturnType<typeof setTimeout> | null = null;
  // Erroring the upstream tap unblocks a downstream reader suspended on the
  // transform pipe; aborting the controller alone does not always do that.
  let upstreamTapController: TransformStreamDefaultController<Uint8Array> | null = null;
  let stallFired = false;
  let activeFired = false;

  // Per-chunk timer by default; one interval with SSE_STALL_WATCHDOG=interval.
  const stallWatchdog = createStallWatchdog(stallEnabled ? stallTimeoutMs : 0, () =>
    triggerWatchdog("stall")
  );
  const clearStall = stallWatchdog.clear;
  const clearActive = () => {
    if (activeTimer) clearTimeout(activeTimer);
    activeTimer = null;
  };
  const clearWatchdogs = () => {
    clearStall();
    clearActive();
  };
  const triggerWatchdog = (kind: "stall" | "active") => {
    if (stallFired || activeFired) return;
    const message = kind === "active" ? "stream active timeout" : "stream stall timeout";
    if (kind === "active") activeFired = true;
    else stallFired = true;
    clearWatchdogs();
    const error = new Error(message);
    try {
      streamController.handleError?.(error);
    } catch (e) {
      console.debug(`[STREAM-HANDLER] ${kind} watchdog handleError failed:`, e);
    }
    try {
      upstreamTapController?.error(error);
    } catch (e) {
      console.debug(`[STREAM-HANDLER] ${kind} watchdog upstream tap error failed:`, e);
    }
    try {
      streamController.abort?.();
    } catch (e) {
      console.debug(`[STREAM-HANDLER] ${kind} watchdog abort failed:`, e);
    }
  };
  const armStall = stallWatchdog.arm;
  const armActive = () => {
    if (!activeEnabled) return;
    clearActive();
    activeTimer = setTimeout(() => triggerWatchdog("active"), activeTimeoutMs);
  };

  // Third, independent watchdog: fires when the upstream keeps sending raw
  // bytes (so armStall() above keeps resetting and never fires) but none of
  // them ever carry real model output — only lifecycle/ping frames
  // (OpenAI Responses response.in_progress/response.created, bare
  // role-only start chunks, etc). ensureStreamReadiness's own gate already
  // treats any one of those as "ready" and hands the connection off (see its
  // own doc comment and kiro.ts's deliberate early role-only chunk — several
  // providers rely on that fast handoff for UX, so tightening readiness
  // itself would regress them). Once handed off there was previously nothing
  // watching whether the model ever actually said anything: a stalled free
  // OpenRouter model (e.g. minimax-m3:free under load) could stream nothing
  // but response.in_progress pings indefinitely, relayed byte-for-byte to
  // the client, until the CLIENT's own idle timeout eventually gave up --
  // sometimes 120s, sometimes 900s depending on the calling task, always
  // slower and less informative than OmniRoute failing this attempt itself
  // with a clear error the client's own retry/fallback logic can react to
  // immediately. Armed at stream start, never re-armed by lifecycle-only
  // bytes (unlike armStall above), restarted by reasoning-progress frames
  // (a model thinking for minutes before its first token is not stalled),
  // and cleared permanently the first time real content is observed -- reuses the exact classifier
  // (createStreamContentWatcher) createDisconnectAwareStream already trusts
  // for its own end-of-stream #8649 empty-content check.
  let contentStallTimer: ReturnType<typeof setTimeout> | null = null;
  let contentStallFired = false;
  const upstreamContentWatcher = createStreamContentWatcher();
  const upstreamContentDecoder = new TextDecoder();
  // Stall diagnostics: what the upstream had sent when the content watchdog
  // trips. Counters live at this tap because it is the only point seeing raw
  // upstream bytes (the sibling client-side contentWatcher in
  // createDisconnectAwareStream observes post-transform output instead —
  // merging the two would be a refactor, out of scope). Best-effort only:
  // `stallTail` is a bounded sliding window, so a line split by truncation
  // may miss a type; encrypted reasoning without an open item reads `no`
  // (out of scope) — never content, only type names and counts.
  const STALL_TAIL_MAX = 16 * 1024;
  const STALL_TYPES_MAX = 50;
  let stallBytes = 0;
  let stallEvents = 0;
  let stallTail = "";
  const stallTypes = new Map<string, number>();

  const bumpStallType = (name: string): void => {
    const known = stallTypes.get(name);
    if (known !== undefined) {
      stallTypes.set(name, known + 1);
      return;
    }
    if (stallTypes.size >= STALL_TYPES_MAX) {
      stallTypes.set("other", (stallTypes.get("other") ?? 0) + 1);
      return;
    }
    stallTypes.set(name, 1);
  };

  const noteStallLine = (trimmed: string): void => {
    if (trimmed.startsWith("event:")) {
      const name = trimmed.slice(6).trim().split(/\s/)[0] ?? "";
      if (name) {
        stallEvents += 1;
        bumpStallType(name);
      }
      return;
    }
    if (!trimmed.startsWith("data:")) return;
    const data = trimmed.slice(5).trim();
    if (!data) return;
    // A decoded chunk with no `data:` boundary at all is not SSE
    // (plain JSON completion forwarded through the same path).
    stallEvents += 1;
    const match = /"type"\s*:\s*"([^"]{1,64})"/.exec(data);
    bumpStallType(match ? match[1] : "non-sse");
  };

  const noteStallText = (text: string): void => {
    if (!text) return;
    stallTail += text;
    if (stallTail.length > STALL_TAIL_MAX) {
      stallTail = stallTail.slice(-STALL_TAIL_MAX);
    }
    for (const line of text.split("\n")) {
      const trimmed = line.trim();
      if (!trimmed) continue;
      noteStallLine(trimmed);
    }
  };

  const formatStallSummary = (): string => {
    const top =
      stallTypes.size === 0
        ? "none"
        : [...stallTypes.entries()]
            .sort((a, b) => b[1] - a[1])
            .slice(0, 5)
            .map(([name, count]) => `${name}:${count}`)
            .join(",");
    return `bytes=${stallBytes} events=${stallEvents} top=${top} reasoning_open=${hasOpenReasoning(stallTail) ? "yes" : "no"}`;
  };

  const clearContentStall = () => {
    if (contentStallTimer) {
      clearTimeout(contentStallTimer);
      contentStallTimer = null;
    }
  };
  const armContentStall = () => {
    if (contentStallTimeoutMs <= 0 || contentStallFired) return;
    contentStallTimer = setTimeout(() => {
      contentStallTimer = null;
      contentStallFired = true;
      const stallSummary = formatStallSummary();
      const stallError = new Error(
        `stream content stall: no model output within ${contentStallTimeoutMs}ms (${stallSummary})`
      );
      console.debug(`[STREAM-HANDLER] content stall: ${stallSummary}`);
      try {
        streamController.handleError?.(stallError);
      } catch (e) {
        console.debug(`[STREAM-HANDLER] content stall watchdog handleError failed:`, e);
      }
      try {
        upstreamTapController?.error(stallError);
      } catch (e) {
        console.debug(`[STREAM-HANDLER] content stall watchdog upstream tap error failed:`, e);
      }
      try {
        streamController.abort?.();
      } catch (e) {
        console.debug(`[STREAM-HANDLER] content stall watchdog abort failed:`, e);
      }
    }, contentStallTimeoutMs);
  };

  // Wrap controller so every termination path clears all watchdog timers.
  // Without this, abort/complete/error/disconnect paths leave a timer armed
  // and a stale abort could fire after the request has already ended.
  const wrappedController: StreamController = {
    ...streamController,
    handleComplete: () => {
      clearWatchdogs();
      clearContentStall();
      streamController.handleComplete();
    },
    handleError: (e: unknown) => {
      clearWatchdogs();
      clearContentStall();
      // A watchdog already fired its own handleError — the inner pull()
      // catch sees the same error propagated through the pipeline; suppress
      // the duplicate to keep onError callbacks single-fire.
      if (stallFired || activeFired || contentStallFired) return;
      streamController.handleError(e);
    },
    handleDisconnect: (reason?: string) => {
      clearWatchdogs();
      clearContentStall();
      streamController.handleDisconnect(reason);
    },
    abort: () => {
      clearWatchdogs();
      clearContentStall();
      streamController.abort();
    },
  };

  // Inert tap that resets the byte-stall timer on every raw upstream chunk
  // and (independently) clears the content-stall timer the first time a
  // chunk carries real output. Sits between the provider body and the SSE
  // transform so reasoning models that buffer many raw bytes into a single
  // emitted event do not look stalled to either watchdog. Reasoning frames
  // with no visible output (Claude thinking/signature deltas, Responses
  // reasoning items) restart the content-stall budget instead of clearing it:
  // the model is still working, but a turn that stops reasoning and only
  // sends heartbeats afterwards must still be caught.
  const upstreamTap = new TransformStream<Uint8Array, Uint8Array>({
    start(controller) {
      upstreamTapController = controller;
      armStall();
      armActive();
      armContentStall();
    },
    transform(chunk, controller) {
      armStall();
      if (contentStallTimeoutMs > 0 && !upstreamContentWatcher.sawContent()) {
        // Second pass over the already-decoded text, not a second decode:
        // the watcher below keeps only booleans, so counting needs its own scan.
        const decoded = upstreamContentDecoder.decode(chunk, { stream: true });
        stallBytes += chunk.byteLength;
        noteStallText(decoded);
        const reasoningBefore = upstreamContentWatcher.reasoningProgress();
        upstreamContentWatcher.note(decoded);
        if (upstreamContentWatcher.sawContent()) {
          clearContentStall();
        } else if (upstreamContentWatcher.reasoningProgress() > reasoningBefore) {
          clearContentStall();
          armContentStall();
        }
      }
      controller.enqueue(chunk);
    },
    flush() {
      clearWatchdogs();
      clearContentStall();
    },
  });

  const transformedBody = providerResponse.body
    .pipeThrough(upstreamTap)
    .pipeThrough(transformStream);
  return createDisconnectAwareStream(
    { readable: transformedBody, writable: createNoopAbortWritable() },
    wrappedController,
    {
      highWaterMark: opts.highWaterMark,
      permitsEmptyTurn: () => hasTrustedEmptyTurn(providerResponse),
    }
  );
}