@runuai/host 0.9.170 → 0.9.172

package/lib/credentials-activation-authority.ts

@@ -65,6 +65,14 @@
  * transition the authority does. Should saying so fail, the
  * runner is pending again, withdraws what it advertised, and says so later.
  *
+ * What stops the switch is said to the cloud as well as logged (`status`,
+ * on every capability frame; `onStatusChange` when it changes): the latest
+ * refusal or blocker, who gave it (the cloud's answer, or this runner), each
+ * blocker apart and every Compose project the retirement could not prove
+ * Uai's. A transient one (the container runtime still preparing after a
+ * reconnect, an unanswered ask) never replaces a substantive one: an
+ * operator reading Connections sees what to fix, not what fixes itself.
+ *
  * The record holds no secret: `{"schemaVersion":1,"step":"local",
  * "stopped":[{"taskId":"…","runEpoch":3}]}`. One the runner cannot read
  * counts as `local`, never as `legacy`: a damaged record may stand for a
@@ -88,6 +96,14 @@ import {
 import { dirname } from "node:path";
 
 import type { CredentialsActivationPhase } from "../src/cloud-credentials";
+import {
+  MAX_CREDENTIALS_SWITCH_BLOCKER_CHARS,
+  MAX_CREDENTIALS_SWITCH_BLOCKERS,
+  MAX_CREDENTIALS_SWITCH_DETAIL_CHARS,
+  MAX_CREDENTIALS_SWITCH_PROJECTS,
+  type CredentialsSwitchCapability,
+  type CredentialsSwitchStuck,
+} from "../src/protocol";
 import type { CredentialsMode } from "./cloud-credential-host";
 import type { RetirementPlan } from "./legacy-runtime-retirement";
 import { isSafeHostTaskId } from "./task-identity";
@@ -167,6 +183,12 @@ export interface ActivationAuthorityDeps<Retirement = RetirementPlan> {
   /** Ask the runner's supervisor for a restart. */
   restart: (why: string) => void;
   log: (line: string) => void;
+  /** `status()` changed: advertise it again. */
+  onStatusChange?: () => void;
+  /** What `status()` says of a blocker, made fit to leave the machine (the
+   *  home directory as `~`). */
+  redact?: (text: string) => string;
+  now?: () => number;
 }
 
 export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
@@ -191,6 +213,14 @@ export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
   #lastNote: string | null = null;
   /** Leaving the runner's own credentials failed in this process. */
   #stuck = false;
+  /** What stops the switch now, as `status()` says it. */
+  #blocker: CredentialsSwitchStuck | null = null;
+  /** Every Compose project the current blocker names, past the status's
+   *  bound too: what the log lists, and what tells one blocker from another
+   *  when only names past that bound changed. */
+  #blockerProjects = "";
+  /** `status()` as last told to `onStatusChange`'s caller. */
+  #published: string | null = null;
 
   constructor(deps: ActivationAuthorityDeps<Retirement>) {
     this.#deps = deps;
@@ -218,6 +248,13 @@ export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
     return this.#record?.step ?? null;
   }
 
+  /** Where the switch stands, for the capability frame (see the header). */
+  status(): CredentialsSwitchCapability {
+    const state = this.mode();
+    const stuck = state === "active" ? null : this.#blocker;
+    return stuck === null ? { state } : { state, stuck: { ...stuck } };
+  }
+
   mode(): CredentialsMode {
     if (this.#record === null) {
       return this.#initiallyPending ? "pending" : "legacy";
@@ -249,9 +286,12 @@ export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
   advance(): Promise<void> {
     if (this.#advancing === null) {
       this.#advancing = this.#advanceOnce()
-        .catch((error: unknown) => this.#note(`activation stopped: ${message(error)}; it tries again later`))
+        .catch((error: unknown) =>
+          this.#block("runner", error, `activation stopped: ${message(error)}; it tries again later`),
+        )
         .finally(() => {
           this.#advancing = null;
+          this.#publish();
         });
     }
     return this.#advancing;
@@ -266,10 +306,13 @@ export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
     }
     let plan: Retirement | null = null;
     if (this.#record === null) {
-      if (!this.#deps.eligible()) return;
-      const prepared = await this.#deps.ask("prepare");
+      if (!this.#deps.eligible()) {
+        this.#blocker = null;
+        return;
+      }
+      const prepared = await this.#ask("prepare");
       if (!prepared.ok) {
-        this.#note(`the cloud did not agree to cloud credentials yet: ${prepared.error}`);
+        this.#block("cloud", prepared.error, `the cloud did not agree to cloud credentials yet: ${prepared.error}`);
         return;
       }
       const paused = this.#deps.pauseLegacyStarts();
@@ -287,7 +330,9 @@ export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
         this.#record ??= readActivationRecord(this.#deps.recordPath);
         if (this.#record === null) {
           paused.resume();
-          this.#note(
+          this.#block(
+            "runner",
+            error,
             this.#initiallyPending
               ? `the v1-required task machine stays pending, with no v0 fallback: ${message(error)}`
               : `the runner stays on its own credentials, nothing changed: ${message(error)}`,
@@ -295,6 +340,7 @@ export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
           return;
         }
       }
+      this.#blocker = null;
       this.#deps.log("[credentials] switching to cloud credentials: leaving the runner's own");
     }
     if (!this.#synced()) return;
@@ -319,11 +365,16 @@ export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
       plan ??= await this.#deps.planRetirement();
       await this.#retire(plan);
       await this.#deps.claimFloor();
-      const committed = await this.#deps.ask("commit");
+      const committed = await this.#ask("commit");
       if (!committed.ok) {
-        this.#note(`the cloud did not record this runner's switch yet: ${committed.error}; it runs no task meanwhile`);
+        this.#block(
+          "cloud",
+          committed.error,
+          `the cloud did not record this runner's switch yet: ${committed.error}; it runs no task meanwhile`,
+        );
         return;
       }
+      this.#blocker = null;
       this.#write({ ...this.#record, step: "cloud" });
     }
     if (this.#record?.step === "cloud") {
@@ -350,7 +401,9 @@ export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
         this.#write(record);
       }
     } catch (error) {
-      this.#note(
+      this.#block(
+        "runner",
+        error,
         `the activation record is not known to be on disk yet (${message(error)}): the switch waits, running no task, ` +
           "until it is",
       );
@@ -373,7 +426,9 @@ export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
       try {
         await this.#deps.sweep();
       } catch (error) {
-        this.#note(
+        this.#block(
+          "runner",
+          error,
           `the recovery sweep failed (${message(error)}): the runner stays pending, running no task, and sweeps again later`,
         );
         return;
@@ -397,10 +452,15 @@ export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
     }
     if (failure === null) {
       this.#announced = true;
+      this.#blocker = null;
       this.#deps.log("[credentials] tasks run on cloud credentials");
       return;
     }
-    this.#note(`saying the runner is active failed (${message(failure)}): it is pending again, and tries again later`);
+    this.#block(
+      "runner",
+      failure,
+      `saying the runner is active failed (${message(failure)}): it is pending again, and tries again later`,
+    );
     try {
       this.#deps.onActiveWithdrawn();
     } catch (error) {
@@ -441,6 +501,67 @@ export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
     this.#durable = true;
   }
 
+  /** One phase asked of the cloud. An ask that could not be made or was not
+   *  answered says nothing about the switch: transient. */
+  async #ask(phase: CredentialsActivationPhase): Promise<ActivationAnswer> {
+    try {
+      return await this.#deps.ask(phase);
+    } catch (error) {
+      throw new TransientActivationError(message(error));
+    }
+  }
+
+  /** A refusal or blocker: logged, and what `status()` says unless it is
+   *  transient and a substantive one is already said (see the header). */
+  #block(by: CredentialsSwitchStuck["by"], why: unknown, line: string): void {
+    this.#note(line);
+    const transient = isTransient(why);
+    if (transient && this.#blocker !== null && this.#blocker.transient !== true) return;
+    const redact = this.#deps.redact ?? ((text: string) => text);
+    const detail = bounded(redact(oneLine(typeof why === "string" ? why : message(why))), MAX_CREDENTIALS_SWITCH_DETAIL_CHARS);
+    const next: CredentialsSwitchStuck = { by, detail, since: (this.#deps.now ?? Date.now)() };
+    const structured = why as { blockers?: unknown; unprovenProjects?: unknown } | null;
+    const blockers = stringList(structured?.blockers);
+    if (blockers.length > 0) {
+      next.blockers = blockers
+        .slice(0, MAX_CREDENTIALS_SWITCH_BLOCKERS)
+        .map((blocker) => bounded(redact(oneLine(blocker)), MAX_CREDENTIALS_SWITCH_BLOCKER_CHARS));
+    }
+    const projects = stringList(structured?.unprovenProjects);
+    if (projects.length > 0) {
+      next.composeProjects = { names: projects.slice(0, MAX_CREDENTIALS_SWITCH_PROJECTS), total: projects.length };
+    }
+    if (transient) next.transient = true;
+    const previous = this.#blocker;
+    const allProjects = projects.join(" ");
+    // The same blocker again keeps when it was first seen. "The same" counts
+    // every project, not only the ones the status has room for.
+    if (previous !== null && sameBlocker(previous, next) && allProjects === this.#blockerProjects) return;
+    this.#blocker = next;
+    this.#blockerProjects = allProjects;
+    // The status names at most MAX_CREDENTIALS_SWITCH_PROJECTS, and the
+    // line above is cut short: the log names every one, once per blocker,
+    // for the operator Connections sends here for the rest.
+    if (projects.length > 0) {
+      this.#deps.log(
+        `[credentials] Compose projects nothing proves Uai's (${projects.length}), each to remove ` +
+          `(docker compose -p <name> down) or rename: ${allProjects}`,
+      );
+    }
+  }
+
+  /** `onStatusChange` when `status()` says something new. */
+  #publish(): void {
+    const now = JSON.stringify(this.status());
+    if (now === this.#published) return;
+    this.#published = now;
+    try {
+      this.#deps.onStatusChange?.();
+    } catch (error) {
+      this.#note(`advertising the switch's status failed: ${message(error)}`);
+    }
+  }
+
   /** The same note twice in a row is logged once: a refusal is asked about
    *  again every few minutes. */
   #note(line: string): void {
@@ -450,6 +571,33 @@ export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
   }
 }
 
+class TransientActivationError extends Error {
+  readonly transient = true;
+}
+
+function isTransient(why: unknown): boolean {
+  return why !== null && typeof why === "object" && (why as { transient?: unknown }).transient === true;
+}
+
+function sameBlocker(a: CredentialsSwitchStuck, b: CredentialsSwitchStuck): boolean {
+  const { since: _a, ...left } = a;
+  const { since: _b, ...right } = b;
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function stringList(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string" && item !== "") : [];
+}
+
+function oneLine(text: string): string {
+  return text.replace(/\s*\n\s*(?:- )?/g, "; ").trim();
+}
+
+function bounded(text: string, max: number): string {
+  const nonEmpty = text === "" ? "unknown" : text;
+  return nonEmpty.length <= max ? nonEmpty : `${nonEmpty.slice(0, max - 1)}…`;
+}
+
 /** The record; null when there is none. One the runner cannot read is
  *  `local` with nothing owed (see the header). */
 export function readActivationRecord(path: string): ActivationRecord | null {

package/lib/custom-connection-capture.ts

@@ -0,0 +1,395 @@
+/** ADR-164 sign-in-box discovery and protocol admission. Provider response
+ * bodies and error text never leave this module. All production I/O goes
+ * through the DNS-pinned safeRequest transport. */
+import {
+  customConnectionEnabled,
+  validConnectionModels,
+  parseCustomConnectionMaterial,
+  parseEngineConnectCustomDiscoverFrame,
+  parseEngineConnectCustomSaveFrame,
+  parseEngineConnectCustomManualSaveFrame,
+  type EngineConnectCustomManualSaveFrame,
+  type CustomConnectionAuthMode,
+  type CustomConnectionDiscoverResult,
+  type CustomConnectionMaterial,
+  type CustomConnectionReason,
+  type CustomConnectionSaveResult,
+  type EngineConnectCustomDiscoverFrame,
+  type EngineConnectCustomSaveFrame,
+} from "../src/custom-connections";
+import { buildEngineCapture, parseCaptureFlow, writeCapture } from "./capture-flow";
+import type { CredentialStore } from "./credential-store";
+import { readOpenRouterBudget } from "./openrouter-budget";
+import { readSafeBody, safeRequest, SafeHttpRefusal, type SafeHttpRequest, type SafeHttpResponse } from "./safe-http";
+
+export const CUSTOM_CONNECTION_DISCOVERY_MAX_BYTES = 1024 * 1024;
+export const CUSTOM_CONNECTION_DISCOVERY_MAX_PAGES = 5;
+export const CUSTOM_CONNECTION_DISCOVERY_MAX_MODELS = 2000;
+export const CUSTOM_CONNECTION_ATTEMPT_MS = 20_000;
+const PROBE_MAX_BYTES = 1024 * 1024;
+
+export interface CustomConnectionCaptureOptions {
+  /** Tests may replace the transport. Production always defaults safeRequest. */
+  request?: typeof safeRequest;
+  signal?: AbortSignal;
+  now?: () => number;
+}
+
+class ConnectionFailure extends Error {
+  constructor(readonly reason: CustomConnectionReason, readonly retryable = reason === "timeout") {
+    super(reason);
+  }
+}
+
+function object(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+
+function failure(error: unknown, signal?: AbortSignal): ConnectionFailure {
+  if (error instanceof ConnectionFailure) return error;
+  if (signal?.aborted || (error instanceof SafeHttpRefusal && error.reason === "timeout")) return new ConnectionFailure("timeout", true);
+  if (error instanceof SafeHttpRefusal) {
+    if (error.reason === "non_public_address") return new ConnectionFailure("private-address");
+    if (["url", "request_too_large", "response_too_large"].includes(error.reason)) return new ConnectionFailure("wrong-protocol");
+  }
+  return new ConnectionFailure("unreachable");
+}
+
+function statusFailure(status: number): ConnectionFailure {
+  if (status === 401) return new ConnectionFailure("unauthorized");
+  if (status === 403) return new ConnectionFailure("forbidden");
+  if (status === 404) return new ConnectionFailure("model-not-found");
+  if (status === 429) return new ConnectionFailure("rate-limited");
+  if (status >= 500 && status <= 599) return new ConnectionFailure("upstream-error", true);
+  return new ConnectionFailure("wrong-protocol");
+}
+
+function headers(settings: CustomConnectionMaterial, auth: CustomConnectionAuthMode = settings.authMode): Record<string, string> {
+  return {
+    ...(auth === "bearer" ? { authorization: `Bearer ${settings.apiKey}` } : { "x-api-key": settings.apiKey }),
+    ...(settings.engine === "claude" && settings.providerType !== "bedrock" ? { "anthropic-version": "2023-06-01" } : {}),
+  };
+}
+
+function deadline(options: CustomConnectionCaptureOptions): AbortSignal {
+  const timeout = AbortSignal.timeout(CUSTOM_CONNECTION_ATTEMPT_MS);
+  return options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+}
+
+async function exchange(request: SafeHttpRequest, options: CustomConnectionCaptureOptions, signal: AbortSignal): Promise<SafeHttpResponse> {
+  try {
+    return await (options.request ?? safeRequest)({ ...request, signal }, {
+      connectMs: CUSTOM_CONNECTION_ATTEMPT_MS,
+      headersMs: CUSTOM_CONNECTION_ATTEMPT_MS,
+      idleMs: CUSTOM_CONNECTION_ATTEMPT_MS,
+      maxRequestBodyBytes: 16 * 1024,
+    });
+  } catch (error) {
+    throw failure(error, signal);
+  }
+}
+
+async function body(response: SafeHttpResponse, maxBytes: number, signal: AbortSignal): Promise<Buffer> {
+  try { return await readSafeBody(response, maxBytes); } catch (error) { throw failure(error, signal); }
+}
+
+function decodeJson(raw: Buffer): unknown {
+  try { return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(raw)); } catch { throw new ConnectionFailure("wrong-protocol"); }
+}
+
+async function json(request: SafeHttpRequest, options: CustomConnectionCaptureOptions, signal: AbortSignal, maxBytes: number): Promise<{ value: Record<string, unknown>; bytes: number }> {
+  const response = await exchange(request, options, signal);
+  if (response.status !== 200) {
+    response.body.destroy();
+    throw statusFailure(response.status);
+  }
+  const raw = await body(response, maxBytes, signal);
+  const value = object(decodeJson(raw));
+  if (!value) throw new ConnectionFailure("wrong-protocol");
+  return { value, bytes: raw.byteLength };
+}
+
+function validated(settings: CustomConnectionMaterial, enabled: EngineConnectCustomDiscoverFrame["enabled"], now: number): CustomConnectionMaterial {
+  const parsed = parseCustomConnectionMaterial(settings);
+  if (!parsed || !customConnectionEnabled(parsed, enabled)) throw new ConnectionFailure("unsupported");
+  if (parsed.expiresAt !== undefined && parsed.expiresAt !== null && parsed.expiresAt <= now) throw new ConnectionFailure("expired");
+  return parsed;
+}
+
+function modelId(value: unknown, key: string): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= 200 && !/[\s\u0000-\u001f\u007f]/.test(value) && !value.includes(key);
+}
+
+/** Pagination never changes the destination or resource carrying the key. */
+function nextPage(value: Record<string, unknown>, current: URL, initial: URL): URL | null {
+  if (value.has_more === true) {
+    if (typeof value.last_id !== "string" || !value.last_id || value.last_id.length > 512) throw new ConnectionFailure("wrong-protocol");
+    const next = new URL(current);
+    next.searchParams.set("after_id", value.last_id);
+    return next;
+  }
+  if (typeof value.nextToken === "string" && value.nextToken) {
+    if (value.nextToken.length > 4096) throw new ConnectionFailure("wrong-protocol");
+    const next = new URL(current);
+    next.searchParams.set("nextToken", value.nextToken);
+    return next;
+  }
+  const links = object(value.links);
+  if (links?.next !== undefined && links.next !== null) {
+    if (typeof links.next !== "string" || links.next.length > 4096) throw new ConnectionFailure("wrong-protocol");
+    const next = new URL(links.next, initial);
+    if (next.origin !== initial.origin || next.pathname !== initial.pathname || next.username || next.password || next.hash) throw new ConnectionFailure("wrong-protocol");
+    return next;
+  }
+  return null;
+}
+
+/** Discover without writing a capture. A denied listing is a non-fatal UI
+ * outcome: the owner can enter model IDs and test them directly. */
+export async function discoverCustomConnection(frame: EngineConnectCustomDiscoverFrame, options: CustomConnectionCaptureOptions = {}): Promise<CustomConnectionDiscoverResult> {
+  const signal = deadline(options);
+  try {
+    const parsedFrame = parseEngineConnectCustomDiscoverFrame(frame);
+    if (!parsedFrame || parsedFrame.settings.internal === true) throw new ConnectionFailure("unsupported");
+    const settings = validated(parsedFrame.settings, parsedFrame.enabled, (options.now ?? Date.now)());
+    if (settings.providerType === "bedrock" && settings.engine === "codex" && settings.transport === "runtime") return { ok: false, reason: "unsupported" };
+    const models = new Set<string>();
+    const streamingFoundationIds = new Set<string>();
+    let bytes = 0;
+    let pages = 0;
+    const bedrockClaude = settings.providerType === "bedrock" && settings.engine === "claude";
+    const roots = bedrockClaude
+      ? [`https://bedrock.${settings.region}.amazonaws.com/foundation-models`, `https://bedrock.${settings.region}.amazonaws.com/inference-profiles`]
+      : [settings.providerType === "bedrock" ? `https://bedrock-mantle.${settings.region}.api.aws/v1/models` : `${settings.baseUrl}${settings.engine === "claude" ? "/v1" : ""}/models`];
+    let truncated = false;
+    discovery: for (const root of roots) {
+      const initial = new URL(root);
+      if (settings.engine === "claude" && settings.providerType !== "bedrock") initial.searchParams.set("limit", "1000");
+      let url: URL | null = initial;
+      const seen = new Set<string>();
+      while (url !== null) {
+        if (pages >= CUSTOM_CONNECTION_DISCOVERY_MAX_PAGES) { truncated = true; break discovery; }
+        if (seen.has(url.href)) throw new ConnectionFailure("wrong-protocol");
+        seen.add(url.href);
+        pages++;
+        const result = await json({ url: url.href, headers: headers(settings) }, options, signal, CUSTOM_CONNECTION_DISCOVERY_MAX_BYTES - bytes);
+        bytes += result.bytes;
+        const list = bedrockClaude ? result.value[root.endsWith("foundation-models") ? "modelSummaries" : "inferenceProfileSummaries"] : result.value.data;
+        if (!Array.isArray(list)) throw new ConnectionFailure("wrong-protocol");
+        for (const entry of list) {
+          const row = object(entry);
+          if (!row) throw new ConnectionFailure("wrong-protocol");
+          const id = bedrockClaude ? row.modelId ?? row.inferenceProfileId : row.id;
+          if (!modelId(id, settings.apiKey)) throw new ConnectionFailure("invalid-models");
+          if (bedrockClaude) {
+            if (root.endsWith("foundation-models")) {
+              if (row.providerName !== "Anthropic" || row.responseStreamingSupported !== true) continue;
+              streamingFoundationIds.add(id);
+            } else {
+              if (!Array.isArray(row.models) || !row.models.length || !row.models.every(value => {
+                const arn = object(value)?.modelArn;
+                return typeof arn === "string" && streamingFoundationIds.has(arn.slice(arn.lastIndexOf("/") + 1));
+              })) continue;
+              if (row.status !== undefined && row.status !== "ACTIVE") continue;
+            }
+          } else if (settings.providerType === "bedrock") {
+            // Mantle lists several incompatible route families. Names alone
+            // are not proof that a model serves the /openai/v1 transport.
+            const paths = row.supported_api_paths ?? row.supportedApiPaths;
+            if (row.api_path !== "/openai/v1" && row.apiPath !== "/openai/v1" && !(Array.isArray(paths) && paths.includes("/openai/v1"))) continue;
+          }
+          if (!models.has(id) && models.size >= CUSTOM_CONNECTION_DISCOVERY_MAX_MODELS) {
+            truncated = true;
+            break discovery;
+          }
+          models.add(id);
+        }
+        url = nextPage(result.value, url, initial);
+      }
+    }
+    if (settings.providerType === "bedrock" && settings.transport === "mantle" && models.size === 0) return { ok: false, reason: "unsupported" };
+    return { ok: true, models: [...models], ...(truncated ? { truncated: true } : {}) };
+  } catch (error) {
+    return { ok: false, reason: failure(error, signal).reason };
+  }
+}
+
+function validMessages(value: unknown): boolean {
+  const message = object(value);
+  const usage = object(message?.usage);
+  return Boolean(message && message.type === "message" && message.role === "assistant" && typeof message.id === "string" && message.id.length > 0 && typeof message.model === "string" && Array.isArray(message.content) && usage && [usage.input_tokens, usage.output_tokens].every(n => Number.isSafeInteger(n) && (n as number) >= 0));
+}
+
+/** Responses terminals are protocol outcomes, not merely successful HTTP. */
+export function validateResponsesProbe(raw: Buffer): void {
+  let text: string;
+  try { text = new TextDecoder("utf-8", { fatal: true }).decode(raw).replace(/\r\n/g, "\n"); } catch { throw new ConnectionFailure("wrong-protocol"); }
+  const chunks = text.split("\n\n");
+  const tail = chunks.pop();
+  if (tail?.trim()) throw new ConnectionFailure("wrong-protocol");
+  let terminal = false;
+  for (const chunk of chunks) {
+    let event: string | undefined;
+    const data: string[] = [];
+    for (const line of chunk.split("\n")) {
+      if (line.startsWith(":")) continue;
+      if (line.startsWith("event:")) event = line.slice(6).trim();
+      else if (line.startsWith("data:")) data.push(line.slice(5).trimStart());
+      else if (line && !line.startsWith("id:") && !line.startsWith("retry:")) throw new ConnectionFailure("wrong-protocol");
+    }
+    if (!data.length) continue;
+    if (data.join("\n") === "[DONE]") {
+      if (!terminal) throw new ConnectionFailure("wrong-protocol");
+      continue;
+    }
+    if (terminal) throw new ConnectionFailure("wrong-protocol");
+    const value = object(decodeJson(Buffer.from(data.join("\n"))));
+    if (!value || typeof value.type !== "string" || (event !== undefined && event !== value.type)) throw new ConnectionFailure("wrong-protocol");
+    if (value.type === "error" || value.type === "response.failed") throw new ConnectionFailure("upstream-error");
+    if (value.type === "response.completed") {
+      if (object(value.response)?.status !== "completed") throw new ConnectionFailure("wrong-protocol");
+      terminal = true;
+    } else if (value.type === "response.incomplete") {
+      const response = object(value.response);
+      if (response?.status !== "incomplete" || object(response.incomplete_details)?.reason !== "max_output_tokens") throw new ConnectionFailure("wrong-protocol");
+      terminal = true;
+    }
+  }
+  if (!terminal) throw new ConnectionFailure("wrong-protocol");
+}
+
+/** AWS EventStream has two CRC32 checks: prelude and the complete message. */
+export function eventStreamCrc32(bytes: Uint8Array): number {
+  let crc = 0xffffffff;
+  for (const byte of bytes) {
+    crc ^= byte;
+    for (let i = 0; i < 8; i++) crc = (crc >>> 1) ^ (crc & 1 ? 0xedb88320 : 0);
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+export function validateBedrockProbe(raw: Buffer): void {
+  let offset = 0;
+  let started = false;
+  let finishedMessage = false;
+  let stopped = false;
+  while (offset < raw.length) {
+    if (raw.length - offset < 16) throw new ConnectionFailure("wrong-protocol");
+    const length = raw.readUInt32BE(offset);
+    const headersLength = raw.readUInt32BE(offset + 4);
+    if (length < 16 || length > PROBE_MAX_BYTES || headersLength > length - 16 || offset + length > raw.length || raw.readUInt32BE(offset + 8) !== eventStreamCrc32(raw.subarray(offset, offset + 8)) || raw.readUInt32BE(offset + length - 4) !== eventStreamCrc32(raw.subarray(offset, offset + length - 4))) throw new ConnectionFailure("wrong-protocol");
+    const headerEnd = offset + 12 + headersLength;
+    let cursor = offset + 12;
+    const parsedHeaders = new Map<string, string>();
+    while (cursor < headerEnd) {
+      const nameLength = raw[cursor++]!;
+      if (!nameLength || cursor + nameLength + 3 > headerEnd) throw new ConnectionFailure("wrong-protocol");
+      const name = raw.subarray(cursor, cursor + nameLength).toString("utf8");
+      cursor += nameLength;
+      if (raw[cursor++] !== 7) throw new ConnectionFailure("wrong-protocol");
+      const valueLength = raw.readUInt16BE(cursor);
+      cursor += 2;
+      if (cursor + valueLength > headerEnd || parsedHeaders.has(name)) throw new ConnectionFailure("wrong-protocol");
+      parsedHeaders.set(name, raw.subarray(cursor, cursor + valueLength).toString("utf8"));
+      cursor += valueLength;
+    }
+    if (parsedHeaders.get(":message-type") !== "event" || parsedHeaders.get(":event-type") !== "chunk") {
+      const type = parsedHeaders.get(":event-type") ?? parsedHeaders.get(":exception-type") ?? "";
+      throw new ConnectionFailure(/throttl/i.test(type) ? "rate-limited" : /timeout/i.test(type) ? "timeout" : "upstream-error");
+    }
+    const payload = object(decodeJson(raw.subarray(headerEnd, offset + length - 4)));
+    if (!payload || typeof payload.bytes !== "string" || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(payload.bytes)) throw new ConnectionFailure("wrong-protocol");
+    const event = object(decodeJson(Buffer.from(payload.bytes, "base64")));
+    if (!event || typeof event.type !== "string" || stopped) throw new ConnectionFailure("wrong-protocol");
+    if (event.type === "error") throw new ConnectionFailure("upstream-error");
+    if (event.type === "message_start") {
+      if (started || !validMessages(event.message)) throw new ConnectionFailure("wrong-protocol");
+      started = true;
+    } else if (event.type === "message_stop") {
+      if (!started || !finishedMessage) throw new ConnectionFailure("wrong-protocol");
+      stopped = true;
+    } else if (event.type === "message_delta") {
+      if (!started || typeof object(event.delta)?.stop_reason !== "string" || !Number.isSafeInteger(object(event.usage)?.output_tokens)) throw new ConnectionFailure("wrong-protocol");
+      finishedMessage = true;
+    } else if (!started || !["content_block_start", "content_block_delta", "content_block_stop", "ping"].includes(event.type)) throw new ConnectionFailure("wrong-protocol");
+    offset += length;
+  }
+  if (!started || !stopped) throw new ConnectionFailure("wrong-protocol");
+}
+
+async function probe(settings: CustomConnectionMaterial, model: string, auth: CustomConnectionAuthMode, options: CustomConnectionCaptureOptions, allowFallback: boolean): Promise<CustomConnectionAuthMode> {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const signal = deadline(options);
+    try {
+      const bedrock = settings.providerType === "bedrock" && settings.engine === "claude";
+      const request: SafeHttpRequest = {
+        url: bedrock ? `${settings.baseUrl}/model/${encodeURIComponent(model)}/invoke-with-response-stream` : `${settings.baseUrl}${settings.engine === "claude" ? "/v1/messages" : "/responses"}`,
+        method: "POST",
+        headers: { ...headers(settings, auth), "content-type": "application/json", accept: bedrock ? "application/vnd.amazon.eventstream" : settings.engine === "codex" ? "text/event-stream" : "application/json" },
+        body: JSON.stringify(settings.engine === "codex" ? { model, input: "Hi", store: false, stream: true, max_output_tokens: 16 } : { ...(bedrock ? { anthropic_version: "bedrock-2023-05-31" } : { model }), messages: [{ role: "user", content: "Hi" }], max_tokens: 1 }),
+      };
+      let response = await exchange(request, options, signal);
+      let usedAuth = auth;
+      if (response.status === 401 && allowFallback && settings.providerType === "custom" && settings.engine === "claude" && auth === "bearer") {
+        response.body.destroy();
+        response = await exchange({ ...request, headers: { ...headers(settings, "x-api-key"), "content-type": "application/json", accept: "application/json" } }, options, signal);
+        usedAuth = "x-api-key";
+      }
+      if (response.status !== 200) { response.body.destroy(); throw statusFailure(response.status); }
+      const raw = await body(response, PROBE_MAX_BYTES, signal);
+      if (bedrock) validateBedrockProbe(raw);
+      else if (settings.engine === "codex") validateResponsesProbe(raw);
+      else if (!validMessages(decodeJson(raw))) throw new ConnectionFailure("wrong-protocol");
+      return usedAuth;
+    } catch (error) {
+      const refused = failure(error, signal);
+      if (attempt === 0 && refused.retryable && !options.signal?.aborted) continue;
+      throw refused;
+    }
+  }
+  throw new ConnectionFailure("upstream-error");
+}
+
+/** All selected models are probed before the single immutable write. */
+export async function saveCustomConnection(frame: EngineConnectCustomSaveFrame, store: CredentialStore | null, options: CustomConnectionCaptureOptions = {}): Promise<CustomConnectionSaveResult> {
+  try {
+    if (!parseCustomConnectionMaterial(frame?.settings) || frame.settings.internal === true) throw new ConnectionFailure("unsupported");
+    const parsed = parseEngineConnectCustomSaveFrame(frame);
+    if (!parsed || !validConnectionModels(parsed.models, parsed.defaultModel, parsed.backgroundModel, parsed.settings.engine, parsed.settings.apiKey)) throw new ConnectionFailure("invalid-models");
+    const settings = validated(parsed.settings, parsed.enabled, (options.now ?? Date.now)());
+    const flow = parseCaptureFlow(parsed.flow);
+    if (!flow || !store?.putImmutable) throw new ConnectionFailure("unsupported");
+    // Refuse an envelope that will never fit before spending any inference
+    // tokens. The successful auth mode is checked again before persistence.
+    try { buildEngineCapture(flow, { authKind: "custom-connection", connection: settings }); } catch { throw new ConnectionFailure("unsupported"); }
+    const authMode = await probe(settings, parsed.defaultModel, "bearer", options, true);
+    if (parsed.backgroundModel && parsed.backgroundModel !== parsed.defaultModel) await probe(settings, parsed.backgroundModel, authMode, options, false);
+    const connection = { ...settings, authMode };
+    const budget = connection.providerType === "openrouter" ? await readOpenRouterBudget(connection.apiKey, options) : undefined;
+    validated(connection, parsed.enabled, (options.now ?? Date.now)());
+    let built;
+    try { built = buildEngineCapture(flow, { authKind: "custom-connection", connection }); } catch { throw new ConnectionFailure("unsupported"); }
+    if ("error" in built) throw new ConnectionFailure("unsupported");
+    const capture = await writeCapture(store, flow, built, { signal: options.signal });
+    return { ok: true, capture, authMode, ...(budget ? { budget } : {}) };
+  } catch (error) {
+    return { ok: false, reason: failure(error, options.signal).reason };
+  }
+}
+
+/** Internal saves deliberately have no transport or resolver path. The person
+ * selects Claude's header; the fenced write records exactly that choice. */
+export async function saveCustomConnectionManual(frame: EngineConnectCustomManualSaveFrame, store: CredentialStore | null, options: Pick<CustomConnectionCaptureOptions, "signal" | "now"> = {}): Promise<CustomConnectionSaveResult> {
+  try {
+    const parsed = parseEngineConnectCustomManualSaveFrame(frame);
+    if (!parsed) throw new ConnectionFailure("unsupported");
+    if (!validConnectionModels(parsed.models, parsed.defaultModel, parsed.backgroundModel, parsed.settings.engine, parsed.settings.apiKey)) throw new ConnectionFailure("invalid-models");
+    const connection = validated(parsed.settings, parsed.enabled, (options.now ?? Date.now)());
+    const flow = parseCaptureFlow(parsed.flow);
+    if (!flow || !store?.putImmutable) throw new ConnectionFailure("unsupported");
+    const built = buildEngineCapture(flow, { authKind: "custom-connection", connection });
+    if ("error" in built) throw new ConnectionFailure("unsupported");
+    const capture = await writeCapture(store, flow, built, { signal: options.signal });
+    return { ok: true, capture, authMode: connection.authMode };
+  } catch (error) { return { ok: false, reason: failure(error, options.signal).reason }; }
+}