chainlesschain 0.166.132 → 0.166.133

package/src/lib/evolution/governed-hub-resolver.js

@@ -77,8 +77,16 @@ function captureEmbeddingTransport(stage, sdk) {
   };
 }
 
-export function createGovernedHubResolver(ports, factory, sdkPorts) {
-  if (typeof factory !== "function")
+export function createGovernedHubResolver(
+  ports,
+  factory,
+  sdkPorts,
+  options = {},
+) {
+  if (
+    typeof factory !== "function" &&
+    !(factory === null && options.evolutionDisabled === true)
+  )
     throw new TypeError("A resolver evolution factory is required");
   const {
     resolver,
@@ -102,13 +110,14 @@ export function createGovernedHubResolver(ports, factory, sdkPorts) {
         const turn = await prepareGovernedModelTurn(factory, {
           mode: "hub-embedding",
           messages: [{ role: "user", content: profile }],
+          evolutionDisabled: options.evolutionDisabled === true,
         });
         // Chat projection prepends host provenance. Embed only the projected
         // profile: per-Run evidence IDs must not change semantic similarity.
-        const profileMessage = turn.messages[1];
+        const profileMessage = turn.messages[turn.governed ? 1 : 0];
         if (
-          turn.messages.length !== 2 ||
-          turn.messages[0].role !== "system" ||
+          turn.messages.length !== (turn.governed ? 2 : 1) ||
+          (turn.governed && turn.messages[0].role !== "system") ||
           profileMessage?.role !== "user" ||
           typeof profileMessage.content !== "string"
         )
@@ -133,7 +142,7 @@ export function createGovernedHubResolver(ports, factory, sdkPorts) {
   const model =
     resolver._llmStage &&
     new LLMStage({
-      llm: createGovernedHubLlm(llm, factory, {}, sdk),
+      llm: createGovernedHubLlm(llm, factory, options, sdk),
       acceptNonLocal: false,
     });
   return new EntityResolver({

package/src/lib/evolution/governed-hub-skill.js

@@ -9,6 +9,7 @@ export async function runGovernedHubSkill(
   name,
   options,
   sdkPorts,
+  modelTurnOptions = {},
 ) {
   let failure;
   let failed = false;
@@ -16,6 +17,7 @@ export async function runGovernedHubSkill(
     hub.llm,
     factory,
     {
+      evolutionDisabled: modelTurnOptions.evolutionDisabled === true,
       onFailure(error) {
         failure = error;
         failed = true;

package/src/lib/evolution/optional-ui-model-turn.js

@@ -12,9 +12,20 @@ export async function loadConfiguredUiEvolutionFactory(options = {}) {
 }
 
 export async function resolveServerEvolutionFactory(server) {
-  return typeof server.resolveEvolutionCompositionFactory === "function"
+  return typeof server?.resolveEvolutionCompositionFactory === "function"
     ? server.resolveEvolutionCompositionFactory()
-    : (server.evolutionCompositionFactory ?? null);
+    : (server?.evolutionCompositionFactory ?? null);
+}
+
+/** Apply the host's current UI policy for every turn, including old sessions. */
+export async function prepareServerUiModelTurn(server, context) {
+  if (typeof server?.prepareUiModelTurn === "function") {
+    return server.prepareUiModelTurn(context);
+  }
+  return prepareGovernedModelTurn(
+    await resolveServerEvolutionFactory(server),
+    context,
+  );
 }
 
 export async function prepareConfiguredUiModelTurn(context, options = {}) {

package/src/lib/llm-config-defaults.js

@@ -35,7 +35,12 @@
  * so an intentionally-custom endpoint is left untouched.
  */
 export async function reconcileConfigLlmProvider(cfgLlm = {}) {
-  if (!cfgLlm || !cfgLlm.provider || !cfgLlm.baseUrl) {
+  if (
+    !cfgLlm ||
+    !cfgLlm.provider ||
+    !cfgLlm.baseUrl ||
+    cfgLlm.provider === "custom"
+  ) {
     return { llm: cfgLlm, changed: false };
   }
   const { inferProviderFromBaseUrl, modelForeignToProvider } = await import(
@@ -71,22 +76,29 @@ export function applyConfigLlmDefaults(options = {}, cfgLlm = {}, opts = {}) {
   // credentials are exactly right. Mixing config into a DIFFERENT explicit
   // provider is still avoided (handled by the early return below).
   if (options.provider && configMatchesTarget) {
-    if (!options.baseUrl && cfgLlm.baseUrl) options.baseUrl = connection.baseUrl;
+    if (!options.baseUrl && cfgLlm.baseUrl)
+      options.baseUrl = connection.baseUrl;
     if (options.serviceTier == null && cfgLlm.serviceTier != null)
       options.serviceTier = cfgLlm.serviceTier;
-    if (!options.apiKey && connection.apiKey) options.apiKey = connection.apiKey;
+    if (!options.apiKey && connection.apiKey)
+      options.apiKey = connection.apiKey;
     if (!options.model && !opts.explicitModel && cfgLlm.model) {
       options.model = cfgLlm.model;
     }
     return options;
   }
   if (options.provider) {
-    if (!options.apiKey && connection.apiKey) options.apiKey = connection.apiKey;
+    if (!options.apiKey && connection.apiKey)
+      options.apiKey = connection.apiKey;
     return options;
   }
   if (!cfgLlm.provider) return options;
   options.provider = connection.provider;
-  if (configMatchesTarget && options.serviceTier == null && cfgLlm.serviceTier != null)
+  if (
+    configMatchesTarget &&
+    options.serviceTier == null &&
+    cfgLlm.serviceTier != null
+  )
     options.serviceTier = cfgLlm.serviceTier;
   if (opts.explicitModel) {
     options.model = opts.explicitModel;

package/src/lib/llm-connection-config.js

@@ -31,7 +31,10 @@ export function normalizeLlmConnection(input) {
     if (value[key].length > (key === "apiKey" ? 8192 : 2048))
       throw new Error(`${key} is too long`);
   }
-  if (!Object.hasOwn(BUILT_IN_PROVIDERS, value.provider))
+  if (
+    value.provider !== "custom" &&
+    !Object.hasOwn(BUILT_IN_PROVIDERS, value.provider)
+  )
     throw new Error("Choose a supported provider/protocol");
   if (!value.model || /[\r\n\0]/.test(value.model + value.visionModel))
     throw new Error("A valid model name is required");
@@ -84,7 +87,7 @@ export function saveLlmConnection(input, { storage = "auto" } = {}) {
         current.baseUrl || BUILT_IN_PROVIDERS[current.provider]?.baseUrl || "",
       ).replace(/\/+$/, "") === value.baseUrl;
     if (
-      value.provider !== "ollama" &&
+      !["ollama", "custom"].includes(value.provider) &&
       !value.apiKey &&
       (!sameEndpoint || !current.apiKey)
     )
@@ -98,6 +101,11 @@ export function saveLlmConnection(input, { storage = "auto" } = {}) {
       baseUrl: value.baseUrl,
       visionModel: value.visionModel || null,
     };
+    // A keyless custom endpoint must never receive the previous target's key.
+    if (!sameEndpoint && !value.apiKey && value.provider === "custom") {
+      delete config.llm.apiKey;
+      delete config.llm.apiKeyHelper;
+    }
   };
   // A single lock and atomic rename bind endpoint and credential together.
   // An interrupted save cannot route the old credential to the new endpoint.

package/src/lib/llm-connection-probe.js

@@ -3,6 +3,7 @@ import { estimateCost } from "./llm-pricing.js";
 import { providerFetch } from "./formal-budget-provider-scope.js";
 import { isFormalBudgetError } from "./formal-budget-errors.js";
 import { normalizeOllamaBaseUrl } from "./ollama-base-url.js";
+import { assertCustomProviderConnection } from "./provider-protocol.js";
 import { resolveModelCapabilityProfile } from "./model-capabilities.js";
 import {
   projectEnvelopePricingContext,
@@ -159,6 +160,7 @@ export async function probeLlmConnection(
   target,
   { fetchImpl = fetch, timeoutMs = 20_000, includeUsage = false } = {},
 ) {
+  assertCustomProviderConnection(target.provider, target);
   const base =
     target.provider === "ollama"
       ? normalizeOllamaBaseUrl(target.baseUrl)
@@ -183,7 +185,8 @@ export async function probeLlmConnection(
       options: { num_predict: PROBE_OUTPUT_TOKENS },
     };
   } else {
-    if (!target.apiKey) throw new Error("API key required");
+    if (!target.apiKey && target.provider !== "custom")
+      throw new Error("API key required");
     if (target.provider === "anthropic") {
       url = `${base}/messages`;
       headers["x-api-key"] = target.apiKey;
@@ -211,7 +214,7 @@ export async function probeLlmConnection(
       });
     } else {
       url = `${base}/chat/completions`;
-      headers.Authorization = `Bearer ${target.apiKey}`;
+      if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
       body = {
         model: target.model,
         messages: [{ role: "user", content: "Say hi in one word." }],

package/src/lib/llm-connection-resolution.js

@@ -1,6 +1,9 @@
 import { BUILT_IN_PROVIDERS } from "./llm-providers.js";
 import { normalizeOllamaBaseUrl } from "./ollama-base-url.js";
-import { normalizeProviderBaseUrl } from "./provider-protocol.js";
+import {
+  assertCustomProviderConnection,
+  normalizeProviderBaseUrl,
+} from "./provider-protocol.js";
 import { resolveApiKeyFromHelper } from "./api-key-helper.js";
 
 const DEFAULT_PROVIDER = "ollama";
@@ -33,9 +36,8 @@ export function resolveLlmConnection(
     defaultBaseUrl = null,
   } = {},
 ) {
-  const sources = (Array.isArray(configuredSources)
-    ? configuredSources
-    : [configuredSources]
+  const sources = (
+    Array.isArray(configuredSources) ? configuredSources : [configuredSources]
   ).filter((source) => source && typeof source === "object");
   const provider =
     (nonEmpty(options.provider) && options.provider) ||
@@ -67,6 +69,7 @@ export function resolveLlmConnection(
     defaultModel ||
     definition?.models?.[0] ||
     null;
+  assertCustomProviderConnection(provider, { baseUrl, model });
   let apiKey =
     (nonEmpty(options.apiKey) && options.apiKey) ||
     (nonEmpty(env?.CC_API_KEY) && env.CC_API_KEY) ||

package/src/lib/llm-providers.js

@@ -127,6 +127,19 @@ export const BUILT_IN_PROVIDERS = {
   },
 };
 
+/** Custom platforms use Chat Completions with an explicit endpoint and model. */
+export function resolveProviderDefinition(provider) {
+  return provider === "custom"
+    ? {
+        name: "custom",
+        baseUrl: null,
+        models: [],
+        apiKeyEnv: "CC_API_KEY",
+        custom: true,
+      }
+    : BUILT_IN_PROVIDERS[provider];
+}
+
 // A connectivity probe (`testProvider`) sends a tiny "Hi" and expects a quick
 // reply, so it must fail fast — a probe that hangs forever defeats its purpose
 // (it backs `cc llm test`, provider selection, doctor). Bound it with a total
@@ -402,17 +415,17 @@ export class LLMProviderRegistry {
       const res = await _fetchWithTimeout(
         `${normalizeProviderBaseUrl(provider.baseUrl)}/messages`,
         {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          "x-api-key": key,
-          "anthropic-version": "2023-06-01",
-        },
-        body: JSON.stringify({
-          model: testModel,
-          max_tokens: 10,
-          messages: [{ role: "user", content: "Hi" }],
-        }),
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "x-api-key": key,
+            "anthropic-version": "2023-06-01",
+          },
+          body: JSON.stringify({
+            model: testModel,
+            max_tokens: 10,
+            messages: [{ role: "user", content: "Hi" }],
+          }),
         },
       );
       if (!res.ok) throw new Error(`HTTP ${res.status}`);

package/src/lib/openai-responses.js

@@ -103,7 +103,8 @@ function sanitizeReasoningItems(items) {
       type: "reasoning",
       ...(id ? { id } : {}),
       ...(encryptedContent ? { encrypted_content: encryptedContent } : {}),
-      ...(summary.length ? { summary } : {}),
+      // Responses requires this field even when no summary was requested.
+      summary,
       ...(status ? { status } : {}),
     });
   }

package/src/lib/personal-data-hub-wiring.js

@@ -644,35 +644,44 @@ async function initHub() {
       // collector can pull WebView cookies from the user's Android Bilibili
       // App. The factory is a pure function — no side effects until the
       // handler is invoked, so cost of always-registering is zero.
-      const { createBilibiliCookiesExtension } =
-        await import("@chainlesschain/personal-data-hub/adapters/social-bilibili-adb");
+      const { createBilibiliCookiesExtension } = await import(
+        "@chainlesschain/personal-data-hub/adapters/social-bilibili-adb"
+      );
       // Phase 2a: register `douyin.pull-im-db` extension so the
       // douyinAdbSync hub method can pull <uid>_im.db cohort from the
       // user's Android Douyin App.
       const { createDouyinDbExtension, createDouyinWatchExtension } =
-        await import("@chainlesschain/personal-data-hub/adapters/social-douyin-adb");
+        await import(
+          "@chainlesschain/personal-data-hub/adapters/social-douyin-adb"
+        );
       // Phase 3a: register `weibo.cookies` extension for the Weibo
       // C-path collector (m.weibo.cn cookies + 4 HTTP endpoints).
-      const { createWeiboCookiesExtension } =
-        await import("@chainlesschain/personal-data-hub/adapters/social-weibo-adb");
+      const { createWeiboCookiesExtension } = await import(
+        "@chainlesschain/personal-data-hub/adapters/social-weibo-adb"
+      );
       // Phase 3c: register `xhs.cookies` extension for the Xhs C-path
       // collector (xiaohongshu.com cookies + 4 endpoints with X-S sign).
-      const { createXhsCookiesExtension } =
-        await import("@chainlesschain/personal-data-hub/adapters/social-xiaohongshu-adb");
+      const { createXhsCookiesExtension } = await import(
+        "@chainlesschain/personal-data-hub/adapters/social-xiaohongshu-adb"
+      );
       // Phase 6c: register `toutiao.cookies` extension for the Toutiao
       // C-path collector (www.toutiao.com cookies + 4 endpoints, 3 of
       // which need _signature signing — CLI context falls back to -99
       // short-circuit, desktop wiring upgrades via ToutiaoSignBridge).
       const { createToutiaoCookiesExtension, createToutiaoAccountExtension } =
-        await import("@chainlesschain/personal-data-hub/adapters/social-toutiao-adb");
+        await import(
+          "@chainlesschain/personal-data-hub/adapters/social-toutiao-adb"
+        );
       // Phase 6d: register `kuaishou.cookies` extension. Profile from
       // cookie's api_ph payload (no HTTP); 3 GraphQL POST endpoints need
       // __NS_sig3 + kpf/kpn — CLI short-circuits, desktop upgrades via
       // KuaishouSignBridge.
-      const { createKuaishouCookiesExtension } =
-        await import("@chainlesschain/personal-data-hub/adapters/social-kuaishou-adb");
-      const { createWhatsAppBackupExtension } =
-        await import("@chainlesschain/personal-data-hub/adapters/messaging-whatsapp");
+      const { createKuaishouCookiesExtension } = await import(
+        "@chainlesschain/personal-data-hub/adapters/social-kuaishou-adb"
+      );
+      const { createWhatsAppBackupExtension } = await import(
+        "@chainlesschain/personal-data-hub/adapters/messaging-whatsapp"
+      );
       hostAdbBridge = createHostAdbBridge({
         extensions: {
           "bilibili.cookies": createBilibiliCookiesExtension(),
@@ -1105,16 +1114,20 @@ async function initHub() {
     alipayAccountsPath,
     entityResolver,
     aichatAccountsStore,
-    async drainResolver(options = {}, factory = null) {
-      if (typeof factory !== "function") {
+    async drainResolver(options = {}, factory = null, modelTurnOptions = {}) {
+      if (
+        typeof factory !== "function" &&
+        !(factory === null && modelTurnOptions.evolutionDisabled === true)
+      ) {
         const error = new Error(
           "Personal Data Hub resolver egress requires an authenticated evolution composition factory",
         );
         error.code = "CC_AGENT_EVOLUTION_INGRESS_FAILED";
         throw error;
       }
-      const { createGovernedHubResolver } =
-        await import("./evolution/governed-hub-resolver.js");
+      const { createGovernedHubResolver } = await import(
+        "./evolution/governed-hub-resolver.js"
+      );
       const scoped = createGovernedHubResolver(
         {
           resolver: entityResolver,
@@ -1125,6 +1138,8 @@ async function initHub() {
           LLMStage: EntityResolverLLMStage,
         },
         factory,
+        undefined,
+        modelTurnOptions,
       );
       return scoped.drain(options);
     },
@@ -1656,8 +1671,9 @@ async function initHub() {
       }
       let collector;
       try {
-        const mod =
-          await import("@chainlesschain/personal-data-hub/adapters/social-bilibili-adb");
+        const mod = await import(
+          "@chainlesschain/personal-data-hub/adapters/social-bilibili-adb"
+        );
         collector = mod.default ? mod.default : mod;
       } catch (err) {
         return {
@@ -1708,8 +1724,9 @@ async function initHub() {
       }
       let collector;
       try {
-        const mod =
-          await import("@chainlesschain/personal-data-hub/adapters/social-douyin-adb");
+        const mod = await import(
+          "@chainlesschain/personal-data-hub/adapters/social-douyin-adb"
+        );
         collector = mod.default ? mod.default : mod;
       } catch (err) {
         return {
@@ -1752,8 +1769,9 @@ async function initHub() {
       }
       let collector;
       try {
-        const mod =
-          await import("@chainlesschain/personal-data-hub/adapters/social-douyin-adb");
+        const mod = await import(
+          "@chainlesschain/personal-data-hub/adapters/social-douyin-adb"
+        );
         collector = mod.default ? mod.default : mod;
       } catch (err) {
         return {
@@ -1799,8 +1817,9 @@ async function initHub() {
       }
       let collector;
       try {
-        const mod =
-          await import("@chainlesschain/personal-data-hub/adapters/social-weibo-adb");
+        const mod = await import(
+          "@chainlesschain/personal-data-hub/adapters/social-weibo-adb"
+        );
         collector = mod.default ? mod.default : mod;
       } catch (err) {
         return {
@@ -1852,8 +1871,9 @@ async function initHub() {
       }
       let collector;
       try {
-        const mod =
-          await import("@chainlesschain/personal-data-hub/adapters/social-xiaohongshu-adb");
+        const mod = await import(
+          "@chainlesschain/personal-data-hub/adapters/social-xiaohongshu-adb"
+        );
         collector = mod.default ? mod.default : mod;
       } catch (err) {
         return {
@@ -1905,8 +1925,9 @@ async function initHub() {
       }
       let collector;
       try {
-        const mod =
-          await import("@chainlesschain/personal-data-hub/adapters/social-toutiao-adb");
+        const mod = await import(
+          "@chainlesschain/personal-data-hub/adapters/social-toutiao-adb"
+        );
         collector = mod.default ? mod.default : mod;
       } catch (err) {
         return {
@@ -1960,8 +1981,9 @@ async function initHub() {
       }
       let collector;
       try {
-        const mod =
-          await import("@chainlesschain/personal-data-hub/adapters/social-kuaishou-adb");
+        const mod = await import(
+          "@chainlesschain/personal-data-hub/adapters/social-kuaishou-adb"
+        );
         collector = mod.default ? mod.default : mod;
       } catch (err) {
         return {
@@ -2149,11 +2171,19 @@ export async function getHub() {
   return _initPromise;
 }
 
-export async function getGovernedAnalysisHub(evolutionCompositionFactory) {
+export async function getGovernedAnalysisHub(
+  evolutionCompositionFactory,
+  modelTurnOptions = {},
+) {
   const hub = await getHub();
-  const { createGovernedHubLlm } =
-    await import("./evolution/governed-hub-llm.js");
-  const llm = createGovernedHubLlm(hub.engine.llm, evolutionCompositionFactory);
+  const { createGovernedHubLlm } = await import(
+    "./evolution/governed-hub-llm.js"
+  );
+  const llm = createGovernedHubLlm(
+    hub.engine.llm,
+    evolutionCompositionFactory,
+    modelTurnOptions,
+  );
   const engine = new AnalysisEngine({
     vault: hub.engine.vault,
     llm,
@@ -2162,8 +2192,9 @@ export async function getGovernedAnalysisHub(evolutionCompositionFactory) {
     maxQueryLimit: hub.engine.maxQueryLimit,
     systemPrompt: hub.engine.systemPrompt,
   });
-  const { runGovernedHubSkill } =
-    await import("./evolution/governed-hub-skill.js");
+  const { runGovernedHubSkill } = await import(
+    "./evolution/governed-hub-skill.js"
+  );
   return Object.freeze({
     ...hub,
     llm,
@@ -2175,6 +2206,8 @@ export async function getGovernedAnalysisHub(evolutionCompositionFactory) {
         runAnalysisSkill,
         name,
         options,
+        undefined,
+        modelTurnOptions,
       ),
   });
 }

package/src/lib/provider-protocol.js

@@ -4,6 +4,29 @@ export function normalizeProviderBaseUrl(baseUrl) {
   return String(baseUrl || "").replace(/\/+$/u, "");
 }
 
+/** Validate custom targets without assuming a vendor, path, model, or key. */
+export function assertCustomProviderConnection(provider, { baseUrl, model }) {
+  if (provider !== "custom") return;
+  let url;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    throw new Error("Custom provider requires an HTTP(S) API base URL");
+  }
+  if (
+    !["http:", "https:"].includes(url.protocol) ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash
+  )
+    throw new Error(
+      "Custom provider requires an HTTP(S) API base URL without credentials, query or fragment",
+    );
+  if (typeof model !== "string" || !model.trim())
+    throw new Error("Custom provider requires an explicit model name");
+}
+
 /**
  * Google's OpenAI-compatible API lives below `/v1beta/openai`. The provider
  * registry stores the native API root (`/v1beta`), so adapt only that exact
@@ -28,7 +51,11 @@ export function openAICompatibleBaseUrl(provider, baseUrl) {
   return base;
 }
 
-export function geminiGenerateContentUrl(baseUrl, model, { stream = false } = {}) {
+export function geminiGenerateContentUrl(
+  baseUrl,
+  model,
+  { stream = false } = {},
+) {
   const action = stream ? "streamGenerateContent" : "generateContent";
   const endpoint = `${normalizeProviderBaseUrl(baseUrl)}/models/${encodeURIComponent(model)}:${action}`;
   return stream ? `${endpoint}?alt=sse` : endpoint;
@@ -58,7 +85,10 @@ export function geminiRequestBody(
       continue;
     }
     contents.push({
-      role: message.role === "assistant" || message.role === "model" ? "model" : "user",
+      role:
+        message.role === "assistant" || message.role === "model"
+          ? "model"
+          : "user",
       parts,
     });
   }
@@ -66,7 +96,9 @@ export function geminiRequestBody(
   if (Number.isFinite(temperature)) generationConfig.temperature = temperature;
   return {
     contents,
-    ...(systemParts.length ? { systemInstruction: { parts: systemParts } } : {}),
+    ...(systemParts.length
+      ? { systemInstruction: { parts: systemParts } }
+      : {}),
     generationConfig,
   };
 }

package/src/lib/provider-stream.js

@@ -8,10 +8,11 @@ import {
  * of token deltas suitable for piping through session-core StreamRouter.
  */
 
-import { BUILT_IN_PROVIDERS } from "./llm-providers.js";
+import { resolveProviderDefinition } from "./llm-providers.js";
 import { normalizeOllamaBaseUrl } from "./ollama-base-url.js";
 import { ollamaProviderFetch } from "./ollama-provider-fetch.js";
 import {
+  assertCustomProviderConnection,
   geminiGenerateContentUrl,
   geminiRequestBody,
   normalizeProviderBaseUrl,
@@ -111,7 +112,7 @@ export async function* openAIStream({
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        Authorization: `Bearer ${apiKey}`,
+        ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
       },
       body: JSON.stringify({
         model,
@@ -276,6 +277,7 @@ export async function* anthropicTokenStream({
  * Throws on unsupported provider / missing API key.
  */
 export function buildProviderSource(provider, opts = {}) {
+  assertCustomProviderConnection(provider, opts);
   const {
     model,
     baseUrl,
@@ -295,11 +297,11 @@ export function buildProviderSource(provider, opts = {}) {
       requireCompletion,
     });
   }
-  const def = BUILT_IN_PROVIDERS[provider];
+  const def = resolveProviderDefinition(provider);
   if (!def) throw new Error(`Unsupported provider: ${provider}`);
   const finalKey =
     apiKey || (def.apiKeyEnv ? process.env[def.apiKeyEnv] : null);
-  if (!finalKey) {
+  if (!finalKey && provider !== "custom") {
     throw new Error(
       `API key required for ${provider} (--api-key or ${def.apiKeyEnv})`,
     );

package/src/lib/runnable-provider.js

@@ -146,6 +146,8 @@ export function makeRunnableProviderFallback(
   // react to an auth failure AND pre-empt the known-bad attempt on later turns.
   const computeFallback = (options) => {
     const failed = options.provider;
+    // A custom protocol selection is intentional, including on localhost.
+    if (failed === "custom") return null;
     const inferred = inferProviderFromBaseUrl(options.baseUrl);
     if (inferred && inferred !== failed) {
       return {
@@ -269,6 +271,8 @@ export function hasUsableKey(
   provider,
   { apiKey, isActive = true, env = process.env } = {},
 ) {
+  // Custom platforms may be keyless; connection validation checks their target.
+  if (provider === "custom") return true;
   const def = BUILT_IN_PROVIDERS[provider];
   if (!def) return false;
   if (!def.apiKeyEnv) return true; // keyless local provider (e.g. ollama)