@iislee/opencodex 2.11.0

package/src/lib/errors.ts

@@ -0,0 +1,364 @@
+export interface OcxErrorPayload {
+  message: string;
+  type: string;
+  code: string | null;
+}
+
+/** OpenAI / Codex hard block for high-risk cybersecurity activity (HTTP 400 or mid-stream). */
+export const CYBER_POLICY_ERROR_CODE = "cyber_policy";
+
+export function isCyberPolicyCode(code: string | null | undefined): boolean {
+  return code === CYBER_POLICY_ERROR_CODE;
+}
+
+/**
+ * Detect OpenAI cyber-policy refusals from message text when structured `code` was stripped.
+ * Matches Codex fallback copy and Cursor/API agent wording (session evidence 2026-07-24).
+ * Does not treat a bare `cyber_policy` token as conclusive — model ids / routing errors can
+ * include that substring without being a policy refusal.
+ */
+export function isCyberPolicyMessage(text: string): boolean {
+  const lower = text.toLowerCase();
+  // Serialized error-code signatures only (not bare model-id collisions).
+  if (/"code"\s*:\s*"cyber_policy"/.test(lower)) return true;
+  if (/\bcode\s*[:=]\s*["']?cyber_policy\b/.test(lower)) return true;
+  if (lower.includes("high-risk cybersecurity")) return true;
+  if (lower.includes("high-risk cyber activity") || lower.includes("high-risk cyber ")) return true;
+  if (lower.includes("possible cybersecurity risk")) return true;
+  if (lower.includes("flagged") && lower.includes("cybersecurity")) return true;
+  if (lower.includes("flagged") && lower.includes("cyber activity")) return true;
+  return false;
+}
+
+function isSubscriptionGateMessage(text: string): boolean {
+  return (
+    text.includes("requires a subscription") ||
+    text.includes("requires subscription") ||
+    text.includes("subscription required") ||
+    text.includes("upgrade for access") ||
+    text.includes("upgrade to pro") ||
+    text.includes("pro subscription") ||
+    text.includes("ollama.com/upgrade") ||
+    (text.includes("upgrade") && text.includes("subscription"))
+  );
+}
+
+function isAuthenticationMessage(text: string): boolean {
+  const accessDeniedWithCredentialCue = (
+    text.includes("access denied") ||
+    text.includes("accessdeniedexception")
+  ) && (
+    text.includes("authentication") ||
+    text.includes("credential") ||
+    text.includes("api key") ||
+    text.includes("token") ||
+    text.includes("signature")
+  );
+  return (
+    text.includes("authentication failed") ||
+    text.includes("authentication") ||
+    text.includes("invalid_api_key") ||
+    text.includes("invalid api key") ||
+    text.includes("invalid token") ||
+    text.includes("unauthorizedexception") ||
+    text.includes("unrecognizedclientexception") ||
+    text.includes("unrecognizedclient") ||
+    text.includes("expired token") ||
+    text.includes("expiredtoken") ||
+    text.includes("unauthenticated") ||
+    text.includes("unauthorized") ||
+    accessDeniedWithCredentialCue
+  );
+}
+
+function isPermissionMessage(text: string): boolean {
+  return (
+    text.includes("permission_denied") ||
+    text.includes("permission denied") ||
+    text.includes("forbidden") ||
+    text.includes("access denied") ||
+    text.includes("accessdeniedexception") ||
+    text.includes("not allowed to use") ||
+    text.includes("model access")
+  );
+}
+
+/**
+ * Client cancelled / closed the turn. Matches ONLY abort phrases this codebase
+ * produces — "client closed request during web-search" (src/web-search/loop.ts),
+ * "Client cancelled request" (src/server/responses.ts) — plus the explicit
+ * "request cancel(l)ed by client" forms. Deliberately narrow: bare "client closed"
+ * would also swallow legitimate upstream failures like "upstream HTTP client
+ * closed idle connection" and turn a real 502 into a 499.
+ */
+export function isClientClosedMessage(text: string): boolean {
+  const lower = text.toLowerCase();
+  return (
+    lower.includes("client closed request") ||
+    lower.includes("client cancelled request") ||
+    lower.includes("client canceled request") ||
+    lower.includes("request canceled by client") ||
+    lower.includes("request cancelled by client")
+  );
+}
+
+export function classifyError(status: number, type: string, message: string): OcxErrorPayload {
+  const text = message.toLowerCase();
+  if (type === "previous_response_not_found") {
+    return { message, type: "invalid_request_error", code: "previous_response_not_found" };
+  }
+  // Preserve explicit cancel types used by compact/combo JSON errors; unify message-inferred
+  // client closes (web-search abort text) onto client_closed_request for /api/logs.
+  if (type === "client_cancelled") {
+    return { message, type: "client_cancelled", code: "client_cancelled" };
+  }
+  if (
+    status === 499 ||
+    type === "client_closed_request" ||
+    isClientClosedMessage(text)
+  ) {
+    return { message, type: "invalid_request_error", code: "client_closed_request" };
+  }
+  // Codex only shows the dedicated cyber UI when error.code === "cyber_policy".
+  // Prefer that code (and invalid_request_error) over generic remaps / 502 upstream_server_error.
+  if (type === CYBER_POLICY_ERROR_CODE || isCyberPolicyMessage(text)) {
+    return { message, type: "invalid_request_error", code: CYBER_POLICY_ERROR_CODE };
+  }
+  if (
+    text.includes("context_length_exceeded") ||
+    text.includes("context window") ||
+    text.includes("context length") ||
+    text.includes("maximum context") ||
+    text.includes("too many tokens")
+  ) {
+    return { message, type: "invalid_request_error", code: "context_length_exceeded" };
+  }
+  // "Cursor resource limit exceeded" is emitted only for explicit request-size overflow
+  // details (isCursorRequestTooLargeDetail in cursor-errors.ts); quota-style resource
+  // exhaustion arrives as "Cursor rate limit exceeded" and falls through to 429 below.
+  if (text.includes("cursor resource limit exceeded")) {
+    return { message, type: "invalid_request_error", code: "tool_catalog_too_large" };
+  }
+  // The Cursor adapter's classified rate-limit prefix is authoritative: its DETAIL may echo
+  // quota wording ("... quota exhausted") that would otherwise hit the insufficient_quota
+  // branch below and break the planned retry-with-backoff contract (WP3 review blocker 1).
+  if (text.includes("cursor rate limit exceeded")) {
+    return { message, type: "rate_limit_error", code: "rate_limit_exceeded" };
+  }
+  if (
+    text.includes("insufficient_quota") ||
+    text.includes("exceeded your current quota") ||
+    text.includes("quota exhausted") ||
+    text.includes("account quota exceeded") ||
+    text.includes("monthly quota exceeded") ||
+    text.includes("daily quota exceeded")
+  ) {
+    return { message, type: "insufficient_quota", code: "insufficient_quota" };
+  }
+  if (
+    status === 429 ||
+    text.includes("rate limit") ||
+    text.includes("rate limited") ||
+    text.includes("too many requests") ||
+    text.includes("resource_exhausted") ||
+    text.includes("resource exhausted") ||
+    text.includes("throttlingexception") ||
+    text.includes("throttling")
+  ) {
+    return { message, type: "rate_limit_error", code: "rate_limit_exceeded" };
+  }
+  if (type === "origin_rejected") {
+    return { message, type: "invalid_request_error", code: "origin_rejected" };
+  }
+  // HTTP 401 and explicit auth failures are authoritative even when provider text
+  // also advertises an upgrade or subscription.
+  if (
+    status === 401 ||
+    type === "authentication_error" ||
+    isAuthenticationMessage(text)
+  ) {
+    return { message, type: "authentication_error", code: "invalid_api_key" };
+  }
+  // Subscription labels are valid only in a known permission context.
+  if (
+    (status === 403 || type === "permission_error") &&
+    isSubscriptionGateMessage(text)
+  ) {
+    return { message, type: "permission_error", code: "subscription_required" };
+  }
+  if (
+    status === 403 ||
+    type === "permission_error" ||
+    isPermissionMessage(text)
+  ) {
+    return { message, type: "permission_error", code: "permission_denied" };
+  }
+  if (
+    status === 503 ||
+    text.includes("overloaded") ||
+    text.includes("server is busy") ||
+    text.includes("temporarily unavailable")
+  ) {
+    // Codex recognizes "server_is_overloaded" and applies retry-after backoff
+    // (responses.rs is_server_overloaded_error); generic "upstream_server_error" is not recognized.
+    return { message, type: "server_error", code: "server_is_overloaded" };
+  }
+  if (
+    text.includes("validationexception") ||
+    text.includes("invalid request") ||
+    text.includes("model unavailable") ||
+    text.includes("model not found") ||
+    text.includes("unsupported model") ||
+    text.includes("profile arn") ||
+    text.includes("wrong region") ||
+    text.includes("invalid region")
+  ) {
+    return { message, type: "invalid_request_error", code: "invalid_request_error" };
+  }
+  if (status >= 500) {
+    return { message, type: "server_error", code: "upstream_server_error" };
+  }
+  if (status === 400 || type === "invalid_request_error") {
+    return { message, type: "invalid_request_error", code: "invalid_request_error" };
+  }
+  return { message, type, code: type || null };
+}
+
+/**
+ * True when a provider failure should participate in rate-limit / quota health blocking.
+ * Reuses {@link classifyError} so generic 429 wording and quota phrases stay aligned.
+ */
+export function isRateLimitOrQuotaFailureMessage(message: string): boolean {
+  const normalized = String(message ?? "").trim();
+  if (!normalized) return false;
+  const numericStatus = Number(normalized);
+  if (numericStatus === 429 || numericStatus === 402) return true;
+  const statusHint = Number.isInteger(numericStatus) && numericStatus > 0 ? numericStatus : 0;
+  const classified = classifyError(statusHint, "", normalized);
+  if (
+    classified.type === "rate_limit_error"
+    || classified.code === "rate_limit_exceeded"
+    || classified.type === "insufficient_quota"
+    || classified.code === "insufficient_quota"
+  ) {
+    return true;
+  }
+  // Retained quota cue used by subagent health before classifyError covered it.
+  return normalized.toLowerCase().includes("usage limit");
+}
+
+/** Best-effort parse of a retry delay embedded in an upstream error message. */
+export function parseRetryAfterFromMessage(message: string): number | undefined {
+  const patterns = [
+    /try again in (\d+(?:\.\d+)?)\s*s(?:ec(?:ond)?s?)?/i,
+    /retry after (\d+(?:\.\d+)?)\s*s(?:ec(?:ond)?s?)?/i,
+    /retry[- ]after[:\s]+(\d+)/i,
+  ];
+  for (const pattern of patterns) {
+    const match = message.match(pattern);
+    if (!match?.[1]) continue;
+    const seconds = Number.parseFloat(match[1]);
+    if (Number.isFinite(seconds) && seconds > 0) return Math.ceil(seconds);
+  }
+  return undefined;
+}
+
+/** Infer HTTP status from adapter terminal error text (provider-agnostic keyword matching). */
+export function inferHttpStatusFromAdapterMessage(message: string): number {
+  const lower = message.toLowerCase();
+  // Client aborts (e.g. mid web-search loop) must not look like upstream 502s in /api/logs.
+  if (isClientClosedMessage(lower)) return 499;
+  // Codex Transport maps cyber_policy only on HTTP 400 (SSE is code-based).
+  if (isCyberPolicyMessage(lower)) return 400;
+  // See classifyError: this prefix now only means explicit request-size overflow (400);
+  // quota-style Cursor resource exhaustion carries the rate-limit prefix and maps to 429.
+  if (lower.includes("cursor resource limit exceeded")) return 400;
+  if (
+    lower.includes("resource_exhausted") ||
+    lower.includes("resource exhausted") ||
+    lower.includes("rate limit") ||
+    lower.includes("too many requests") ||
+    lower.includes("throttling")
+  ) return 429;
+  // Strong authentication signals win when a message contains mixed auth and
+  // subscription/permission wording.
+  if (isAuthenticationMessage(lower)) return 401;
+  if (isSubscriptionGateMessage(lower) || isPermissionMessage(lower)) return 403;
+  if (
+    lower.includes("unavailable") ||
+    lower.includes("overloaded") ||
+    lower.includes("temporarily") ||
+    lower.includes("server is busy")
+  ) return 503;
+  if (
+    lower.includes("invalid") ||
+    lower.includes("not found") ||
+    lower.includes("unsupported") ||
+    lower.includes("malformed") ||
+    lower.includes("unimplemented")
+  ) return 400;
+  if (
+    lower.includes("timed out") ||
+    lower.includes("timeout") ||
+    lower.includes("etimedout") ||
+    lower.includes("deadline")
+  ) return 504;
+  return 502;
+}
+
+/** Map an adapter terminal error message to HTTP status + classified Codex error payload. */
+export function adapterFailureFromMessage(message: string): { httpStatus: number; error: OcxErrorPayload } {
+  const httpStatus = inferHttpStatusFromAdapterMessage(message);
+  let finalMessage = message;
+  const retryAfterSeconds = parseRetryAfterFromMessage(message);
+  if (retryAfterSeconds && !/please try again in /i.test(message)) {
+    finalMessage = `${message} Please try again in ${retryAfterSeconds}s.`;
+  }
+  const errorType = httpStatus === 499
+    ? "client_closed_request"
+    : httpStatus === 429
+      ? "rate_limit_error"
+      : httpStatus === 401
+        ? "authentication_error"
+        : httpStatus === 403
+          ? "permission_error"
+          : httpStatus === 503 || httpStatus === 504
+            ? "server_error"
+            : httpStatus === 400
+              ? "invalid_request_error"
+              : "upstream_error";
+  return {
+    httpStatus,
+    error: classifyError(httpStatus, errorType, finalMessage),
+  };
+}
+
+/** Map a terminal Responses error object to the HTTP status we record in /api/logs. */
+export function httpStatusFromTerminalError(error: {
+  type?: string;
+  code?: string | null;
+  message?: string;
+} | undefined): number {
+  if (!error) return 502;
+  if (error.code === "client_closed_request" || error.code === "client_cancelled") return 499;
+  if (isCyberPolicyCode(error.code) || (error.message ? isCyberPolicyMessage(error.message) : false)) {
+    return 400;
+  }
+  if (error.type === "rate_limit_error" || error.code === "rate_limit_exceeded") return 429;
+  if (error.type === "authentication_error" || error.code === "invalid_api_key") return 401;
+  if (
+    error.type === "permission_error" ||
+    error.code === "permission_denied" ||
+    error.code === "subscription_required"
+  ) return 403;
+  if (error.type === "insufficient_quota" || error.code === "insufficient_quota") return 429;
+  if (error.type === "server_error" && error.code === "server_is_overloaded") return 503;
+  // Client-closed messages often arrive as invalid_request_error after classifyError; check message
+  // before treating every invalid_request_error as HTTP 400.
+  const message = error.message ?? "";
+  if (message && isClientClosedMessage(message)) return 499;
+  if (error.type === "invalid_request_error") return 400;
+  if (error.type === "proxy_error") return 500;
+  if (message) return inferHttpStatusFromAdapterMessage(message);
+  return 502;
+}

package/src/lib/eventstream-decoder.ts

@@ -0,0 +1,253 @@
+/**
+ * `application/vnd.amazon.eventstream` decoder.
+ *
+ * Ported from jawcode `packages/ai/src/providers/aws-eventstream.ts` (verbatim logic).
+ * Foundational dependency for AWS-eventstream providers: kiro (CodeWhisperer
+ * GenerateAssistantResponse) and amazon-bedrock (Converse). Self-contained — only
+ * uses Buffer / DataView / TextDecoder (Bun + Node compatible).
+ *
+ * Wire format (all integers big-endian):
+ *
+ *   [total length     u32]
+ *   [headers length   u32]
+ *   [prelude CRC32    u32]   <- CRC over the first 8 bytes
+ *   [headers          headers_length]
+ *   [payload          total_length - headers_length - 16]
+ *   [message CRC32    u32]   <- CRC over the entire message minus the trailing 4 bytes
+ *
+ * Headers: a sequence of `[name_len u8][name utf8][value_type u8][value …]`.
+ */
+
+const PRELUDE_LEN = 8;
+const PRELUDE_CRC_LEN = 4;
+const MESSAGE_CRC_LEN = 4;
+const HEADER_BLOCK_OFFSET = PRELUDE_LEN + PRELUDE_CRC_LEN;
+const MIN_MESSAGE_LEN = HEADER_BLOCK_OFFSET + MESSAGE_CRC_LEN;
+const MAX_MESSAGE_LEN = 16 * 1024 * 1024;
+const MAX_HEADERS_LEN = 128 * 1024;
+
+export interface EventStreamMessage {
+	/** Header casing is preserved verbatim (e.g. `:event-type`, `:message-type`). */
+	headers: Record<string, string>;
+	payload: Uint8Array;
+}
+
+/** CRC32 (IEEE / zlib polynomial 0xEDB88320), matches `@aws-crypto/crc32`. */
+const CRC_TABLE = (() => {
+	const t = new Uint32Array(256);
+	for (let i = 0; i < 256; i++) {
+		let c = i;
+		for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+		t[i] = c >>> 0;
+	}
+	return t;
+})();
+
+export function crc32(bytes: Uint8Array, seed = 0): number {
+	let c = (seed ^ 0xffffffff) >>> 0;
+	for (let i = 0; i < bytes.length; i++) c = (CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8)) >>> 0;
+	return (c ^ 0xffffffff) >>> 0;
+}
+
+/**
+ * Decode a single, fully buffered eventstream message. Throws if the framing is
+ * malformed or either CRC mismatches.
+ */
+export function decodeMessage(frame: Uint8Array): EventStreamMessage {
+	if (frame.length < MIN_MESSAGE_LEN) throw new Error("eventstream: frame too short");
+	const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
+	const total = view.getUint32(0, false);
+	if (total !== frame.length) throw new Error(`eventstream: framed length ${total} != buffer ${frame.length}`);
+	if (total > MAX_MESSAGE_LEN) throw new Error(`eventstream: total length ${total} exceeds maximum`);
+	const headersLen = view.getUint32(4, false);
+	const preludeCrc = view.getUint32(8, false);
+	const computedPreludeCrc = crc32(frame.subarray(0, PRELUDE_LEN));
+	if (computedPreludeCrc !== preludeCrc) throw new Error("eventstream: prelude CRC mismatch");
+	if (headersLen > MAX_HEADERS_LEN) throw new Error(`eventstream: headers length ${headersLen} exceeds maximum`);
+	if (headersLen > total - MIN_MESSAGE_LEN) throw new Error("eventstream: headers length exceeds frame payload");
+	const msgCrc = view.getUint32(total - MESSAGE_CRC_LEN, false);
+	const computedMsgCrc = crc32(frame.subarray(0, total - MESSAGE_CRC_LEN));
+	if (computedMsgCrc !== msgCrc) throw new Error("eventstream: message CRC mismatch");
+
+	const headersBytes = frame.subarray(HEADER_BLOCK_OFFSET, HEADER_BLOCK_OFFSET + headersLen);
+	const payload = frame.subarray(HEADER_BLOCK_OFFSET + headersLen, total - MESSAGE_CRC_LEN);
+	return { headers: parseHeaders(headersBytes), payload };
+}
+
+function parseHeaders(buf: Uint8Array): Record<string, string> {
+	const out: Record<string, string> = {};
+	const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+	const decoder = new TextDecoder();
+	let p = 0;
+	const need = (n: number, label: string) => {
+		if (p + n > buf.length) throw new Error(`eventstream: truncated header ${label}`);
+	};
+	while (p < buf.length) {
+		need(1, "name length");
+		const nameLen = view.getUint8(p);
+		p += 1;
+		need(nameLen, "name");
+		const name = decoder.decode(buf.subarray(p, p + nameLen));
+		p += nameLen;
+		need(1, "type");
+		const type = view.getUint8(p);
+		p += 1;
+		switch (type) {
+			case 0: // bool true
+				out[name] = "true";
+				break;
+			case 1: // bool false
+				out[name] = "false";
+				break;
+			case 2: // byte
+				need(1, "byte value");
+				out[name] = String(view.getInt8(p));
+				p += 1;
+				break;
+			case 3: // short
+				need(2, "short value");
+				out[name] = String(view.getInt16(p, false));
+				p += 2;
+				break;
+			case 4: // integer
+				need(4, "integer value");
+				out[name] = String(view.getInt32(p, false));
+				p += 4;
+				break;
+			case 5: // long — decimal string to avoid precision loss
+				need(8, "long value");
+				out[name] = bigIntFromBytes(buf.subarray(p, p + 8)).toString();
+				p += 8;
+				break;
+			case 6: {
+				// byte array — base64 for safe transport
+				need(2, "byte-array length");
+				const len = view.getUint16(p, false);
+				p += 2;
+				need(len, "byte-array value");
+				out[name] = Buffer.from(buf.buffer, buf.byteOffset + p, len).toString("base64");
+				p += len;
+				break;
+			}
+			case 7: {
+				// string
+				need(2, "string length");
+				const len = view.getUint16(p, false);
+				p += 2;
+				need(len, "string value");
+				out[name] = decoder.decode(buf.subarray(p, p + len));
+				p += len;
+				break;
+			}
+			case 8: // timestamp (ms since epoch as i64)
+				need(8, "timestamp value");
+				out[name] = new Date(Number(bigIntFromBytes(buf.subarray(p, p + 8)))).toISOString();
+				p += 8;
+				break;
+			case 9: {
+				// uuid
+				need(16, "uuid value");
+				const u = buf.subarray(p, p + 16);
+				const hex: string[] = [];
+				for (let i = 0; i < 16; i++) hex.push(u[i].toString(16).padStart(2, "0"));
+				out[name] =
+					`${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10, 16).join("")}`;
+				p += 16;
+				break;
+			}
+			default:
+				throw new Error(`eventstream: unknown header value type ${type}`);
+		}
+	}
+	return out;
+}
+
+function bigIntFromBytes(b: Uint8Array): bigint {
+	let v = 0n;
+	for (let i = 0; i < b.length; i++) v = (v << 8n) | BigInt(b[i]);
+	// sign-extend (two's complement)
+	if (b.length === 8 && b[0] & 0x80) v -= 1n << 64n;
+	return v;
+}
+
+/**
+ * Async generator that consumes a `ReadableStream<Uint8Array>` (a fetch response
+ * body) and yields fully-framed messages, handling arbitrary chunk boundaries.
+ */
+export async function* decodeEventStream(source: ReadableStream<Uint8Array>): AsyncGenerator<EventStreamMessage> {
+	const reader = source.getReader();
+	let buf: Uint8Array = new Uint8Array(0);
+	try {
+		while (true) {
+			const { value, done } = await reader.read();
+			if (value && value.length > 0) buf = buf.length === 0 ? value : Buffer.concat([buf, value]);
+			let offset = 0;
+			while (buf.length - offset >= 4) {
+				const dv = new DataView(buf.buffer, buf.byteOffset + offset, buf.length - offset);
+				const total = dv.getUint32(0, false);
+				if (total < MIN_MESSAGE_LEN) throw new Error(`eventstream: total length ${total} below minimum`);
+				if (total > MAX_MESSAGE_LEN) throw new Error(`eventstream: total length ${total} exceeds maximum`);
+				if (buf.length - offset >= HEADER_BLOCK_OFFSET) {
+					const headersLen = dv.getUint32(4, false);
+					const preludeCrc = dv.getUint32(8, false);
+					const computedPreludeCrc = crc32(buf.subarray(offset, offset + PRELUDE_LEN));
+					if (computedPreludeCrc !== preludeCrc) throw new Error("eventstream: prelude CRC mismatch");
+					if (headersLen > MAX_HEADERS_LEN) throw new Error(`eventstream: headers length ${headersLen} exceeds maximum`);
+				}
+				if (buf.length - offset < total) break;
+				const frame = buf.subarray(offset, offset + total);
+				yield decodeMessage(frame);
+				offset += total;
+			}
+			if (offset > 0) buf = buf.slice(offset);
+			if (buf.length > MAX_MESSAGE_LEN) throw new Error(`eventstream: buffered frame exceeds maximum ${MAX_MESSAGE_LEN}`);
+			if (done) break;
+		}
+		if (buf.length > 0) throw new Error("eventstream: truncated message at end of stream");
+	} finally {
+		// Early termination (consumer break/return, turn abort, or an HTTP/2 mid-body reset) can leave
+		// an in-flight `reader.read()` pending when this generator's `finally` runs. Releasing the lock
+		// does NOT settle that orphaned read — Bun then surfaces it as an off-path
+		// `unhandledRejection: TypeError: null is not an object` that no caller try/catch can intercept.
+		// Cancel first (settles the pending read + closes the body), then release. On a clean `done`
+		// finish the read is already settled, so cancel() is a harmless no-op.
+		try {
+			await reader.cancel();
+		} catch {
+			/* body already errored/closed — nothing to cancel */
+		}
+		try {
+			reader.releaseLock();
+		} catch {
+			/* lock already released by cancel() on some runtimes */
+		}
+	}
+}
+
+/** Build a single eventstream frame (string headers only) — used by tests and fixtures. */
+export function encodeMessage(headers: Record<string, string>, payload: Uint8Array): Uint8Array {
+	const enc = new TextEncoder();
+	const headerParts: Uint8Array[] = [];
+	for (const [name, value] of Object.entries(headers)) {
+		const nameBytes = enc.encode(name);
+		const valueBytes = enc.encode(value);
+		const head = new Uint8Array(1 + nameBytes.length + 1 + 2);
+		const hv = new DataView(head.buffer);
+		hv.setUint8(0, nameBytes.length);
+		head.set(nameBytes, 1);
+		hv.setUint8(1 + nameBytes.length, 7); // string type
+		hv.setUint16(1 + nameBytes.length + 1, valueBytes.length, false);
+		headerParts.push(head, valueBytes);
+	}
+	const headersBytes = Buffer.concat(headerParts.map(p => Buffer.from(p)));
+	const total = HEADER_BLOCK_OFFSET + headersBytes.length + payload.length + MESSAGE_CRC_LEN;
+	const frame = new Uint8Array(total);
+	const dv = new DataView(frame.buffer);
+	dv.setUint32(0, total, false);
+	dv.setUint32(4, headersBytes.length, false);
+	dv.setUint32(8, crc32(frame.subarray(0, PRELUDE_LEN)), false);
+	frame.set(headersBytes, HEADER_BLOCK_OFFSET);
+	frame.set(payload, HEADER_BLOCK_OFFSET + headersBytes.length);
+	dv.setUint32(total - MESSAGE_CRC_LEN, crc32(frame.subarray(0, total - MESSAGE_CRC_LEN)), false);
+	return frame;
+}