@moondeck/station 0.0.0-stage → 1.0.0

package/lib/custom-connection-launch.ts

@@ -0,0 +1,384 @@
+/** ADR-164: compile one validated, hard-pinned connection into a CLI launch.
+ * Only the runner calls these builders. No caller may supply arbitrary TOML,
+ * environment keys, credential-helper commands or a second destination. */
+import { createHash } from "node:crypto";
+
+import {
+  customConnectionEnabled,
+  isCustomConnectionReason,
+  parseCustomConnectionLease,
+  parseCustomConnectionMaterial,
+  validConnectionModels,
+  type CustomConnectionCombination,
+  type CustomConnectionLease,
+  type CustomConnectionMaterial,
+  type CustomConnectionReason,
+} from "../src/custom-connections";
+import { isIP } from "node:net";
+import { isOwnedInternalConnectionRuntime } from "./internal-connections";
+import { isPublicAddress, isInternalConnectionAddress } from "./secrets-proxy/address";
+
+export class CustomConnectionLaunchError extends Error {
+  /** `detail` says what this runner refused or could not do, in words for the
+   *  chat. Only ever about the runner's own checks: addresses, ports and names
+   *  the person configured, never an upstream's text and never the key. */
+  constructor(readonly reason: CustomConnectionReason, readonly detail?: string) {
+    super(reason);
+    this.name = "CustomConnectionLaunchError";
+  }
+}
+
+/**
+ * What a failed pre-launch step (home, address check, connect check) is
+ * reported as. Every local refusal says so: a step that fails for any reason
+ * the runner did not anticipate is `unsupported` with a plain account, never
+ * the `upstream-error` that `connectionFailureReason` would default an unknown
+ * exception to (that label means the provider answered badly, and nothing was
+ * asked of the provider yet).
+ */
+export function launchRefusal(error: unknown): { reason: CustomConnectionReason; detail?: string } {
+  if (error instanceof CustomConnectionLaunchError) return { reason: error.reason, ...(error.detail ? { detail: error.detail } : {}) };
+  const text = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+  if (isCustomConnectionReason(text)) return { reason: text };
+  const why = text.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim().slice(0, 120);
+  return { reason: "unsupported", detail: `the station's pre-launch check could not run${why ? `: ${why}` : ""}` };
+}
+
+/** JSON string escaping is also valid for TOML basic string values. Never
+ * interpolate an unquoted model id, URL or label into a -c argument. */
+export function tomlString(value: string): string {
+  return JSON.stringify(value).replace(/\u007f/g, "\\u007f");
+}
+
+/** A native account must not inherit a previous connection's route, token or
+ * model aliases. Native credentials are applied AFTER these blanks. AWS's
+ * ordinary identity is isolated below only for a connection launch. */
+const CONNECTION_ENV_NAMES = [
+  "ANTHROPIC_BASE_URL", "ANTHROPIC_CUSTOM_HEADERS", "ANTHROPIC_MODEL",
+  "CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST",
+  "ANTHROPIC_DEFAULT_MODEL", "ANTHROPIC_DEFAULT_FABLE_MODEL",
+  "ANTHROPIC_DEFAULT_OPUS_MODEL", "ANTHROPIC_DEFAULT_SONNET_MODEL",
+  "ANTHROPIC_DEFAULT_HAIKU_MODEL", "ANTHROPIC_SMALL_FAST_MODEL",
+  "ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION", "CLAUDE_CODE_SUBAGENT_MODEL",
+  "CLAUDE_CODE_SUBAGENT_MODEL_FORCE", "CLAUDE_CODE_EXTRA_BODY",
+  "CLAUDE_CODE_USE_BEDROCK", "CLAUDE_CODE_USE_MANTLE", "CLAUDE_CODE_USE_GATEWAY",
+  "CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD", "CLAUDE_CODE_API_BASE_URL",
+  "ANTHROPIC_UNIX_SOCKET", "_CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL",
+  "CLAUDE_CODE_USE_VERTEX", "CLAUDE_CODE_USE_FOUNDRY",
+  "CLAUDE_CODE_USE_ANTHROPIC_AWS", "CLAUDE_CODE_SKIP_BEDROCK_AUTH",
+  "CLAUDE_CODE_SKIP_MANTLE_AUTH", "CLAUDE_CODE_SKIP_VERTEX_AUTH",
+  "CLAUDE_CODE_SKIP_FOUNDRY_AUTH", "ANTHROPIC_BEDROCK_BASE_URL",
+  "ANTHROPIC_BEDROCK_MANTLE_BASE_URL", "ANTHROPIC_BEDROCK_REGION_PREFIX",
+  "ANTHROPIC_VERTEX_BASE_URL", "ANTHROPIC_VERTEX_PROJECT_ID",
+  "ANTHROPIC_FOUNDRY_BASE_URL", "ANTHROPIC_FOUNDRY_RESOURCE",
+  "ANTHROPIC_FOUNDRY_API_KEY", "ANTHROPIC_FOUNDRY_AUTH_TOKEN",
+  "ANTHROPIC_AWS_API_KEY", "ANTHROPIC_AWS_BASE_URL", "ANTHROPIC_AWS_WORKSPACE_ID",
+  "ANTHROPIC_GOOGLE_CLOUD_BASE_URL", "CLAUDE_CODE_AUTO_MODE_MODEL",
+  "CLAUDE_CODE_BG_CLASSIFIER_MODEL", "CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL",
+  "ANTHROPIC_PROFILE", "ANTHROPIC_ORGANIZATION_ID",
+  "ANTHROPIC_WORKSPACE_ID", "ANTHROPIC_FEDERATION_RULE_ID",
+  "CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK",
+  "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC",
+  "OPENAI_API_KEY", "OPENAI_BASE_URL", "OPENAI_ORGANIZATION", "OPENAI_PROJECT",
+  "UAI_CUSTOM_API_KEY", "UAI_INFERENCE_TOKEN", "AWS_BEARER_TOKEN_BEDROCK",
+] as const;
+
+const ENGINE_AUTH_BLANKS = {
+  CLAUDE_CODE_OAUTH_TOKEN: "", CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR: "", CCR_OAUTH_TOKEN_FILE: "",
+  CLAUDE_CODE_HOST_AUTH_ENV_VAR: "", CLAUDE_CODE_HOST_CREDS_FILE: "",
+  ANTHROPIC_API_KEY: "", ANTHROPIC_AUTH_TOKEN: "", OPENAI_API_KEY: "",
+};
+
+export const CONNECTION_NATIVE_BLANKS: Readonly<Record<string, string>> = Object.freeze(
+  Object.fromEntries(CONNECTION_ENV_NAMES.map(name => [name, ""])),
+);
+
+export function connectionNativeBlanks(): Record<string, string> {
+  return { ...CONNECTION_NATIVE_BLANKS };
+}
+
+/** The AWS SDK must never consult an ambient credential provider or endpoint.
+ * Empty files, not a nonexistent path, make profile/process lookup inert. */
+export const CONNECTION_AWS_BLANKS: Readonly<Record<string, string>> = Object.freeze(
+  Object.fromEntries([
+    "AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN", "AWS_SECURITY_TOKEN",
+    "AWS_PROFILE", "AWS_DEFAULT_PROFILE", "AWS_ROLE_ARN", "AWS_ROLE_SESSION_NAME",
+    "AWS_WEB_IDENTITY_TOKEN_FILE", "AWS_CONTAINER_CREDENTIALS_RELATIVE_URI",
+    "AWS_CONTAINER_CREDENTIALS_FULL_URI", "AWS_CONTAINER_AUTHORIZATION_TOKEN",
+    "AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE", "AWS_ENDPOINT_URL",
+    "AWS_ENDPOINT_URL_BEDROCK", "AWS_ENDPOINT_URL_BEDROCK_RUNTIME",
+    "AWS_EC2_METADATA_SERVICE_ENDPOINT", "AWS_EC2_METADATA_SERVICE_ENDPOINT_MODE",
+    "AWS_REGION", "AWS_DEFAULT_REGION", "AWS_SDK_LOAD_CONFIG",
+  ].map(name => [name, ""])),
+);
+
+/** Shared by connection launches and the Managed Engine delegation. */
+export function endpointAuthEnv(
+  provider: "anthropic" | "openai",
+  baseUrl: string,
+  token: string,
+  authMode: "bearer" | "x-api-key" = "bearer",
+  tokenVariable = "UAI_CUSTOM_API_KEY",
+): Record<string, string> {
+  return provider === "anthropic"
+    ? { ...connectionNativeBlanks(), ...ENGINE_AUTH_BLANKS, ANTHROPIC_BASE_URL: baseUrl,
+        [authMode === "bearer" ? "ANTHROPIC_AUTH_TOKEN" : "ANTHROPIC_API_KEY"]: token }
+    : { ...connectionNativeBlanks(), ...ENGINE_AUTH_BLANKS,
+        ...(tokenVariable === "UAI_INFERENCE_TOKEN" ? { OPENAI_BASE_URL: baseUrl, OPENAI_API_KEY: token } : {}),
+        [tokenVariable]: token };
+}
+
+/** baseUrl is already the provider's Responses root, including /v1 where
+ * appropriate. Only Managed Engine's caller appends its own /v1. */
+export function codexProviderOverrides(
+  baseUrl: string,
+  options: { provider?: "uai" | "uai_custom"; name?: string; envKey?: "UAI_INFERENCE_TOKEN" | "UAI_CUSTOM_API_KEY" } = {},
+): string[] {
+  const provider = options.provider ?? "uai_custom";
+  return [
+    `model_provider=${provider}`,
+    `model_providers.${provider}.name=${tomlString(options.name ?? "Custom connection")}`,
+    `model_providers.${provider}.base_url=${tomlString(baseUrl)}`,
+    `model_providers.${provider}.env_key=${tomlString(options.envKey ?? "UAI_CUSTOM_API_KEY")}`,
+    `model_providers.${provider}.wire_api="responses"`,
+    `model_providers.${provider}.requires_openai_auth=false`,
+    `model_providers.${provider}.supports_websockets=false`,
+  ];
+}
+
+export interface CustomConnectionLaunch {
+  model: string;
+  agentEnv: Record<string, string>;
+  cliConfigOverrides: string[];
+  claudeSettings?: Record<string, unknown>;
+}
+
+export function buildCustomConnectionLaunch(args: {
+  material: CustomConnectionMaterial;
+  connection: CustomConnectionLease;
+  model?: string;
+  enabled: readonly CustomConnectionCombination[];
+  /** A connection-owned home prepared without copying a native account. */
+  home: string;
+  now?: number;
+  /** Actual destination provider, never inferred from sealed settings. */
+  runtimeProvider?: string;
+}): CustomConnectionLaunch {
+  const material = parseCustomConnectionMaterial(args.material);
+  const connection = parseCustomConnectionLease(args.connection, args.material.engine);
+  if (!material || !connection || !customConnectionEnabled(material, args.enabled)) throw new CustomConnectionLaunchError("unsupported");
+  if (material.internal === true && !isOwnedInternalConnectionRuntime(args.runtimeProvider)) throw new CustomConnectionLaunchError("unsupported");
+  if ((material.internal === true) !== (connection.internal === true)) throw new CustomConnectionLaunchError("unsupported");
+  if (new URL(material.baseUrl).host !== connection.host || material.providerType !== connection.providerType || material.authMode !== connection.authMode || material.region !== connection.region || material.transport !== connection.transport || (material.expiresAt ?? null) !== (connection.expiresAt ?? null)) throw new CustomConnectionLaunchError("unsupported");
+  if (material.expiresAt !== undefined && material.expiresAt !== null && material.expiresAt <= (args.now ?? Date.now())) throw new CustomConnectionLaunchError("expired");
+  if (!validConnectionModels(connection.models, connection.defaultModel, connection.backgroundModel, material.engine, material.apiKey)) throw new CustomConnectionLaunchError("invalid-models");
+  const model = args.model ?? connection.defaultModel;
+  if (!connection.models.includes(model)) throw new CustomConnectionLaunchError("model-not-found");
+  assertConnectionHome(args.home);
+  const aws = { ...CONNECTION_AWS_BLANKS, AWS_EC2_METADATA_DISABLED: "true",
+    AWS_CONFIG_FILE: `${args.home}/aws-config`, AWS_SHARED_CREDENTIALS_FILE: `${args.home}/aws-credentials` };
+  const agentEnv: Record<string, string> = {
+    ...connectionNativeBlanks(), ...ENGINE_AUTH_BLANKS, ...aws,
+    // Bound Claude's SDK attempts as well as its CLI retry loop. The
+    // host applies the connection's separate rate-limit recovery backoff.
+    AWS_MAX_ATTEMPTS: "1",
+    UAI_CUSTOM_CONNECTION: "1",
+  };
+  if (material.providerType === "bedrock") {
+    agentEnv.AWS_REGION = material.region!;
+    agentEnv.AWS_BEARER_TOKEN_BEDROCK = material.apiKey;
+    if (material.engine === "claude") agentEnv.CLAUDE_CODE_USE_BEDROCK = "1";
+  } else {
+    Object.assign(agentEnv, endpointAuthEnv(material.engine === "claude" ? "anthropic" : "openai", material.baseUrl, material.apiKey, material.authMode));
+  }
+  if (material.engine === "claude") {
+    Object.assign(agentEnv, {
+      // Claude 2.1.312 ignores settings-sourced provider/auth/headers when
+      // its embedding host owns routing. Keep project hooks/plugins intact.
+      CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST: "1",
+      // Verified on 2.1.312: replaces its ten-retry cloud-auth loop while
+      // retaining one retry for a transient 429/5xx response.
+      CLAUDE_CODE_MAX_RETRIES: "1",
+      ANTHROPIC_MODEL: model, ANTHROPIC_DEFAULT_FABLE_MODEL: model,
+      ANTHROPIC_DEFAULT_OPUS_MODEL: model, ANTHROPIC_DEFAULT_SONNET_MODEL: model,
+      ANTHROPIC_DEFAULT_HAIKU_MODEL: connection.backgroundModel!, CLAUDE_CODE_SUBAGENT_MODEL: model,
+      CLAUDE_CODE_AUTO_MODE_MODEL: connection.backgroundModel!, CLAUDE_CODE_BG_CLASSIFIER_MODEL: connection.backgroundModel!,
+      CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL: model,
+      CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1", CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK: "1",
+    });
+    return { model, agentEnv, cliConfigOverrides: [], claudeSettings: {
+      apiKeyHelper: "", awsAuthRefresh: "", awsCredentialExport: "", fallbackModel: [],
+    } };
+  }
+  agentEnv.CODEX_HOME = args.home;
+  const cliConfigOverrides = material.providerType === "bedrock"
+    ? [`model_provider=${tomlString(material.transport === "runtime" ? "amazon-bedrock-runtime" : "amazon-bedrock")}`,
+        `model_providers.${material.transport === "runtime" ? "amazon-bedrock-runtime" : "amazon-bedrock"}.aws.region=${tomlString(material.region!)}`]
+    : codexProviderOverrides(material.baseUrl);
+  const provider = material.providerType === "bedrock"
+    ? material.transport === "runtime" ? "amazon-bedrock-runtime" : "amazon-bedrock"
+    : "uai_custom";
+  // Codex 0.164 rejects retry overrides on its built-in AWS providers.
+  // The connection runner bounds their streamed retries instead.
+  const retryOverrides = material.providerType === "bedrock" ? [] : [
+    `model_providers.${provider}.request_max_retries=1`,
+    `model_providers.${provider}.stream_max_retries=1`,
+  ];
+  return { model, agentEnv, cliConfigOverrides: [...cliConfigOverrides, ...retryOverrides,
+    'web_search="disabled"'] };
+}
+
+const HOME_ROOT = "/home/node/.uai-connection";
+function assertConnectionHome(home: string): void {
+  if (!new RegExp(`^${HOME_ROOT.replaceAll(".", "\\.")}/[A-Za-z0-9_-]{1,128}$`).test(home)) throw new CustomConnectionLaunchError("unsupported");
+}
+export function newConnectionHome(credentialId: string, revision: string, agentId: string, settingsHash: string): string {
+  const segment = createHash("sha256").update(JSON.stringify([credentialId, revision, agentId, settingsHash])).digest("hex");
+  return `${HOME_ROOT}/${segment}`;
+}
+
+const HOME_PREPARE = String.raw`
+import os, stat, sys
+home = sys.argv[1]
+parent, name = home.rsplit("/", 1)
+fd = os.open("/", os.O_RDONLY | os.O_DIRECTORY)
+try:
+    for part in parent.split("/"):
+        if not part: continue
+        try: os.mkdir(part, 0o700, dir_fd=fd)
+        except FileExistsError: pass
+        child = os.open(part, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=fd)
+        os.close(fd)
+        fd = child
+    info = os.fstat(fd)
+    if info.st_uid != os.getuid() or (info.st_mode & 0o077): raise PermissionError()
+    try: os.mkdir(name, 0o700, dir_fd=fd)
+    except FileExistsError: pass
+    child = os.open(name, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=fd)
+    try:
+        info = os.fstat(child)
+        if info.st_uid != os.getuid() or (info.st_mode & 0o077): raise PermissionError()
+        # This provider authenticates through its scoped env key. A saved
+        # interactive login is never accepted when resuming the same home.
+        try: os.stat("auth.json", dir_fd=child, follow_symlinks=False)
+        except FileNotFoundError: pass
+        else: raise PermissionError()
+        # Provider/model/tool settings are generated as CLI overrides. The
+        # only config.toml we generate is empty; reject planted commands.
+        for filename in ["config.toml", "aws-config", "aws-credentials"]:
+            file = os.open(filename, os.O_WRONLY | os.O_CREAT | os.O_NOFOLLOW | os.O_NONBLOCK, 0o600, dir_fd=child)
+            try:
+                info = os.fstat(file)
+                if not stat.S_ISREG(info.st_mode) or info.st_uid != os.getuid() or info.st_nlink != 1 or info.st_size or (info.st_mode & 0o077): raise PermissionError()
+            finally: os.close(file)
+    finally: os.close(child)
+finally: os.close(fd)
+`;
+
+/** Execute as the task user. Nonzero exit fails the launch; there is no
+ * fallback home. Reuses only a private home with the empty generated config
+ * and empty AWS credential files. */
+export function connectionHomePreparation(home: string): [string, ...string[]] {
+  assertConnectionHome(home);
+  return ["/usr/bin/python3", "-I", "-c", HOME_PREPARE, home];
+}
+
+const DNS_LOOKUP = String.raw`require("node:dns").lookup(process.argv[1],{all:true,verbatim:true},(error,answers)=>{if(error||!answers.length||answers.length>64){process.exitCode=1;return;}process.stdout.write(JSON.stringify(answers.map(x=>x.address)));});`;
+export function connectionDnsLookupArgv(baseUrl: string): [string, ...string[]] {
+  const hostname = new URL(baseUrl).hostname.replace(/^\[|\]$/g, "");
+  return ["node", "-e", DNS_LOOKUP, "--", hostname];
+}
+/** The name every Docker task container gets for its host (`extra_hosts:
+ * host.docker.internal:host-gateway`, task-up.sh). What it points at depends on
+ * the runtime: Docker Desktop 192.168.65.x and Linux Docker the bridge gateway
+ * (both private, so allowed anyway), OrbStack 0.250.250.254, which sits in
+ * 0.0.0.0/8 and so fails the address classifier. Apple containers have no such
+ * name; their host is the vmnet gateway (192.168.64.x, private). */
+export const HOST_GATEWAY_NAME = "host.docker.internal";
+/** OrbStack's host-gateway address (checked on the owner's Mac, 2026-11-01). */
+export const ORBSTACK_HOST_GATEWAY = "0.250.250.254";
+
+/** Evaluate all DNS answers from inside the task runtime, not the runner's
+ * own resolver. The caller bounds exec output/time and rejects nonzero exit.
+ * Returns the answers, all of which passed.
+ *
+ * An internal connection may also reach OrbStack's host gateway, but only as
+ * that one address and only through the name `host.docker.internal` (which the
+ * container's own hosts file defines): never the rest of 0.0.0.0/8, and never
+ * another name that resolves to it. */
+export function validateConnectionAddresses(raw: string, internal = false, hostname?: string): string[] {
+  let addresses: unknown;
+  const unresolved = new CustomConnectionLaunchError("unreachable", `${hostname ? `${hostname} ` : "the name "}did not resolve from the task`);
+  try { addresses = JSON.parse(raw); } catch { throw unresolved; }
+  if (!Array.isArray(addresses) || !addresses.length || addresses.length > 64 || !addresses.every(x => typeof x === "string")) throw unresolved;
+  const viaHostGateway = internal && hostname?.toLowerCase().replace(/\.$/, "") === HOST_GATEWAY_NAME;
+  const allowed = (address: string): boolean =>
+    (internal ? isInternalConnectionAddress(address) : isPublicAddress(address)) ||
+    (viaHostGateway && address === ORBSTACK_HOST_GATEWAY);
+  const refused = (addresses as string[]).filter((address) => !allowed(address));
+  if (refused.length > 0) {
+    const where = hostname && isIP(hostname.replace(/^\[|\]$/g, "")) === 0 ? `${hostname} resolves to ` : "";
+    const list = refused.slice(0, 3).join(", ") + (refused.length > 3 ? ", …" : "");
+    throw new CustomConnectionLaunchError(
+      "private-address",
+      internal
+        ? `${where}${list}, which an internal connection may not use (loopback, link-local and 0.0.0.0/8 are refused${hostname === HOST_GATEWAY_NAME ? "" : `; to reach the station's computer use ${HOST_GATEWAY_NAME}`})`
+        : `${where}${list}, which is not a public address`,
+    );
+  }
+  return addresses as string[];
+}
+
+/**
+ * Whether this build's launch preflight lets an internal connection reach the
+ * runner's computer through `host.docker.internal`, OrbStack's address
+ * included: the promise `INTERNAL_HOST_GATEWAY_PROTOCOL_FEATURE` makes. Asked
+ * of the check itself, not assumed, so the feature can't be advertised by a
+ * build whose preflight would refuse what the cloud then suggests.
+ */
+export function internalHostGatewayAdvertisable(): boolean {
+  try {
+    return validateConnectionAddresses(JSON.stringify([ORBSTACK_HOST_GATEWAY]), true, HOST_GATEWAY_NAME).length === 1;
+  } catch {
+    return false;
+  }
+}
+
+/** How long an internal endpoint gets to accept a connection at launch. */
+export const CONNECTION_CONNECT_TIMEOUT_MS = 3000;
+// TCP handshake only: connect, then close at once. Nothing is written, so
+// neither the key nor any request reaches the endpoint. Run only on addresses
+// validateConnectionAddresses accepted; any one that answers passes.
+const CONNECT_PROBE = String.raw`const net=require("node:net");const port=Number(process.argv[1]);const hosts=process.argv.slice(2);let pending=hosts.length;setTimeout(()=>process.exit(1),${CONNECTION_CONNECT_TIMEOUT_MS});for(const host of hosts){const s=net.connect({host,port});s.once("connect",()=>{s.destroy();process.exit(0);});s.once("error",()=>{if(--pending===0)process.exit(1);});}`;
+/** The command that checks, from inside the task runtime, that one of the
+ * validated addresses accepts a TCP connection on the URL's port. A nonzero
+ * exit means `unreachable`. */
+export function connectionConnectArgv(baseUrl: string, addresses: readonly string[]): [string, ...string[]] {
+  const url = new URL(baseUrl);
+  const port = Number(url.port || (url.protocol === "https:" ? 443 : 80));
+  if (!Number.isInteger(port) || port < 1 || port > 65535 || !addresses.length || addresses.length > 64 || !addresses.every(a => isIP(a) !== 0)) {
+    throw new CustomConnectionLaunchError("unreachable", "the endpoint's port or address could not be checked");
+  }
+  return ["node", "-e", CONNECT_PROBE, "--", String(port), ...addresses];
+}
+
+export function redactConnectionText(value: string, key: string): string {
+  if (!key) return value;
+  return value.split(key).join("[redacted]".includes(key) ? "" : "[redacted]");
+}
+/** A diagnostic may be inspected to choose a reason, never sent back. */
+export function connectionFailureReason(error: unknown): CustomConnectionReason {
+  if (error instanceof CustomConnectionLaunchError) return error.reason;
+  const o = error && typeof error === "object" ? error as Record<string, unknown> : {};
+  if (isCustomConnectionReason(o.reason)) return o.reason;
+  const status = o.statusCode ?? o.status;
+  const text = typeof error === "string" ? error : error instanceof Error ? error.message : "";
+  if (isCustomConnectionReason(text)) return text;
+  if (status === 401 || /\b401\b|unauthori[sz]ed|authentication_failed|unrecognized.?client|expired.?token|token.{0,80}(?:expired|revoked)|invalid api.?key/i.test(text)) return "unauthorized";
+  if (status === 403 || /\b403\b|forbidden|access.?denied/i.test(text)) return "forbidden";
+  if (status === 404 || /\b404\b|model.{0,30}not.found/i.test(text)) return "model-not-found";
+  if (status === 429 || /\b429\b|rate.?limit|throttl/i.test(text)) return "rate-limited";
+  if (/expired/i.test(text)) return "expired";
+  if (status === 408 || /timeout|timed.out/i.test(text)) return "timeout";
+  return "upstream-error";
+}

package/lib/custom-connection-runtime.ts

@@ -0,0 +1,141 @@
+import type { AgentEvent } from "./agents/types";
+
+import { connectionFailureReason, redactConnectionText } from "./custom-connection-launch";
+import { UPSTREAM_TEXT_WITHHELD, upstreamTextWithheld } from "../src/custom-connections";
+import { scrubHostString } from "./obs";
+export { connectionFailureReason } from "./custom-connection-launch";
+
+/** Redact literal secrets recursively, including tool arguments and notices. */
+export function redactConnectionValue<T>(value: T, key: string): T {
+  if (typeof value === "string") return redactConnectionText(value, key) as T;
+  if (Array.isArray(value)) return value.map(v => redactConnectionValue(v, key)) as T;
+  if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([k, v]) => [redactConnectionValue(k, key), redactConnectionValue(v, key)])) as T;
+  return value;
+}
+
+/** The longest excerpt of an upstream error that leaves the runner. */
+export const CONNECTION_DETAIL_MAX = 200;
+
+/**
+ * A short, scrubbed account of why a connection turn failed, for the chat and
+ * the connection's last error (ADR-164 addendum, 2026-11-01; owner: "surface
+ * the upstream's status code and a short excerpt"). It replaces nothing in
+ * `connectionFailureReason`: the reason code still drives every decision.
+ *
+ * What may leave: an HTTP status (3 digits, after the words that introduce
+ * one), and the upstream's own error message when it sent one in the usual
+ * JSON shapes, else its first line; one line, control characters removed, at
+ * most CONNECTION_DETAIL_MAX characters. Scrubbed first: the connection's
+ * exact key, then the runner's pattern scrub (tokens, bearer values, URL
+ * credentials and query strings, emails, home and workspace paths), then any
+ * opaque run of 32+ token characters. Before all of that, the text is withheld
+ * entirely (status and a fixed phrase only) when it contains the key under any
+ * splitting, or any 24+ letter-and-digit run (`upstreamTextWithheld`). Null
+ * when nothing is left.
+ */
+export function connectionFailureDetail(raw: string, key: string): string | null {
+  if (typeof raw !== "string" || !raw) return null;
+  const text = raw.length > 8192 ? raw.slice(0, 8192) : raw;
+  // After the words that introduce a status, else a bare 4xx/5xx that is not
+  // part of an address, port, version or longer number.
+  const status =
+    /(?:\bstatus(?:\s*code)?\s*[:=]?\s*|\bAPI Error:?\s*|\bHTTP\/?[\d.]*\s*|^\s*)([1-5]\d\d)\b/i.exec(text)?.[1] ??
+    /(?<![\w.:\-/])([45]\d\d)(?![\w.:\-/])/.exec(text.slice(0, 400))?.[1];
+  let body = text;
+  const json = /\{[\s\S]*\}/.exec(text)?.[0];
+  if (json) {
+    try {
+      const parsed = JSON.parse(json) as Record<string, unknown>;
+      const error = parsed.error;
+      const message =
+        typeof error === "string" ? error
+          : error && typeof error === "object" && typeof (error as Record<string, unknown>).message === "string" ? (error as Record<string, string>).message
+            : typeof parsed.message === "string" ? parsed.message
+              : null;
+      if (message) body = message;
+    } catch {
+      // Not JSON after all: the first line below.
+    }
+  }
+  if (body === text) {
+    // Drop what introduced the status, so it is not said twice.
+    body = text.replace(/^\s*(?:API Error:?\s*)?(?:HTTP\/?[\d.]*\s*)?[1-5]\d\d\b[\s:.\-–—]*/i, "");
+  }
+  // A hostile endpoint can echo the key split by a space, newline, zero-width
+  // character or dot, which no pattern above would see. If the key (however
+  // split) or any 24+ letter-and-digit run is in what the upstream said, none
+  // of its text is shown: the status and a fixed phrase stand in for it. The
+  // whole text and the extracted message are both checked, since JSON escapes
+  // (\u0073k-…) only decode in the latter.
+  if (upstreamTextWithheld(body, key, [text])) return status ? `HTTP ${status}: ${UPSTREAM_TEXT_WITHHELD}` : UPSTREAM_TEXT_WITHHELD;
+  let excerpt = redactConnectionText(body, key);
+  excerpt = scrubHostString(excerpt);
+  excerpt = excerpt.replace(/[A-Za-z0-9_\-+/=]{32,}/g, "[redacted]");
+  excerpt = excerpt.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim();
+  if (excerpt.length > CONNECTION_DETAIL_MAX) excerpt = `${excerpt.slice(0, CONNECTION_DETAIL_MAX - 1).trimEnd()}…`;
+  if (status && excerpt) return `HTTP ${status}: ${excerpt}`;
+  if (status) return `HTTP ${status}`;
+  return excerpt || null;
+}
+
+export function sanitizeConnectionEvent(event: AgentEvent, key: string): AgentEvent {
+  const redacted = redactConnectionValue(event, key);
+  if (event.type === "error") {
+    const diagnostic = event.diagnosticMessage ?? event.message;
+    const message = connectionFailureReason(diagnostic);
+    let resetsAt = Number.isSafeInteger(event.resetsAt) && event.resetsAt! > 0 ? event.resetsAt : undefined;
+    if (message === "rate-limited") {
+      // Preserve only a numeric retry deadline, never provider text/headers.
+      const retryAfter = /retry-after\s*[:=]\s*([^\r\n]+)/i.exec(diagnostic)?.[1]?.trim();
+      const deadline = retryAfter && /^\d+(?:\.\d+)?$/.test(retryAfter)
+        ? Date.now() + Math.ceil(Number(retryAfter) * 1000)
+        : retryAfter ? Date.parse(retryAfter) : NaN;
+      if (Number.isSafeInteger(deadline) && deadline > 0) resetsAt = Math.max(resetsAt ?? 0, deadline);
+    }
+    // An adapter that already reduced its message (Codex) sends the excerpt it
+    // scrubbed; it is scrubbed again here, which changes nothing it did right.
+    const detail = connectionFailureDetail(event.detail ?? diagnostic, key);
+    return { type: "error", message, aborted: event.aborted, code: event.code,
+      ...(detail ? { detail } : {}),
+      ...(message === "rate-limited" && resetsAt !== undefined ? { resetsAt } : {}) };
+  }
+  if (event.type === "notice") return { type: "notice", message: connectionFailureReason(event.message) };
+  if (event.type === "turn_complete" && event.usage) {
+    const usage = { ...event.usage };
+    delete usage.costUsd;
+    return redactConnectionValue({ ...event, usage }, key);
+  }
+  return redacted;
+}
+
+/** A delta may end inside a credential. Retain only a possible credential
+ * prefix; no byte of a complete key can cross the output boundary. */
+export class ConnectionEventSanitizer {
+  private tail = "";
+  constructor(private readonly key: string) {}
+
+  push(event: AgentEvent): AgentEvent[] {
+    if (event.type === "message_delta") {
+      const text = this.tail + event.text;
+      let keep = 0;
+      for (let n = Math.min(this.key.length - 1, text.length); n > 0; n--) {
+        if (text.endsWith(this.key.slice(0, n))) { keep = n; break; }
+      }
+      // Replace first: a complete key may itself end in a key prefix.
+      const safe = redactConnectionText(text, this.key);
+      keep = Math.min(keep, safe.length);
+      if (keep && !safe.endsWith(this.key.slice(0, keep))) keep = 0;
+      this.tail = keep ? safe.slice(-keep) : "";
+      const emitted = keep ? safe.slice(0, -keep) : safe;
+      return emitted ? [{ type: "message_delta", text: emitted }] : [];
+    }
+    if (event.type === "message_complete") {
+      this.tail = ""; // The complete assembled message replaces the deltas.
+      return [sanitizeConnectionEvent(event, this.key)];
+    }
+    const final = event.type === "turn_complete" || event.type === "error" || event.type === "exit";
+    const pending: AgentEvent[] = final && this.tail ? [{ type: "message_delta", text: this.tail }] : [];
+    if (final) this.tail = "";
+    return [...pending, sanitizeConnectionEvent(event, this.key)];
+  }
+}

package/lib/db.ts

@@ -0,0 +1,80 @@
+/**
+ * Host-local SQLite access (ADR-020).
+ *
+ * This DB contains only runtime state for tasks assigned to this host. Cloud
+ * metadata remains in the cloud DB and arrives over command arguments.
+ */
+
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import Database from "better-sqlite3";
+import { drizzle } from "drizzle-orm/better-sqlite3";
+import { migrate } from "drizzle-orm/better-sqlite3/migrator";
+
+import { env } from "./env";
+import * as schema from "../db/schema";
+
+let cached: ReturnType<typeof drizzle> | null = null;
+let migrated = false;
+
+function migrationsFolder(): string {
+  return resolve(
+    dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "db",
+    "migrations",
+  );
+}
+
+function ensureDataDir(): void {
+  const dir = dirname(env.hostDbPath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+
+export function migrateHostDb(): void {
+  if (migrated) return;
+  ensureDataDir();
+  const sqlite = new Database(env.hostDbPath);
+  try {
+    const journalMode = String(
+      sqlite.pragma("journal_mode = WAL", { simple: true }),
+    ).toLowerCase();
+    if (journalMode !== "wal") {
+      throw new Error(
+        `host.sqlite journal_mode must be WAL; got "${journalMode}"`,
+      );
+    }
+    sqlite.pragma("foreign_keys = ON");
+    migrate(drizzle(sqlite), { migrationsFolder: migrationsFolder() });
+    migrated = true;
+  } finally {
+    sqlite.close();
+  }
+}
+
+export function getDb(): ReturnType<typeof drizzle> {
+  if (cached) return cached;
+  migrateHostDb();
+  const sqlite = new Database(env.hostDbPath);
+  sqlite.pragma("journal_mode = WAL");
+  sqlite.pragma("foreign_keys = ON");
+  cached = drizzle(sqlite, { schema });
+  return cached;
+}
+
+/**
+ * Run `use` on the connection behind `getDb()`, for what drizzle does not
+ * express: a pragma, VACUUM, a WAL checkpoint. Never a second connection:
+ * `secure_delete` is a setting of the connection, so it has to be on the one
+ * every delete goes through. VACUUM and a checkpoint run outside any
+ * transaction.
+ */
+export function withHostSqlite<T>(use: (sqlite: Database.Database) => T): T {
+  return use(getDb().$client);
+}
+
+export type Db = ReturnType<typeof getDb>;
+export type { HostTask } from "../db/schema";
+export { schema };

package/lib/disk-pressure.ts

@@ -0,0 +1,42 @@
+import { execFile } from "node:child_process";
+import { statfs } from "node:fs/promises";
+import { homedir } from "node:os";
+import type { HostCapabilities } from "../src/protocol";
+
+type DiskSample = NonNullable<HostCapabilities["disk"]>;
+const dockerInfo = (args: string[]): Promise<string | null> => new Promise(resolve => {
+  execFile("docker", args, { timeout: 5_000, maxBuffer: 4096 }, (error, stdout) => {
+    resolve(error ? null : stdout.trim());
+  });
+});
+async function dockerRoot(): Promise<string | null> {
+  // A remote daemon (including Docker Desktop's VM) has no local filesystem
+  // we can measure. Never report a coincidentally matching local path.
+  if (process.platform !== "linux") return null;
+  const endpoint = process.env.DOCKER_HOST && !process.env.DOCKER_CONTEXT
+    ? process.env.DOCKER_HOST
+    : await dockerInfo(["context", "inspect", "--format", "{{.Endpoints.docker.Host}}"]);
+  if (!endpoint?.startsWith("unix://")) return null;
+  // Do not guess /var/lib/docker: data-root can be configured elsewhere.
+  const root = await dockerInfo(["info", "--format", "{{.DockerRootDir}}"]);
+  return root?.startsWith("/") ? root : null;
+}
+
+async function measure(path: string | null): Promise<DiskSample["home"]> {
+  if (!path) return null;
+  try {
+    const fs = await statfs(path);
+    const totalBytes = fs.blocks * fs.bsize;
+    // bavail (not bfree) accounts for root-reserved blocks: the host's
+    // unprivileged updater cannot use those even though root can.
+    const availableBytes = Math.max(0, fs.bavail * fs.bsize);
+    if (!Number.isSafeInteger(totalBytes) || totalBytes <= 0 || !Number.isSafeInteger(availableBytes) || availableBytes < 0 || availableBytes > totalBytes) return null;
+    return { totalBytes, availableBytes };
+  } catch { return null; }
+}
+
+export async function sampleDiskPressure(): Promise<DiskSample> {
+  const [home, docker] = await Promise.all([measure(homedir()), dockerRoot().then(measure)]);
+  // No local paths are sent to the cloud; an unavailable probe is unknown.
+  return { sampledAt: Date.now(), home, docker };
+}