@stage-labs/metro 0.1.0-beta.31 → 0.1.0-beta.310

package/runtime/node_modules/@metro-labs/daemon/src/gateway/effort.ts

@@ -0,0 +1,103 @@
+import type { IncomingMessage } from 'node:http';
+import { isRecord } from '@metro-labs/core/is-record';
+
+const MAIN_EFFORT = 'low';
+const SUBAGENT_EFFORT = 'max';
+export const BINDING_BETA = 'thinking-binding-controls-2026-08-01';
+
+const SUBAGENT_HEADER = 'x-claude-code-agent-id';
+const SUBAGENT_MARK = 'cc_is_subagent=true';
+const ABOVE_HIGH = new Set(['xhigh', 'max']);
+
+export type RequestKind = 'main' | 'subagent' | 'other';
+
+type Body = Record<string, unknown>;
+
+const record = (value: unknown): Body => (isRecord(value) ? value : {});
+
+const effortOf = (body: Body): string => {
+  const effort = record(body.output_config).effort;
+  return typeof effort === 'string' ? effort : '';
+};
+
+function header(req: IncomingMessage, name: string): string {
+  const raw = req.headers[name];
+  return (Array.isArray(raw) ? raw[0] : raw)?.trim() ?? '';
+}
+
+function systemMarksSubagent(body: Body): boolean {
+  const system = body.system;
+  if (!Array.isArray(system)) return false;
+  return system.some((block) => isRecord(block) && typeof block.text === 'string' && block.text.includes(SUBAGENT_MARK));
+}
+
+const chore = (body: Body): boolean => record(body.output_config).format !== undefined || record(body.thinking).type === 'disabled';
+
+export function requestKind(req: IncomingMessage, body: Body): RequestKind {
+  if (header(req, SUBAGENT_HEADER) !== '' || systemMarksSubagent(body)) return 'subagent';
+  return chore(body) ? 'other' : 'main';
+}
+
+const messagesOf = (body: Body): unknown[] => (Array.isArray(body.messages) ? body.messages : []);
+
+const askedEfforts = (body: Body): string[] => [body, ...messagesOf(body).map(record)].map(effortOf).filter((effort) => effort !== '');
+
+export function plannedEffort(req: IncomingMessage, body: Body): string | null {
+  const asked = askedEfforts(body);
+  if (asked.length === 0) return null;
+  const kind = requestKind(req, body);
+  if (kind === 'other') return null;
+  const wanted = kind === 'subagent' ? SUBAGENT_EFFORT : MAIN_EFFORT;
+  return asked.every((effort) => effort === wanted) ? null : wanted;
+}
+
+const withOwnEffort = (item: Body, effort: string): Body => (effortOf(item) === '' ? item : { ...item, output_config: { ...record(item.output_config), effort } });
+
+export function withEffort(body: Body, effort: string): Body {
+  const top = withOwnEffort(body, effort);
+  if (!Array.isArray(body.messages)) return top;
+  return { ...top, messages: body.messages.map((message: unknown) => (isRecord(message) ? withOwnEffort(message, effort) : message)) };
+}
+
+export function withoutEffort(body: Body): Body {
+  const config = Object.fromEntries(Object.entries(record(body.output_config)).filter(([key]) => key !== 'effort'));
+  if (Object.keys(config).length > 0) return { ...body, output_config: config };
+  return Object.fromEntries(Object.entries(body).filter(([key]) => key !== 'output_config'));
+}
+
+export function effortToApply(body: Body): string | null {
+  if (chore(body)) return null;
+  const effort = effortOf(body);
+  return effort === '' ? null : effort;
+}
+
+export const cappedEffort = (effort: string): string => (ABOVE_HIGH.has(effort) ? 'high' : effort);
+
+const THINKING_ALWAYS_ON = /claude-(fable|mythos)-5|claude-opus-5-5/;
+const REFUSES_THINKING_OFF = '"thinking.type.disabled" is not supported';
+const thinkingAlwaysOn = new Set<string>();
+
+export const thinkingOff = (body: Body): boolean => record(body.thinking).type === 'disabled';
+
+const alwaysThinks = (model: string): boolean => THINKING_ALWAYS_ON.test(model) || thinkingAlwaysOn.has(model);
+
+export function withThinkingFor(body: Body, model: string): Body {
+  if (!alwaysThinks(model) || !thinkingOff(body)) return body;
+  return Object.fromEntries(Object.entries(body).filter(([key]) => key !== 'thinking'));
+}
+
+export function learnAlwaysThinks(model: string, refusal: string): boolean {
+  if (!refusal.includes(REFUSES_THINKING_OFF)) return false;
+  thinkingAlwaysOn.add(model);
+  return true;
+}
+
+export function forgetLearnedThinking(): void {
+  thinkingAlwaysOn.clear();
+}
+
+export function withBlockBinding(body: Body): Body {
+  const thinking = body.thinking;
+  if (!isRecord(thinking) || thinking.block_binding !== undefined) return body;
+  return { ...body, thinking: { ...thinking, block_binding: { prefix_mismatch_behavior: 'drop_block' } } };
+}

package/runtime/node_modules/@metro-labs/daemon/src/gateway/eventstream.ts

@@ -0,0 +1,123 @@
+export interface EventStreamMessage {
+  headers: Record<string, string>;
+  payload: Buffer;
+}
+
+const PRELUDE_BYTES = 12;
+const CRC_BYTES = 4;
+
+const HEADER_TRUE = 0;
+const HEADER_FALSE = 1;
+const HEADER_BYTE = 2;
+const HEADER_SHORT = 3;
+const HEADER_INT = 4;
+const HEADER_LONG = 5;
+const HEADER_BYTES = 6;
+const HEADER_STRING = 7;
+const HEADER_TIMESTAMP = 8;
+const HEADER_UUID = 9;
+
+const FIXED_WIDTH: Record<number, number> = {
+  [HEADER_TRUE]: 0,
+  [HEADER_FALSE]: 0,
+  [HEADER_BYTE]: 1,
+  [HEADER_SHORT]: 2,
+  [HEADER_INT]: 4,
+  [HEADER_LONG]: 8,
+  [HEADER_TIMESTAMP]: 8,
+  [HEADER_UUID]: 16,
+};
+
+function readHeaderValue(buf: Buffer, at: number, type: number): { value: string; next: number } {
+  if (type === HEADER_BYTES || type === HEADER_STRING) {
+    const len = buf.readUInt16BE(at);
+    const raw = buf.subarray(at + 2, at + 2 + len);
+    const value = type === HEADER_STRING ? raw.toString('utf8') : raw.toString('base64');
+    return { value, next: at + 2 + len };
+  }
+  const width = FIXED_WIDTH[type];
+  if (width === undefined) throw new Error(`eventstream: unknown header type ${String(type)}`);
+  if (type === HEADER_TRUE) return { value: 'true', next: at };
+  if (type === HEADER_FALSE) return { value: 'false', next: at };
+  return { value: buf.subarray(at, at + width).toString('hex'), next: at + width };
+}
+
+function readHeaders(buf: Buffer): Record<string, string> {
+  const out: Record<string, string> = {};
+  let at = 0;
+  while (at < buf.length) {
+    const nameLen = buf.readUInt8(at);
+    const name = buf.subarray(at + 1, at + 1 + nameLen).toString('utf8');
+    const type = buf.readUInt8(at + 1 + nameLen);
+    const parsed = readHeaderValue(buf, at + 2 + nameLen, type);
+    out[name] = parsed.value;
+    at = parsed.next;
+  }
+  return out;
+}
+
+function decodeFrame(buf: Buffer, offset: number): { message: EventStreamMessage; end: number } | null {
+  if (buf.length - offset < PRELUDE_BYTES) return null;
+  const total = buf.readUInt32BE(offset);
+  const headersLen = buf.readUInt32BE(offset + 4);
+  if (total < PRELUDE_BYTES + CRC_BYTES || headersLen > total) throw new Error('eventstream: malformed frame prelude');
+  if (buf.length - offset < total) return null;
+  const headersStart = offset + PRELUDE_BYTES;
+  const payloadStart = headersStart + headersLen;
+  const payloadEnd = offset + total - CRC_BYTES;
+  return {
+    message: {
+      headers: readHeaders(buf.subarray(headersStart, payloadStart)),
+      payload: Buffer.from(buf.subarray(payloadStart, payloadEnd)),
+    },
+    end: offset + total,
+  };
+}
+
+export class EventStreamDecoder {
+  private pending: Buffer = Buffer.alloc(0);
+
+  push(chunk: Buffer): EventStreamMessage[] {
+    this.pending = this.pending.length === 0 ? chunk : Buffer.concat([this.pending, chunk]);
+    const out: EventStreamMessage[] = [];
+    let offset = 0;
+    for (;;) {
+      const frame = decodeFrame(this.pending, offset);
+      if (frame === null) break;
+      out.push(frame.message);
+      offset = frame.end;
+    }
+    this.pending = this.pending.subarray(offset);
+    return out;
+  }
+}
+
+function encodeHeader(name: string, value: string): Buffer {
+  const nameBuf = Buffer.from(name, 'utf8');
+  const valueBuf = Buffer.from(value, 'utf8');
+  const out = Buffer.alloc(1 + nameBuf.length + 1 + 2 + valueBuf.length);
+  let at = 0;
+  out.writeUInt8(nameBuf.length, at);
+  at += 1;
+  nameBuf.copy(out, at);
+  at += nameBuf.length;
+  out.writeUInt8(HEADER_STRING, at);
+  at += 1;
+  out.writeUInt16BE(valueBuf.length, at);
+  at += 2;
+  valueBuf.copy(out, at);
+  return out;
+}
+
+export function encodeFrame(headers: Record<string, string>, payload: Buffer): Buffer {
+  const headerBuf = Buffer.concat(Object.entries(headers).map(([name, value]) => encodeHeader(name, value)));
+  const total = PRELUDE_BYTES + headerBuf.length + payload.length + CRC_BYTES;
+  const out = Buffer.alloc(total);
+  out.writeUInt32BE(total, 0);
+  out.writeUInt32BE(headerBuf.length, 4);
+  out.writeUInt32BE(0, 8);
+  headerBuf.copy(out, PRELUDE_BYTES);
+  payload.copy(out, PRELUDE_BYTES + headerBuf.length);
+  out.writeUInt32BE(0, total - CRC_BYTES);
+  return out;
+}

package/runtime/node_modules/@metro-labs/daemon/src/gateway/fallback.ts

@@ -0,0 +1,146 @@
+import { log } from '@metro-labs/core/log';
+import { lastServed } from './served.js';
+import { PER_MINUTE, usageOf, type UsageWindow } from './usage.js';
+import { bareModel, connectionOf, isSmallModel, notReady, primaryRoute, routeLabel, type Connection, type Fallback, type ModelSetup, type Route } from './model-config.js';
+
+export const USAGE_LIMIT = 0.95;
+const COOLDOWN_MS = 60_000;
+const SCOPED = 'Weekly, ';
+const MS_PER_SECOND = 1000;
+
+export interface Hold {
+  reason: string;
+  until: string | null;
+}
+
+interface Cooling {
+  until: number;
+  reason: string;
+}
+
+const cooling = new Map<string, Cooling>();
+let lastChoice = '';
+
+const keyOf = (route: Route): string => `${route.connection.id}\n${route.model}`;
+
+export function forgetFallbackState(): void {
+  cooling.clear();
+  lastChoice = '';
+}
+
+function scopeOf(label: string): string | null {
+  if (!label.startsWith(SCOPED) || label === 'Weekly, all models') return null;
+  return (label.slice(SCOPED.length).trim().split(/\s+/)[0] ?? '').toLowerCase();
+}
+
+function applies(window: UsageWindow, route: Route, now: number): boolean {
+  if (window.used === null || window.label === PER_MINUTE) return false;
+  if (window.resetAt !== null && Date.parse(window.resetAt) <= now) return false;
+  const scope = scopeOf(window.label);
+  return scope === null || route.model.toLowerCase().split(/[^a-z0-9]+/).includes(scope);
+}
+
+export function windowsFor(route: Route, now = Date.now()): UsageWindow[] {
+  return (usageOf(route.connection.id)?.windows ?? []).filter((w) => applies(w, route, now));
+}
+
+const percent = (used: number): string => `${String(Math.round(used * 100))}%`;
+
+export function holdOf(route: Route, now = Date.now()): Hold | null {
+  const cool = cooling.get(keyOf(route));
+  if (cool !== undefined && cool.until > now) return { reason: cool.reason, until: new Date(cool.until).toISOString() };
+  const over = windowsFor(route, now).find((w) => (w.used ?? 0) > USAGE_LIMIT);
+  return over === undefined ? null : { reason: `${over.label} ${percent(over.used ?? 0)}`, until: over.resetAt };
+}
+
+function fallbackModel(requested: string, conn: Connection, model: string): string {
+  const bare = bareModel(requested);
+  return model === '' || (conn.provider === 'anthropic' && isSmallModel(bare)) ? bare : model;
+}
+
+function fallbackRoute(setup: ModelSetup, fallback: Fallback, requested: string): Route | null {
+  const conn = connectionOf(setup, fallback.connection);
+  if (conn === null || notReady({ connection: conn, model: fallback.model }) !== null) return null;
+  return { connection: conn, model: fallbackModel(requested, conn, fallback.model) };
+}
+
+const unique = (routes: Route[]): Route[] => routes.filter((route, at) => routes.findIndex((other) => keyOf(other) === keyOf(route)) === at);
+
+export const chainOf = (primary: Route, setup: ModelSetup, requested: string): Route[] =>
+  unique([primary, ...setup.fallbacks.flatMap((f) => fallbackRoute(setup, f, requested) ?? [])]);
+
+export function routesToTry(chain: Route[], now = Date.now()): Route[] {
+  const open = chain.filter((route) => holdOf(route, now) === null);
+  return open.length > 0 ? open : chain.slice(0, 1);
+}
+
+function secondsHeader(headers: Headers, name: string): number | null {
+  const raw = headers.get(name);
+  if (raw === null || raw.trim() === '') return null;
+  const value = Number(raw);
+  return Number.isFinite(value) && value > 0 ? value : null;
+}
+
+function coolUntil(headers: Headers, now: number): number {
+  const after = secondsHeader(headers, 'retry-after');
+  if (after !== null) return now + after * MS_PER_SECOND;
+  const reset = secondsHeader(headers, 'anthropic-ratelimit-unified-reset');
+  if (reset !== null && reset * MS_PER_SECOND > now) return reset * MS_PER_SECOND;
+  return now + COOLDOWN_MS;
+}
+
+export function noteRefused(route: Route, status: number, headers: Headers, next: Route | undefined, now = Date.now()): void {
+  const reason = `answered ${String(status)}`;
+  cooling.set(keyOf(route), { until: coolUntil(headers, now), reason });
+  log.warn({ from: routeLabel(route), to: next === undefined ? null : routeLabel(next), status }, 'gateway: the model hit its limit, so the request goes to the next fallback model');
+}
+
+export function noteChoice(primary: Route, chosen: Route, now = Date.now()): void {
+  const key = keyOf(chosen);
+  if (key === lastChoice) return;
+  const first = lastChoice === '';
+  lastChoice = key;
+  if (key === keyOf(primary)) {
+    if (!first) log.info({ model: routeLabel(chosen), connection: chosen.connection.label }, 'gateway: back on the first model of the fallback list');
+    return;
+  }
+  const hold = holdOf(primary, now);
+  log.info(
+    { from: routeLabel(primary), to: routeLabel(chosen), connection: chosen.connection.label, reason: hold?.reason ?? null, until: hold?.until ?? null },
+    'gateway: the first model is over its limit, so requests go to a fallback model',
+  );
+}
+
+export interface ChainRow {
+  connection: string;
+  model: string;
+  used: number | null;
+  hold: Hold | null;
+  active: boolean;
+}
+
+function primaryOf(setup: ModelSetup): Route | null {
+  const primary = primaryRoute(setup);
+  if (primary === null) return null;
+  const served = lastServed();
+  const model = primary.model !== '' ? primary.model : served?.connection === primary.connection.id ? served.model : '';
+  return { connection: primary.connection, model };
+}
+
+function rowOf(route: Route, now: number): Omit<ChainRow, 'active'> {
+  const reason = notReady(route);
+  const used = windowsFor(route, now).reduce<number | null>((most, w) => Math.max(most ?? 0, w.used ?? 0), null);
+  return { connection: route.connection.id, model: route.model, used, hold: reason === null ? holdOf(route, now) : { reason, until: null } };
+}
+
+export function chainStatus(setup: ModelSetup, now = Date.now()): ChainRow[] {
+  const primary = primaryOf(setup);
+  if (primary === null) return [];
+  const listed = setup.fallbacks.flatMap((f) => {
+    const conn = connectionOf(setup, f.connection);
+    return conn === null ? [] : [{ connection: conn, model: f.model }];
+  });
+  const rows = unique([primary, ...listed]).map((route) => rowOf(route, now));
+  const active = Math.max(0, rows.findIndex((row) => row.hold === null));
+  return rows.map((row, at) => ({ ...row, active: at === active }));
+}

package/runtime/node_modules/@metro-labs/daemon/src/gateway/forward.ts

@@ -0,0 +1,284 @@
+import type { IncomingMessage, OutgoingHttpHeader, OutgoingHttpHeaders, ServerResponse } from 'node:http';
+import { UsageScanner } from './usage.js';
+
+export class GatewayError extends Error {
+  constructor(
+    readonly status: number,
+    readonly kind: string,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+const BODY_MAX = 64 * 1024 * 1024;
+const DRAIN_FACTOR = 2;
+const PING_MS = 25_000;
+const PING_FRAME = 'event: ping\ndata: {"type":"ping"}\n\n';
+const IDLE_MS = 300_000;
+const HOP_BY_HOP = new Set([
+  'host',
+  'connection',
+  'content-length',
+  'transfer-encoding',
+  'keep-alive',
+  'proxy-authorization',
+  'te',
+  'trailer',
+  'upgrade',
+  'accept-encoding',
+  'x-metro-key',
+]);
+const RESPONSE_DROP = new Set(['content-length', 'content-encoding', 'transfer-encoding', 'connection', 'keep-alive']);
+
+export function sendError(res: ServerResponse, status: number, kind: string, message: string): void {
+  res.writeHead(status, { 'content-type': 'application/json' });
+  res.end(JSON.stringify({ type: 'error', error: { type: kind, message } }));
+}
+
+export const errorFrame = (kind: string, message: string): string => `event: error\ndata: ${JSON.stringify({ type: 'error', error: { type: kind, message } })}\n\n`;
+
+export const providerStatus = (status: number): number => (status === 401 ? 403 : status);
+
+const idleMs = (): number => Number(process.env.METRO_GATEWAY_IDLE_MS) || IDLE_MS;
+
+const idleMessage = (ms: number): string => `metro gateway: the provider sent nothing for ${String(Math.round(ms / 1000))}s; giving up on this request`;
+
+export interface Watch {
+  signal: AbortSignal;
+  ms: number;
+  touch: () => void;
+  idle: () => boolean;
+  stop: () => void;
+}
+
+export function watchUpstream(res: ServerResponse, ms = idleMs()): Watch {
+  const control = new AbortController();
+  let expired = false;
+  let timer: NodeJS.Timeout | null = null;
+  const stop = (): void => {
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+  };
+  const arm = (): void => {
+    stop();
+    timer = setTimeout(() => {
+      expired = true;
+      control.abort();
+    }, ms);
+    timer.unref();
+  };
+  res.on('close', () => {
+    stop();
+    if (!res.writableEnded) control.abort();
+  });
+  arm();
+  return { signal: control.signal, ms, touch: arm, idle: () => expired, stop };
+}
+
+export async function readBody(req: IncomingMessage): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  let total = 0;
+  let over = false;
+  for await (const chunk of req) {
+    const buf = chunk as Buffer;
+    total += buf.length;
+    if (total > BODY_MAX) {
+      over = true;
+      if (total > BODY_MAX * DRAIN_FACTOR) break;
+      continue;
+    }
+    chunks.push(buf);
+  }
+  if (over) throw new GatewayError(413, 'invalid_request_error', 'request too large');
+  return Buffer.concat(chunks);
+}
+
+export function parseJson(raw: Buffer): Record<string, unknown> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw.toString('utf8'));
+  } catch {
+    throw new GatewayError(400, 'invalid_request_error', 'body must be JSON');
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+    throw new GatewayError(400, 'invalid_request_error', 'body must be a JSON object');
+  return parsed as Record<string, unknown>;
+}
+
+export function forwardedHeaders(req: IncomingMessage): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [name, value] of Object.entries(req.headers)) {
+    if (HOP_BY_HOP.has(name) || value === undefined) continue;
+    out[name] = Array.isArray(value) ? value.join(', ') : value;
+  }
+  return out;
+}
+
+export function anthropicHeaders(req: IncomingMessage, apiKey: string): Record<string, string> {
+  const headers = forwardedHeaders(req);
+  delete headers.authorization;
+  const betas = (headers['anthropic-beta'] ?? '')
+    .split(',')
+    .map((beta) => beta.trim())
+    .filter((beta) => beta !== '' && !beta.includes('oauth'));
+  if (betas.length > 0) headers['anthropic-beta'] = betas.join(',');
+  else delete headers['anthropic-beta'];
+  headers['x-api-key'] = apiKey;
+  return headers;
+}
+
+export const OAUTH_BETA = 'oauth-2025-04-20';
+
+export function loginHeaders(req: IncomingMessage, token: string): Record<string, string> {
+  const headers = forwardedHeaders(req);
+  delete headers['x-api-key'];
+  headers.authorization = `Bearer ${token}`;
+  return addBeta(headers, OAUTH_BETA);
+}
+
+export function addBeta(headers: Record<string, string>, beta: string): Record<string, string> {
+  const listed = (headers['anthropic-beta'] ?? '')
+    .split(',')
+    .map((one) => one.trim())
+    .filter((one) => one !== '');
+  if (listed.includes(beta)) return headers;
+  return { ...headers, 'anthropic-beta': [...listed, beta].join(',') };
+}
+
+export interface PipeOptions {
+  keepalive?: boolean;
+  ownCredential?: boolean;
+  scanner?: UsageScanner;
+}
+
+function openResponse(upstream: Response, res: ServerResponse, opts: PipeOptions): boolean {
+  const headers: Record<string, string> = {};
+  upstream.headers.forEach((value, name) => {
+    if (!RESPONSE_DROP.has(name)) headers[name] = value;
+  });
+  res.writeHead(opts.ownCredential === true ? providerStatus(upstream.status) : upstream.status, headers);
+  return (upstream.headers.get('content-type') ?? '').startsWith('text/event-stream');
+}
+
+async function pump(body: ReadableStream<Uint8Array>, res: ServerResponse, watch: Watch, scanner?: UsageScanner): Promise<void> {
+  const reader = body.getReader();
+  const decoder = scanner === undefined ? null : new TextDecoder();
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) return;
+    watch.touch();
+    if (decoder !== null) scanner?.feed(decoder.decode(value, { stream: true }));
+    res.write(value);
+  }
+}
+
+export async function pipeResponse(upstream: Response, res: ServerResponse, watch: Watch, opts: PipeOptions = {}): Promise<void> {
+  const streaming = openResponse(upstream, res, opts);
+  const body = upstream.body;
+  if (body === null) {
+    res.end();
+    return;
+  }
+  const ping = opts.keepalive === true && streaming ? setInterval(() => res.write(PING_FRAME), PING_MS) : null;
+  try {
+    await pump(body, res, watch, opts.scanner);
+  } catch (err) {
+    if (!watch.idle()) throw err;
+    if (streaming) res.write(errorFrame('api_error', idleMessage(watch.ms)));
+  } finally {
+    if (ping !== null) clearInterval(ping);
+    watch.stop();
+    res.end();
+    opts.scanner?.done();
+  }
+}
+
+export interface Relayed {
+  push: (chunk: Uint8Array, emit: (frames: string) => void) => void;
+  close: () => string;
+  idle: (message: string) => string;
+}
+
+export async function relayFrames(upstream: Response, res: ServerResponse, watch: Watch, key: string, relayed: Relayed): Promise<void> {
+  res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-store', connection: 'keep-alive' });
+  const body = upstream.body;
+  if (body === null) {
+    res.end(relayed.close());
+    return;
+  }
+  const ping = setInterval(() => res.write(PING_FRAME), PING_MS);
+  const scanner = new UsageScanner(key);
+  const emit = (frames: string): void => {
+    if (frames === '') return;
+    scanner.feed(frames);
+    res.write(frames);
+  };
+  try {
+    const reader = body.getReader();
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      watch.touch();
+      relayed.push(value, emit);
+    }
+    emit(relayed.close());
+  } catch (err) {
+    if (!watch.idle()) throw err;
+    res.write(relayed.idle(idleMessage(watch.ms)));
+  } finally {
+    clearInterval(ping);
+    watch.stop();
+    res.end();
+    scanner.done();
+  }
+}
+
+export function upstreamMessage(text: string, fallback: string): string {
+  if (text === '') return fallback;
+  try {
+    const parsed = JSON.parse(text) as { message?: unknown; Message?: unknown; error?: { message?: unknown } };
+    const message = parsed.message ?? parsed.Message ?? parsed.error?.message;
+    return typeof message === 'string' && message !== '' ? message : text;
+  } catch {
+    return text;
+  }
+}
+
+const LIMIT_STATUSES = new Set([402, 429]);
+
+export interface Refusal {
+  status: number;
+  headers: Headers;
+}
+
+export interface Held {
+  res: ServerResponse;
+  refusal: () => Refusal | null;
+}
+
+function headersOf(raw: OutgoingHttpHeaders | OutgoingHttpHeader[] | undefined): Headers {
+  const out = new Headers();
+  if (raw === undefined || Array.isArray(raw)) return out;
+  for (const [name, value] of Object.entries(raw)) if (value !== undefined) out.set(name, Array.isArray(value) ? value.join(', ') : String(value));
+  return out;
+}
+
+export function holdLimitRefusal(res: ServerResponse): Held {
+  let refusal: Refusal | null = null;
+  const swallow = (): boolean => true;
+  const held: ServerResponse = new Proxy(res, {
+    get(target, prop) {
+      if (prop === 'writeHead')
+        return (status: number, headers?: OutgoingHttpHeaders | OutgoingHttpHeader[]): ServerResponse => {
+          if (!LIMIT_STATUSES.has(status)) return target.writeHead(status, headers);
+          refusal = { status, headers: headersOf(headers) };
+          return held;
+        };
+      if (refusal !== null && (prop === 'write' || prop === 'end')) return swallow;
+      const value: unknown = Reflect.get(target, prop, target);
+      return typeof value === 'function' ? (value as (...args: unknown[]) => unknown).bind(target) : value;
+    },
+  });
+  return { res: held, refusal: () => refusal };
+}