@runuai/host 0.9.170 → 0.9.172

package/lib/agents/claude.ts

@@ -561,6 +561,7 @@ export class ClaudeSession implements AgentSession {
     executionProfile?: "communicator" | "astronaut";
     attachCompatibilityKey?: string;
     agentEnv?: Record<string, string>;
+    claudeSettings?: Record<string, unknown>;
   }) {
     this.agentId = args.agent.id;
 
@@ -575,6 +576,16 @@ export class ClaudeSession implements AgentSession {
           ? CLAUDE_ASTRONAUT_ARGS
           : CLAUDE_FULL_ACCESS_ARGS),
     ];
+    if (args.claudeSettings) {
+      // Empty helper settings and fallbackModel override inherited values.
+      // Preserve native settings sources, including project hooks/plugins.
+      // Connection env separately pins routing with PROVIDER_MANAGED_BY_HOST.
+      const settings = {
+        ...(args.executionProfile === "communicator" ? JSON.parse(CLAUDE_COMMUNICATOR_SETTINGS) as Record<string, unknown> : {}),
+        ...args.claudeSettings,
+      };
+      cliArgs.push("--settings", JSON.stringify(settings));
+    }
     if (process.env.UAI_CLAUDE_INCLUDE_PARTIAL_MESSAGES === "1") {
       cliArgs.push("--include-partial-messages");
     }
@@ -845,6 +856,7 @@ register({
     executionProfile,
     attachCompatibilityKey,
     agentEnv,
+    claudeSettings,
   }) =>
     new ClaudeSession({
       taskId,
@@ -854,5 +866,6 @@ register({
       executionProfile,
       attachCompatibilityKey,
       agentEnv,
+      claudeSettings,
     }),
 });

package/lib/agents/codex.ts

@@ -29,6 +29,7 @@
  * namespaces inside it anyway.
  */
 
+import { connectionFailureReason, tomlString } from "../custom-connection-launch";
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -573,6 +574,7 @@ export class CodexSession implements AgentSession {
   private readonly handlers = new Set<AgentEventHandler>();
   private readonly systemPreamble: string;
   private readonly taskId: string;
+  private readonly customConnection: boolean;
   /** ADR-078: a thread id persisted by a PRIOR host process, to resume. */
   private readonly resumeThreadId: string | null;
   private closed = false;
@@ -624,6 +626,7 @@ export class CodexSession implements AgentSession {
     this.agentId = args.agent.id;
     this.systemPreamble = args.systemPreamble;
     this.taskId = args.taskId;
+    this.customConnection = args.agentEnv?.UAI_CUSTOM_CONNECTION === "1";
     this.attachCompatibilityKey = args.attachCompatibilityKey;
     // ADR-078: read BEFORE createAgentTransport (whose session-row upsert
     // preserves this column). Non-null → a host restart; resume the thread.
@@ -639,10 +642,10 @@ export class CodexSession implements AgentSession {
     // `app-server` subcommand. Without them codex uses its configured defaults.
     const codexArgs: string[] = [];
     if (args.agent.model) {
-      codexArgs.push("-c", `model=${args.agent.model}`);
+      codexArgs.push("-c", `model=${tomlString(args.agent.model)}`);
     }
     if (args.agent.effort) {
-      codexArgs.push("-c", `model_reasoning_effort=${args.agent.effort}`);
+      codexArgs.push("-c", `model_reasoning_effort=${tomlString(args.agent.effort)}`);
     }
     for (const override of args.cliConfigOverrides ?? []) {
       codexArgs.push("-c", override);
@@ -759,7 +762,8 @@ export class CodexSession implements AgentSession {
         }
       } else if (fired === "turn/interrupt" && isObj(msg.error)) {
         const code = typeof msg.error.code === "number" ? msg.error.code : undefined;
-        const message = `Couldn't stop the message: ${this.cliLabel}${code === undefined ? "" : ` (code ${code})`}: ${str(msg.error.message, "Unknown error. Please try again.")}`;
+        let message = `Couldn't stop the message: ${this.cliLabel}${code === undefined ? "" : ` (code ${code})`}: ${str(msg.error.message, "Unknown error. Please try again.")}`;
+        if (this.customConnection) message = connectionFailureReason(message);
         this.reportError(message, code);
         this.emit({ type: "notice", message: agentErrorMessage(message) });
       }
@@ -1076,8 +1080,8 @@ export class CodexSession implements AgentSession {
           continue;
         }
         console.warn(
-          `[codex] thread/resume ${threadId} failed (${
-            err instanceof Error ? err.message : String(err)
+          `[codex] thread/resume ${this.customConnection ? "connection" : threadId} failed (${
+            this.customConnection ? connectionFailureReason(err) : err instanceof Error ? err.message : String(err)
           }) — starting a fresh thread`,
         );
         return false;
@@ -1196,6 +1200,7 @@ export class CodexSession implements AgentSession {
   }
 
   private reportError(message: string, rpcCode?: number, capture = true): void {
+    if (this.customConnection) message = connectionFailureReason(message);
     reportAgentError(message, { taskId: this.taskId, agentId: this.agentId, engine: this.kind, rpcCode }, { capture });
   }
 
@@ -1204,6 +1209,7 @@ export class CodexSession implements AgentSession {
   private failTurn(message: string, code?: number, usage?: AgentUsage): void {
     if (this.failed || this.closed) return;
     this.failed = true;
+    if (this.customConnection) message = connectionFailureReason(message);
     this.reportError(message, code);
     const aborted = this.outstandingTurns > 0;
     const settles = this.outstandingTurns + [...this.turnStarts.values()]

package/lib/agents/session-state.ts

@@ -9,6 +9,8 @@
  */
 
 
+import { isOwnedInternalConnectionRuntime } from "../internal-connections";
+import { spawn } from "node:child_process";
 import { and, eq } from "drizzle-orm";
 
 import { getDb, schema } from "../db";
@@ -118,3 +120,78 @@ export async function stopPersistedAgentSession(
     .run();
   return row.sessionDir;
 }
+
+/** Remove internal runner generations only after the caller has proven every
+ * covered anchored process stopped. The persisted compatibility key survives
+ * restart and binds this deletion to the run and credential being cleaned. */
+export async function purgeInternalAgentSessionState(
+  request: { taskId: string; runEpoch: number; credentialIds?: readonly string[] },
+  environments: readonly TaskEnvironmentHandle<unknown>[],
+  removeDirectory: (root: string, path: string) => Promise<void> = removeInternalSessionDirectory,
+): Promise<void> {
+  const db = getDb();
+  const rows = db.select().from(schema.hostAgentSessions).where(eq(schema.hostAgentSessions.taskId, request.taskId)).all();
+  for (const row of rows) {
+    let key: unknown;
+    try { key = JSON.parse(row.attachCompatibilityKey ?? "null"); } catch { continue; }
+    if (!Array.isArray(key) || key[1] !== "lease-v1" || !Number.isSafeInteger(key[2]) || key[2] > request.runEpoch || key.at(-1) !== "custom-internal" ||
+      (request.credentialIds && !request.credentialIds.includes(key[3] as string))) continue;
+    if (!/^[A-Za-z0-9_-]{1,128}$/.test(row.agentId)) throw new Error("unsupported");
+    if (!environments.length) throw new Error("unsupported");
+    // Owned-runtime workspaces are host mounts; they persist even after the
+    // container disappears. Delete through host directory FDs, not exec into
+    // a container which may already be stopped/absent.
+    if (environments.some(e => e.descriptor.taskId !== request.taskId || !isOwnedInternalConnectionRuntime(e.descriptor.locator.provider))) throw new Error("unsupported");
+    const root = taskWorkspaceDir(request.taskId);
+    await removeDirectory(root, `${root}/.uai/sessions/${row.agentId}`);
+    db.delete(schema.hostAgentSessions).where(and(eq(schema.hostAgentSessions.taskId, row.taskId), eq(schema.hostAgentSessions.agentId, row.agentId), eq(schema.hostAgentSessions.sessionDir, row.sessionDir))).run();
+  }
+}
+
+/** FD-relative tree removal. A task can
+ * replace entries concurrently; links are never followed, and a race fails
+ * closed for the cleanup coordinator to retry. No provider text is read. */
+export const INTERNAL_SESSION_UNLINK_HELPER = String.raw`
+import os, stat, sys
+root, absolute = sys.argv[1:3]
+prefix = root.rstrip("/") + "/"
+if not absolute.startswith(prefix): raise RuntimeError()
+parts = absolute[len(prefix):].split("/")
+if not parts or any(p in ("", ".", "..") for p in parts): raise RuntimeError()
+flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW
+fds = []
+def remove(parent, name):
+    try: info = os.stat(name, dir_fd=parent, follow_symlinks=False)
+    except FileNotFoundError: return
+    if not stat.S_ISDIR(info.st_mode): raise RuntimeError()
+    child = os.open(name, flags, dir_fd=parent)
+    try:
+        for entry in os.listdir(child):
+            info = os.stat(entry, dir_fd=child, follow_symlinks=False)
+            if stat.S_ISDIR(info.st_mode): remove(child, entry)
+            else: os.unlink(entry, dir_fd=child)
+    finally: os.close(child)
+    os.rmdir(name, dir_fd=parent)
+try:
+    current = os.open("/", flags); fds.append(current)
+    for p in root.split("/") + parts[:-1]:
+        if not p: continue
+        current = os.open(p, flags, dir_fd=current); fds.append(current)
+    remove(current, parts[-1])
+    try: os.stat(parts[-1], dir_fd=current, follow_symlinks=False)
+    except FileNotFoundError: sys.exit(0)
+    raise RuntimeError()
+except FileNotFoundError: sys.exit(0)
+finally:
+    for fd in reversed(fds): os.close(fd)
+`;
+function removeInternalSessionDirectory(root: string, path: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn("/usr/bin/python3", ["-I", "-", root, path], { stdio: ["pipe", "ignore", "ignore"], env: { PATH: "/usr/bin:/bin" } });
+    const timer = setTimeout(() => { proc.kill("SIGKILL"); reject(new Error("unsupported")); }, 10_000);
+    proc.on("error", () => { clearTimeout(timer); reject(new Error("unsupported")); });
+    proc.on("exit", code => { clearTimeout(timer); if (code === 0) resolve(); else reject(new Error("unsupported")); });
+    proc.stdin.on("error", () => {});
+    proc.stdin.end(INTERNAL_SESSION_UNLINK_HELPER);
+  });
+}

package/lib/agents/transport.ts

@@ -201,6 +201,8 @@ function claimCompatibleAttachRow(
 }
 
 export function createAgentTransport(opts: AgentTransportOptions): LineTransport {
+  // Connection stderr/provider errors may contain arbitrary credentials.
+  if (opts.explicitEnv?.UAI_CUSTOM_CONNECTION === "1") opts = { ...opts, debugLabel: undefined };
   // ADR-121: machine-backed sessions ride the environment's own transport —
   // the container-runtime preflight is a docker/apple concern a machine task
   // must not trip over, and the host-FS durable flow below polls files a

package/lib/agents/types.ts

@@ -58,6 +58,7 @@ export const RosterAgent = z.object({
     .max(128)
     .regex(/^[A-Za-z0-9_.:-]+$/)
     .optional(),
+  accountBinding: z.enum(["required", "preferred"]).optional(),
   defaultPrompt: z.string().optional(), // persona
   initialPrompt: z.string().optional(), // first-turn instructions, this task only
   skills: z.array(RosterSkill).optional(), // ADR-046 reference material
@@ -243,5 +244,7 @@ export interface AgentSessionFactory {
      *  `-c key=value`), e.g. the Uai Managed Engine's model-provider block
      *  that points codex at the inference gateway. Never from the roster. */
     cliConfigOverrides?: string[];
+    /** Host-generated per-launch Claude settings; never from roster input. */
+    claudeSettings?: Record<string, unknown>;
   }): Promise<AgentSession>;
 }

package/lib/agents/uai.ts

@@ -15,6 +15,7 @@
  * the request's `model`, and the gateway maps slug → upstream id.
  */
 
+import { codexProviderOverrides, endpointAuthEnv } from "../custom-connection-launch";
 import { factoryFor, register, supportsExecutionProfile } from "./registry";
 import type { AgentSession, AgentSessionFactory } from "./types";
 
@@ -30,23 +31,7 @@ export function uaiGatewayEnv(
   url: string,
   taskToken: string,
 ): Record<string, string> {
-  if (provider === "openai") {
-    return {
-      OPENAI_BASE_URL: url,
-      OPENAI_API_KEY: taskToken,
-      // Read by the `uai` model provider's `env_key` (see uaiCodexOverrides).
-      UAI_INFERENCE_TOKEN: taskToken,
-    };
-  }
-  return {
-    ANTHROPIC_BASE_URL: url,
-    ANTHROPIC_AUTH_TOKEN: taskToken,
-    // Explicit blanks WIN over the claude adapter's passEnv inheritance
-    // (same mechanism its communicator profile uses to scrub) — the host's
-    // real credential must never ride a gateway-billed session.
-    ANTHROPIC_API_KEY: "",
-    CLAUDE_CODE_OAUTH_TOKEN: "",
-  };
+  return endpointAuthEnv(provider, url, taskToken, "bearer", "UAI_INFERENCE_TOKEN");
 }
 
 /**
@@ -63,14 +48,7 @@ export function uaiGatewayEnv(
  */
 export function uaiCodexOverrides(url: string): string[] {
   const base = `${url.replace(/\/+$/, "")}/v1`;
-  return [
-    "model_provider=uai",
-    'model_providers.uai.name="Uai Managed Engine"',
-    `model_providers.uai.base_url="${base}"`,
-    'model_providers.uai.env_key="UAI_INFERENCE_TOKEN"',
-    'model_providers.uai.wire_api="responses"',
-    "model_providers.uai.requires_openai_auth=false",
-  ];
+  return codexProviderOverrides(base, { provider: "uai", name: "Uai Managed Engine", envKey: "UAI_INFERENCE_TOKEN" });
 }
 
 const create: AgentSessionFactory["create"] = async (args): Promise<AgentSession> => {

package/lib/assignment-evidence.ts

@@ -34,7 +34,7 @@ export class AssignmentEvidenceJournal {
     const dir = openSync(dirname(this.path), "r");
     try { fsyncSync(dir); } finally { closeSync(dir); }
   }
-  begin(input: { sessionId: string; engine: string; runEpoch: number; runtimeVersion: string | null; recipientGeneration: string | null; assignment?: AssignmentDelivery | null; replay?: boolean; leadRunId?: string | null }): (AssignmentTurnEvidence & { assignment: AssignmentDelivery | null }) | null {
+  begin(input: { actualAccount?: { credentialId: string; credentialRevision: string; connection: boolean } | null; sessionId: string; engine: string; runEpoch: number; runtimeVersion: string | null; recipientGeneration: string | null; assignment?: AssignmentDelivery | null; replay?: boolean; leadRunId?: string | null }): (AssignmentTurnEvidence & { assignment: AssignmentDelivery | null }) | null {
     const state = this.read(input.sessionId);
     if (state.current && (state.current.runEpoch !== input.runEpoch || state.current.recipientGeneration !== input.recipientGeneration)) {
       state.current = null;
@@ -59,6 +59,7 @@ export class AssignmentEvidenceJournal {
       ...(input.leadRunId ? { leadRunId: input.leadRunId } : {}),
       correlation: input.assignment || input.leadRunId ? "explicit" : current ? "followup" : "unknown",
       acceptedAt: Date.now(), engine: input.engine, runtimeVersion: input.runtimeVersion,
+      ...(input.actualAccount !== undefined ? { credentialId: input.actualAccount?.credentialId ?? null, credentialRevision: input.actualAccount?.credentialRevision ?? null, connection: input.actualAccount?.connection ?? null } : {}),
     };
     // Concurrent prompts aren't assumed to execute FIFO. Without a provider
     // turn/request join, every overlapping turn is explicitly unallocated.

package/lib/capture-flow.ts

@@ -26,6 +26,7 @@ import {
   type CaptureResultWire,
   type CredentialLocation,
 } from "../src/cloud-credentials";
+import { parseCustomConnectionMaterial, type CustomConnectionMaterial } from "../src/custom-connections";
 import { ImmutableParameterAbortedError, storeFailureKind, type CredentialStore } from "./credential-store";
 import { laneFor } from "./token-lanes/registry";
 import {
@@ -48,7 +49,8 @@ export interface BrokerEngineValue {
 
 export type EngineCaptureMaterial =
   | { authKind: "env"; env: Record<string, string> }
-  | { authKind: "config-dir"; files: CredentialFiles };
+  | { authKind: "config-dir"; files: CredentialFiles }
+  | { authKind: "custom-connection"; connection: CustomConnectionMaterial };
 
 export interface BuiltCapture {
   lease: string;
@@ -87,6 +89,17 @@ export function buildEngineCapture(
     return { error: "This capture is not an AI account." };
   }
   const kind = location.engineKind!;
+  if (material.authKind === "custom-connection") {
+    const connection = parseCustomConnectionMaterial(material.connection);
+    if (!connection || connection.engine !== kind || flow.brokerParameter !== null) {
+      return { error: "unsupported" };
+    }
+    return {
+      lease: serializeLeasedValue({ v: 1, part: "lease", location, class: "engine", authKind: "custom-connection", connection }),
+      broker: null,
+      expiresAt: connection.expiresAt ?? null,
+    };
+  }
   if (material.authKind === "env") {
     if (!onlyKeys(material.env, ENGINE_ENV_CREDENTIAL_KEYS[kind] ?? [])) {
       return { error: "This key is not one the engine reads." };

package/lib/cloud-credential-leases.ts

@@ -1,3 +1,4 @@
+import type { CustomConnectionCombination } from "../src/custom-connections";
 import { parseTaskSecretMaterial, type TaskSecretManifestEntry, type TaskSecretMaterial } from "../src/task-secrets";
 /**
  * ADR-154 task-scoped credential leases.
@@ -137,6 +138,8 @@ export interface TaskStaticCredential<T extends LeasedValue> {
 
 /** A task-facing view. It contains material, but never STS credentials. */
 export interface TaskCredentialView {
+  connectionsEnabled?: readonly CustomConnectionCombination[];
+  connectionsUnsupported?: readonly string[];
   taskSecrets?: readonly { manifest: Readonly<TaskSecretManifestEntry>; material: Readonly<TaskSecretMaterial> | null }[];
   assignment: Readonly<TaskAssignment>;
   leaseId: string;
@@ -293,7 +296,7 @@ type CredentialDescriptor = {
   parameter: string | null;
   version: number | null;
   sessionId: string | null;
-  authKind: "env" | "config-dir" | "oauth" | "token" | "none" | null;
+  authKind: "custom-connection" | "env" | "config-dir" | "oauth" | "token" | "none" | null;
   location: CredentialLocation | null;
   taskSecret?: { entry: TaskSecretManifestEntry; orgId: string; taskId: string };
 };
@@ -552,7 +555,8 @@ function freezeMaterial<T extends LeasedValue | TaskSecretMaterial>(material: T)
   Object.freeze(material.location);
   if (material.class === "engine") {
     if (material.authKind === "env") Object.freeze(material.env);
-    else Object.freeze(material.files);
+    else if (material.authKind === "config-dir") Object.freeze(material.files);
+    else Object.freeze(material.connection);
   } else if (material.class === "mcp" && material.authKind === "token") {
     Object.freeze(material.header);
   }
@@ -581,7 +585,7 @@ function freezeView(
       throw new CredentialLeaseError("engine material is incomplete");
     }
     return Object.freeze({
-      manifest: Object.freeze({ ...manifest }),
+      manifest: Object.freeze({ ...manifest, ...(manifest.connection ? { connection: Object.freeze({ ...manifest.connection, models: Object.freeze([...manifest.connection.models]) as unknown as string[] }) } : {}) }),
       availability: record.availability,
       material: record.material as Readonly<EngineLeasedValue> | null,
       observedVersion: record.observedVersion,
@@ -633,6 +637,8 @@ function freezeView(
     manifestRevision: lease.manifestRevision,
     manifestDigest: lease.manifestDigest,
     expiresAt,
+    ...(lease.manifest.connectionsEnabled ? { connectionsEnabled: Object.freeze([...lease.manifest.connectionsEnabled]) } : {}),
+    ...(lease.manifest.connectionsUnsupported ? { connectionsUnsupported: Object.freeze([...lease.manifest.connectionsUnsupported]) } : {}),
     projectIds: Object.freeze(lease.manifest.projects.map((project) => project.projectId)),
     ...(lease.manifest.taskSecrets?.length ? { taskSecrets: Object.freeze(lease.manifest.taskSecrets.map(manifest => {
       const record = requireRecord(manifest.credentialId);

package/lib/cloud-credential-runtime.ts

@@ -1,3 +1,4 @@
+import { isOwnedInternalConnectionRuntime } from "./internal-connections";
 import type { TaskSecretApplied } from "../src/task-secrets";
 import { openTaskSecrets, closeTaskSecrets } from "./credential-consumers/task-secrets";
 /**
@@ -149,6 +150,9 @@ export class AuthoritativeTaskFilesFailure extends Error {
 
 export interface CloudCredentialRuntimeDeps {
   runnerKind: "owned" | "task-machine";
+  /** Actual persisted provider, or the authoritative plan for a new runtime.
+   * Missing/unknown refuses internal credentials. Rechecked before opening. */
+  internalRuntimeProvider?(assignment: Readonly<TaskAssignment>): string | null | undefined;
   /** To the cloud, over the authenticated bridge. False: not sent now. */
   send(frame: LeaseRequestV1Frame | CredentialRefreshFrame | ProjectEnvReplicaV1AckFrame | TaskSecretApplied): boolean;
   /** Every engine of the run (and older) proven stopped in every runtime it
@@ -1071,6 +1075,8 @@ export class CloudCredentialRuntime {
 
   #openGate(assignment: Readonly<TaskAssignment>, view: TaskCredentialView): void {
     if (this.#shutDown) throw new CredentialLeaseUnavailableError("the runner is shutting down");
+    if (view.engines.some(e => e.manifest.connection?.internal === true) &&
+      (this.#deps.runnerKind !== "owned" || !isOwnedInternalConnectionRuntime(this.#deps.internalRuntimeProvider?.(assignment)))) throw new CredentialLeaseUnavailableError("unsupported");
     openTaskSecrets(assignment, view);
     openEngineGate(assignment, view);
     openMcpGate(assignment, view);
@@ -1261,6 +1267,8 @@ export class CloudCredentialRuntime {
   }
 
   #assertInstallCurrent(request: CredentialInstallRequest): void {
+    if (request.next.engines.some(e => e.manifest.connection?.internal === true) &&
+      (this.#deps.runnerKind !== "owned" || !isOwnedInternalConnectionRuntime(this.#deps.internalRuntimeProvider?.(request.assignment)))) throw new CredentialLeaseUnavailableError("unsupported");
     if (this.#shutDown) throw new CredentialLeaseUnavailableError("the runner is shutting down");
     if (!request.isCurrent()) {
       throw new CredentialLeaseUnavailableError("the grant was withdrawn while it was being installed");

package/lib/connection-secret-redaction.ts

@@ -0,0 +1,25 @@
+/** Exact, session-scoped defense for diagnostics that reach host telemetry. */
+const active = new Map<string, number>();
+
+export function registerConnectionSecret(key: string): () => void {
+  if (!key) return () => {};
+  active.set(key, (active.get(key) ?? 0) + 1);
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    const remaining = (active.get(key) ?? 1) - 1;
+    if (remaining) active.set(key, remaining);
+    else active.delete(key);
+  };
+}
+
+export function redactActiveConnectionSecrets(text: string): string {
+  // Empty replacement cannot itself contain another active secret.
+  let previous: string;
+  do {
+    previous = text;
+    for (const key of active.keys()) text = text.split(key).join("");
+  } while (text !== previous);
+  return text;
+}

package/lib/credential-cleanup-inventory.ts

@@ -146,6 +146,7 @@ export function forgetCredentialCleanupPending(
 
 /** An engine account's file, or the intermediate its writer stages
  * (`.uai-tmp`) before renaming it into place. */
+const CONNECTION_AUTH_PATH = /^\/home\/node\/\.uai-connection\/[a-f0-9]{64}(?:\/(?:auth\.json|config\.toml|aws-config|aws-credentials))?$/;
 const ENGINE_AUTH_PATH = /^\/home\/node\/(?:\.codex(?:-acct-[A-Za-z0-9_-]+)?(?:-agent-[A-Za-z0-9_-]+)?|\.grok(?:-acct-[A-Za-z0-9_-]+)?|\.local\/share\/opencode(?:-acct-[A-Za-z0-9_-]+)?)\/auth\.json(?:\.uai-tmp)?$/;
 /** A file a writer stages (`.uai-tmp`) before renaming it into place. */
 function andStaged(...paths: string[]): string[] {
@@ -188,7 +189,7 @@ export function assertCredentialCleanupPath(
     throw new Error("credential cleanup path is invalid");
   }
   const allowed =
-    (lane === "engine-auth" && ENGINE_AUTH_PATH.test(value)) ||
+    (lane === "engine-auth" && (ENGINE_AUTH_PATH.test(value) || CONNECTION_AUTH_PATH.test(value))) ||
     (lane === "github" && GITHUB_PATHS.has(value)) ||
     (lane === "ssh" && SSH_PATHS.has(value)) ||
     (lane === "files-session" && FILES_SESSION_PATHS.has(value));

package/lib/credential-consumers/engines.ts

@@ -1,3 +1,4 @@
+import { validConnectionModels, type CustomConnectionCombination, type CustomConnectionLease, type CustomConnectionMaterial } from "../../src/custom-connections";
 /**
  * ADR-154 §6, §8, §10 on the runner: a task's AI accounts, from its lease.
  *
@@ -89,7 +90,9 @@ export interface LeasedEngineAccount {
   engineKind: string;
   scope: CredentialScope;
   label: string;
-  authKind: "env" | "config-dir";
+  authKind: "env" | "config-dir" | "custom-connection";
+  connection?: CustomConnectionLease;
+  connectionMaterial?: CustomConnectionMaterial;
   /** The lease parameter's version this material was read at. */
   version: number;
   /** Env-token accounts: the variables the engine's spawn takes. */
@@ -109,14 +112,17 @@ export interface UnavailableEngineAccount {
   engineKind: string;
   scope: CredentialScope;
   label: string;
-  authKind: "env" | "config-dir";
+  authKind: "env" | "config-dir" | "custom-connection";
   home: string | null;
+  connection?: CustomConnectionLease;
   unavailable: true;
 }
 
 export type ServedEngineAccount = LeasedEngineAccount | UnavailableEngineAccount;
 
 export interface TaskEngineLease {
+  connectionsEnabled?: readonly CustomConnectionCombination[];
+  connectionsUnsupported?: readonly string[];
   assignment: TaskAssignment;
   /** False while the registry's gate is closed: spawn nothing. */
   open: boolean;
@@ -142,6 +148,8 @@ interface WrittenHome {
 }
 
 interface TaskEngineState {
+  connectionsEnabled: readonly CustomConnectionCombination[];
+  connectionsUnsupported: readonly string[];
   assignment: TaskAssignment;
   /** The accounts of the view the gate opened on; null while it is closed. */
   served: ServedEngineAccount[] | null;
@@ -200,6 +208,7 @@ function accountOf(credential: TaskEngineCredential): ServedEngineAccount {
     label: manifest.label,
     authKind: manifest.authKind,
     home,
+    ...(manifest.connection ? { connection: manifest.connection } : {}),
   };
   if (
     credential.availability !== "available" ||
@@ -210,6 +219,13 @@ function accountOf(credential: TaskEngineCredential): ServedEngineAccount {
   ) {
     return { ...identity, unavailable: true };
   }
+  if (material.authKind === "custom-connection") {
+    const c = manifest.connection;
+    const m = material.connection;
+    const matches = c && (c.internal === true) === (m.internal === true) && c.providerType === m.providerType && c.authMode === m.authMode && c.host === new URL(m.baseUrl).host && c.region === m.region && c.transport === m.transport && (c.expiresAt ?? null) === (m.expiresAt ?? null) && m.engine === manifest.engineKind && validConnectionModels(c.models, c.defaultModel, c.backgroundModel, m.engine, m.apiKey);
+    if (!matches) return { ...identity, unavailable: true };
+    return { ...identity, version: credential.observedVersion, env: null, files: null, expiresAt: m.expiresAt ?? null, connectionMaterial: m };
+  }
   return material.authKind === "env"
     ? { ...identity, version: credential.observedVersion, env: { ...material.env }, files: null, expiresAt: null }
     : {
@@ -235,7 +251,8 @@ function sameAccount(a: ServedEngineAccount, b: ServedEngineAccount): boolean {
     a.credentialId === b.credentialId &&
     a.revision === b.revision &&
     a.engineKind === b.engineKind &&
-    a.authKind === b.authKind
+    a.authKind === b.authKind &&
+    a.connection?.settingsHash === b.connection?.settingsHash
   );
 }
 
@@ -261,6 +278,8 @@ function stateFor(assignment: TaskAssignment): TaskEngineState {
   if (current) current.served = null;
   const fresh: TaskEngineState = {
     assignment: { taskId: assignment.taskId, runEpoch: assignment.runEpoch },
+    connectionsEnabled: [],
+    connectionsUnsupported: [],
     served: null,
     queue: Promise.resolve(),
     writing: 0,
@@ -312,6 +331,8 @@ export async function installEngineCredentials(request: CredentialInstallRequest
   // the runner's own store.
   const state = stateFor(request.assignment);
   const next = accountsOf(request.next);
+  state.connectionsEnabled = request.next.connectionsEnabled ?? [];
+  state.connectionsUnsupported = request.next.connectionsUnsupported ?? [];
   const floors = next.filter(isLeasedEngineAccount).flatMap((account) => {
     const served = state.exposed.get(exposureKey(account));
     return served !== undefined && account.version > served
@@ -350,6 +371,8 @@ export async function installEngineCredentials(request: CredentialInstallRequest
 export function openEngineGate(assignment: TaskAssignment, view: TaskCredentialView): void {
   if (olderRun(assignment)) return;
   const state = stateFor(assignment);
+  state.connectionsEnabled = view.connectionsEnabled ?? [];
+  state.connectionsUnsupported = view.connectionsUnsupported ?? [];
   state.served = accountsOf(view);
   expose(state, state.served);
   notify(assignment.taskId);
@@ -444,7 +467,7 @@ export function engineVersionHeldBack(
 export function leasedEnginesFor(taskId: string): TaskEngineLease | undefined {
   const state = tasks.get(taskId);
   if (!state) return undefined;
-  return { assignment: { ...state.assignment }, open: state.served !== null, accounts: [...(state.served ?? [])] };
+  return { assignment: { ...state.assignment }, open: state.served !== null, accounts: [...(state.served ?? [])], connectionsEnabled: state.connectionsEnabled, ...(state.connectionsUnsupported.length ? { connectionsUnsupported: state.connectionsUnsupported } : {}) };
 }
 
 /** The live, open record for this exact run, or a failure: never "none". */
@@ -483,7 +506,7 @@ export function waitForEngineGate(
       return new CredentialLeaseUnavailableError("the task moved on to another run");
     }
     if (!sameAssignment(state.assignment, assignment) || !state.served) return "closed";
-    return { assignment: { ...state.assignment }, open: true, accounts: [...state.served] };
+    return { assignment: { ...state.assignment }, open: true, accounts: [...state.served], connectionsEnabled: state.connectionsEnabled, ...(state.connectionsUnsupported.length ? { connectionsUnsupported: state.connectionsUnsupported } : {}) };
   };
   const now = check();
   if (now instanceof Error) return Promise.reject(now);
@@ -533,6 +556,7 @@ function homeOf(account: LeasedEngineAccount, home: string | undefined): string
  * a home derived from it). Never the files' content.
  */
 export function engineSpawnEnv(account: LeasedEngineAccount, home?: string): Record<string, string> {
+  if (account.authKind === "custom-connection") throw new Error("a connection requires its launch builder");
   if (account.authKind === "env") return { ...(account.env ?? {}) };
   const selector = ENGINE_ACCOUNT_HOMES[account.engineKind];
   if (!selector) throw new Error("the account's engine reads no file");