@skein-code/cli 0.3.29 → 0.3.30

package/dist/cli.js

@@ -220,7 +220,7 @@ function isSqliteBusy(error) {
 // package.json
 var package_default = {
   name: "@skein-code/cli",
-  version: "0.3.29",
+  version: "0.3.30",
   description: "A context-first, model-agnostic coding agent with an auditable terminal workspace.",
   type: "module",
   license: "MIT",
@@ -236,6 +236,13 @@ var package_default = {
   },
   skein: {
     releaseNotes: [
+      "Named primary connections now target third-party compatible relays only, use explicit env or none authentication, and resolve one complete profile automatically while requiring an explicit choice for ambiguity",
+      "OpenAI Responses is the recommended new transport with POST /responses, store false, typed SSE, normalized tools and usage, and bounded exact output-item replay for stateless reasoning continuation",
+      "OpenAI Chat Completions and Anthropic Messages remain explicit relay transports without cross-protocol retries; inference and OpenAI-style model catalog base URLs are configured independently",
+      "Relay model discovery now uses a bounded 15-minute ETag cache isolated by endpoint and credential fingerprints, invalidates authentication failures, and never stores or echoes credential values",
+      "First-run and agents setup flows are relay-only, save only credential environment-variable names, and expose redacted connection state consistently across TUI, text, JSON, JSONL, doctor, and config output",
+      "Provider diagnostics redact secrets, authorization headers, URL credentials, and query strings while Responses replay state is capped at 128 items and 4 MiB in memory and persisted sessions",
+      "External delegated CLIs now receive a minimal runtime-owned environment instead of inheriting provider, Skein, relay, or NODE_OPTIONS secrets",
       "TERM=dumb and screen-reader sessions now use deterministic ASCII, monochrome, reduced-motion, non-incremental rendering without losing keyboard input",
       "SKEIN_SCREEN_READER=1 enables Ink accessibility output with semantic timeline, permission, and composer roles plus clean phase boundaries",
       "PTY release gates now replay eight terminal scenarios through a headless emulator and reject final-frame overflow, stale panels, announcement joins, and missing status",
@@ -1923,13 +1930,28 @@ var memoryConfigSchema = z2.object({
   maxPromptTokens: z2.number().int().positive().max(2e4).optional()
 }).partial();
 var agentConnectionNameSchema = z2.string().regex(/^[a-z][a-z0-9_-]{0,63}$/);
+var connectionAuthSchema = z2.discriminatedUnion("type", [
+  z2.object({ type: z2.literal("env"), name: z2.string().regex(/^[A-Z][A-Z0-9_]{0,127}$/) }).strict(),
+  z2.object({ type: z2.literal("none") }).strict()
+]);
+var connectionUrlSchema = z2.string().url().refine((value) => {
+  const url = new URL(value);
+  return /^https?:$/i.test(url.protocol) && !url.username && !url.password && !url.search && !url.hash;
+}, {
+  message: "connection URL must use http or https without credentials, query parameters, or fragments"
+});
 var agentConnectionSchema = z2.object({
   provider: z2.enum(["openai", "anthropic", "gemini", "compatible"]),
-  baseUrl: z2.string().url().refine((value) => /^https?:$/i.test(new URL(value).protocol), {
-    message: "agent connection baseUrl must use http or https"
-  }).optional(),
+  label: z2.string().min(1).max(128).optional(),
+  protocol: z2.enum(["openai-responses", "openai-chat", "anthropic-messages", "gemini"]).optional(),
+  baseUrl: connectionUrlSchema.optional(),
+  modelsBaseUrl: connectionUrlSchema.optional(),
+  defaultModel: z2.string().min(1).max(256).optional(),
+  auth: connectionAuthSchema.optional(),
   apiKeyEnv: z2.string().regex(/^[A-Z][A-Z0-9_]{0,127}$/).optional()
-}).strict();
+}).strict().refine((value) => !(value.auth && value.apiKeyEnv), {
+  message: "agent connection auth and apiKeyEnv are mutually exclusive"
+});
 var agentTeamConfigSchema = z2.object({
   enabled: z2.boolean().optional(),
   maxConcurrent: z2.number().int().positive().max(16).optional(),
@@ -2353,6 +2375,17 @@ function validateAgentConnections(agents) {
   if (agents?.defaultConnection && !agents.connections?.[agents.defaultConnection]) {
     throw new Error(`Agent defaults reference unknown connection ${agents.defaultConnection}.`);
   }
+  for (const [name, connection] of Object.entries(agents?.connections ?? {})) {
+    if (connection.protocol && connection.provider !== "compatible") {
+      throw new Error(`Agent connection ${name} must use provider compatible when protocol is explicit.`);
+    }
+    if (connection.provider === "compatible" && connection.protocol === "gemini") {
+      throw new Error(`Agent connection ${name} cannot use the Gemini transport.`);
+    }
+    if (connection.protocol === "anthropic-messages" && !connection.modelsBaseUrl) {
+      throw new Error(`Agent connection ${name} requires modelsBaseUrl for Anthropic transport.`);
+    }
+  }
   for (const [profile, route] of Object.entries(agents?.routes ?? {})) {
     if (route.connection && !agents?.connections?.[route.connection]) {
       throw new Error(`Agent route ${profile} references unknown connection ${route.connection}.`);
@@ -2496,6 +2529,8 @@ function configSummary(config) {
     model: `${config.model.provider}/${config.model.model}`,
     endpoint: redactEndpoint(config.model.baseUrl),
     apiKey: config.model.apiKey ? "configured" : "missing",
+    activeConnection: config.activeConnection,
+    connectionCatalog: config.connectionCatalog,
     context: {
       maxTokens: config.context.maxTokens,
       topK: config.context.topK
@@ -2537,8 +2572,11 @@ function configSummary(config) {
       maxWriterPatchBytes: config.agents.maxWriterPatchBytes,
       connections: Object.fromEntries(Object.entries(config.agents.connections ?? {}).map(([name, connection]) => [name, {
         provider: connection.provider,
+        protocol: connection.protocol,
+        defaultModel: connection.defaultModel,
         endpoint: redactEndpoint(connection.baseUrl),
-        credentials: connection.apiKeyEnv ? `env:${connection.apiKeyEnv}` : "provider default environment"
+        modelsEndpoint: redactEndpoint(connection.modelsBaseUrl ?? connection.baseUrl),
+        credentials: connection.auth?.type === "env" ? `env:${connection.auth.name}` : connection.auth?.type ?? (connection.apiKeyEnv ? `env:${connection.apiKeyEnv}` : "provider default environment")
       }])),
       routes: Object.fromEntries(Object.entries(config.agents.routes ?? {}).map(([profile, route]) => [profile, {
         runtime: route.runtime ?? "api",
@@ -4788,7 +4826,7 @@ function formatContextHits(hits, roots) {
 }
 
 // src/agent/runner.ts
-import { randomUUID as randomUUID15 } from "node:crypto";
+import { randomUUID as randomUUID16 } from "node:crypto";
 
 // src/context/manager.ts
 import { randomUUID as randomUUID5 } from "node:crypto";
@@ -5376,7 +5414,7 @@ function concise(value, max) {
   return normalized.length <= max ? normalized : `${normalized.slice(0, max - 1)}\u2026`;
 }
 function estimateMessages(messages) {
-  return messages.reduce((sum, message2) => sum + estimateTokens(message2.content) + estimateTokens(JSON.stringify(message2.toolCalls ?? [])), 0);
+  return messages.reduce((sum, message2) => sum + estimateTokens(message2.content) + estimateTokens(JSON.stringify(message2.toolCalls ?? [])) + estimateTokens(JSON.stringify(message2.providerMetadata ?? {})), 0);
 }
 function toolTokens(messages) {
   return messages.filter((message2) => message2.role === "tool").reduce((sum, message2) => sum + estimateTokens(message2.content), 0);
@@ -5683,17 +5721,42 @@ function requireApiKey(config) {
   }
   return config.apiKey;
 }
-async function parseErrorResponse(response) {
-  const details = await response.text();
+async function parseErrorResponse(response, secrets = []) {
+  const rawDetails = await response.text();
+  const details = sanitizeProviderErrorText(rawDetails, secrets, 2e3);
   let message2 = `Model API request failed (${response.status})`;
   try {
-    const body = JSON.parse(details);
+    const body = JSON.parse(rawDetails);
     if (typeof body.error === "string") message2 = body.error;
-    else if (body.error?.message) message2 = body.error.message;
+    else if (body.error && typeof body.error === "object" && typeof body.error.message === "string") {
+      message2 = body.error.message;
+    }
   } catch {
-    if (details.trim()) message2 = `${message2}: ${details.slice(0, 300)}`;
+    if (rawDetails.trim()) message2 = `${message2}: ${rawDetails}`;
+  }
+  throw new ProviderError(
+    sanitizeProviderErrorText(message2, secrets, 500),
+    response.status,
+    details
+  );
+}
+function sanitizeProviderErrorText(input2, secrets = [], maxLength = 500) {
+  let value = input2.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/gu, "").replace(/\b(sk-[A-Za-z0-9_-]{12,}|AIza[0-9A-Za-z_-]{20,})\b/gu, "[redacted-secret]").replace(/\b(authorization\s*:\s*(?:bearer\s+|basic\s+)?)\S+/giu, "$1[redacted]").replace(/\b((?:api[_-]?key|access[_-]?token|authorization|cookie|password|client[_-]?secret)\s*[:=]\s*)(?:"[^"]+"|'[^']+'|\S+)/giu, "$1[redacted]").replace(/https?:\/\/[^\s"'<>]+/giu, (candidate) => redactDiagnosticUrl(candidate));
+  for (const secret of secrets) {
+    if (!secret) continue;
+    value = value.split(secret).join("[redacted-secret]");
+  }
+  const normalized = value.trim();
+  return normalized.length > maxLength ? `${normalized.slice(0, Math.max(0, maxLength - 1))}\u2026` : normalized;
+}
+function redactDiagnosticUrl(candidate) {
+  try {
+    const url = new URL(candidate);
+    const authentication = url.username || url.password ? "<redacted>@" : "";
+    return `${url.protocol}//${authentication}${url.host}${url.pathname}${url.search ? "?<redacted>" : ""}${url.hash ? "#<redacted>" : ""}`;
+  } catch {
+    return "configured endpoint";
   }
-  throw new ProviderError(message2, response.status, details);
 }
 function safeJsonArguments(value) {
   if (!value) return {};
@@ -5751,18 +5814,19 @@ function parseEventBlock(block) {
 var AnthropicProvider = class {
   constructor(config) {
     this.config = config;
+    this.name = config.provider === "compatible" ? "compatible" : "anthropic";
   }
   config;
-  name = "anthropic";
+  name;
   async complete(messages, tools, signal, maxOutputTokens) {
-    const apiKey = requireApiKey(this.config);
+    const apiKey = this.config.provider === "compatible" ? this.config.apiKey : requireApiKey(this.config);
     const base = this.config.baseUrl ?? "https://api.anthropic.com/v1";
     const system = messages.filter((message2) => message2.role === "system").map((message2) => message2.content).join("\n\n");
-    const response = await fetch(joinUrl(base, "messages"), {
+    const response = await fetch(anthropicMessagesEndpoint(base), {
       method: "POST",
       redirect: "error",
       headers: {
-        "x-api-key": apiKey,
+        ...anthropicAuthHeaders(this.config, apiKey),
         "anthropic-version": "2023-06-01",
         "content-type": "application/json"
       },
@@ -5780,7 +5844,7 @@ var AnthropicProvider = class {
       }),
       ...signal ? { signal } : {}
     });
-    if (!response.ok) return parseErrorResponse(response);
+    if (!response.ok) return parseErrorResponse(response, [apiKey]);
     const data = await response.json();
     const blocks = data.content ?? [];
     return {
@@ -5795,14 +5859,14 @@ var AnthropicProvider = class {
     };
   }
   async *stream(messages, tools, signal, maxOutputTokens) {
-    const apiKey = requireApiKey(this.config);
+    const apiKey = this.config.provider === "compatible" ? this.config.apiKey : requireApiKey(this.config);
     const base = this.config.baseUrl ?? "https://api.anthropic.com/v1";
     const system = messages.filter((message2) => message2.role === "system").map((message2) => message2.content).join("\n\n");
-    const response = await fetch(joinUrl(base, "messages"), {
+    const response = await fetch(anthropicMessagesEndpoint(base), {
       method: "POST",
       redirect: "error",
       headers: {
-        "x-api-key": apiKey,
+        ...anthropicAuthHeaders(this.config, apiKey),
         "anthropic-version": "2023-06-01",
         "content-type": "application/json"
       },
@@ -5821,7 +5885,7 @@ var AnthropicProvider = class {
       }),
       ...signal ? { signal } : {}
     });
-    if (!response.ok) return parseErrorResponse(response);
+    if (!response.ok) return parseErrorResponse(response, [apiKey]);
     if (!response.headers.get("content-type")?.includes("text/event-stream")) {
       const normalized = normalizeAnthropicResponse(await response.json());
       if (normalized.content) yield { type: "text_delta", content: normalized.content };
@@ -5896,6 +5960,15 @@ var AnthropicProvider = class {
     };
   }
 };
+function anthropicMessagesEndpoint(base) {
+  const normalized = base.replace(/\/+$/u, "");
+  if (normalized.endsWith("/messages")) return normalized;
+  return normalized.endsWith("/v1") ? joinUrl(normalized, "messages") : joinUrl(normalized, "v1/messages");
+}
+function anthropicAuthHeaders(config, apiKey) {
+  if (!apiKey) return {};
+  return config.provider === "compatible" ? { authorization: `Bearer ${apiKey}` } : { "x-api-key": apiKey };
+}
 function normalizeAnthropicResponse(data) {
   const blocks = data.content ?? [];
   return {
@@ -5979,7 +6052,7 @@ var GeminiProvider = class {
       }),
       ...signal ? { signal } : {}
     });
-    if (!response.ok) return parseErrorResponse(response);
+    if (!response.ok) return parseErrorResponse(response, [apiKey]);
     const data = await response.json();
     const candidate = data.candidates?.[0];
     const parts = candidate?.content?.parts ?? [];
@@ -6020,7 +6093,7 @@ var GeminiProvider = class {
       }),
       ...signal ? { signal } : {}
     });
-    if (!response.ok) return parseErrorResponse(response);
+    if (!response.ok) return parseErrorResponse(response, [apiKey]);
     if (!response.headers.get("content-type")?.includes("text/event-stream")) {
       const normalized = normalizeGeminiResponse(await response.json());
       if (normalized.content) yield { type: "text_delta", content: normalized.content };
@@ -6173,7 +6246,7 @@ var OpenAIProvider = class {
       body: JSON.stringify(body),
       ...signal ? { signal } : {}
     });
-    if (!response.ok) return parseErrorResponse(response);
+    if (!response.ok) return parseErrorResponse(response, [apiKey]);
     const data = await response.json();
     return normalizeOpenAIResponse(data);
   }
@@ -6218,7 +6291,7 @@ var OpenAIProvider = class {
         yield { type: "result", response: fallback };
         return;
       }
-      return parseErrorResponse(response);
+      return parseErrorResponse(response, [apiKey]);
     }
     if (!response.headers.get("content-type")?.includes("text/event-stream")) {
       const data = await response.json();
@@ -6330,6 +6403,193 @@ function toOpenAIMessage(message2) {
   return { role: message2.role, content: message2.content };
 }
 
+// src/providers/responses.ts
+import { randomUUID as randomUUID9 } from "node:crypto";
+var MAX_RESPONSES_OUTPUT_ITEMS = 128;
+var MAX_RESPONSES_REPLAY_BYTES = 4 * 1024 * 1024;
+var ResponsesProvider = class {
+  constructor(config) {
+    this.config = config;
+    this.name = config.provider === "compatible" ? "compatible" : "openai";
+  }
+  config;
+  name;
+  async complete(messages, tools, signal, maxOutputTokens) {
+    const response = await this.request(messages, tools, false, signal, maxOutputTokens);
+    if (!response.ok) return parseErrorResponse(response, [this.config.apiKey]);
+    return normalizeResponsesResponse(await response.json());
+  }
+  async *stream(messages, tools, signal, maxOutputTokens) {
+    const response = await this.request(messages, tools, true, signal, maxOutputTokens);
+    if (!response.ok) return parseErrorResponse(response, [this.config.apiKey]);
+    if (!response.headers.get("content-type")?.includes("text/event-stream")) {
+      const normalized2 = normalizeResponsesResponse(await response.json());
+      if (normalized2.content) yield { type: "text_delta", content: normalized2.content };
+      yield { type: "result", response: normalized2 };
+      return;
+    }
+    let content = "";
+    let completed;
+    const calls = /* @__PURE__ */ new Map();
+    for await (const event of parseServerSentEvents(response)) {
+      if (event.data === "[DONE]") break;
+      const chunk = JSON.parse(event.data);
+      const eventType = chunk.type ?? event.event;
+      if (eventType === "response.output_text.delta" && chunk.delta) {
+        content += chunk.delta;
+        yield { type: "text_delta", content: chunk.delta };
+      }
+      if (eventType === "response.output_item.added" && chunk.item?.type === "function_call") {
+        const key = streamCallKey(chunk);
+        calls.set(key, {
+          id: chunk.item.call_id ?? chunk.item.id ?? randomUUID9(),
+          name: chunk.item.name ?? "unknown",
+          arguments: chunk.item.arguments ?? ""
+        });
+      }
+      if (eventType === "response.function_call_arguments.delta") {
+        const key = streamCallKey(chunk);
+        const call = calls.get(key) ?? { id: chunk.item_id ?? randomUUID9(), name: "unknown", arguments: "" };
+        call.arguments += chunk.delta ?? "";
+        calls.set(key, call);
+      }
+      if (eventType === "response.output_item.done" && chunk.item?.type === "function_call") {
+        const key = streamCallKey(chunk);
+        const existing = calls.get(key);
+        calls.set(key, {
+          id: chunk.item.call_id ?? existing?.id ?? chunk.item.id ?? randomUUID9(),
+          name: chunk.item.name ?? existing?.name ?? "unknown",
+          arguments: chunk.item.arguments ?? existing?.arguments ?? ""
+        });
+      }
+      if (eventType === "response.completed" || eventType === "response.incomplete") {
+        completed = chunk.response;
+      }
+      if (eventType === "error" || eventType === "response.failed") {
+        throw new ProviderError(sanitizeProviderErrorText(
+          chunk.error?.message ?? chunk.response?.error?.message ?? "Model API stream failed.",
+          [this.config.apiKey]
+        ));
+      }
+    }
+    const normalized = completed ? normalizeResponsesResponse(completed) : emptyResponsesResult();
+    const streamedCalls = [...calls.values()].map((call) => ({
+      id: call.id,
+      name: call.name,
+      arguments: safeJsonArguments(call.arguments)
+    }));
+    yield {
+      type: "result",
+      response: {
+        ...normalized,
+        content: content || normalized.content,
+        toolCalls: normalized.toolCalls.length ? normalized.toolCalls : streamedCalls
+      }
+    };
+  }
+  async request(messages, tools, stream, signal, maxOutputTokens) {
+    const apiKey = this.config.provider === "compatible" ? this.config.apiKey : requireApiKey(this.config);
+    if (this.config.provider === "compatible" && !this.config.baseUrl) {
+      throw new ProviderError("Responses-compatible providers require a baseUrl.");
+    }
+    const base = this.config.baseUrl ?? "https://api.openai.com/v1";
+    const endpoint = base.endsWith("/responses") ? base : joinUrl(base, "responses");
+    return fetch(endpoint, {
+      method: "POST",
+      redirect: "error",
+      headers: {
+        ...apiKey ? { authorization: `Bearer ${apiKey}` } : {},
+        "content-type": "application/json"
+      },
+      body: JSON.stringify({
+        model: this.config.model,
+        input: messages.flatMap(toResponsesInput),
+        tools: tools.map((tool) => ({
+          type: "function",
+          name: tool.name,
+          description: tool.description,
+          parameters: tool.inputSchema,
+          strict: false
+        })),
+        tool_choice: tools.length ? "auto" : void 0,
+        store: false,
+        stream,
+        max_output_tokens: maxOutputTokens ?? this.config.maxTokens
+      }),
+      ...signal ? { signal } : {}
+    });
+  }
+};
+function toResponsesInput(message2) {
+  if (message2.role === "tool") {
+    return [{
+      type: "function_call_output",
+      call_id: message2.toolCallId,
+      output: message2.content
+    }];
+  }
+  const storedOutput = message2.providerMetadata?.responses?.outputItems;
+  if (message2.role === "assistant" && storedOutput?.length) return storedOutput;
+  if (message2.role === "assistant" && message2.toolCalls?.length) {
+    return [
+      ...message2.content ? [{ type: "message", role: "assistant", content: message2.content }] : [],
+      ...message2.toolCalls.map((call) => ({
+        type: "function_call",
+        call_id: call.id,
+        name: call.name,
+        arguments: JSON.stringify(call.arguments)
+      }))
+    ];
+  }
+  return [{ type: "message", role: message2.role, content: message2.content }];
+}
+function normalizeResponsesResponse(data) {
+  if (data.output !== void 0 && !Array.isArray(data.output)) {
+    throw new ProviderError("Model API returned an invalid Responses output array.");
+  }
+  const output2 = data.output ?? [];
+  if (output2.some((item) => !item || typeof item !== "object" || Array.isArray(item))) {
+    throw new ProviderError("Model API returned an invalid Responses output item.");
+  }
+  const toolCalls = output2.filter((item) => item.type === "function_call").map((item) => ({
+    id: item.call_id ?? item.id ?? randomUUID9(),
+    name: item.name ?? "unknown",
+    arguments: safeJsonArguments(item.arguments)
+  }));
+  const outputText = output2.flatMap((item) => item.type === "message" ? (item.content ?? []).flatMap((part) => part.type === "output_text" && typeof part.text === "string" ? [part.text] : []) : []).join("");
+  return {
+    content: data.output_text ?? outputText,
+    toolCalls,
+    usage: normalizeResponsesUsage(data.usage),
+    ...output2.length ? { providerMetadata: { responses: { outputItems: boundedOutputItems(output2) } } } : {},
+    ...toolCalls.length ? { stopReason: "tool_calls" } : data.incomplete_details?.reason ? { stopReason: data.incomplete_details.reason } : data.status ? { stopReason: data.status } : {}
+  };
+}
+function boundedOutputItems(output2) {
+  if (output2.length > MAX_RESPONSES_OUTPUT_ITEMS) {
+    throw new ProviderError(`Model API returned more than ${MAX_RESPONSES_OUTPUT_ITEMS} Responses output items.`);
+  }
+  const serialized = JSON.stringify(output2);
+  if (new TextEncoder().encode(serialized).byteLength > MAX_RESPONSES_REPLAY_BYTES) {
+    throw new ProviderError("Model API returned Responses replay state larger than the 4 MiB safety limit.");
+  }
+  return JSON.parse(serialized);
+}
+function normalizeResponsesUsage(usage) {
+  return {
+    ...usage?.input_tokens !== void 0 ? { inputTokens: usage.input_tokens } : {},
+    ...usage?.output_tokens !== void 0 ? { outputTokens: usage.output_tokens } : {},
+    ...usage?.input_tokens_details?.cached_tokens !== void 0 ? { cachedInputTokens: usage.input_tokens_details.cached_tokens } : {},
+    ...usage?.output_tokens_details?.reasoning_tokens !== void 0 ? { reasoningTokens: usage.output_tokens_details.reasoning_tokens } : {}
+  };
+}
+function emptyResponsesResult() {
+  return { content: "", toolCalls: [], usage: {} };
+}
+function streamCallKey(chunk) {
+  return chunk.item_id ?? chunk.item?.id ?? `output:${chunk.output_index ?? 0}`;
+}
+
 // src/providers/index.ts
 function createProvider(config) {
   switch (config.provider) {
@@ -6338,13 +6598,17 @@ function createProvider(config) {
     case "gemini":
       return new GeminiProvider(config);
     case "openai":
+      return new OpenAIProvider(config);
     case "compatible":
+      if (config.protocol === "openai-responses") return new ResponsesProvider(config);
+      if (config.protocol === "anthropic-messages") return new AnthropicProvider(config);
+      if (config.protocol === "gemini") throw new Error("Compatible relay connections cannot use the Gemini transport.");
       return new OpenAIProvider(config);
   }
 }
 
 // src/checkpoint/store.ts
-import { createHash as createHash8, randomUUID as randomUUID9 } from "node:crypto";
+import { createHash as createHash8, randomUUID as randomUUID10 } from "node:crypto";
 import { lstat as lstat10, mkdir as mkdir7, readFile as readFile5, readdir as readdir2, unlink as unlink2 } from "node:fs/promises";
 import { basename as basename6, dirname as dirname8, join as join9, relative as relative6, resolve as resolve12 } from "node:path";
 import { z as z4 } from "zod";
@@ -6380,7 +6644,7 @@ var CheckpointStore = class {
     return this.withManagedLease(() => this.captureUnlocked(sessionId, unique4, options));
   }
   async captureUnlocked(sessionId, unique4, options) {
-    const id = `${Date.now().toString(36)}-${randomUUID9()}`;
+    const id = `${Date.now().toString(36)}-${randomUUID10()}`;
     const target = join9(this.directory, sessionId, id);
     const blobDirectory = join9(target, "blobs");
     await this.ensureDirectory();
@@ -6656,7 +6920,7 @@ var HookRunner = class {
 };
 
 // src/session/store.ts
-import { randomUUID as randomUUID10 } from "node:crypto";
+import { randomUUID as randomUUID11 } from "node:crypto";
 import { constants as constants4 } from "node:fs";
 import {
   chmod as chmod6,
@@ -6678,6 +6942,15 @@ var toolCallSchema = z5.object({
   name: z5.string(),
   arguments: z5.record(z5.string(), z5.unknown())
 }).strict();
+var providerMetadataSchema = z5.object({
+  responses: z5.object({
+    outputItems: z5.array(z5.record(z5.string(), z5.unknown())).max(128).superRefine((items, context) => {
+      if (new TextEncoder().encode(JSON.stringify(items)).byteLength > 4 * 1024 * 1024) {
+        context.addIssue({ code: "custom", message: "Responses replay state exceeds 4 MiB" });
+      }
+    })
+  }).strict().optional()
+}).strict();
 var messageSchema = z5.object({
   id: z5.string(),
   role: z5.enum(["system", "user", "assistant", "tool"]),
@@ -6685,7 +6958,8 @@ var messageSchema = z5.object({
   createdAt: z5.string(),
   toolCalls: z5.array(toolCallSchema).optional(),
   toolCallId: z5.string().optional(),
-  name: z5.string().optional()
+  name: z5.string().optional(),
+  providerMetadata: providerMetadataSchema.optional()
 }).strict();
 var taskSchema = z5.object({
   id: z5.string(),
@@ -7121,7 +7395,7 @@ var SessionStore = class {
     const backup = this.backupPathFor(session.id);
     await this.assertManagedFile(target);
     await this.assertManagedFile(backup);
-    const temporary = join10(this.directory, `.${session.id}.${randomUUID10()}.tmp`);
+    const temporary = join10(this.directory, `.${session.id}.${randomUUID11()}.tmp`);
     const data = `${JSON.stringify(session, null, 2)}
 `;
     const handle = await open2(temporary, "wx", 384);
@@ -7139,7 +7413,7 @@ var SessionStore = class {
     }
   }
   async copyBackup(source, target) {
-    const temporary = join10(this.directory, `.${basename7(target)}.${randomUUID10()}.tmp`);
+    const temporary = join10(this.directory, `.${basename7(target)}.${randomUUID11()}.tmp`);
     try {
       await copyFile(source, temporary, constants4.COPYFILE_EXCL);
       await chmod6(temporary, 384);
@@ -7228,7 +7502,7 @@ var SessionStore = class {
   }
 };
 function createSession(options) {
-  const id = options.id ?? randomUUID10();
+  const id = options.id ?? randomUUID11();
   validateId(id);
   const now = (/* @__PURE__ */ new Date()).toISOString();
   return {
@@ -7244,7 +7518,7 @@ function createSession(options) {
     changedFiles: [],
     audit: [],
     contextEpochs: [{
-      id: randomUUID10(),
+      id: randomUUID11(),
       index: 1,
       startedAt: now,
       usage: { inputTokens: 0, outputTokens: 0 }
@@ -9099,7 +9373,7 @@ async function discoverSnapshotFiles(root) {
 }
 
 // src/tools/task.ts
-import { randomUUID as randomUUID11 } from "node:crypto";
+import { randomUUID as randomUUID12 } from "node:crypto";
 import { z as z14 } from "zod";
 var taskSchema2 = z14.object({
   id: z14.string().min(1).optional(),
@@ -9148,7 +9422,7 @@ var taskTool = {
       case "list":
         break;
       case "add":
-        tasks.push({ id: randomUUID11(), title: input2.title, status: input2.status ?? "pending" });
+        tasks.push({ id: randomUUID12(), title: input2.title, status: input2.status ?? "pending" });
         break;
       case "update": {
         const task = tasks.find((item) => item.id === input2.id);
@@ -9165,7 +9439,7 @@ var taskTool = {
       }
       case "replace":
         tasks.splice(0, tasks.length, ...input2.tasks.map((task) => ({
-          id: task.id ?? randomUUID11(),
+          id: task.id ?? randomUUID12(),
           title: task.title,
           status: task.status
         })));
@@ -9179,11 +9453,11 @@ var taskTool = {
 };
 
 // src/tools/task-contract.ts
-import { randomUUID as randomUUID13 } from "node:crypto";
+import { randomUUID as randomUUID14 } from "node:crypto";
 import { z as z15 } from "zod";
 
 // src/agent/task-contract.ts
-import { randomUUID as randomUUID12 } from "node:crypto";
+import { randomUUID as randomUUID13 } from "node:crypto";
 var EXECUTABLE_INTENTS = /* @__PURE__ */ new Set(["debug", "refactor", "test", "implement"]);
 function shouldUseTaskContract(request, intent, existing) {
   if (existing && existing.state !== "satisfied") return true;
@@ -9249,7 +9523,7 @@ function refreshTaskContractState(contract) {
 }
 function criterion(id, description) {
   return {
-    id: `${id}-${randomUUID12().slice(0, 8)}`,
+    id: `${id}-${randomUUID13().slice(0, 8)}`,
     description,
     required: true,
     status: "pending",
@@ -9803,7 +10077,7 @@ var taskContractTool = {
       }
       const now = (/* @__PURE__ */ new Date()).toISOString();
       const criteria = input2.acceptance_criteria.map((item) => ({
-        id: item.id ?? `criterion-${randomUUID13().slice(0, 8)}`,
+        id: item.id ?? `criterion-${randomUUID14().slice(0, 8)}`,
         description: item.description,
         required: item.required ?? true,
         status: "pending",
@@ -10272,7 +10546,7 @@ function escapeAttribute3(value) {
 }
 
 // src/agent/intent-sufficiency.ts
-import { randomUUID as randomUUID14 } from "node:crypto";
+import { randomUUID as randomUUID15 } from "node:crypto";
 function assessIntentSufficiency(request, intent, context) {
   const assessedAt = (/* @__PURE__ */ new Date()).toISOString();
   const uiChoice = explicitUiChoice(request);
@@ -10340,8 +10614,8 @@ function assessment(route, reason, assessedAt, retrievalHits) {
 }
 function clarification(originalRequest, createdAt, reason, question2, options) {
   return {
-    id: randomUUID14(),
-    runId: randomUUID14(),
+    id: randomUUID15(),
+    runId: randomUUID15(),
     createdAt,
     originalRequest: originalRequest.slice(0, 12e4),
     question: question2,
@@ -11594,7 +11868,7 @@ ${resolvedInput.decision}
             breakdown
           });
         }
-        const assistantId = randomUUID15();
+        const assistantId = randomUUID16();
         const response = await this.completeModel(
           messages,
           visibleTools,
@@ -11604,7 +11878,8 @@ ${resolvedInput.decision}
           assistantId
         );
         const assistantMessage = message("assistant", response.content, {
-          ...response.toolCalls.length ? { toolCalls: response.toolCalls } : {}
+          ...response.toolCalls.length ? { toolCalls: response.toolCalls } : {},
+          ...response.providerMetadata ? { providerMetadata: response.providerMetadata } : {}
         });
         assistantMessage.id = assistantId;
         this.session.messages.push(assistantMessage);
@@ -12095,7 +12370,7 @@ ${completeContent}`;
   }
   appendAudit(event) {
     const audit = this.session.audit ?? (this.session.audit = []);
-    audit.push({ id: randomUUID15(), createdAt: (/* @__PURE__ */ new Date()).toISOString(), ...event });
+    audit.push({ id: randomUUID16(), createdAt: (/* @__PURE__ */ new Date()).toISOString(), ...event });
     if (audit.length > 5e3) audit.splice(0, audit.length - 5e3);
   }
   async acceptChangedFiles(paths) {
@@ -12116,7 +12391,7 @@ ${completeContent}`;
     const results = [];
     for (const command2 of this.config.agent.verifyCommands) {
       const call = {
-        id: `verify-${randomUUID15()}`,
+        id: `verify-${randomUUID16()}`,
         name: "shell",
         arguments: { command: command2, cwd: this.workspace.primaryRoot }
       };
@@ -12282,7 +12557,7 @@ ${completeContent}`;
 };
 function message(role, content, extra = {}) {
   return {
-    id: randomUUID15(),
+    id: randomUUID16(),
     role,
     content,
     createdAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -12300,7 +12575,7 @@ function packConversation(systemPrompt, dynamicPrompt, retrievedContext, history
   let used = 0;
   for (let index = groups.length - 1; index >= 0; index -= 1) {
     const group = groups[index] ?? [];
-    const cost = group.reduce((sum, item) => sum + estimateTokens(item.content) + estimateTokens(JSON.stringify(item.toolCalls ?? [])), 0);
+    const cost = group.reduce((sum, item) => sum + estimateTokens(item.content) + estimateTokens(JSON.stringify(item.toolCalls ?? [])) + estimateTokens(JSON.stringify(item.providerMetadata ?? {})), 0);
     if (selected.length && used + cost > budget) break;
     selected.unshift(group);
     used += cost;
@@ -12339,7 +12614,7 @@ function groupMessages(messages) {
   return groups;
 }
 function estimateMessages2(messages) {
-  return messages.reduce((total, item) => total + estimateTokens(item.content) + estimateTokens(JSON.stringify(item.toolCalls ?? [])), 0);
+  return messages.reduce((total, item) => total + estimateTokens(item.content) + estimateTokens(JSON.stringify(item.toolCalls ?? [])) + estimateTokens(JSON.stringify(item.providerMetadata ?? {})), 0);
 }
 function estimateToolDefinitions(tools) {
   return estimateTokens(JSON.stringify(tools));
@@ -12719,7 +12994,7 @@ function integer(value, fallback, min, max) {
 }
 
 // src/agent/delegation.ts
-import { randomUUID as randomUUID17 } from "node:crypto";
+import { randomUUID as randomUUID18 } from "node:crypto";
 import { join as join18 } from "node:path";
 import { z as z19 } from "zod";
 
@@ -12730,6 +13005,8 @@ async function runExternalAgent(request) {
   if (!executable2) throw new Error(`${command2.binary} CLI is not installed or resolves inside the workspace.`);
   const result = await runProcess(executable2.executable, command2.args, {
     cwd: request.workspace,
+    inheritEnv: false,
+    env: externalRuntimeEnvironment(request.runtime, executable2.path),
     timeoutMs: request.timeoutMs ?? 18e4,
     maxOutputBytes: 2e6,
     ...request.signal ? { signal: request.signal } : {}
@@ -12750,6 +13027,35 @@ async function runExternalAgent(request) {
     toolCalls: telemetry.toolCalls
   };
 }
+function externalRuntimeEnvironment(runtime, safePath, environment = process.env) {
+  const allowed = [
+    "HOME",
+    "USERPROFILE",
+    "APPDATA",
+    "LOCALAPPDATA",
+    "XDG_CONFIG_HOME",
+    "XDG_CACHE_HOME",
+    "TMPDIR",
+    "TMP",
+    "TEMP",
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "TERM",
+    "NO_COLOR",
+    "SystemRoot",
+    "WINDIR",
+    "COMSPEC",
+    "PATHEXT"
+  ];
+  if (runtime === "codex") allowed.push("CODEX_HOME");
+  if (runtime === "claude") allowed.push("CLAUDE_CONFIG_DIR");
+  const selected = { PATH: safePath };
+  for (const name of allowed) {
+    if (environment[name] !== void 0) selected[name] = environment[name];
+  }
+  return selected;
+}
 function externalAgentCommand(request) {
   const prompt = request.prompt.slice(0, 6e4);
   switch (request.runtime) {
@@ -12848,7 +13154,7 @@ function numeric(...values) {
 }
 
 // src/agent/team-store.ts
-import { createHash as createHash16, randomUUID as randomUUID16 } from "node:crypto";
+import { createHash as createHash16, randomUUID as randomUUID17 } from "node:crypto";
 import { lstat as lstat18, readFile as readFile17, readdir as readdir7, rm as rm3 } from "node:fs/promises";
 import { join as join16, resolve as resolve18 } from "node:path";
 import { z as z18 } from "zod";
@@ -12942,7 +13248,7 @@ var TeamRunStore = class {
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const manifest = manifestSchema2.parse({
       version: 2,
-      id: randomUUID16(),
+      id: randomUUID17(),
       workspace: this.workspace,
       objective: input2.objective,
       reviewer: input2.reviewer,
@@ -13189,15 +13495,285 @@ function resolveAgentModelRoute(team, parent, profile) {
   const hasDefaults = team?.defaultConnection !== void 0 || team?.defaultModel !== void 0;
   if (!configured && !hasDefaults) return { source: "parent" };
   const connection = configured?.connection ?? (configured?.provider ? void 0 : team?.defaultConnection);
+  const connectionDefaultModel = connection ? team?.connections?.[connection]?.defaultModel : void 0;
   const route = {
     ...configured,
-    model: configured?.model ?? team?.defaultModel ?? parent.model,
+    model: configured?.model ?? connectionDefaultModel ?? team?.defaultModel ?? parent.model,
     ...connection ? { connection } : {}
   };
   if (!route.connection && !route.provider) route.provider = parent.provider;
   return { route, source: configured ? "profile" : "default" };
 }
 
+// src/agent/connection-catalog.ts
+var relayProtocols = ["openai-responses", "openai-chat", "anthropic-messages"];
+function discoverConnectionCatalog(config, environment = process.env) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const [id, connection] of Object.entries(config.agents?.connections ?? {})) {
+    byId.set(id, normalizeProfile(id, connection, "user", environment));
+  }
+  const environmentCatalog = parseEnvironmentConnections(environment);
+  for (const profile of environmentCatalog.profiles) {
+    if (byId.has(profile.id)) {
+      throw new Error(`Connection ${profile.id} is defined in both user configuration and SKEIN_CONNECTIONS.`);
+    }
+    byId.set(profile.id, profile);
+  }
+  const defaultConnection = config.agents?.defaultConnection ?? environmentCatalog.defaultConnection;
+  if (defaultConnection && !byId.has(defaultConnection)) {
+    throw new Error(`Default connection ${defaultConnection} is not present in the discovered connection catalog.`);
+  }
+  return {
+    profiles: [...byId.values()].sort((left, right) => left.id.localeCompare(right.id)),
+    ...defaultConnection ? { defaultConnection } : {}
+  };
+}
+function parseEnvironmentConnections(environment = process.env) {
+  const rawIds = environment.SKEIN_CONNECTIONS?.split(",").map((value) => value.trim()).filter(Boolean) ?? [];
+  const ids = /* @__PURE__ */ new Set();
+  const suffixes = /* @__PURE__ */ new Map();
+  for (const id of rawIds) {
+    if (!/^[a-z][a-z0-9_-]{0,63}$/u.test(id)) {
+      throw new Error(`Invalid SKEIN_CONNECTIONS id ${JSON.stringify(id)}; use lowercase shell-safe names.`);
+    }
+    if (ids.has(id)) throw new Error(`Duplicate SKEIN_CONNECTIONS id ${id}.`);
+    ids.add(id);
+    const suffix = id.toUpperCase().replace(/-/gu, "_");
+    const collided = suffixes.get(suffix);
+    if (collided) {
+      throw new Error(`Connection ids ${collided} and ${id} collide after environment normalization (${suffix}).`);
+    }
+    suffixes.set(suffix, id);
+  }
+  const profiles = rawIds.map((id) => {
+    const suffix = id.toUpperCase().replace(/-/gu, "_");
+    const prefix = `SKEIN_CONNECTION_${suffix}_`;
+    const provider = parseProviderField(environment[`${prefix}PROVIDER`], `${prefix}PROVIDER`);
+    const protocol = parseProtocolField(environment[`${prefix}PROTOCOL`], provider, `${prefix}PROTOCOL`);
+    const baseUrl = optionalUrl(environment[`${prefix}BASE_URL`], `${prefix}BASE_URL`);
+    const modelsBaseUrl = optionalUrl(environment[`${prefix}MODELS_BASE_URL`], `${prefix}MODELS_BASE_URL`);
+    const apiKeyEnv = optionalEnvironmentName(environment[`${prefix}API_KEY_ENV`], `${prefix}API_KEY_ENV`);
+    const authValue = environment[`${prefix}AUTH`]?.trim().toLowerCase();
+    if (authValue && authValue !== "env" && authValue !== "none") {
+      throw new Error(`${prefix}AUTH must be env or none.`);
+    }
+    if (authValue === "none" && apiKeyEnv) {
+      throw new Error(`${prefix}AUTH=none cannot be combined with ${prefix}API_KEY_ENV.`);
+    }
+    if (authValue === "env" && !apiKeyEnv) {
+      throw new Error(`${prefix}AUTH=env requires ${prefix}API_KEY_ENV.`);
+    }
+    const label = environment[`${prefix}LABEL`]?.trim();
+    const defaultModel = environment[`${prefix}MODEL`]?.trim();
+    const config = {
+      provider,
+      protocol,
+      ...label ? { label } : {},
+      ...baseUrl ? { baseUrl } : {},
+      ...modelsBaseUrl ? { modelsBaseUrl } : {},
+      ...defaultModel ? { defaultModel } : {},
+      ...authValue === "none" ? { auth: { type: "none" } } : apiKeyEnv ? { auth: { type: "env", name: apiKeyEnv } } : {}
+    };
+    return normalizeProfile(id, config, "environment", environment);
+  });
+  const defaultConnection = environment.SKEIN_DEFAULT_CONNECTION?.trim();
+  if (defaultConnection && !ids.has(defaultConnection)) {
+    throw new Error(`SKEIN_DEFAULT_CONNECTION references undiscovered connection ${defaultConnection}.`);
+  }
+  return { profiles, ...defaultConnection ? { defaultConnection } : {} };
+}
+function planConnectionSelection(catalog, environment = process.env, explicitConnection) {
+  if (explicitConnection) {
+    const selected = catalog.profiles.find((profile) => profile.id === explicitConnection);
+    if (!selected) throw new Error(`Unknown connection ${explicitConnection}. Use ${catalog.profiles.map(({ id }) => id).join(", ") || "a configured name"}.`);
+    return { kind: "selected", profile: selected };
+  }
+  if (catalog.defaultConnection) {
+    const selected = catalog.profiles.find((profile) => profile.id === catalog.defaultConnection);
+    if (!selected) throw new Error(`Default connection ${catalog.defaultConnection} is unavailable.`);
+    return { kind: "selected", profile: selected };
+  }
+  const complete = catalog.profiles.filter((profile) => connectionIssues(profile, environment).length === 0);
+  if (complete.length === 1) return { kind: "selected", profile: complete[0] };
+  if (complete.length > 1) return { kind: "ambiguous", profiles: complete };
+  return { kind: "legacy" };
+}
+function resolveConnectionModel(current, profile, overrides = {}, environment = process.env) {
+  const issues = connectionIssues(profile, environment);
+  if (issues.length) throw new Error(`Connection ${profile.id} is incomplete: ${issues.join("; ")}`);
+  const apiKey = profile.auth.type === "env" ? environment[profile.auth.name] : void 0;
+  const model = {
+    provider: profile.provider,
+    protocol: profile.protocol,
+    model: overrides.model ?? profile.defaultModel ?? defaultModelForProvider(profile.provider),
+    ...current.temperature !== void 0 ? { temperature: current.temperature } : {},
+    ...current.maxTokens !== void 0 ? { maxTokens: current.maxTokens } : {},
+    ...profile.baseUrl ? { baseUrl: profile.baseUrl } : {},
+    ...apiKey ? { apiKey } : {}
+  };
+  return { model, activeConnection: connectionRuntimeInfo(profile, environment) };
+}
+function connectionRuntimeCatalog(catalog, environment = process.env) {
+  return {
+    ...catalog.defaultConnection ? { defaultConnection: catalog.defaultConnection } : {},
+    profiles: catalog.profiles.map((profile) => connectionRuntimeInfo(profile, environment))
+  };
+}
+function connectionRuntimeInfo(profile, environment = process.env) {
+  const issues = connectionIssues(profile, environment);
+  const authStatus = profile.auth.type === "none" ? "none" : environment[profile.auth.name] ? "configured" : "missing";
+  return {
+    id: profile.id,
+    ...profile.label ? { label: profile.label } : {},
+    provider: profile.provider,
+    protocol: profile.protocol,
+    source: profile.source,
+    endpoint: redactConnectionEndpoint(profile.baseUrl),
+    modelsEndpoint: redactConnectionEndpoint(profile.modelsBaseUrl ?? profile.baseUrl),
+    ...profile.defaultModel ? { defaultModel: profile.defaultModel } : {},
+    authType: profile.auth.type,
+    authStatus,
+    complete: issues.length === 0,
+    issues
+  };
+}
+function legacyConnectionRuntimeInfo(model) {
+  const remoteCompatibleMissingCredential = model.provider === "compatible" && Boolean(model.baseUrl) && !isLoopbackEndpoint2(model.baseUrl) && !model.apiKey;
+  const issues = [
+    ...model.provider === "compatible" && !model.baseUrl ? ["compatible provider requires base URL"] : [],
+    ...remoteCompatibleMissingCredential ? ["remote compatible provider credential is not configured"] : [],
+    ...model.provider !== "compatible" && !model.apiKey ? ["provider credential is not configured"] : []
+  ];
+  const authExpected = model.provider !== "compatible" || remoteCompatibleMissingCredential || Boolean(model.apiKey);
+  return {
+    id: "legacy",
+    provider: model.provider,
+    protocol: model.protocol ?? defaultProtocol(model.provider),
+    source: "legacy",
+    endpoint: redactConnectionEndpoint(model.baseUrl),
+    modelsEndpoint: redactConnectionEndpoint(model.baseUrl),
+    defaultModel: model.model,
+    authType: authExpected ? "env" : "none",
+    authStatus: model.apiKey ? "configured" : authExpected ? "missing" : "none",
+    complete: issues.length === 0,
+    issues
+  };
+}
+function connectionCredentialReference(profile) {
+  if (profile.auth.type === "env") return `env:${profile.auth.name}`;
+  return "none";
+}
+function connectionEnvironmentTypos(environment = process.env) {
+  return [
+    { name: "SEKIN_API", replacement: "SKEIN_API_KEY" },
+    { name: "SKEIN_BASEURL", replacement: "SKEIN_BASE_URL" }
+  ].filter(({ name }) => Object.hasOwn(environment, name));
+}
+function connectionIssues(profile, environment = process.env) {
+  const issues = [];
+  if (profile.provider !== "compatible") {
+    issues.push("named primary connections support compatible relay providers only");
+  }
+  if (profile.provider === "compatible" && !profile.baseUrl) issues.push("compatible provider requires base URL");
+  if (profile.provider === "compatible" && !relayProtocols.includes(profile.protocol)) {
+    issues.push("relay transport must use openai-responses, openai-chat, or anthropic-messages");
+  }
+  if (profile.protocol === "anthropic-messages" && !profile.modelsBaseUrl) {
+    issues.push("anthropic relay transport requires an explicit models base URL");
+  }
+  if (profile.auth.type === "env" && !environment[profile.auth.name]) {
+    issues.push(`credential environment ${profile.auth.name} is not set`);
+  }
+  if (!profile.explicitAuth && profile.provider !== "compatible" && profile.baseUrl && !isOfficialProviderEndpoint(profile.provider, profile.baseUrl)) {
+    issues.push("custom provider endpoint requires explicit connection auth");
+  }
+  return issues;
+}
+function normalizeProfile(id, connection, source, environment) {
+  const explicitAuth = Boolean(connection.auth || connection.apiKeyEnv);
+  const auth = connection.auth ?? (connection.apiKeyEnv ? { type: "env", name: connection.apiKeyEnv } : defaultAuth(connection.provider, connection.baseUrl, environment));
+  return {
+    id,
+    ...connection.label ? { label: connection.label } : {},
+    provider: connection.provider,
+    protocol: connection.protocol ?? defaultProtocol(connection.provider),
+    ...connection.baseUrl ? { baseUrl: connection.baseUrl } : {},
+    ...connection.modelsBaseUrl ? { modelsBaseUrl: connection.modelsBaseUrl } : {},
+    ...connection.defaultModel ? { defaultModel: connection.defaultModel } : {},
+    auth,
+    source,
+    explicitAuth
+  };
+}
+function defaultAuth(provider, baseUrl, environment) {
+  if (provider === "compatible" && baseUrl && isLoopbackEndpoint2(baseUrl)) return { type: "none" };
+  if (provider === "compatible") {
+    return { type: "env", name: environment.SKEIN_API_KEY ? "SKEIN_API_KEY" : environment.MOSAIC_API_KEY ? "MOSAIC_API_KEY" : "SKEIN_API_KEY" };
+  }
+  return { type: "env", name: providerApiKeyEnv(provider) };
+}
+function defaultProtocol(provider) {
+  if (provider === "anthropic") return "anthropic-messages";
+  if (provider === "gemini") return "gemini";
+  return "openai-chat";
+}
+function parseProviderField(value, name) {
+  const provider = value?.trim().toLowerCase() || "compatible";
+  if (provider !== "compatible") throw new Error(`${name} must be compatible for named relay connections.`);
+  return "compatible";
+}
+function parseProtocolField(value, provider, name) {
+  if (!value?.trim()) return provider === "compatible" ? "openai-responses" : defaultProtocol(provider);
+  const protocol = value.trim().toLowerCase();
+  if (!relayProtocols.includes(protocol)) throw new Error(`${name} must be openai-responses, openai-chat, or anthropic-messages.`);
+  return protocol;
+}
+function optionalUrl(value, name) {
+  if (!value?.trim()) return void 0;
+  try {
+    const url = new URL(value.trim());
+    if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error("protocol");
+    if (url.username || url.password || url.search || url.hash) throw new Error("unsafe URL components");
+    return url.toString().replace(/\/$/u, "");
+  } catch {
+    throw new Error(`${name} must be an http or https URL.`);
+  }
+}
+function optionalEnvironmentName(value, name) {
+  if (!value?.trim()) return void 0;
+  const normalized = value.trim();
+  if (!/^[A-Z][A-Z0-9_]{0,127}$/u.test(normalized)) {
+    throw new Error(`${name} must name an uppercase environment variable.`);
+  }
+  return normalized;
+}
+function isOfficialProviderEndpoint(provider, endpoint) {
+  const official = {
+    openai: "https://api.openai.com/v1",
+    anthropic: "https://api.anthropic.com/v1",
+    gemini: "https://generativelanguage.googleapis.com/v1beta"
+  };
+  return endpoint.replace(/\/+$/u, "") === official[provider];
+}
+function isLoopbackEndpoint2(endpoint) {
+  try {
+    const hostname = new URL(endpoint).hostname.replace(/^\[|\]$/gu, "").toLowerCase();
+    return hostname === "localhost" || hostname.endsWith(".localhost") || hostname === "::1" || /^127(?:\.\d{1,3}){3}$/u.test(hostname);
+  } catch {
+    return false;
+  }
+}
+function redactConnectionEndpoint(endpoint) {
+  if (!endpoint) return "provider default";
+  try {
+    const url = new URL(endpoint);
+    const authentication = url.username || url.password ? "<redacted>@" : "";
+    return `${url.protocol}//${authentication}${url.host}${url.pathname}${url.search ? "?<redacted>" : ""}${url.hash ? "#<redacted>" : ""}`;
+  } catch {
+    return "configured endpoint";
+  }
+}
+
 // src/agent/writer-lane.ts
 import { createHash as createHash17 } from "node:crypto";
 import { lstat as lstat19, mkdtemp, realpath as realpath7, rm as rm4 } from "node:fs/promises";
@@ -13756,7 +14332,7 @@ var DelegationManager = class {
         maxReviewRounds: 0
       });
       await emit?.({ type: "team_start", id: board.id, objective: task });
-      const writerId = randomUUID17();
+      const writerId = randomUUID18();
       await emit?.({ type: "agent_queued", id: writerId, profile: profile.name, task, phase: "write" });
       const draft = await this.writerLane.createDraft(
         Math.min(this.team.maxWriterPatchBytes ?? 6e4, 12e4),
@@ -14126,7 +14702,7 @@ You are the only writer inside a disposable worktree. Make only the bounded requ
     const reviewer = reviewerOverride ?? this.team.reviewerProfile ?? "reviewer";
     const rounds = Math.max(0, this.team.maxReviewRounds ?? 1);
     const board = await this.teamStore?.create({ objective, reviewer, maxReviewRounds: rounds });
-    const runId = board?.id ?? randomUUID17();
+    const runId = board?.id ?? randomUUID18();
     await emit?.({ type: "team_start", id: runId, objective });
     try {
       let results = await this.runBatch(board?.id, tasks, "work", emit, signal);
@@ -14184,7 +14760,7 @@ ${review.summary}`,
     }
   }
   async runBatch(runId, tasks, phase, emit, signal) {
-    const scheduled = tasks.map((task) => ({ id: randomUUID17(), task }));
+    const scheduled = tasks.map((task) => ({ id: randomUUID18(), task }));
     for (const item of scheduled) {
       await emit?.({ type: "agent_queued", id: item.id, profile: item.task.profile, task: item.task.task, phase });
     }
@@ -14293,12 +14869,12 @@ Start the response with exactly VERDICT: ACCEPT when the evidence is sufficient,
     });
   }
   async peerMessage(runId, from, to, content, emit) {
-    const id = randomUUID17();
+    const id = randomUUID18();
     if (runId) await this.teamStore?.recordMessage(runId, { id, from, to, content });
     await emit?.({ type: "agent_message", id, from, to, content });
   }
   async runOne(task, phase, emit, signal, retryOf, scheduledId) {
-    const id = scheduledId ?? randomUUID17();
+    const id = scheduledId ?? randomUUID18();
     const profile = this.options.profiles.get(task.profile);
     const configuredRoute = this.team.routes?.[task.profile];
     const budgetMode = configuredRoute?.budgetMode ?? this.team.budgetMode ?? "observe";
@@ -14582,11 +15158,17 @@ function modelConfigFromRoute(route, parent, environment, connections) {
   if (!provider) throw new Error("Agent route requires a provider or a valid connection.");
   if (!route.model) throw new Error("Agent route requires a model or a team default model.");
   const baseUrl = route.baseUrl ?? connection?.baseUrl;
-  const apiKeyEnv = route.apiKeyEnv ?? connection?.apiKeyEnv;
+  const connectionAuth = connection?.auth;
+  const apiKeyEnv = route.apiKeyEnv ?? connection?.apiKeyEnv ?? (connectionAuth?.type === "env" ? connectionAuth.name : void 0);
   const inheritedKey = provider === parent.provider && baseUrl === parent.baseUrl ? parent.apiKey : void 0;
-  const apiKey = apiKeyEnv ? environment[apiKeyEnv] : inheritedKey ?? defaultProviderApiKey(provider, environment);
+  if (!apiKeyEnv && connectionAuth?.type !== "none" && !inheritedKey && provider !== "compatible" && baseUrl && !isOfficialProviderEndpoint(provider, baseUrl)) {
+    throw new Error("Custom provider endpoints require explicit connection auth.");
+  }
+  const apiKey = connectionAuth?.type === "none" ? void 0 : apiKeyEnv ? environment[apiKeyEnv] : inheritedKey ?? defaultProviderApiKey(provider, environment);
+  if (apiKeyEnv && !apiKey) throw new Error(`Agent connection credential environment ${apiKeyEnv} is not set.`);
   return {
     provider,
+    ...connection?.protocol ? { protocol: connection.protocol } : {},
     model: route.model,
     ...baseUrl ? { baseUrl } : {},
     ...apiKey ? { apiKey } : {},
@@ -14680,22 +15262,44 @@ async function mapConcurrent(values, concurrency, operation) {
 }
 
 // src/agent/model-catalog.ts
+import { createHash as createHash18 } from "node:crypto";
+var MODEL_CATALOG_TTL_MS = 15 * 60 * 1e3;
+var MODEL_CATALOG_CACHE_LIMIT = 32;
+var modelCatalogCache = /* @__PURE__ */ new Map();
 async function listConnectionModels(connection, environment = process.env) {
   if (connection.provider !== "compatible" && connection.provider !== "openai") {
     throw new Error(`Model discovery is currently supported for compatible and openai connections, not ${connection.provider}.`);
   }
-  const baseUrl = connection.baseUrl ?? "https://api.openai.com/v1";
-  const endpoint = `${baseUrl.replace(/\/+$/u, "")}/models`;
-  const apiKey = connection.apiKeyEnv ? environment[connection.apiKeyEnv] : defaultConnectionApiKey(connection.provider, environment);
+  if (connection.protocol === "anthropic-messages" && !connection.modelsBaseUrl) {
+    throw new Error("Anthropic relay model discovery requires an explicit modelsBaseUrl.");
+  }
+  const baseUrl = connection.modelsBaseUrl ?? connection.baseUrl ?? "https://api.openai.com/v1";
+  const endpoint = baseUrl.endsWith("/models") ? baseUrl : `${baseUrl.replace(/\/+$/u, "")}/models`;
+  const apiKey = connectionApiKey(connection, environment);
+  const cacheKey = catalogFingerprint(endpoint, connection.auth?.type ?? (apiKey ? "legacy-env" : "none"), apiKey);
+  const cached = modelCatalogCache.get(cacheKey);
+  const now = Date.now();
+  if (cached && cached.expiresAt > now) {
+    touchCacheEntry(cacheKey, cached);
+    return copyModels(cached.models);
+  }
   const response = await fetch(endpoint, {
+    redirect: "error",
     headers: {
       accept: "application/json",
-      ...apiKey ? { authorization: `Bearer ${apiKey}` } : {}
+      ...apiKey ? { authorization: `Bearer ${apiKey}` } : {},
+      ...cached?.etag ? { "if-none-match": cached.etag } : {}
     },
     signal: AbortSignal.timeout(15e3)
   });
+  if (response.status === 304 && cached) {
+    const refreshed = { ...cached, lastSuccessAt: now, expiresAt: now + MODEL_CATALOG_TTL_MS };
+    touchCacheEntry(cacheKey, refreshed);
+    return copyModels(refreshed.models);
+  }
+  if (response.status === 401 || response.status === 403) modelCatalogCache.delete(cacheKey);
   const body = await response.text();
-  if (!response.ok) throw new Error(`Model discovery failed (${response.status}): ${body.replace(/\s+/gu, " ").slice(0, 240)}`);
+  if (!response.ok) throw new Error(`Model discovery failed (${response.status}).`);
   if (body.length > 2e6) throw new Error("Model discovery response is too large.");
   let parsed;
   try {
@@ -14703,17 +15307,62 @@ async function listConnectionModels(connection, environment = process.env) {
   } catch {
     throw new Error("Model discovery returned invalid JSON.");
   }
-  const data = parsed && typeof parsed === "object" && Array.isArray(parsed.data) ? parsed.data : Array.isArray(parsed) ? parsed : [];
-  return data.flatMap((value) => {
-    if (!value || typeof value !== "object" || typeof value.id !== "string") return [];
+  const data = parsed && typeof parsed === "object" && Array.isArray(parsed.data) ? parsed.data : parsed && typeof parsed === "object" && Array.isArray(parsed.models) ? parsed.models : Array.isArray(parsed) ? parsed : [];
+  const models = data.flatMap((value) => {
+    if (!value || typeof value !== "object") return [];
+    const candidate = value;
+    const id = typeof candidate.id === "string" ? candidate.id : typeof candidate.model_id === "string" ? candidate.model_id : void 0;
+    if (!id) return [];
     const item = value;
     const contextLength = typeof item.context_length === "number" ? item.context_length : typeof item.contextLength === "number" ? item.contextLength : void 0;
     return [{
-      id: item.id,
+      id,
       ...typeof item.owned_by === "string" ? { ownedBy: item.owned_by } : typeof item.ownedBy === "string" ? { ownedBy: item.ownedBy } : {},
       ...contextLength !== void 0 ? { contextLength } : {}
     }];
   }).sort((left, right) => left.id.localeCompare(right.id));
+  touchCacheEntry(cacheKey, {
+    models,
+    ...response.headers.get("etag") ? { etag: response.headers.get("etag") } : {},
+    lastSuccessAt: now,
+    expiresAt: now + MODEL_CATALOG_TTL_MS
+  });
+  trimModelCatalogCache();
+  return copyModels(models);
+}
+function catalogFingerprint(endpoint, authType, apiKey) {
+  return createHash18("sha256").update(endpoint).update("\0").update(authType).update("\0").update(apiKey ?? "").digest("hex");
+}
+function touchCacheEntry(key, entry) {
+  modelCatalogCache.delete(key);
+  modelCatalogCache.set(key, entry);
+}
+function trimModelCatalogCache() {
+  while (modelCatalogCache.size > MODEL_CATALOG_CACHE_LIMIT) {
+    const oldest = modelCatalogCache.keys().next().value;
+    if (!oldest) return;
+    modelCatalogCache.delete(oldest);
+  }
+}
+function copyModels(models) {
+  return models.map((model) => ({ ...model }));
+}
+function connectionApiKey(connection, environment) {
+  if (connection.auth?.type === "env") {
+    const value = environment[connection.auth.name];
+    if (!value) throw new Error(`Connection credential environment ${connection.auth.name} is not set.`);
+    return value;
+  }
+  if (connection.auth?.type === "none") return void 0;
+  if (connection.apiKeyEnv) {
+    const value = environment[connection.apiKeyEnv];
+    if (!value) throw new Error(`Connection credential environment ${connection.apiKeyEnv} is not set.`);
+    return value;
+  }
+  if (connection.provider === "openai" && connection.baseUrl && connection.baseUrl.replace(/\/+$/u, "") !== "https://api.openai.com/v1") {
+    throw new Error("Custom OpenAI model endpoints require explicit connection auth.");
+  }
+  return defaultConnectionApiKey(connection.provider, environment);
 }
 function defaultConnectionApiKey(provider, environment) {
   if (provider === "openai") return environment.OPENAI_API_KEY;
@@ -14731,33 +15380,54 @@ function createAgentConnectionSetup(input2) {
   if (!defaultModel || defaultModel.length > 256) {
     throw new Error("Default model must contain between 1 and 256 characters.");
   }
-  const baseUrl = input2.baseUrl?.trim() || void 0;
-  if (input2.provider === "compatible" && !baseUrl) {
-    throw new Error("OpenAI-compatible connections require a base URL.");
+  if (input2.provider !== "compatible") {
+    throw new Error("Named primary connections support third-party compatible relays only.");
   }
-  if (baseUrl) {
-    let protocol;
+  const protocol = input2.protocol ?? "openai-responses";
+  if (protocol === "gemini") throw new Error("Relay protocol must use openai-responses, openai-chat, or anthropic-messages.");
+  const baseUrl = input2.baseUrl?.trim() || void 0;
+  if (!baseUrl) throw new Error("Compatible relay connections require an inference base URL.");
+  const modelsBaseUrl = input2.modelsBaseUrl?.trim() || void 0;
+  if (protocol === "anthropic-messages" && !modelsBaseUrl) {
+    throw new Error("Anthropic relay connections require a separate models base URL.");
+  }
+  for (const [label, value] of [["Connection base URL", baseUrl], ["Models base URL", modelsBaseUrl]]) {
+    if (!value) continue;
+    let url;
     try {
-      protocol = new URL(baseUrl).protocol;
+      url = new URL(value);
     } catch {
-      throw new Error("Connection base URL must be a valid http or https URL.");
+      throw new Error(`${label} must be a valid http or https URL.`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      throw new Error(`${label} must use http or https.`);
     }
-    if (protocol !== "http:" && protocol !== "https:") {
-      throw new Error("Connection base URL must use http or https.");
+    if (url.username || url.password || url.search || url.hash) {
+      throw new Error(`${label} cannot contain credentials, query parameters, or fragments.`);
     }
   }
   const apiKeyEnv = input2.apiKeyEnv?.trim() || void 0;
   if (apiKeyEnv && !/^[A-Z][A-Z0-9_]{0,127}$/.test(apiKeyEnv)) {
     throw new Error("Credential environment variable must use uppercase letters, numbers, and underscores.");
   }
+  const auth = input2.auth ?? (apiKeyEnv ? "env" : "none");
+  if (auth === "env" && !apiKeyEnv) {
+    throw new Error("Environment authentication requires a credential environment variable.");
+  }
+  if (auth === "none" && apiKeyEnv) {
+    throw new Error("Unauthenticated connections cannot include a credential environment variable.");
+  }
   return {
     defaultConnection: name,
     defaultModel,
     connections: {
       [name]: {
         provider: input2.provider,
-        ...baseUrl ? { baseUrl } : {},
-        ...apiKeyEnv ? { apiKeyEnv } : {}
+        protocol,
+        defaultModel,
+        baseUrl,
+        ...modelsBaseUrl ? { modelsBaseUrl } : {},
+        auth: auth === "env" ? { type: "env", name: apiKeyEnv } : { type: "none" }
       }
     }
   };
@@ -14945,6 +15615,22 @@ async function runDoctor(config, options = {}) {
       required: false
     });
   }
+  for (const typo of connectionEnvironmentTypos()) {
+    checks.push({
+      name: `Environment: ${typo.name}`,
+      ok: false,
+      detail: `unsupported spelling; use ${typo.replacement} (value was not read or printed)`,
+      required: false
+    });
+  }
+  for (const connection of config.connectionCatalog?.profiles ?? []) {
+    checks.push({
+      name: `Connection: ${connection.id}`,
+      ok: connection.complete,
+      detail: `${connection.source} ${connection.provider}/${connection.protocol}; ${connection.authType}/${connection.authStatus}; inference ${connection.endpoint}; models ${connection.modelsEndpoint}${connection.issues.length ? `; ${connection.issues.join("; ")}` : ""}`,
+      required: false
+    });
+  }
   const nodeOk = supportsNodeVersion(process.versions.node);
   checks.push({
     name: "Node.js",
@@ -15244,6 +15930,7 @@ var HeadlessReporter = class {
       process.stdout.write(`${JSON.stringify({
         type: "session",
         ...outcome2,
+        ...this.options.connection ? { connection: this.options.connection } : {},
         session: sessionSummary(session)
       })}
 `);
@@ -15253,6 +15940,7 @@ var HeadlessReporter = class {
       process.stdout.write(`${JSON.stringify({
         type: "result",
         ...outcome2,
+        ...this.options.connection ? { connection: this.options.connection } : {},
         response: this.finalResponse,
         session: sessionSummary(session),
         ...completion ? { completion } : {},
@@ -15274,6 +15962,13 @@ var HeadlessReporter = class {
 ${this.glyphs.meta} ${session.changedFiles.length} changed files ${this.glyphs.separator} ${usage.toLocaleString()} tokens (${usageLabel}) ${this.glyphs.separator} session ${session.id.slice(0, 8)}
 `
       ));
+      if (this.options.connection) {
+        const connection = this.options.connection;
+        process.stderr.write(this.paint.dim(
+          `${this.glyphs.meta} connection @${connection.id} ${this.glyphs.separator} ${connection.protocol} ${this.glyphs.separator} ${connection.source} ${this.glyphs.separator} ${connection.authType}/${connection.authStatus} ${this.glyphs.separator} inference ${connection.endpoint} ${this.glyphs.separator} models ${connection.modelsEndpoint}
+`
+        ));
+      }
     }
     return outcome2;
   }
@@ -15285,6 +15980,7 @@ ${this.glyphs.meta} ${session.changedFiles.length} changed files ${this.glyphs.s
         type: "final",
         ...outcome2,
         error: message2,
+        ...this.options.connection ? { connection: this.options.connection } : {},
         ...session ? { session: sessionSummary(session) } : {}
       })}
 `);
@@ -15295,6 +15991,7 @@ ${this.glyphs.meta} ${session.changedFiles.length} changed files ${this.glyphs.s
         type: "result",
         ...outcome2,
         error: message2,
+        ...this.options.connection ? { connection: this.options.connection } : {},
         ...session ? { session: sessionSummary(session) } : {}
       }, null, 2)}
 `);
@@ -16206,7 +16903,7 @@ function Header({ config, askMode, planMode = false, width = 80, glyphMode = "au
   const brand = `${glyphs.brand} ${PRODUCT_NAME.toUpperCase()}`;
   const modeLabel = `${glyphs.activity} ${mode}`;
   const separator = ` ${glyphs.separator} `;
-  const model = sanitizeInlineTerminalText(`${config.model.provider}/${config.model.model}`);
+  const model = sanitizeInlineTerminalText(`${config.activeConnection && config.activeConnection.source !== "legacy" ? `@${config.activeConnection.id} ` : ""}${config.model.provider}/${config.model.model}`);
   const repository = sanitizeInlineTerminalText(basename11(root) || root);
   const minimum2 = `${brand} ${modeLabel}`;
   const withRepository = `${brand}${separator}${repository}${separator}${modeLabel}`;
@@ -19250,10 +19947,19 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
         return true;
       }
       const routes = Object.values(config.agents?.routes ?? {});
-      const connections = Object.entries(config.agents?.connections ?? {});
-      appendList("Model connections", connections.length ? connections.map(([name, connection]) => ({
-        label: `${name}  ${connection.provider}`,
-        detail: `${redactEndpoint(connection.baseUrl)}${separator}${connection.apiKeyEnv ? `env:${connection.apiKeyEnv}` : "provider default environment"}${separator}${routes.filter((route) => route.connection === name).length} explicit routes${config.agents?.defaultConnection === name ? `${separator}team default` : ""}`
+      const connections = config.connectionCatalog?.profiles ?? [];
+      appendList("Model connections", connections.length ? connections.map((connection) => ({
+        label: `${connection.id}  ${connection.provider}  ${connection.source}`,
+        detail: [
+          ...config.activeConnection?.id === connection.id ? ["active"] : [],
+          ...config.connectionCatalog?.defaultConnection === connection.id ? ["default"] : [],
+          `${connection.authType}/${connection.authStatus}`,
+          connection.protocol,
+          `inference ${connection.endpoint}`,
+          `models ${connection.modelsEndpoint}`,
+          `${routes.filter((route) => route.connection === connection.id).length} explicit routes`
+        ].join(separator),
+        tone: connection.complete ? "success" : "warning"
       })) : [{ label: "No named model connections configured.", detail: `Run ${PRODUCT_COMMAND} agents setup before starting another session.` }]);
       return true;
     }
@@ -19890,7 +20596,7 @@ function SkeinApp({ runner, config, extensions, initialPrompt, askMode = false,
   const mcpServers = extensions?.mcpStatus() ?? [];
   const memoryStats = extensions?.memoryStats();
   const workspacePanelStatus = workspaceReadiness ? {
-    model: `${config.model.provider}/${config.model.model}`,
+    model: `${config.activeConnection && config.activeConnection.source !== "legacy" ? `@${config.activeConnection.id} ` : ""}${config.model.provider}/${config.model.model}`,
     mode: interactionMode,
     context: workspaceReadiness.files ? "ready" : "empty",
     files: workspaceReadiness.files,
@@ -20566,19 +21272,16 @@ var build_default = TextInput;
 
 // src/ui/onboarding.tsx
 import { jsx as jsx5, jsxs as jsxs5 } from "react/jsx-runtime";
-var officialProviders = [
-  { provider: "openai", label: "OpenAI API", detail: "Native API protocol \xB7 API key" },
-  { provider: "anthropic", label: "Anthropic API", detail: "Messages API \xB7 API key" },
-  { provider: "gemini", label: "Google Gemini API", detail: "generateContent API \xB7 API key" }
-];
-var methods = [
-  { value: "official", label: "Provider API key", detail: "OpenAI, Anthropic, or Gemini \xB7 direct billing" },
-  { value: "relay", label: "Compatible endpoint", detail: "Local server or relay \xB7 protocol chosen explicitly" }
+var relayProtocols2 = [
+  { value: "openai-responses", label: "OpenAI Responses", detail: "Recommended \xB7 /responses \xB7 stateless history replay" },
+  { value: "openai-chat", label: "OpenAI Chat Completions", detail: "Compatibility \xB7 /chat/completions" },
+  { value: "anthropic-messages", label: "Anthropic Messages", detail: "Compatibility \xB7 Anthropic SDK-style base URL" }
 ];
-var relayProtocols = [
-  { value: "openai-compatible", label: "OpenAI-compatible", detail: "Chat Completions \xB7 Bearer key" },
-  { value: "anthropic-compatible", label: "Anthropic-compatible", detail: "Messages API \xB7 x-api-key" }
+var authMethods = [
+  { value: "env", label: "Environment variable", detail: "Recommended \xB7 only the variable name is saved" },
+  { value: "none", label: "No authentication", detail: "For trusted keyless relays or local servers" }
 ];
+var DEFAULT_CONNECTION_NAME = "primary-relay";
 var forbiddenDirectionControls = /[\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/u;
 var directionControls = /[\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/gu;
 var inputControl = /[\u0000-\u001f\u007f-\u009f]/u;
@@ -20588,18 +21291,16 @@ function needsFirstRunOnboarding(config) {
 }
 function createOnboardingState(config) {
   return {
-    step: "method",
+    step: "relay-protocol",
     history: [],
     selected: 0,
     draft: {
-      method: void 0,
-      provider: void 0,
       relayProtocol: void 0,
       baseUrl: config.model.baseUrl ?? "",
-      model: config.model.model,
-      // Never import a provider environment key into a relay draft. The user
-      // must deliberately provide the credential for the selected transport.
-      apiKey: ""
+      modelsBaseUrl: "",
+      model: config.model.provider === "compatible" ? config.model.model : "default",
+      auth: void 0,
+      apiKeyEnv: "SKEIN_API_KEY"
     },
     error: void 0
   };
@@ -20662,78 +21363,58 @@ function validateRelayBaseUrl(value) {
     return { ok: false, error: "Remote relays must use HTTPS; HTTP is allowed only for loopback." };
   }
   const path = url.pathname.replace(/\/+$/u, "").toLocaleLowerCase();
-  if (path.endsWith("/chat/completions") || path.endsWith("/messages")) {
-    return { ok: false, error: "Enter the API base URL, not the final /chat/completions or /messages endpoint." };
+  if (path.endsWith("/responses") || path.endsWith("/chat/completions") || path.endsWith("/messages")) {
+    return { ok: false, error: "Enter the API base URL, not a final inference endpoint." };
   }
   url.pathname = url.pathname.replace(/\/+$/u, "");
   const normalized = url.toString().replace(/\/+$/u, "");
   return { ok: true, value: normalized, loopback };
 }
 function buildOnboardingConfig(state) {
-  const provider = state.draft.provider;
+  const protocol = state.draft.relayProtocol;
   const model = validateModel(state.draft.model);
-  if (!provider || !model.ok) throw new Error("Onboarding model configuration is incomplete.");
-  const apiKey = validateApiKey(state.draft.apiKey, apiKeyRequired(state));
-  if (!apiKey.ok) throw new Error("Onboarding credential configuration is incomplete.");
-  if (state.draft.method === "relay") {
-    const endpoint = validateRelayBaseUrl(state.draft.baseUrl);
-    if (!endpoint.ok) throw new Error("Onboarding relay configuration is incomplete.");
-    return {
-      model: {
-        provider,
-        model: model.value,
-        baseUrl: endpoint.value,
-        ...apiKey.value ? { apiKey: apiKey.value } : {}
-      }
-    };
+  const endpoint = validateRelayBaseUrl(state.draft.baseUrl);
+  const modelsEndpoint = validateModelsBaseUrl(state.draft.modelsBaseUrl, protocol === "anthropic-messages");
+  const auth = state.draft.auth;
+  const apiKeyEnv = validateEnvironmentName(state.draft.apiKeyEnv, auth === "env");
+  if (!protocol || !model.ok || !endpoint.ok || !modelsEndpoint.ok || !auth || !apiKeyEnv.ok) {
+    throw new Error("Onboarding relay configuration is incomplete.");
   }
-  return { model: { provider, model: model.value, apiKey: apiKey.value } };
+  const setup = createAgentConnectionSetup({
+    name: DEFAULT_CONNECTION_NAME,
+    provider: "compatible",
+    protocol,
+    baseUrl: endpoint.value,
+    ...modelsEndpoint.value ? { modelsBaseUrl: modelsEndpoint.value } : {},
+    auth,
+    ...apiKeyEnv.value ? { apiKeyEnv: apiKeyEnv.value } : {},
+    defaultModel: model.value
+  });
+  return { agents: mergeAgentSetup(void 0, setup) };
 }
 function selectCurrentOption(state) {
-  if (state.step === "method") {
-    const method = methods[state.selected]?.value;
-    if (!method) return state;
-    if (method === "official") {
-      return advance({ ...state, draft: { ...state.draft, method, relayProtocol: void 0 } }, "official-provider");
-    }
-    if (method === "relay") {
-      return advance({ ...state, draft: { ...state.draft, method } }, "relay-protocol");
-    }
-    return state;
-  }
-  if (state.step === "official-provider") {
-    const provider = officialProviders[state.selected]?.provider;
-    if (!provider) return state;
-    return advance({
-      ...state,
-      draft: {
-        ...state.draft,
-        method: "official",
-        provider,
-        relayProtocol: void 0,
-        baseUrl: "",
-        model: defaultModelForProvider(provider),
-        apiKey: ""
-      }
-    }, "model");
-  }
   if (state.step === "relay-protocol") {
-    const relayProtocol = relayProtocols[state.selected]?.value;
+    const relayProtocol = relayProtocols2[state.selected]?.value;
     if (!relayProtocol) return state;
-    const provider = relayProtocol === "openai-compatible" ? "compatible" : "anthropic";
     return advance({
       ...state,
       draft: {
         ...state.draft,
-        method: "relay",
-        provider,
         relayProtocol,
         baseUrl: "",
-        model: defaultModelForProvider(provider),
-        apiKey: ""
+        modelsBaseUrl: "",
+        model: "default",
+        auth: void 0,
+        apiKeyEnv: "SKEIN_API_KEY"
       }
     }, "endpoint");
   }
+  if (state.step === "auth") {
+    const auth = authMethods[state.selected]?.value;
+    if (!auth) return state;
+    const next = { ...state, draft: { ...state.draft, auth, apiKeyEnv: auth === "env" ? state.draft.apiKeyEnv : "" } };
+    return advance(next, auth === "env" ? "api-key-env" : "confirm");
+  }
   return state;
 }
 function submitInput(state, field, rawValue) {
@@ -20742,22 +21423,30 @@ function submitInput(state, field, rawValue) {
   if (field === "baseUrl") {
     const endpoint = validateRelayBaseUrl(value);
     if (!endpoint.ok) return { ...next, error: endpoint.error };
-    return advance({ ...next, draft: { ...next.draft, baseUrl: endpoint.value } }, "model");
+    return advance({ ...next, draft: { ...next.draft, baseUrl: endpoint.value } }, "models-endpoint");
+  }
+  if (field === "modelsBaseUrl") {
+    const endpoint = validateModelsBaseUrl(value, state.draft.relayProtocol === "anthropic-messages");
+    if (!endpoint.ok) return { ...next, error: endpoint.error };
+    return advance({ ...next, draft: { ...next.draft, modelsBaseUrl: endpoint.value } }, "model");
   }
   if (field === "model") {
     const model = validateModel(value);
     if (!model.ok) return { ...next, error: model.error };
-    return advance({ ...next, draft: { ...next.draft, model: model.value } }, "api-key");
+    return advance({ ...next, draft: { ...next.draft, model: model.value } }, "auth");
+  }
+  const apiKeyEnv = validateEnvironmentName(value, true);
+  if (!apiKeyEnv.ok) return { ...next, error: apiKeyEnv.error };
+  if (!process.env[apiKeyEnv.value]) {
+    return { ...next, error: `Environment variable ${apiKeyEnv.value} is not set. Export it, then restart Skein.` };
   }
-  const apiKey = validateApiKey(value, apiKeyRequired(next));
-  if (!apiKey.ok) return { ...next, error: apiKey.error };
-  return advance({ ...next, draft: { ...next.draft, apiKey: apiKey.value } }, "confirm");
+  return advance({ ...next, draft: { ...next.draft, apiKeyEnv: apiKeyEnv.value } }, "confirm");
 }
 function advance(state, step2) {
   return { ...state, step: step2, history: [...state.history, state.step], selected: 0, error: void 0 };
 }
 function sanitizeFieldInput(field, value) {
-  const max = field === "baseUrl" ? 2048 : field === "model" ? 256 : 1024;
+  const max = field === "baseUrl" || field === "modelsBaseUrl" ? 2048 : field === "model" ? 256 : 128;
   return sanitizeTerminalText(value).replace(directionControls, "").replace(/\r?\n/gu, "").slice(0, max);
 }
 function validateModel(value) {
@@ -20768,18 +21457,18 @@ function validateModel(value) {
   }
   return { ok: true, value: model };
 }
-function validateApiKey(value, required) {
-  const apiKey = value.trim();
-  if (!apiKey && required) return { ok: false, error: "Enter the API key for this provider or relay." };
-  if (/\s/u.test(apiKey) || forbiddenDirectionControls.test(apiKey)) {
-    return { ok: false, error: "The API key contains unsupported whitespace or control characters." };
-  }
-  return { ok: true, value: apiKey };
+function validateModelsBaseUrl(value, required) {
+  if (!value.trim() && !required) return { ok: true, value: "" };
+  if (!value.trim()) return { ok: false, error: "Anthropic transport requires an OpenAI-style models base URL." };
+  return validateRelayBaseUrl(value);
 }
-function apiKeyRequired(state) {
-  if (state.draft.method !== "relay") return true;
-  const endpoint = validateRelayBaseUrl(state.draft.baseUrl);
-  return state.draft.provider === "anthropic" || !endpoint.ok || !endpoint.loopback;
+function validateEnvironmentName(value, required) {
+  const name = value.trim();
+  if (!name && !required) return { ok: true, value: "" };
+  if (!/^[A-Z][A-Z0-9_]{0,127}$/u.test(name)) {
+    return { ok: false, error: "Use an uppercase environment variable name, for example RELAY_API_KEY." };
+  }
+  return { ok: true, value: name };
 }
 function isLoopbackHostname(hostname) {
   const normalized = hostname.replace(/^\[|\]$/gu, "").toLocaleLowerCase();
@@ -20870,9 +21559,8 @@ function OnboardingScreen({ state, dispatch, width, compact: compact3 = false })
     !compact3 ? /* @__PURE__ */ jsx5(Text6, { color: theme.muted, wrap: "wrap", children: descriptionForStep(state) }) : null,
     summary ? /* @__PURE__ */ jsx5(Text6, { color: theme.dim, children: truncateDisplay(summary, headerWidth) }) : null,
     !compact3 ? /* @__PURE__ */ jsx5(Box4, { height: 1 }) : null,
-    state.step === "method" ? /* @__PURE__ */ jsx5(OptionList, { options: methods, selected: state.selected, marker, width: headerWidth, compact: compact3 }) : null,
-    state.step === "official-provider" ? /* @__PURE__ */ jsx5(OptionList, { options: officialProviders, selected: state.selected, marker, width: headerWidth, compact: compact3 }) : null,
-    state.step === "relay-protocol" ? /* @__PURE__ */ jsx5(OptionList, { options: relayProtocols, selected: state.selected, marker, width: headerWidth, compact: compact3 }) : null,
+    state.step === "relay-protocol" ? /* @__PURE__ */ jsx5(OptionList, { options: relayProtocols2, selected: state.selected, marker, width: headerWidth, compact: compact3 }) : null,
+    state.step === "auth" ? /* @__PURE__ */ jsx5(OptionList, { options: authMethods, selected: state.selected, marker, width: headerWidth, compact: compact3 }) : null,
     inputField ? /* @__PURE__ */ jsxs5(Box4, { flexDirection: "column", children: [
       /* @__PURE__ */ jsxs5(Box4, { children: [
         /* @__PURE__ */ jsx5(Text6, { color: theme.textStrong, bold: true, children: inputField.label }),
@@ -20889,8 +21577,7 @@ function OnboardingScreen({ state, dispatch, width, compact: compact3 = false })
             value: state.draft[inputField.field],
             onChange: (value) => dispatch({ type: "INPUT", field: inputField.field, value }),
             onSubmit: (value) => dispatch({ type: "SUBMIT_INPUT", field: inputField.field, value }),
-            placeholder: inputField.placeholder,
-            ...inputField.field === "apiKey" ? { mask: ascii ? "*" : "\u2022" } : {}
+            placeholder: inputField.placeholder
           }
         ) })
       ] })
@@ -20927,13 +21614,13 @@ function OptionList({ options, selected, marker, width, compact: compact3 }) {
 }
 function Confirmation({ state, width }) {
   const theme = useTheme();
-  const relay = state.draft.method === "relay";
   const values = [
-    ["Mode", relay ? "Compatible endpoint" : "Provider API"],
-    ["Protocol", relay ? relayLabel(state.draft.relayProtocol) : providerLabel(state.draft.provider)],
-    ...relay ? [["Base URL", redactEndpoint(state.draft.baseUrl)]] : [],
+    ["Connection", DEFAULT_CONNECTION_NAME],
+    ["Protocol", relayLabel(state.draft.relayProtocol)],
+    ["Inference", redactEndpoint(state.draft.baseUrl)],
+    ["Models", state.draft.modelsBaseUrl ? redactEndpoint(state.draft.modelsBaseUrl) : "same base as inference"],
     ["Model", state.draft.model],
-    ["Credential", state.draft.apiKey ? "configured \xB7 masked \xB7 owner-only" : "not required for this loopback endpoint"]
+    ["Credential", state.draft.auth === "env" ? `env:${state.draft.apiKeyEnv} \xB7 configured` : "none"]
   ];
   const tabular = width >= 36;
   return /* @__PURE__ */ jsxs5(Box4, { flexDirection: "column", children: [
@@ -20945,53 +21632,61 @@ function Confirmation({ state, width }) {
   ] });
 }
 function menuCount(step2) {
-  if (step2 === "method") return methods.length;
-  if (step2 === "official-provider") return officialProviders.length;
-  if (step2 === "relay-protocol") return relayProtocols.length;
+  if (step2 === "relay-protocol") return relayProtocols2.length;
+  if (step2 === "auth") return authMethods.length;
   return 0;
 }
 function inputFieldForStep(state) {
-  if (state.step === "endpoint") return { field: "baseUrl", label: "Base URL", placeholder: "https://relay.example/v1", required: true };
+  if (state.step === "endpoint") return { field: "baseUrl", label: "Inference base URL", placeholder: "https://relay.example/v1", required: true };
+  if (state.step === "models-endpoint") return {
+    field: "modelsBaseUrl",
+    label: "Models base URL",
+    placeholder: state.draft.relayProtocol === "anthropic-messages" ? "https://relay.example/v1" : "blank uses inference base",
+    required: state.draft.relayProtocol === "anthropic-messages"
+  };
   if (state.step === "model") return { field: "model", label: "Model identifier", placeholder: "provider-model-id", required: true };
-  if (state.step === "api-key") return { field: "apiKey", label: "API key", placeholder: "paste key \xB7 input is masked", required: apiKeyRequired(state) };
+  if (state.step === "api-key-env") return {
+    field: "apiKeyEnv",
+    label: "Credential environment variable",
+    placeholder: "RELAY_API_KEY",
+    required: true
+  };
   return void 0;
 }
 function setupStage(state) {
-  const index = state.step === "endpoint" || state.step === "model" ? 2 : state.step === "api-key" ? 3 : state.step === "confirm" || state.step === "saving" ? 4 : 1;
-  const name = index === 1 ? "CONNECTION" : index === 2 ? "MODEL" : index === 3 ? "CREDENTIAL" : "REVIEW";
-  return { index, name, progress: `SETUP ${index}/4` };
+  const index = state.step === "endpoint" || state.step === "models-endpoint" ? 2 : state.step === "model" ? 3 : state.step === "auth" || state.step === "api-key-env" ? 4 : state.step === "confirm" || state.step === "saving" ? 5 : 1;
+  const name = index === 1 ? "TRANSPORT" : index === 2 ? "ENDPOINTS" : index === 3 ? "MODEL" : index === 4 ? "AUTH" : "REVIEW";
+  return { index, name, progress: `SETUP ${index}/5` };
 }
 function stageDivider(ascii, width) {
   return (ascii ? "-" : "\u2500").repeat(Math.max(1, width));
 }
 function connectionSummary(state) {
-  if (!state.draft.method) return "";
-  const parts = [state.draft.method === "relay" ? "Compatible endpoint" : "Provider API"];
-  if (state.draft.provider) parts.push(
-    state.draft.method === "relay" ? relayLabel(state.draft.relayProtocol) : providerLabel(state.draft.provider)
-  );
+  if (!state.draft.relayProtocol) return "";
+  const parts = ["Relay"];
+  parts.push(relayLabel(state.draft.relayProtocol));
   if (state.draft.baseUrl) parts.push(redactEndpoint(state.draft.baseUrl));
   if (state.draft.model) parts.push(state.draft.model);
   return parts.join("  /  ");
 }
 function titleForStep(step2) {
-  if (step2 === "method") return "Choose how Skein reaches the model";
-  if (step2 === "official-provider") return "Choose a provider";
-  if (step2 === "relay-protocol") return "Choose the endpoint protocol";
-  if (step2 === "endpoint") return "Enter the endpoint base URL";
+  if (step2 === "relay-protocol") return "Choose the relay protocol";
+  if (step2 === "endpoint") return "Enter the inference base URL";
+  if (step2 === "models-endpoint") return "Enter the model catalog base URL";
   if (step2 === "model") return "Enter the model identifier";
-  if (step2 === "api-key") return "Add the API key";
+  if (step2 === "auth") return "Choose relay authentication";
+  if (step2 === "api-key-env") return "Reference the credential environment";
   if (step2 === "confirm") return "Review and save";
   return "Saving configuration";
 }
 function descriptionForStep(state) {
-  if (state.step === "method") return "Skein's primary agent needs an API credential. OpenAI, Anthropic, and Gemini subscription logins are not API keys; signed-in coding CLIs are separate delegated tools.";
-  if (state.step === "official-provider") return "Use the API credential issued by the selected provider.";
-  if (state.step === "relay-protocol") return "The protocol is explicit so requests and credentials are never guessed.";
+  if (state.step === "relay-protocol") return "Skein connects through third-party relays only. Responses is recommended; Chat Completions and Anthropic Messages remain explicit compatibility transports.";
   if (state.step === "endpoint") return "Remote endpoints require HTTPS. Loopback development servers may use HTTP.";
-  if (state.step === "model") return "Use the exact model identifier accepted by this provider or endpoint.";
-  if (state.step === "api-key") return apiKeyRequired(state) ? "Masked on screen and saved only to your owner-readable user configuration." : "This loopback endpoint may be keyless. Leave blank if it does not authenticate.";
-  if (state.step === "confirm") return "The values below are sanitized before Skein saves and validates them.";
+  if (state.step === "models-endpoint") return state.draft.relayProtocol === "anthropic-messages" ? "Anthropic inference bases often differ from the OpenAI-style /models directory, so this value is required." : "Leave blank when GET /models uses the same base as inference.";
+  if (state.step === "model") return "Use the exact model identifier returned or documented by the relay.";
+  if (state.step === "auth") return "Credentials are referenced from the environment and are never written to Skein configuration.";
+  if (state.step === "api-key-env") return "Enter the variable name only. It must already exist in this process environment.";
+  if (state.step === "confirm") return "Only redacted endpoints, model metadata, and the credential variable name are saved.";
   return "The configuration is saved only after this step succeeds.";
 }
 function footerForStep(state, width) {
@@ -21002,10 +21697,9 @@ function footerForStep(state, width) {
   return width < 48 ? "Enter next \xB7 Esc back" : "Enter continue \xB7 Esc back \xB7 Ctrl+C cancel";
 }
 function relayLabel(protocol) {
-  return protocol === "anthropic-compatible" ? "Anthropic-compatible" : "OpenAI-compatible";
-}
-function providerLabel(provider) {
-  return officialProviders.find((item) => item.provider === provider)?.label ?? provider ?? "not selected";
+  if (protocol === "anthropic-messages") return "Anthropic Messages";
+  if (protocol === "openai-chat") return "OpenAI Chat Completions";
+  return "OpenAI Responses";
 }
 async function runFirstRunOnboarding(initialConfig, options = {}) {
   let result;
@@ -21047,7 +21741,7 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 import stripAnsi6 from "strip-ansi";
 
 // src/mcp/tool.ts
-import { createHash as createHash18 } from "node:crypto";
+import { createHash as createHash19 } from "node:crypto";
 import stripAnsi4 from "strip-ansi";
 var MAX_ARGUMENT_BYTES = 256e3;
 var MAX_DESCRIPTION_LENGTH = 4e3;
@@ -21283,7 +21977,7 @@ function fitToolName(name, identity2) {
   return `${name.slice(0, 64 - suffix.length).replace(/_+$/g, "")}${suffix}`;
 }
 function shortHash(value) {
-  return createHash18("sha256").update(value).digest("hex").slice(0, 8);
+  return createHash19("sha256").update(value).digest("hex").slice(0, 8);
 }
 function sanitizeOutputText(value) {
   return stripAnsi4(value).replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "");
@@ -21449,7 +22143,7 @@ function isLoopbackHost(hostname) {
 }
 
 // src/mcp/capabilities.ts
-import { createHash as createHash19 } from "node:crypto";
+import { createHash as createHash20 } from "node:crypto";
 import { homedir as homedir4 } from "node:os";
 import { basename as basename12, isAbsolute as isAbsolute9, relative as relative11, resolve as resolve23 } from "node:path";
 import stripAnsi5 from "strip-ansi";
@@ -21478,7 +22172,7 @@ function capabilityFingerprint(name, config, workspace = process.cwd()) {
     envNames: Object.keys(config.env ?? {}).sort(),
     headerNames: Object.keys(config.headers ?? {}).map((key) => key.toLocaleLowerCase()).sort()
   };
-  return createHash19("sha256").update(stableJson2({ manifest, privateTransport })).digest("hex");
+  return createHash20("sha256").update(stableJson2({ manifest, privateTransport })).digest("hex");
 }
 function searchMcpCapabilities(config, query) {
   const terms = new Set(sanitizeText(query, 500).toLocaleLowerCase().match(/[\p{L}\p{N}_-]{2,}/gu) ?? []);
@@ -23185,7 +23879,7 @@ process.on("warning", (warning) => {
 var program = new Command();
 program.enablePositionalOptions();
 program.name(PRODUCT_COMMAND).description("A context-first, model-agnostic coding agent with an auditable workspace.").version(package_default.version).showSuggestionAfterError();
-program.argument("[prompt...]", "instruction for the agent").option("-p, --print", "run once and print the result").option("-a, --ask", "retrieval and inspection mode; mutation tools are denied").option("--plan", "read-only planning mode; propose changes without mutating the workspace").option("-q, --quiet", "print only the final response in text mode").addOption(new Option("--output-format <format>", "text, json, or stream-json").choices(["text", "json", "stream-json"]).default("text")).option("--compact", "reduce progress output in print mode").option("--yes", "approve all non-denied tool requests for this run").option("--auto-edit", "approve read/write requests and ask before shell/Git/network").option("--trust-project-config", "allow executable and security-sensitive settings from project config").option("--queue <prompt>", "run an additional prompt after the first one", collect, []).option("-w, --workspace <path>", "primary workspace root", process.cwd()).option("--add-workspace <path>", "additional workspace root", collect, []).option("--config <path>", "explicit config file").option("--provider <provider>", "model provider").option("--model <model>", "model identifier").option("--base-url <url>", "OpenAI-compatible or provider base URL").option("--max-turns <n>", "maximum agent turns").option("--epoch-token-budget <n>", "maximum tokens before an internal context handoff").option("--token-budget <n>", "maximum lifetime tokens across the resumed session").option("--resume [session]", "resume a session by id or prefix").option("-c, --continue", "resume the latest session").option("--no-color", "disable color output").option("--no-checkpoint", "disable pre-mutation checkpoints for this run").action(async (prompts, options) => {
+program.argument("[prompt...]", "instruction for the agent").option("-p, --print", "run once and print the result").option("-a, --ask", "retrieval and inspection mode; mutation tools are denied").option("--plan", "read-only planning mode; propose changes without mutating the workspace").option("-q, --quiet", "print only the final response in text mode").addOption(new Option("--output-format <format>", "text, json, or stream-json").choices(["text", "json", "stream-json"]).default("text")).option("--compact", "reduce progress output in print mode").option("--yes", "approve all non-denied tool requests for this run").option("--auto-edit", "approve read/write requests and ask before shell/Git/network").option("--trust-project-config", "allow executable and security-sensitive settings from project config").option("--queue <prompt>", "run an additional prompt after the first one", collect, []).option("-w, --workspace <path>", "primary workspace root", process.cwd()).option("--add-workspace <path>", "additional workspace root", collect, []).option("--config <path>", "explicit config file").option("--connection <name>", "named model connection").option("--provider <provider>", "model provider").option("--model <model>", "model identifier").option("--base-url <url>", "OpenAI-compatible or provider base URL").option("--max-turns <n>", "maximum agent turns").option("--epoch-token-budget <n>", "maximum tokens before an internal context handoff").option("--token-budget <n>", "maximum lifetime tokens across the resumed session").option("--resume [session]", "resume a session by id or prefix").option("-c, --continue", "resume the latest session").option("--no-color", "disable color output").option("--no-checkpoint", "disable pre-mutation checkpoints for this run").action(async (prompts, options) => {
   await runChat(prompts, options);
 });
 program.command("init").description("Create a project-local config (preserving an existing .mosaic namespace)").option("-w, --workspace <path>", "workspace root").option("--provider <provider>", "openai, anthropic, gemini, or compatible", "openai").option("--model <model>", "model identifier").option("--base-url <url>", "provider base URL").option("--api-key <key>", "store a provider key in project config (prefer env vars)").option("--index", "build the index after writing config").option("--yes", "use defaults without prompting").action(async (options) => {
@@ -23517,31 +24211,36 @@ agentsCommand.command("list").description("List built-in and discovered expert p
 `);
   }
 });
-agentsCommand.command("setup").description("Configure one shared model connection and team defaults").option("-w, --workspace <path>", "workspace used to resolve current defaults").option("--name <name>", "connection name").option("--provider <provider>", "openai, anthropic, gemini, or compatible").option("--base-url <url>", "provider or relay base URL").option("--api-key-env <name>", "environment variable containing the credential").option("--model <model>", "default model identifier").option("--yes", "use supplied or existing defaults without prompting").option("--json", "print JSON").action(async (options) => {
+agentsCommand.command("setup").description("Configure one shared model connection and team defaults").option("-w, --workspace <path>", "workspace used to resolve current defaults").option("--name <name>", "connection name").option("--provider <provider>", "relay provider; only compatible is supported").option("--protocol <protocol>", "openai-responses, openai-chat, or anthropic-messages").option("--base-url <url>", "relay inference base URL").option("--models-base-url <url>", "separate OpenAI-compatible base URL for GET /models").option("--auth <type>", "connection authentication: env or none").option("--api-key-env <name>", "environment variable containing the credential").option("--model <model>", "default model identifier").option("--yes", "use supplied or existing defaults without prompting").option("--json", "print JSON").action(async (options) => {
   await runAgentSetup(options);
 });
 agentsCommand.command("connections").description("List named model endpoints and credential references").option("-w, --workspace <path>", "workspace root").option("--config <path>", "explicit config file").option("--json", "print JSON").action(async (options) => {
   const workspace = workspaceOption(options.workspace);
   const config = await runtimeConfig(workspace, runtimeOptions(options));
-  const connections = Object.entries(config.agents?.connections ?? {}).map(([name, connection]) => ({
-    name,
+  const catalog = discoverConnectionCatalog(config);
+  const connections = catalog.profiles.map((connection) => ({
+    name: connection.id,
     provider: connection.provider,
+    protocol: connection.protocol,
+    source: connection.source,
     endpoint: redactEndpoint(connection.baseUrl),
-    credentials: connection.apiKeyEnv ? `env:${connection.apiKeyEnv}` : "provider default environment",
-    routes: Object.values(config.agents?.routes ?? {}).filter((route) => route.connection === name).length,
-    default: config.agents?.defaultConnection === name
+    modelsEndpoint: redactEndpoint(connection.modelsBaseUrl ?? connection.baseUrl),
+    credentials: connectionCredentialReference(connection),
+    routes: Object.values(config.agents?.routes ?? {}).filter((route) => route.connection === connection.id).length,
+    default: catalog.defaultConnection === connection.id,
+    complete: connectionRuntimeCatalog({ profiles: [connection] }).profiles[0]?.complete ?? false
   }));
   if (options.json) printObject(connections, true);
   else if (!connections.length) process.stdout.write("No named model connections configured.\n");
   else for (const connection of connections) {
-    process.stdout.write(`${connection.name.padEnd(16)} ${connection.provider.padEnd(10)} ${connection.credentials.padEnd(28)} ${connection.routes} explicit${connection.default ? " + team default" : ""}  ${connection.endpoint}
+    process.stdout.write(`${connection.name.padEnd(16)} ${connection.protocol.padEnd(20)} ${connection.credentials.padEnd(28)} ${connection.source.padEnd(11)} ${connection.complete ? "ready" : "incomplete"}${connection.default ? " + default" : ""}  inference=${connection.endpoint} models=${connection.modelsEndpoint}
 `);
   }
 });
 agentsCommand.command("models <connection>").description("List model IDs exposed by a named compatible connection").option("-w, --workspace <path>", "workspace root").option("--config <path>", "explicit config file").option("--json", "print JSON").action(async (connectionName, options) => {
   const workspace = workspaceOption(options.workspace);
   const config = await runtimeConfig(workspace, runtimeOptions(options));
-  const connection = config.agents?.connections?.[connectionName];
+  const connection = discoverConnectionCatalog(config).profiles.find(({ id }) => id === connectionName);
   if (!connection) throw new Error(`Unknown model connection: ${connectionName}`);
   const models = await listConnectionModels(connection);
   if (options.json) printObject(models, true);
@@ -23900,14 +24599,15 @@ async function runChat(prompts, options) {
   const firstPrompt = [...prompts, stdinPrompt].filter(Boolean).join("\n\n").trim();
   if (shouldPrint && !firstPrompt) throw new Error("Provide a prompt argument or pipe input on stdin.");
   const workspace = resolve27(options.workspace);
-  let config = await runtimeConfig(workspace, options);
+  const connectionSelection = shouldPrint ? "required" : "interactive";
+  let config = await runtimeConfig(workspace, { ...options, connectionSelection });
   let completedOnboarding = false;
   if (!shouldPrint && needsFirstRunOnboarding(config)) {
     if (!options.config) {
       const onboarding = await runFirstRunOnboarding(config);
       if (onboarding.status === "cancelled") return;
       completedOnboarding = true;
-      config = await runtimeConfig(workspace, options);
+      config = await runtimeConfig(workspace, { ...options, connectionSelection });
     }
   }
   validateModelSetup(config);
@@ -23956,7 +24656,8 @@ async function runChat(prompts, options) {
     format: options.outputFormat,
     quiet: options.quiet ?? false,
     compact: options.compact ?? false,
-    color: (options.color ?? config.ui.color) && !process.env.NO_COLOR
+    color: (options.color ?? config.ui.color) && !process.env.NO_COLOR,
+    ...config.activeConnection ? { connection: config.activeConnection } : {}
   });
   const colorOutput = (options.color ?? config.ui.color) && !process.env.NO_COLOR;
   const requestPermission = options.yes ? async () => true : options.autoEdit ? async (_call, category, reason) => category === "read" || category === "write" ? true : askConsolePermission(_call, category, colorOutput, reason) : async (call, category, reason) => askConsolePermission(call, category, colorOutput, reason);
@@ -24076,20 +24777,23 @@ async function runAgentSetup(options) {
   const currentConnection = current.agents?.connections?.[currentName];
   let name = options.name ?? currentName;
   let provider = validateProvider(options.provider ?? currentConnection?.provider ?? "compatible");
+  let protocol = validateConnectionProtocol(options.protocol ?? currentConnection?.protocol ?? "openai-responses");
   let baseUrl = options.baseUrl ?? currentConnection?.baseUrl ?? "";
-  let apiKeyEnv = options.apiKeyEnv ?? currentConnection?.apiKeyEnv ?? providerEnvironment(provider);
+  let modelsBaseUrl = options.modelsBaseUrl ?? currentConnection?.modelsBaseUrl ?? "";
+  let auth = validateConnectionAuth(options.auth ?? currentConnection?.auth?.type ?? "env");
+  const currentApiKeyEnv = currentConnection?.apiKeyEnv ?? (currentConnection?.auth?.type === "env" ? currentConnection.auth.name : void 0);
+  let apiKeyEnv = options.apiKeyEnv ?? (auth === "env" ? currentApiKeyEnv ?? providerEnvironment(provider) : "");
   let model = options.model ?? current.agents?.defaultModel ?? current.model.model;
   if (!options.yes && process.stdin.isTTY && process.stdout.isTTY) {
     const readline = createInterface2({ input, output });
     try {
       name = await question(readline, "Connection name", name);
-      const previousProvider = provider;
-      provider = validateProvider(await question(readline, "Provider", provider));
-      if (!options.apiKeyEnv && !currentConnection?.apiKeyEnv && apiKeyEnv === providerEnvironment(previousProvider)) {
-        apiKeyEnv = providerEnvironment(provider);
-      }
-      baseUrl = await question(readline, "Base URL", baseUrl);
-      apiKeyEnv = await question(readline, "Credential environment variable", apiKeyEnv || providerEnvironment(provider));
+      provider = validateProvider(await question(readline, "Relay provider", provider));
+      protocol = validateConnectionProtocol(await question(readline, "Inference protocol", protocol));
+      baseUrl = await question(readline, "Inference base URL", baseUrl);
+      modelsBaseUrl = await question(readline, "Models base URL (optional unless Anthropic)", modelsBaseUrl);
+      auth = validateConnectionAuth(await question(readline, "Authentication (env or none)", auth));
+      apiKeyEnv = auth === "env" ? await question(readline, "Credential environment variable", apiKeyEnv || providerEnvironment(provider)) : "";
       model = await question(readline, "Default model", model);
     } finally {
       readline.close();
@@ -24098,7 +24802,10 @@ async function runAgentSetup(options) {
   const setup = createAgentConnectionSetup({
     name,
     provider,
+    protocol,
     ...baseUrl ? { baseUrl } : {},
+    ...modelsBaseUrl ? { modelsBaseUrl } : {},
+    auth,
     ...apiKeyEnv ? { apiKeyEnv } : {},
     defaultModel: model
   });
@@ -24108,7 +24815,10 @@ async function runAgentSetup(options) {
     path,
     connection: setup.defaultConnection,
     provider,
+    protocol,
     endpoint: redactEndpoint(baseUrl),
+    modelsEndpoint: redactEndpoint(modelsBaseUrl || baseUrl),
+    auth,
     apiKeyEnv: apiKeyEnv || null,
     credentialConfigured,
     defaultModel: setup.defaultModel
@@ -24119,11 +24829,11 @@ async function runAgentSetup(options) {
   }
   process.stdout.write(`${chalk4.green(cliGlyphs.success)} Saved shared connection ${setup.defaultConnection} to ${path}
 `);
-  process.stdout.write(`  Default: ${provider}/${setup.defaultModel} via ${redactEndpoint(baseUrl)}
+  process.stdout.write(`  Default: ${protocol}/${setup.defaultModel} via ${redactEndpoint(baseUrl)}
 `);
-  process.stdout.write(`  Credential: ${apiKeyEnv ? `env:${apiKeyEnv} (${credentialConfigured ? "configured" : "not set"})` : "provider default environment"}
+  process.stdout.write(`  Models: ${PRODUCT_COMMAND} agents models ${setup.defaultConnection} via ${redactEndpoint(modelsBaseUrl || baseUrl)}
 `);
-  process.stdout.write(`  Models: ${provider === "compatible" || provider === "openai" ? `${PRODUCT_COMMAND} agents models ${setup.defaultConnection}` : "managed by the provider or official CLI"}
+  process.stdout.write(`  Credential: ${auth === "none" ? "none" : `env:${apiKeyEnv} (${credentialConfigured ? "configured" : "not set"})`}
 `);
   process.stdout.write(`  Routes: ${PRODUCT_COMMAND} agents list
 `);
@@ -24139,14 +24849,40 @@ async function runtimeConfig(workspaceInput, options) {
     ...(options.addWorkspace ?? []).map((root) => resolve27(workspace, root))
   ];
   const provider = options.provider ? validateProvider(options.provider) : loaded.model.provider;
+  const legacyModel = resolveRuntimeModel(loaded.model, {
+    provider,
+    ...options.model ? { model: options.model } : {},
+    ...options.baseUrl ? { baseUrl: options.baseUrl } : {}
+  });
+  const catalog = discoverConnectionCatalog(loaded);
+  let model = legacyModel;
+  let activeConnection = legacyConnectionRuntimeInfo(legacyModel);
+  if (options.provider || options.baseUrl) {
+    if (options.connection) throw new Error("--connection cannot be combined with --provider or --base-url.");
+    activeConnection = { ...activeConnection, id: "cli", source: "cli" };
+  } else if (options.connectionSelection !== "inspect" || options.connection) {
+    let selection = planConnectionSelection(catalog, process.env, options.connection);
+    if (selection.kind === "ambiguous") {
+      if (options.connectionSelection === "interactive") {
+        selection = { kind: "selected", profile: await promptConnectionSelection(selection.profiles) };
+      } else if (options.connectionSelection === "required") {
+        throw new Error(`Multiple complete model connections found: ${selection.profiles.map(({ id }) => id).join(", ")}. Pass --connection <name>.`);
+      }
+    }
+    if (selection.kind === "selected") {
+      const resolved = resolveConnectionModel(legacyModel, selection.profile, {
+        ...options.model ? { model: options.model } : {}
+      });
+      model = resolved.model;
+      activeConnection = resolved.activeConnection;
+    }
+  }
   return {
     ...loaded,
     workspaceRoots: [...new Set(roots)],
-    model: resolveRuntimeModel(loaded.model, {
-      provider,
-      ...options.model ? { model: options.model } : {},
-      ...options.baseUrl ? { baseUrl: options.baseUrl } : {}
-    }),
+    model,
+    connectionCatalog: connectionRuntimeCatalog(catalog),
+    activeConnection,
     context: loaded.context,
     agent: {
       ...loaded.agent,
@@ -24157,6 +24893,23 @@ async function runtimeConfig(workspaceInput, options) {
     ui: { ...loaded.ui, ...options.color === false ? { color: false } : {} }
   };
 }
+async function promptConnectionSelection(profiles) {
+  process.stdout.write("Multiple model connections are ready:\n");
+  profiles.forEach((profile, index) => {
+    process.stdout.write(`  ${index + 1}. ${profile.id}  ${profile.provider}/${profile.defaultModel ?? defaultModelForProvider(profile.provider)}  ${redactEndpoint(profile.baseUrl)}
+`);
+  });
+  const readline = createInterface2({ input, output });
+  try {
+    const answer = (await question(readline, "Select connection by number or name", "")).trim();
+    const numeric2 = Number(answer);
+    const selected = Number.isInteger(numeric2) && numeric2 >= 1 ? profiles[numeric2 - 1] : profiles.find(({ id }) => id === answer);
+    if (!selected) throw new Error(`Unknown connection selection ${answer || "<empty>"}. Pass --connection <name> to choose explicitly.`);
+    return selected;
+  } finally {
+    readline.close();
+  }
+}
 async function loadSessionSelector(store, selector) {
   const summaries = await store.list();
   if (!summaries.length) {
@@ -24328,6 +25081,7 @@ function workspaceOption(value) {
 function runtimeOptions(options) {
   const root = program.opts();
   const config = options.config ?? root.config;
+  const connection = options.connection ?? root.connection;
   const provider = options.provider ?? root.provider;
   const model = options.model ?? root.model;
   const baseUrl = options.baseUrl ?? root.baseUrl;
@@ -24336,6 +25090,7 @@ function runtimeOptions(options) {
   return {
     addWorkspace: [...root.addWorkspace ?? [], ...options.addWorkspace ?? []],
     ...config ? { config } : {},
+    ...connection ? { connection } : {},
     ...provider ? { provider } : {},
     ...model ? { model } : {},
     ...baseUrl ? { baseUrl } : {},
@@ -24355,6 +25110,14 @@ function validateProvider(value) {
   if (value === "openai" || value === "anthropic" || value === "gemini" || value === "compatible") return value;
   throw new Error(`Unknown provider ${value}; use openai, anthropic, gemini, or compatible.`);
 }
+function validateConnectionProtocol(value) {
+  if (value === "openai-responses" || value === "openai-chat" || value === "anthropic-messages") return value;
+  throw new Error(`Unknown relay protocol ${value}; use openai-responses, openai-chat, or anthropic-messages.`);
+}
+function validateConnectionAuth(value) {
+  if (value === "env" || value === "none") return value;
+  throw new Error(`Unknown connection authentication ${value}; use env or none.`);
+}
 function environmentName(provider) {
   return providerEnvironment(provider);
 }