chainlesschain 0.166.99 → 0.166.101

package/src/lib/formal-budget-transport.js

@@ -0,0 +1,345 @@
+import {
+  budgetError,
+  canonical,
+  requireBudget,
+} from "./formal-budget-contract.js";
+
+export const FORMAL_BUDGET_RUNTIME_READINESS = Object.freeze({
+  paidReady: false,
+  reason:
+    "Agent, Chat, compaction, advisor, probes, retries and child-process egress are not yet all routed through this authority",
+});
+export function requireFormalBudgetRuntime() {
+  throw budgetError(
+    "CC_BUDGET_RUNTIME_NOT_COVERED",
+    FORMAL_BUDGET_RUNTIME_READINESS.reason,
+  );
+}
+
+// JSON.parse alone accepts duplicate keys (including escaped aliases) and
+// overflows numeric literals to Infinity. Neither is safe accounting evidence.
+export function parseBudgetJson(text) {
+  requireBudget(typeof text === "string", "JSON text required");
+  let at = 0;
+  const whitespace = () => {
+    while (at < text.length && /[\x20\t\r\n]/u.test(text[at])) at++;
+  };
+  function string() {
+    requireBudget(text[at] === '"', "JSON string expected");
+    const start = at++;
+    while (at < text.length) {
+      const char = text[at++];
+      if (char === '"') return JSON.parse(text.slice(start, at));
+      if (char === "\\") at++;
+    }
+    requireBudget(false, "Unterminated JSON string");
+  }
+  function value(depth) {
+    requireBudget(depth <= 64, "JSON nesting exceeds accounting parser bound");
+    whitespace();
+    if (text[at] === '"') {
+      string();
+      return;
+    }
+    if (text[at] === "{") {
+      at++;
+      whitespace();
+      const keys = new Set();
+      if (text[at] === "}") {
+        at++;
+        return;
+      }
+      for (;;) {
+        whitespace();
+        const key = string();
+        requireBudget(
+          !keys.has(key),
+          "Duplicate JSON member in provider evidence",
+        );
+        keys.add(key);
+        whitespace();
+        requireBudget(text[at++] === ":", "JSON member separator expected");
+        value(depth + 1);
+        whitespace();
+        const separator = text[at++];
+        if (separator === "}") return;
+        requireBudget(separator === ",", "JSON object separator expected");
+      }
+    }
+    if (text[at] === "[") {
+      at++;
+      whitespace();
+      if (text[at] === "]") {
+        at++;
+        return;
+      }
+      for (;;) {
+        value(depth + 1);
+        whitespace();
+        const separator = text[at++];
+        if (separator === "]") return;
+        requireBudget(separator === ",", "JSON array separator expected");
+      }
+    }
+    for (const literal of ["true", "false", "null"])
+      if (text.startsWith(literal, at)) {
+        at += literal.length;
+        return;
+      }
+    const number = text
+      .slice(at)
+      .match(/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/u)?.[0];
+    requireBudget(
+      number && Number.isFinite(Number(number)),
+      "Invalid or non-finite JSON number",
+    );
+    at += number.length;
+  }
+  value(0);
+  whitespace();
+  requireBudget(at === text.length, "Trailing JSON input");
+  return JSON.parse(text);
+}
+
+/** Allowlist only; the caller must still supply the existing OS sandbox. */
+export function formalBudgetTaskEnvironment(environment = process.env) {
+  return Object.fromEntries(
+    [
+      "PATH",
+      "Path",
+      "SystemRoot",
+      "SYSTEMROOT",
+      "WINDIR",
+      "ComSpec",
+      "PATHEXT",
+      "TEMP",
+      "TMP",
+      "TMPDIR",
+      "LANG",
+      "LC_ALL",
+      "LC_CTYPE",
+    ]
+      .filter((key) => typeof environment[key] === "string")
+      .map((key) => [key, environment[key]]),
+  );
+}
+
+async function boundedText(response, maximumBytes) {
+  requireBudget(response.body?.getReader, "Response body unavailable");
+  const reader = response.body.getReader(),
+    chunks = [];
+  let size = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      requireBudget(
+        size <= maximumBytes,
+        "Provider response exceeded bounded parser",
+      );
+      chunks.push(Buffer.from(value));
+    }
+  } catch (error) {
+    try {
+      await reader.cancel();
+    } catch {
+      /* keep original unknown outcome */
+    }
+    throw error;
+  } finally {
+    reader.releaseLock();
+  }
+  return new TextDecoder("utf-8", { fatal: true }).decode(
+    Buffer.concat(chunks),
+  );
+}
+function streamReceipt(text) {
+  let terminal = false,
+    receipt = null,
+    usage = null,
+    finishReason = null;
+  for (const frame of text.replaceAll("\r\n", "\n").split("\n\n")) {
+    if (!frame.trim()) continue;
+    const data = frame
+      .split("\n")
+      .filter((line) => line.startsWith("data:"))
+      .map((line) => line.slice(5).trimStart())
+      .join("\n");
+    if (!data) continue;
+    requireBudget(!terminal, "Unexpected stream data after terminal marker");
+    if (data === "[DONE]") {
+      requireBudget(
+        finishReason !== null,
+        "Stream ended without a completed choice",
+      );
+      terminal = true;
+      continue;
+    }
+    const row = parseBudgetJson(data);
+    requireBudget(row && !Object.hasOwn(row, "error"), "Provider stream error");
+    const identity = {
+      id: row.id,
+      model: row.model,
+      service_tier: row.service_tier,
+    };
+    if (!receipt) receipt = identity;
+    else {
+      // Some providers only send service_tier on the final usage frame.
+      requireBudget(
+        row.id === receipt.id && row.model === receipt.model,
+        "Stream identity changed",
+      );
+      if (row.service_tier !== undefined) {
+        requireBudget(
+          receipt.service_tier === undefined ||
+            row.service_tier === receipt.service_tier,
+          "Stream tier changed",
+        );
+        receipt.service_tier = row.service_tier;
+      }
+    }
+    requireBudget(
+      Array.isArray(row.choices) &&
+        row.choices.length <= 1 &&
+        row.choices.every((choice) => choice.index === 0),
+      "Multiple/unknown streamed completions",
+    );
+    for (const choice of row.choices) {
+      requireBudget(
+        finishReason === null,
+        "Choice data received after completed stream choice",
+      );
+      if (choice.finish_reason != null) {
+        requireBudget(
+          ["stop", "length", "tool_calls"].includes(choice.finish_reason),
+          "Unsupported stream finish reason",
+        );
+        finishReason = choice.finish_reason;
+      }
+    }
+    if (row.usage != null) {
+      requireBudget(
+        finishReason !== null,
+        "Usage received before complete stream choice",
+      );
+      requireBudget(
+        usage === null || canonical(usage) === canonical(row.usage),
+        "Conflicting streamed usage",
+      );
+      usage = row.usage;
+    }
+  }
+  requireBudget(
+    terminal && finishReason !== null && receipt && usage,
+    "Incomplete stream or missing usage",
+  );
+  return { ...receipt, usage };
+}
+
+/**
+ * Trusted-host JSON/SSE transport: credential stays in this closure, and every
+ * physical request consumes a durable dispatch exactly once. No auto retries.
+ * This is not the unrestricted Agent/Chat transport and is not auto-enabled.
+ */
+export function createFormalBudgetTransport({
+  authority,
+  credentialProvider,
+  fetchImpl = globalThis.fetch,
+  maximumResponseBytes = 16 * 1024 * 1024,
+  timeoutMs = 60_000,
+}) {
+  requireBudget(
+    authority &&
+      typeof credentialProvider === "function" &&
+      typeof fetchImpl === "function",
+    "Authority and trusted credential provider required",
+  );
+  requireBudget(
+    Number.isSafeInteger(maximumResponseBytes) &&
+      maximumResponseBytes > 0 &&
+      maximumResponseBytes <= 16 * 1024 * 1024,
+    "Invalid response byte bound",
+  );
+  requireBudget(
+    Number.isSafeInteger(timeoutMs) && timeoutMs > 0 && timeoutMs <= 300_000,
+    "Invalid timeout",
+  );
+  return Object.freeze({
+    async dispatch({ runId, callId, body, signal }) {
+      // Snapshot before await so caller mutation cannot alter the reserved body.
+      const request = JSON.parse(canonical(body));
+      authority.reserve({ runId, callId, body: request });
+      let settled = false;
+      try {
+        const reserved = authority.reservedContract(callId);
+        const credential = await credentialProvider({
+          contractId: reserved.id,
+          provider: reserved.provider,
+          endpoint: reserved.endpoint,
+        });
+        requireBudget(
+          typeof credential === "string" &&
+            credential.length > 0 &&
+            !/[\r\n]/u.test(credential),
+          "Credential unavailable",
+        );
+        const deadline = AbortSignal.timeout(timeoutMs);
+        const options = {
+          method: "POST",
+          redirect: "error",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${credential}`,
+          },
+          body: JSON.stringify(request),
+          signal: signal ? AbortSignal.any([signal, deadline]) : deadline,
+        };
+        // Final expiry/request check is AFTER every awaited preparation. There
+        // must be no await between this durable admission and physical fetch.
+        const contract = authority.markDispatched(callId, request);
+        const response = await fetchImpl(contract.endpoint, options);
+        requireBudget(response.ok, "Provider HTTP response not successful");
+        const text = await boundedText(response, maximumResponseBytes);
+        let receipt;
+        if (request.stream === true) {
+          requireBudget(
+            response.headers.get("content-type")?.includes("text/event-stream"),
+            "Unexpected stream content type",
+          );
+          receipt = streamReceipt(text);
+        } else {
+          receipt = parseBudgetJson(text);
+          requireBudget(
+            receipt && !Object.hasOwn(receipt, "error"),
+            "Provider error envelope cannot settle",
+          );
+          requireBudget(
+            Array.isArray(receipt.choices) &&
+              receipt.choices.length === 1 &&
+              receipt.choices[0].index === 0 &&
+              ["stop", "length", "tool_calls"].includes(
+                receipt.choices[0].finish_reason,
+              ),
+            "Incomplete or multiple completion response",
+          );
+        }
+        const cost = authority.settle(callId, receipt);
+        settled = true;
+        return { body: text, streaming: request.stream === true, cost };
+      } catch {
+        if (!settled) {
+          // Do not persist provider errors which may contain credentials/content.
+          authority.markUnknown(
+            callId,
+            "transport or settlement outcome unknown",
+          );
+        }
+        throw budgetError(
+          "CC_BUDGET_TRANSPORT_UNKNOWN",
+          "Provider outcome unknown; reservation retained and further dispatch blocked",
+        );
+      }
+    },
+  });
+}

package/src/lib/provider-http-error.js

@@ -3,6 +3,11 @@
  * Keep structured provider diagnostics while redacting credential-shaped text.
  */
 
+import {
+  attachStreamRetryMetadata,
+  captureStreamRetryMetadata,
+} from "./stream-retry.js";
+
 function safePart(value, secrets = []) {
   if (value == null) return "";
   let text = String(value);
@@ -111,3 +116,14 @@ export async function formatProviderResponseError(
     secrets,
   });
 }
+
+/** Keep response status authoritative even if reading its error body fails. */
+export async function createProviderResponseError(provider, response, options) {
+  const metadata = captureStreamRetryMetadata(response);
+  let message = await formatProviderResponseError(provider, response, options);
+  const remaining = metadata.retryAfterAt - Date.now();
+  if (Number.isFinite(remaining) && remaining > 0) {
+    message += ` Retry-After: wait at least ${Math.ceil(remaining / 1000)}s before an explicit retry.`;
+  }
+  return attachStreamRetryMetadata(new Error(message), metadata);
+}

package/src/lib/stream-retry.js

@@ -12,11 +12,196 @@
  * agent runtime.
  */
 
-import { isAbortError } from "./abort-utils.js";
+import {
+  createAbortError,
+  isAbortError,
+  raceWithAbort,
+  throwIfAborted,
+} from "./abort-utils.js";
 
 /** Bounded auto-retry budget for streaming connection drops (Claude-Code 2.1.181). */
 export const STREAM_RETRY_MAX = 2;
 export const STREAM_RETRY_BASE_MS = 400;
+export const STREAM_RETRY_MAX_DELAY_MS = 60_000;
+
+function isFailureStatus(status) {
+  return Number.isInteger(status) && status >= 400 && status <= 599;
+}
+
+function retryAfterHeader(headers) {
+  if (!headers) return undefined;
+  if (typeof headers.get === "function") return headers.get("retry-after");
+  const entries = Object.entries(headers).filter(
+    ([name]) => name.toLowerCase() === "retry-after",
+  );
+  // Multiple spellings or a list of values are ambiguous, not a delay.
+  return entries.length === 1 ? entries[0][1] : undefined;
+}
+
+function httpDate(value, now) {
+  // Accept the three HTTP-date wire formats, not Date.parse's permissive
+  // numeric/local-date syntax (e.g. "-1", "1.5", or "2026-10-12").
+  const weekday = "(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun)";
+  const month = "(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)";
+  let match = new RegExp(
+    `^(${weekday}), (\\d{2}) ${month} (\\d{4}) (\\d{2}):(\\d{2}):(\\d{2}) GMT$`,
+  ).exec(value);
+  let day, monthName, year, hour, minute, second, dayName;
+  if (match) {
+    [, dayName, day, monthName, year, hour, minute, second] = match;
+  } else {
+    match = new RegExp(
+      `^(Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday), (\\d{2})-${month}-(\\d{2}) (\\d{2}):(\\d{2}):(\\d{2}) GMT$`,
+    ).exec(value);
+    if (match) {
+      [, dayName, day, monthName, year, hour, minute, second] = match;
+      const currentYear = new Date(now).getUTCFullYear();
+      year = Math.floor(currentYear / 100) * 100 + Number(year);
+      if (year > currentYear + 50) year -= 100;
+    } else {
+      match = new RegExp(
+        `^(${weekday}) ${month} ( [1-9]|[12]\\d|3[01]) (\\d{2}):(\\d{2}):(\\d{2}) (\\d{4})$`,
+      ).exec(value);
+      if (!match) return undefined;
+      [, dayName, monthName, day, hour, minute, second, year] = match;
+    }
+  }
+  const months = "Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec".split(" ");
+  const monthIndex = months.indexOf(monthName);
+  const date = new Date(0);
+  date.setUTCFullYear(Number(year), monthIndex, Number(day));
+  date.setUTCHours(Number(hour), Number(minute), Number(second), 0);
+  // Reject normalized invalid calendar dates/times and mismatched weekdays.
+  if (
+    date.getUTCFullYear() !== Number(year) ||
+    date.getUTCMonth() !== monthIndex ||
+    date.getUTCDate() !== Number(day) ||
+    date.getUTCHours() !== Number(hour) ||
+    date.getUTCMinutes() !== Number(minute) ||
+    date.getUTCSeconds() !== Number(second) ||
+    date.toUTCString().slice(0, 3) !== dayName.slice(0, 3)
+  ) {
+    return undefined;
+  }
+  return date.getTime();
+}
+
+/** Capture a deadline when headers arrive, before reading a slow response body.
+ * No metadata here grants permission to retry an HTTP/provider verdict.
+ */
+export function captureStreamRetryMetadata(response, now = Date.now()) {
+  const metadata = {};
+  if (Number.isInteger(response?.status)) metadata.status = response.status;
+  const raw = retryAfterHeader(response?.headers);
+  if (typeof raw !== "string" || !Number.isFinite(now)) return metadata;
+  const value = raw.trim();
+  if (/^\d+$/.test(value)) {
+    const seconds = Number(value);
+    const deadline = now + seconds * 1000;
+    // A valid but unrepresentably large delay is a refusal to retry within our
+    // budget, NOT a missing header. Infinity is an internal fail-closed sentinel.
+    metadata.retryAfterAt = Number.isSafeInteger(deadline)
+      ? deadline
+      : Infinity;
+  } else {
+    const deadline = httpDate(value, now);
+    if (deadline !== undefined) metadata.retryAfterAt = deadline;
+  }
+  return metadata;
+}
+
+/** Preserve the original Error identity/code and the strongest known verdict. */
+export function attachStreamRetryMetadata(error, metadata = {}) {
+  if (!error || (typeof error !== "object" && typeof error !== "function"))
+    return error;
+  const hasFailureStatus = [
+    error.status,
+    error.statusCode,
+    error.cause?.status,
+    error.cause?.statusCode,
+  ].some(isFailureStatus);
+  if (!hasFailureStatus && Number.isInteger(metadata.status)) {
+    error.status = metadata.status;
+  }
+  if (
+    typeof metadata.retryAfterAt === "number" &&
+    !Number.isNaN(metadata.retryAfterAt) &&
+    metadata.retryAfterAt !== -Infinity
+  ) {
+    const previous = [error.retryAfterAt, error.cause?.retryAfterAt].filter(
+      (value) => typeof value === "number" && !Number.isNaN(value),
+    );
+    error.retryAfterAt = Math.max(metadata.retryAfterAt, ...previous);
+  }
+  return error;
+}
+
+/** Resolve the wait AFTER retry eligibility is checked; null means give up.
+ * Never clamp a server deadline to a shorter wait or authorize an HTTP replay.
+ * Attempt 1 is the first retry, matching the existing retry observer contract.
+ */
+export function resolveStreamRetryDelay(error, attempt, options = {}) {
+  const base = options.baseDelayMs ?? STREAM_RETRY_BASE_MS;
+  const now = options.now ?? Date.now();
+  const max = options.maxDelayMs ?? STREAM_RETRY_MAX_DELAY_MS;
+  if (
+    !Number.isInteger(attempt) ||
+    attempt < 1 ||
+    !Number.isFinite(base) ||
+    base < 0 ||
+    !Number.isFinite(now) ||
+    !Number.isFinite(max) ||
+    max < 0
+  )
+    return null;
+  const deadlines = [error?.retryAfterAt, error?.cause?.retryAfterAt].filter(
+    (value) => typeof value === "number" && !Number.isNaN(value),
+  );
+  const delay = Math.ceil(
+    Math.max(base * 2 ** (attempt - 1), 0, ...deadlines.map((at) => at - now)),
+  );
+  // Node clamps overflowing setTimeout delays to 1ms. Reject rather than
+  // accidentally turning a requested long delay into an immediate replay.
+  return Number.isFinite(delay) && delay <= max && delay <= 2_147_483_647
+    ? delay
+    : null;
+}
+
+/** Wait without keeping an obsolete backoff alive after user cancellation. */
+export async function waitForStreamRetry(ms, signal, { sleep } = {}) {
+  throwIfAborted(signal);
+  if (!Number.isFinite(ms) || ms < 0 || ms > 2_147_483_647)
+    throw new RangeError("Invalid streaming retry delay");
+  if (sleep) {
+    await raceWithAbort(
+      Promise.resolve().then(() => {
+        throwIfAborted(signal);
+        return sleep(ms);
+      }),
+      signal,
+    );
+    throwIfAborted(signal);
+    return;
+  }
+  await new Promise((resolve, reject) => {
+    let timer;
+    const cleanup = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener?.("abort", onAbort);
+    };
+    const onAbort = () => {
+      cleanup();
+      reject(signal.reason || createAbortError());
+    };
+    timer = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+    signal?.addEventListener?.("abort", onAbort, { once: true });
+    if (signal?.aborted) onAbort();
+  });
+  throwIfAborted(signal);
+}
 
 /**
  * Hard ceiling on the *configurable* retry budget (Claude-Code 2.1.186:
@@ -61,6 +246,15 @@ export function isRetryableStreamError(err, signal) {
   if (isAbortError(err)) return false;
   if (signal && signal.aborted) return false;
   if (!err) return false;
+  if (
+    [err, err.cause].some(
+      (error) =>
+        error?.noReplay === true ||
+        error?.streamOutputVisible === true ||
+        error?.isOutputBackpressureFailure === true,
+    )
+  )
+    return false;
   const msg = String(err.message || err).toLowerCase();
   // A provider verdict stays terminal even when its detail mentions a timeout,
   // reset or network failure. Inspect it before transport codes and wording so