@jskit-ai/assistant-core 0.2.18 → 0.2.20

package/CHANGELOG.md

@@ -7,7 +7,10 @@
 - The OpenCode version mismatch, Claude control-request timeout and unreadable saved Claude conversation errors carry `params` for their catalog English.
 - The assistant settings resource sends its system prompt field messages in the coded `{ code, message, params }` form.
 
-### New message keys (163)
+- Custom model endpoints: `customAiProvider({ engineId, baseUrl, model, contextWindow })` (with `CUSTOM_AI_PROVIDER_ID`, `CUSTOM_AI_MINIMUM_CONTEXT`, `CUSTOM_AI_PLACEHOLDER_TOKEN` and `connectionAiProvider`) in `shared/native-providers` describes a model server the host's user runs, such as Ollama, LM Studio, `llama-server` or vLLM, in the native provider shape, so Codex, Claude Code and the Colleague drivers connect to it. Codex gets no bearer token without a key, no freeform `apply_patch` and no parallel tool calls; Claude Code always gets a token (the key, or `local`) so a saved claude.ai login never reaches the endpoint, its model in every slot and an output limit of a quarter of the context. The Codex history adapter routes `custom~<base64url(baseUrl)>` to plain `http(s)` upstreams only and ends a turn whose server is down with `assistant_custom_endpoint_unreachable`. `readCodexCustomModels(codexHome)` reads a custom Codex home's catalogue.
+- `server/custom-endpoint` adds `checkCustomEndpoint` (one bounded request on the engine's own API, up to 2 minutes, then Ollama's loaded context from `/api/ps`, refusing one smaller than entered), `verifyCustomEndpoint`, `readOllamaLoadedContext` and `probeCustomEndpoint` (one model-list read for health). Errors carry `custom_endpoint_*` codes and say what to fix.
+
+### New message keys (164)
 
 <details><summary>Key list</summary>
 
@@ -174,10 +177,11 @@
 - `jskit.errors.assistant_tool_output_invalid`
 - `jskit.errors.assistant_tool_unknown`
 - `jskit.errors.assistant_claude_control_timeout`
+- `jskit.errors.assistant_custom_endpoint_unreachable`
 
 </details>
 
-### Codes (163)
+### Codes (164)
 
 Error, field-error and message codes this package now sends, with their English. Undotted codes kept their existing values and render from `jskit.errors.<code>`.
 
@@ -346,6 +350,7 @@ Error, field-error and message codes this package now sends, with their English.
 | `assistant_tool_output_invalid` | Assistant tool output validation failed. |
 | `assistant_tool_unknown` | Unknown tool. |
 | `assistant_claude_control_timeout` | Claude {request} timed out. |
+| `assistant_custom_endpoint_unreachable` | Your model server at {upstream} isn't answering. Start it, then send your message again. |
 
 ## 0.2.0 - 2026-10-29
 

package/examples/conversation/package.json

@@ -8,14 +8,14 @@
     "build": "vite build"
   },
   "dependencies": {
-    "@jskit-ai/assistant-core": "0.2.18",
-    "@jskit-ai/http-runtime": "0.2.8",
-    "@jskit-ai/kernel": "0.2.8",
+    "@jskit-ai/assistant-core": "0.2.20",
+    "@jskit-ai/http-runtime": "0.2.9",
+    "@jskit-ai/kernel": "0.2.9",
     "@mdi/js": "^7.4.47",
     "vue": "^3.5.13",
     "vuetify": "^4.0.0",
-    "@jskit-ai/connectors-core": "0.2.9",
-    "@jskit-ai/connectors-catalog": "0.2.9"
+    "@jskit-ai/connectors-core": "0.2.10",
+    "@jskit-ai/connectors-catalog": "0.2.10"
   },
   "devDependencies": {
     "@vitejs/plugin-vue": "^6.0.7",

package/locales/en.json

@@ -530,6 +530,7 @@
       "assistant_codex_provider_switch_busy": "Stop the current turn before immediately changing model providers.",
       "assistant_codex_history_request_too_large": "Codex history exceeds the adapter request limit.",
       "assistant_codex_history_request_unreadable": "Codex sent an unreadable or oversized history request.",
+      "assistant_custom_endpoint_unreachable": "Your model server at {upstream} isn't answering. Start it, then send your message again.",
       "assistant_codex_app_server_message_too_large": "Codex app-server message exceeded the configured transport limit.",
       "codex_reconnect_required": "Sign in with codex login before continuing.",
       "codex_provider_connection_changed": "This Codex provider connection changed. Work is stopped; use Send or Resume after reconnecting.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant-core",
-  "version": "0.2.18",
+  "version": "0.2.20",
   "type": "module",
   "scripts": {
     "test": "node --test --test-concurrency=1"
@@ -30,6 +30,7 @@
     "./server/opencode-turn": "./src/server/hosts/openCodeTurn.js",
     "./server/opencode-process": "./src/server/hosts/openCodeProcess.js",
     "./shared/native-providers": "./src/shared/nativeProviders.js",
+    "./server/custom-endpoint": "./src/server/hosts/customEndpoint.js",
     "./server/codex-provider": "./src/server/hosts/codexProvider.js",
     "./server/native-history": "./src/server/hosts/nativeHistory.js",
     "./testing/native-codex": "./src/testing/nativeCodex.js",
@@ -51,8 +52,8 @@
     "@ai-sdk/togetherai": "^3.0.49",
     "@ai-sdk/xai": "^4.0.58",
     "@jskit-ai/agent": "0.1.1",
-    "@jskit-ai/resource-core": "0.1.199",
-    "@jskit-ai/resource-crud-core": "0.1.199",
+    "@jskit-ai/resource-core": "0.1.200",
+    "@jskit-ai/resource-crud-core": "0.1.200",
     "@mdi/js": "^7.4.47",
     "@openrouter/ai-sdk-provider": "^3.0.0",
     "ai": "^7.0.152",
@@ -61,8 +62,8 @@
     "ws": "^8.20.1"
   },
   "peerDependencies": {
-    "@jskit-ai/http-runtime": "0.2.8",
-    "@jskit-ai/kernel": "0.2.8",
+    "@jskit-ai/http-runtime": "0.2.9",
+    "@jskit-ai/kernel": "0.2.9",
     "vue": "^3.5.13",
     "vuetify": "^4.0.0"
   },
@@ -178,6 +179,10 @@
             "subpath": "./shared/native-providers",
             "summary": "Advanced native host: Exact native provider routes, engine configuration facts and qualified model capabilities; applications choose which models to offer."
           },
+          {
+            "subpath": "./server/custom-endpoint",
+            "summary": "Advanced native host: Checks of a model server the person runs: one connect-time request on the engine's own API, the context Ollama really loaded, and a model-list read for health."
+          },
           {
             "subpath": "./server/codex-provider",
             "summary": "Advanced native host: Original Codex provider acquisition, thread selection, control, recovery, native history retirement and private renewal identity operations."

package/src/server/conversation/claudeProcess.js

@@ -1,5 +1,5 @@
 import { jsonHash } from "./normalize.js";
-import { nativeAiProvider } from "../../shared/nativeProviders.js";
+import { CUSTOM_AI_PLACEHOLDER_TOKEN, CUSTOM_AI_PROVIDER_ID, connectionAiProvider, nativeAiProvider } from "../../shared/nativeProviders.js";
 import { Duplex } from "node:stream";
 import { stat } from "node:fs/promises";
 import { homedir } from "node:os";
@@ -132,18 +132,24 @@ export function claudeConnectionIdentity(configRoot, providerId, baseUrl, apiKey
 
 /** Native provider routing; the application supplies only its authorized selection. */
 export function claudeModelConfiguration({ providerId, model: modelId }, connection) {
-  const provider = nativeAiProvider(providerId);
+  const provider = connectionAiProvider(providerId, connection);
   const definition = provider?.models.find(({ id }) => id === modelId);
-  if (provider && (!definition || !connection?.apiKey)) throw Object.assign(new Error("Choose a connected Claude Code model."), {
+  if ((provider || providerId === CUSTOM_AI_PROVIDER_ID) &&
+      (!definition || !(connection?.apiKey || provider.custom))) throw Object.assign(new Error("Choose a connected Claude Code model."), {
     messageCode: "assistant.claude.chooseConnectedModel", messageParams: {}
   });
-  const model = definition?.contextWindow >= 1000000 ? `${definition.id}[1m]` : modelId;
+  const model = !provider?.custom && definition?.contextWindow >= 1000000 ? `${definition.id}[1m]` : modelId;
+  // A custom endpoint's own window: Claude Code assumes 200K and 32K output for
+  // a model it does not know, past what most model servers load.
+  const outputTokens = provider?.custom ? Math.min(32000, Math.floor(definition.contextWindow / 4)) : 0;
   const externalModel = provider ? model : "";
   // Reset every provider override when returning to the native subscription.
   // Background calls and subagents must stay on the selected provider too.
   const env = {
     ANTHROPIC_BASE_URL: connection?.baseUrl || "https://api.anthropic.com",
-    ANTHROPIC_AUTH_TOKEN: connection?.apiKey || "", ANTHROPIC_API_KEY: "", CLAUDE_CODE_OAUTH_TOKEN: "",
+    // Never empty for a custom endpoint, so the saved claude.ai login is not sent there.
+    ANTHROPIC_AUTH_TOKEN: connection?.apiKey || (provider?.custom ? CUSTOM_AI_PLACEHOLDER_TOKEN : ""),
+    ANTHROPIC_API_KEY: "", CLAUDE_CODE_OAUTH_TOKEN: "",
     ANTHROPIC_MODEL: externalModel, ANTHROPIC_DEFAULT_MODEL: externalModel,
     ANTHROPIC_DEFAULT_OPUS_MODEL: externalModel,
     ANTHROPIC_DEFAULT_SONNET_MODEL: externalModel,
@@ -151,6 +157,7 @@ export function claudeModelConfiguration({ providerId, model: modelId }, connect
     ANTHROPIC_DEFAULT_HAIKU_MODEL: definition?.id || "",
     CLAUDE_CODE_SUBAGENT_MODEL: definition?.id || "",
     CLAUDE_CODE_AUTO_COMPACT_WINDOW: provider ? String(provider.claudeAutoCompactWindow) : "",
+    CLAUDE_CODE_MAX_OUTPUT_TOKENS: outputTokens ? String(outputTokens) : "",
     CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: provider ? "1" : "",
     CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST: "1"
   };
@@ -244,7 +251,7 @@ export async function stopClaudeCodeProcess({ process: native, executionId, stop
 
 export async function bindClaudeConversationAccount(entry, { identity, providerId, allowAccountChange = false, stop, save }) {
   entry.accountIdentities ||= {};
-  if (!nativeAiProvider(providerId) && entry.accountIdentities[providerId] && entry.accountIdentities[providerId] !== identity) {
+  if (!nativeAiProvider(providerId) && providerId !== CUSTOM_AI_PROVIDER_ID && entry.accountIdentities[providerId] && entry.accountIdentities[providerId] !== identity) {
     await stop(entry, "The signed-in Claude account changed.");
     if (!allowAccountChange) {
       throw Object.assign(new Error("This conversation belongs to another Claude account. Reconnect that account or start a new session."), {

package/src/server/conversation/codexConfiguration.js

@@ -320,7 +320,7 @@ export function codexProviderModelCatalog({ models }) {
       context_window: model.contextWindow,
       max_context_window: model.contextWindow,
       effective_context_window_percent: 95,
-      supports_parallel_tool_calls: true,
+      supports_parallel_tool_calls: model.parallelToolCalls !== false,
       experimental_supported_tools: [],
       input_modalities: model.images ? ["text", "image"] : ["text"],
       prefer_websockets: false,
@@ -336,7 +336,9 @@ export function codexProviderConfiguration(provider, apiKey) {
     web_search: provider.webSearch ? "live" : "disabled",
     [`model_providers.${provider.id}`]: {
       name: provider.label || provider.id, base_url: provider.baseUrl, wire_api: "responses",
-      requires_openai_auth: false, experimental_bearer_token: apiKey
+      requires_openai_auth: false,
+      // A custom endpoint may need no key; Codex then sends no Authorization header.
+      ...(apiKey ? { experimental_bearer_token: apiKey } : {})
     }
   };
 }
@@ -356,7 +358,7 @@ export function codexProviderFileConfiguration(provider, key, codexHome) {
     `model = ${JSON.stringify(provider.models[0].id)}`,
     `model_provider = ${JSON.stringify(provider.id)}`,
     codexProviderCatalogSetting(codexHome),
-    `model_reasoning_effort = ${JSON.stringify(provider.models[0].defaultThinking)}`,
+    ...(provider.models[0].defaultThinking ? [`model_reasoning_effort = ${JSON.stringify(provider.models[0].defaultThinking)}`] : []),
     'model_reasoning_summary = "none"',
     `web_search = "${provider.webSearch ? "live" : "disabled"}"`,
     `[model_providers.${provider.id}]`,
@@ -364,11 +366,27 @@ export function codexProviderFileConfiguration(provider, key, codexHome) {
     `base_url = ${JSON.stringify(provider.baseUrl)}`,
     'wire_api = "responses"',
     'requires_openai_auth = false',
-    `experimental_bearer_token = ${JSON.stringify(key)}`,
+    ...(key ? [`experimental_bearer_token = ${JSON.stringify(key)}`] : []),
     ""
   ].join("\n");
 }
 
+/**
+ * The catalogue rows of a home codexProviderFileConfiguration wrote for a
+ * custom endpoint, whose model only its saved connection names; none for any
+ * other home.
+ */
+export async function readCodexCustomModels(codexHome) {
+  const config = await readFile(path.join(codexHome, "config.toml"), "utf8").catch((error) => {
+    if (error.code === "ENOENT") return "";
+    throw error;
+  });
+  if (!/^model_provider = "custom"$/mu.test(config)) return [];
+  const catalogue = JSON.parse(await readFile(codexProviderCatalogPath(codexHome), "utf8"));
+  if (!Array.isArray(catalogue?.models)) throw new Error("Codex custom endpoint home is incomplete.");
+  return catalogue.models;
+}
+
 /**
  * Copy a curated provider home's config and catalogue into another home, with
  * the copied config naming the copied catalogue. A config that does not name

package/src/server/conversation/codexHistoryAdapter.js

@@ -6,7 +6,7 @@ import path from "node:path";
 import { Readable } from "node:stream";
 import { isDeepStrictEqual } from "node:util";
 import { gunzipSync, zstdDecompressSync } from "node:zlib";
-import { nativeAiModel, nativeAiProvider } from "../../shared/nativeProviders.js";
+import { CUSTOM_AI_PROVIDER_ID, nativeAiModel, nativeAiProvider } from "../../shared/nativeProviders.js";
 
 const MAX_REQUEST_BYTES = 32 * 1024 * 1024;
 const UPSTREAMS = Object.freeze({
@@ -19,6 +19,28 @@ const UPSTREAMS = Object.freeze({
 const HOP_HEADERS = ["connection", "keep-alive", "proxy-authenticate", "proxy-authorization",
   "te", "trailer", "transfer-encoding", "upgrade"];
 
+// A custom endpoint's route segment carries its own base URL, so any runtime can
+// reach the endpoint a thread names; its single model is qualified for history
+// recovery like the curated routes.
+function historyRouted(destination) {
+  return Boolean(nativeAiProvider(destination) || destination === CUSTOM_AI_PROVIDER_ID);
+}
+
+function customRouteSegment(baseUrl) {
+  return `${CUSTOM_AI_PROVIDER_ID}~${Buffer.from(baseUrl.replace(/\/$/u, "")).toString("base64url")}`;
+}
+
+function customUpstream(encoded = "") {
+  let url;
+  try {
+    url = new URL(Buffer.from(encoded, "base64url").toString("utf8"));
+  } catch {
+    return undefined;
+  }
+  return ["http:", "https:"].includes(url.protocol) && !url.username && !url.password && !url.search && !url.hash
+    ? url.href.replace(/\/$/u, "") : undefined;
+}
+
 function unsupportedHistory(message) {
   return new AppError(422, message, { code: "assistant_codex_history_unsupported" });
 }
@@ -170,9 +192,10 @@ async function* readCodexHistoryRows(file, start, end, signal, { strictComplete
 // cannot read OpenAI's encrypted replacement. Recover that exact boundary as
 // historical data, only when it is actually present in a foreign request.
 async function restoreCompactedHistory(body, { destination, historyPath, codexHome, signal, maxRequestBytes }) {
-  if (!nativeAiProvider(destination) || !Array.isArray(body?.input) ||
+  if (!historyRouted(destination) || !Array.isArray(body?.input) ||
       !body.input.some((item) => item?.type === "compaction")) return body;
-  const model = nativeAiModel(body.model, destination);
+  const model = destination === CUSTOM_AI_PROVIDER_ID ? { modelProviderId: destination, codexHistoryRouting: true }
+    : nativeAiModel(body.model, destination);
   if (model?.modelProviderId !== destination || !model.codexHistoryRouting) {
     throw compactionHistoryError("this model has not been qualified for history recovery.");
   }
@@ -342,8 +365,8 @@ async function startCodexHistoryAdapter({ token, codexHome, readHistoryPath = re
     try {
       const url = new URL(request.url, "http://127.0.0.1");
       const parts = url.pathname.split("/");
-      const destination = parts[3];
-      const upstream = UPSTREAMS[destination];
+      const [destination, encodedUpstream] = (parts[3] || "").split("~", 2);
+      const upstream = destination === CUSTOM_AI_PROVIDER_ID ? customUpstream(encodedUpstream) : UPSTREAMS[destination];
       const hasHistory = parts[4] === "history";
       let historyPath = hasHistory ? Buffer.from(parts[5] || "", "base64url").toString("utf8") : "";
       const route = parts.slice(hasHistory ? 6 : 4).join("/");
@@ -370,7 +393,7 @@ async function startCodexHistoryAdapter({ token, codexHome, readHistoryPath = re
         } catch {
           throw new AppError(400, "Codex sent an unreadable or oversized history request.", { code: "assistant_codex_history_request_unreadable" });
         }
-        if (!historyPath && nativeAiProvider(destination) && Array.isArray(body?.input) && body.input.some(item => item?.type === "compaction")) {
+        if (!historyPath && historyRouted(destination) && Array.isArray(body?.input) && body.input.some(item => item?.type === "compaction")) {
           // An exclusively owned conversation can resolve its current native
           // file, including compaction during its very first turn.
           historyPath = await readHistoryPath(abort.signal);
@@ -381,9 +404,17 @@ async function startCodexHistoryAdapter({ token, codexHome, readHistoryPath = re
       }
       const headers = forwardedHeaders(request.headers);
       headers.set("accept-encoding", "identity");
-      const result = await fetchImpl(`${upstream}/${route}${url.search}`, {
-        method: request.method, headers, body, signal: abort.signal, redirect: "error"
-      });
+      let result;
+      try {
+        result = await fetchImpl(`${upstream}/${route}${url.search}`, {
+          method: request.method, headers, body, signal: abort.signal, redirect: "error"
+        });
+      } catch (error) {
+        // The owner's own server is down more often than a provider: say which and what to do.
+        if (destination !== CUSTOM_AI_PROVIDER_ID || abort.signal.aborted) throw error;
+        throw Object.assign(new AppError(502, `Your model server at ${upstream} isn't answering. Start it, then send your message again.`,
+          { code: "assistant_custom_endpoint_unreachable" }), { params: { upstream } });
+      }
       // DeepSeek labels this explicit context rejection as a generic invalid
       // request. Preserve the provider's details while exposing the native
       // recovery code; the adapter never retries the rejected inference.
@@ -446,13 +477,18 @@ async function prepareCodexHistory(params, client, { baseUrl, modelProviderId, .
   if (!baseUrl) return params;
   const modelProvider = params.modelProvider || modelProviderId || "openai";
   const curatedProvider = nativeAiProvider(modelProvider);
-  if (curatedProvider) {
+  if (curatedProvider || modelProvider === CUSTOM_AI_PROVIDER_ID) {
     const configKey = `model_providers.${modelProvider}`;
     const config = params.config?.[configKey];
     // Only the curated route owns these credentials. Do not redirect an
-    // unrelated custom provider to our fixed upstream.
-    const providerUrl = `${baseUrl}/${modelProvider}`;
-    if (config?.base_url !== curatedProvider.baseUrl &&
+    // unrelated provider to our fixed upstream. The custom endpoint's route
+    // names the base URL its thread configuration gave.
+    if (!curatedProvider && typeof config?.base_url !== "string") return params;
+    const customPrefix = `${baseUrl}/${CUSTOM_AI_PROVIDER_ID}~`;
+    const providerUrl = curatedProvider ? `${baseUrl}/${modelProvider}`
+      : config.base_url.startsWith(customPrefix) ? `${baseUrl}/${config.base_url.slice(baseUrl.length + 1).split("/")[0]}`
+        : `${baseUrl}/${customRouteSegment(config.base_url)}`;
+    if (curatedProvider && config?.base_url !== curatedProvider.baseUrl &&
         config?.base_url !== providerUrl && !config?.base_url?.startsWith(`${providerUrl}/history/`)) return params;
     let historyPath = options.historyPath;
     if (!historyPath && options.threadId) {

package/src/server/conversation/codexNotificationObserver.js

@@ -1,4 +1,4 @@
-import { codexAppServerTurnStatusIsActive, codexAppServerTurnStatusIsSuccessfulComplete, codexAppServerTurnStatusIsProviderFailure, CODEX_APP_SERVER_AGENT_RUN_ID, CODEX_AGENT_PROVIDER, CODEX_APP_SERVER_RUN_STATE } from "./codexTurnState.js";
+import { codexAppServerTurnStatusIsActive, codexAppServerTurnStatusIsSuccessfulComplete, codexAppServerTurnStatusIsProviderFailure, codexAppServerTurnKey, CODEX_APP_SERVER_AGENT_RUN_ID, CODEX_AGENT_PROVIDER, CODEX_APP_SERVER_RUN_STATE } from "./codexTurnState.js";
 import { codexAppServerProviderConnectionGeneration } from "./codexModelCatalog.js";
 import {
   codexAppServerAssistantItemText,
@@ -239,6 +239,8 @@ export function createCodexNotificationObserver({
         threadId: normalizedThreadId,
         turnId: codexAppServerNotificationTurnId(notification)
       };
+      // Anything Codex reports about a turn means it has started that turn.
+      journal.unstartedTurns.delete(codexAppServerTurnKey(normalizedThreadId, notificationContext.turnId));
       if (method === "thread/tokenUsage/updated") {
         notificationQueue.run(notificationContext, async () => {
           const store = await createStore(normalizedSessionId);

package/src/server/conversation/codexProcess.js

@@ -7,7 +7,7 @@ import { setTimeout as delay } from "node:timers/promises";
 import { createConversationProcessIdentity } from "./processIdentity.js";
 import { isRecord, normalizePositiveInteger } from "@jskit-ai/kernel/shared/support/normalize";
 import { normalizeNullableText } from "./normalize.js";
-import { prepareCodexModelCatalog } from "./codexConfiguration.js";
+import { prepareCodexModelCatalog, readCodexCustomModels } from "./codexConfiguration.js";
 import { startCodexHistoryAdapter } from "./codexHistoryAdapter.js";
 
 const CODEX_APP_SERVER_METADATA_FILE = "runtime.json";
@@ -28,11 +28,13 @@ export async function runCodexAppServerProcess({
   process.once("SIGTERM", abortStartup);
   process.once("SIGINT", abortStartup);
   const codexHome = env.CODEX_HOME || path.join(os.homedir(), ".codex");
+  // A custom endpoint's home brings its own model's catalogue row.
+  const customModels = await readCodexCustomModels(codexHome);
   const catalogPath = await prepareCodexModelCatalog({
     command,
     runtimeDir,
     bundled,
-    additionalModels,
+    additionalModels: [...additionalModels, ...customModels],
     codexHome,
     signal: startup.signal
   });

package/src/server/conversation/codexPromptDispatch.js

@@ -1,4 +1,4 @@
-import { codexAppServerTurnStatusIsSuccessfulComplete, codexAppServerTurnStatusIsProviderFailure, codexAppServerErrorMessage, codexAppServerSteerFailure, codexAppServerMessageRequiresNewTurn, codexAppServerMessageDeferred } from "./codexTurnState.js";
+import { codexAppServerTurnStatusIsComplete, codexAppServerTurnStatusIsSuccessfulComplete, codexAppServerTurnStatusIsProviderFailure, codexAppServerErrorMessage, codexAppServerSteerFailure, codexAppServerMessageRequiresNewTurn, codexAppServerMessageDeferred, codexAppServerTurnKey } from "./codexTurnState.js";
 import { codexAppServerRequestIsInvalid } from "./codexProviderThreads.js";
 import { codexLocalImageInput, codexAppServerDeliveredTurn, sendCodexAppServerPrompt } from "./codexProviderTurns.js";
 import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
@@ -74,6 +74,10 @@ export function createCodexPromptDispatch({
     if (!deliveredTurnId) {
       throw new Error("Codex app-server accepted the prompt without returning a turn id.");
     }
+    // Codex answers turn/start before it starts the turn; its notifications about the turn say when it has.
+    if (!codexAppServerTurnStatusIsComplete(deliveredTurnStatus)) {
+      journal.unstartedTurns.add(codexAppServerTurnKey(threadId, deliveredTurnId));
+    }
     delivery.pendingUserMessage(promptSessionId, clientUserMessageId)?.onNativeReceipt();
     await recovery.markTurnActive(sessionId, {
       requireTrackedTurn: true,

package/src/server/conversation/codexRunJournal.js

@@ -88,6 +88,8 @@ export function createCodexRunJournal({
   isClosing
 }) {
   const codexAppServerCompletedTurns = new Set();
+  // Turns Codex accepted with turn/start but has not yet reported: until it does, its thread still reads idle.
+  const codexAppServerUnstartedTurns = new Set();
   const codexAppServerProcessedTurns = new Set();
   const codexAppServerActiveTimers = new Map();
   const codexAppServerFinalizingTimers = new Map();
@@ -637,6 +639,7 @@ export function createCodexRunJournal({
 
   return Object.freeze({
     completedTurns: codexAppServerCompletedTurns,
+    unstartedTurns: codexAppServerUnstartedTurns,
     processedTurns: codexAppServerProcessedTurns,
     activeTimers: codexAppServerActiveTimers,
     finalizingTimers: codexAppServerFinalizingTimers,

package/src/server/conversation/codexThreadStatus.js

@@ -1,4 +1,4 @@
-import { codexAppServerTurnStatusIsActive, codexAppServerTurnStatusIsComplete, codexAppServerTurnStatusIsSuccessfulComplete, codexAppServerTurnStatusIsProviderFailure, codexAppServerThreadStatus, codexAppServerReadThreadStatus, codexAppServerAgentRun, codexAppServerTurnCanReceiveProviderCompletion, codexAppServerTurnCanAdoptSuccessor, codexAppServerErrorMessage } from "./codexTurnState.js";
+import { codexAppServerTurnStatusIsActive, codexAppServerTurnStatusIsComplete, codexAppServerTurnStatusIsSuccessfulComplete, codexAppServerTurnStatusIsProviderFailure, codexAppServerThreadStatus, codexAppServerReadThreadStatus, codexAppServerAgentRun, codexAppServerTurnCanReceiveProviderCompletion, codexAppServerTurnCanAdoptSuccessor, codexAppServerErrorMessage, codexAppServerTurnKey } from "./codexTurnState.js";
 import { isRecord, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import { codexAppServerStatusFromValue } from "./codexEvents.js";
 import { codexAppServerThreadRawValue, codexAppServerThreadTurnId, codexAppServerThreadError } from "./codexThreadSnapshot.js";
@@ -200,6 +200,27 @@ export function createCodexThreadStatus({ journal, settlement, recovery, output,
         turnId
       };
     }
+    // Codex has accepted the tracked turn but not started it. Until it does, its thread reads idle and lists the
+    // turn as interrupted, so only Codex's own report about the turn settles it.
+    if (
+      trackedProviderTurn?.state === "active" &&
+      !codexAppServerTurnStatusIsActive(status) &&
+      journal.unstartedTurns.has(codexAppServerTurnKey(trackedProviderTurn.threadId, trackedProviderTurn.turnId))
+    ) {
+      debugLog("appServerThread.reconcile.awaitingProviderStart", {
+        sessionId: normalizedSessionId,
+        source: normalizeText(source),
+        status,
+        threadId: trackedProviderTurn.threadId,
+        turnId: trackedProviderTurn.turnId
+      });
+      return {
+        ok: true,
+        reason: "provider_turn_not_started",
+        status: trackedProviderTurn.status || "inProgress",
+        turnId: trackedProviderTurn.turnId
+      };
+    }
     if (
       trackedProviderTurn &&
       turnId &&

package/src/server/conversation/codexTurnRecovery.js

@@ -1,4 +1,4 @@
-import { codexAppServerTurnStatusIsActive, codexAppServerTurnStatusIsComplete, codexAppServerTurnStatusIsSuccessfulComplete, codexAppServerTurnStatusIsProviderFailure, codexAppServerThreadStatus, codexAppServerReadThreadStatus, codexAppServerAgentRun, codexAppServerPendingUserMessageOwnership, codexAppServerTurnCanAdoptSuccessor } from "./codexTurnState.js";
+import { codexAppServerTurnStatusIsActive, codexAppServerTurnStatusIsComplete, codexAppServerTurnStatusIsSuccessfulComplete, codexAppServerTurnStatusIsProviderFailure, codexAppServerThreadStatus, codexAppServerReadThreadStatus, codexAppServerAgentRun, codexAppServerPendingUserMessageOwnership, codexAppServerTurnCanAdoptSuccessor, codexAppServerTurnKey } from "./codexTurnState.js";
 import { codexAppServerProviderTurnForOperation, codexAppServerThreadTurnId, codexAppServerThreadError } from "./codexThreadSnapshot.js";
 import { createCodexTurnActivity } from "./codexTurnActivity.js";
 import { createCodexTurnEndings } from "./codexTurnEndings.js";
@@ -270,6 +270,17 @@ export function createCodexTurnRecovery({
     if (!codexAppServerTurnStatusIsComplete(status)) {
       return currentSession;
     }
+    if (journal.unstartedTurns.has(codexAppServerTurnKey(currentTurn.threadId, currentTurn.turnId))) {
+      // Codex has accepted this turn but not started it, and its thread reads idle until it does.
+      debugLog("appServerTurn.reconcile.awaitingProviderStart", {
+        sessionId,
+        status,
+        threadId: currentTurn.threadId,
+        turnId: currentTurn.turnId
+      });
+      scheduleCodexAppServerActiveRecovery(sessionId);
+      return currentSession;
+    }
     const completedTurnId = providerTurnId || currentTurn.turnId;
     debugLog("appServerTurn.reconcile.complete", {
       sessionId,

package/src/server/conversation/customEndpoint.js

@@ -0,0 +1,188 @@
+import { CUSTOM_AI_PLACEHOLDER_TOKEN } from "../../shared/nativeProviders.js";
+
+// Loading a model on the person's own server can take this long on first use.
+export const CUSTOM_ENDPOINT_CHECK_TIMEOUT_MS = 120_000;
+const CONTEXT_READ_TIMEOUT_MS = 5_000;
+const RESPONSE_LIMIT_BYTES = 256 * 1024;
+
+const ENGINE_APIS = Object.freeze({
+  codex: Object.freeze({
+    path: "/responses",
+    name: "Responses API",
+    urlHint: "Codex needs an OpenAI Responses-compatible base URL, which usually ends in /v1.",
+    body: (model) => ({ model, input: "Reply with OK.", max_output_tokens: 64, store: false }),
+    usable: (result) => Boolean(result?.id) && Array.isArray(result.output) &&
+      ["completed", "incomplete"].includes(result.status)
+  }),
+  claude: Object.freeze({
+    path: "/v1/messages",
+    name: "Anthropic Messages API",
+    urlHint: "Claude Code needs an Anthropic-compatible base URL without /v1.",
+    body: (model) => ({ model, max_tokens: 64, messages: [{ role: "user", content: "Reply with OK." }] }),
+    usable: (result) => Boolean(result?.id) && result.type === "message" && Array.isArray(result.content)
+  }),
+  opencode: Object.freeze({
+    path: "/chat/completions",
+    name: "Chat Completions API",
+    urlHint: "OpenCode needs an OpenAI-compatible base URL, which usually ends in /v1.",
+    body: (model) => ({ model, max_tokens: 64, messages: [{ role: "user", content: "Reply with OK." }] }),
+    usable: (result) => Boolean(result?.id) && Array.isArray(result.choices) && result.choices.length > 0
+  })
+});
+
+function checkError(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+async function readLimitedJson(response) {
+  // readable-check: allow optional-call - platform object: a fetch Response body may be absent
+  const reader = response.body?.getReader?.();
+  if (!reader) return null;
+  const chunks = [];
+  let size = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > RESPONSE_LIMIT_BYTES) {
+      await reader.cancel();
+      return null;
+    }
+    chunks.push(value);
+  }
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** A model server answers 404 both for a wrong path and for a model it does not have. */
+function namesMissingModel(result, model) {
+  const message = String(result?.error?.message ?? result?.error ?? result?.message ?? "").toLowerCase();
+  return message.includes("model") && (message.includes("not found") || message.includes(model.toLowerCase()));
+}
+
+/**
+ * One small request on the engine's own API with the entered model: the same
+ * proof as a curated key check, for a server the person runs. Never exposes
+ * the server's raw reply.
+ * @param {{ engineId: "codex" | "claude" | "opencode", baseUrl: string, model: string, apiKey?: string,
+ *   fetchImpl?: typeof fetch, timeoutMs?: number }} input
+ */
+export async function verifyCustomEndpoint({
+  engineId, baseUrl, model, apiKey = "", fetchImpl = fetch, timeoutMs = CUSTOM_ENDPOINT_CHECK_TIMEOUT_MS
+}) {
+  const api = ENGINE_APIS[engineId];
+  if (!api) throw new TypeError("Custom endpoints connect Codex, Claude Code or OpenCode.");
+  const root = baseUrl.replace(/\/$/u, "");
+  const token = apiKey || (engineId === "claude" ? CUSTOM_AI_PLACEHOLDER_TOKEN : "");
+  let response;
+  try {
+    response = await fetchImpl(`${root}${api.path}`, {
+      method: "POST",
+      redirect: "error",
+      signal: AbortSignal.timeout(timeoutMs),
+      headers: {
+        "Content-Type": "application/json",
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        ...(engineId === "claude" ? { "anthropic-version": "2023-06-01" } : {})
+      },
+      body: JSON.stringify(api.body(model))
+    });
+  } catch {
+    throw checkError("custom_endpoint_unreachable",
+      `Nothing answers at ${root}. Start your model server, then choose Check again.`);
+  }
+  const result = await readLimitedJson(response);
+  if (response.status === 401 || response.status === 403) {
+    throw checkError("custom_endpoint_key_rejected",
+      `The server at ${root} rejected the key. Check the key, or leave it empty if the server needs none.`);
+  }
+  if (response.status === 404) {
+    throw namesMissingModel(result, model)
+      ? checkError("custom_endpoint_model_missing", `The server at ${root} has no model named ${model}.`)
+      : checkError("custom_endpoint_path_missing", `${root}${api.path} was not found. ${api.urlHint}`);
+  }
+  if (!response.ok) {
+    throw checkError("custom_endpoint_request_failed",
+      `The server at ${root} could not complete a test request (HTTP ${response.status}).`);
+  }
+  if (!api.usable(result)) {
+    throw checkError("custom_endpoint_answer_unusable",
+      `The server at ${root} did not return a usable ${api.name} answer. ${api.urlHint}`);
+  }
+}
+
+/**
+ * The context Ollama really loaded the model with, read from `/api/ps` after a
+ * check request loaded it. Ollama gives a 4,096-token context by default on
+ * smaller GPUs and cuts longer prompts without an error. Null when the server
+ * is not Ollama or no longer has the model loaded.
+ * @param {{ baseUrl: string, model: string, apiKey?: string, fetchImpl?: typeof fetch }} input
+ */
+export async function readOllamaLoadedContext({ baseUrl, model, apiKey = "", fetchImpl = fetch }) {
+  const root = baseUrl.replace(/\/$/u, "").replace(/\/v1$/u, "");
+  let response;
+  try {
+    response = await fetchImpl(`${root}/api/ps`, {
+      redirect: "error",
+      signal: AbortSignal.timeout(CONTEXT_READ_TIMEOUT_MS),
+      headers: apiKey ? { Authorization: `Bearer ${apiKey}` } : {}
+    });
+  } catch {
+    return null;
+  }
+  const result = response.ok ? await readLimitedJson(response) : null;
+  if (!response.ok) {
+    // readable-check: allow optional-call - platform object: a fetch Response body may be absent
+    await response.body?.cancel?.();
+  }
+  if (!Array.isArray(result?.models)) return null;
+  const names = new Set([model, model.includes(":") ? model : `${model}:latest`]);
+  const loaded = result.models.find((entry) => names.has(entry?.name) || names.has(entry?.model));
+  const contextLength = Number(loaded?.context_length);
+  return Number.isSafeInteger(contextLength) && contextLength > 0 ? contextLength : null;
+}
+
+/**
+ * Whether anything answers at a saved endpoint: one read of its model list,
+ * which loads no model. Any HTTP answer counts, even a refusal; Health shows it
+ * and never polls.
+ * @param {{ engineId: "codex" | "claude" | "opencode", baseUrl: string, fetchImpl?: typeof fetch }} input
+ */
+export async function probeCustomEndpoint({ engineId, baseUrl, fetchImpl = fetch }) {
+  const root = baseUrl.replace(/\/$/u, "");
+  try {
+    const response = await fetchImpl(engineId === "claude" ? `${root}/v1/models` : `${root}/models`, {
+      redirect: "error",
+      signal: AbortSignal.timeout(CONTEXT_READ_TIMEOUT_MS)
+    });
+    // readable-check: allow optional-call - platform object: a fetch Response body may be absent
+    await response.body?.cancel?.();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Connect-time proof for one engine: the engine's API answers with the entered
+ * model, and an Ollama server loaded it with at least the entered context.
+ * @param {{ engineId: "codex" | "claude" | "opencode", baseUrl: string, model: string, contextWindow: number,
+ *   apiKey?: string, fetchImpl?: typeof fetch, timeoutMs?: number }} input
+ */
+export async function checkCustomEndpoint({ contextWindow, ...input }) {
+  await verifyCustomEndpoint(input);
+  const loaded = await readOllamaLoadedContext(input);
+  if (loaded !== null && loaded < contextWindow) {
+    throw checkError("custom_endpoint_context_too_small",
+      `Ollama loaded ${input.model} with ${loaded.toLocaleString("en-US")} tokens of context, less than the ` +
+      `${contextWindow.toLocaleString("en-US")} entered. It would cut prompts without an error. Restart it with ` +
+      `OLLAMA_CONTEXT_LENGTH=${contextWindow}, then choose Check again.`);
+  }
+  return Object.freeze({
+    ok: true,
+    loadedContext: loaded
+  });
+}

package/src/server/conversation/providers/claudeDriver.js

@@ -5,7 +5,7 @@ import path from "node:path";
 import { realpath } from "node:fs/promises";
 import { isDeepStrictEqual } from "node:util";
 import { bindClaudeConversationAccount, claudeConnectionIdentity, claudeFlagSettings, claudeModelConfiguration, readClaudeCodeAuthStatus } from "../claudeProcess.js";
-import { nativeAiModel, nativeAiProvider } from "../../../shared/nativeProviders.js";
+import { connectionAiProvider } from "../../../shared/nativeProviders.js";
 import { claudeNativeMessageId, requireClaudeSessionId, listClaudeConversationStorage } from "../claudeHistory.js";
 import { createClaudeConversationOwner } from "../claudeTurn.js";
 import { CLAUDE_APPLICATION_TOOL_SERVER } from "../claudeTools.js";
@@ -221,8 +221,8 @@ export function createClaudeConversationDriver({
       if (requireBound && !accountBinding?.connectionIdentities?.[providerId]) {
         throw new Error("The completed Claude response has no saved provider account fingerprint.");
       }
-      const provider = nativeAiProvider(providerId);
-      const model = nativeAiModel(connection.model, providerId);
+      const provider = connectionAiProvider(providerId, connection);
+      const model = provider?.models.find(({ id }) => id === connection.model) || null;
       if (providerId !== "anthropic" && (!provider || !model)) throw Object.assign(new Error("This exact provider/model is not supported by the Claude integration. Choose a supported model without renaming it."), {
         messageCode: "assistant.claude.modelUnsupported", messageParams: {}
       });
@@ -231,7 +231,8 @@ export function createClaudeConversationDriver({
         messageCode: "assistant.claude.reasoningEffortUnsupported", messageParams: {}
       });
       selected = claudeModelConfiguration({ providerId, model: connection.model }, {
-        apiKey: connection.apiKey, baseUrl: provider?.claudeBaseUrl || connection.baseURL || "https://api.anthropic.com"
+        apiKey: connection.apiKey, provider: connection.provider,
+        baseUrl: provider?.claudeBaseUrl || connection.baseURL || "https://api.anthropic.com"
       });
       identity = claudeConnectionIdentity(configRoot, providerId, selected.env.ANTHROPIC_BASE_URL, connection.apiKey);
     } else {

package/src/server/conversation/providers/codexDriverConnection.js

@@ -10,7 +10,7 @@ import { codexToolFreeConfiguration } from "../codexIsolation.js";
 import { codexCommandHookCommand } from "../commandWrapper.js";
 import { validateConnectionModel } from "../configuration.js";
 import { jsonHash as hash } from "../normalize.js";
-import { nativeAiProvider, nativeAiModel } from "../../../shared/nativeProviders.js";
+import { connectionAiProvider } from "../../../shared/nativeProviders.js";
 
 /**
  * The native side of one driver conversation: its observation, the provider it acquires and stops, the account it
@@ -197,8 +197,8 @@ export function createCodexDriverConnection({
     }
     const connection = await connections.resolve({ context, integrationId: configuration.integrationId });
     signal.throwIfAborted();
-    const provider = nativeAiProvider(connection.providerId);
-    const model = nativeAiModel(connection.model, connection.providerId);
+    const provider = connectionAiProvider(connection.providerId, connection);
+    const model = provider?.models.find(({ id }) => id === connection.model) || null;
     if (!provider || !model) throw Object.assign(new Error("This exact provider/model is not supported by the Codex integration. Choose a supported model without renaming it."), {
       messageCode: "assistant.codex.modelUnsupported", messageParams: {}
     });

package/src/server/hosts/codexConfiguration.js

@@ -14,6 +14,7 @@ export {
   codexProviderConfiguration,
   codexProviderFileConfiguration,
   codexProviderCatalogPath,
+  readCodexCustomModels,
   verifyCodexProviderKey
 } from "../conversation/codexConfiguration.js";
 export { codexAuthOutputRequiresReconnect, createCodexAccountReader } from "../conversation/codexAccountReader.js";

package/src/server/hosts/customEndpoint.js

@@ -0,0 +1,7 @@
+export {
+  CUSTOM_ENDPOINT_CHECK_TIMEOUT_MS,
+  checkCustomEndpoint,
+  probeCustomEndpoint,
+  readOllamaLoadedContext,
+  verifyCustomEndpoint
+} from "../conversation/customEndpoint.js";

package/src/shared/nativeProviders.js

@@ -29,6 +29,43 @@ const NATIVE_AI_PROVIDERS = Object.freeze([
   })
 ]);
 
+// A model server the person runs or reaches. Its route comes from their saved
+// connection, never from this table: one base URL and one model per engine.
+const CUSTOM_AI_PROVIDER_ID = "custom";
+const CUSTOM_AI_MINIMUM_CONTEXT = 32768;
+// Claude Code needs a token: without one it sends the saved claude.ai login.
+const CUSTOM_AI_PLACEHOLDER_TOKEN = "local";
+
+/**
+ * The native shape of a custom endpoint for one engine. Codex gets reasoning
+ * levels (its catalogue needs them); Claude Code and OpenCode get none, so no
+ * effort the server may not understand is sent. Freeform patching and parallel
+ * tool calls stay off: Codex refuses Ollama's freeform apply_patch replies.
+ * @param {{ engineId?: string, baseUrl: string, model: string, contextWindow: number, label?: string }} connection
+ */
+function customAiProvider({ engineId = "codex", baseUrl, model: modelId, contextWindow, label = "Custom endpoint" }) {
+  const variants = engineId === "codex" ? ["low", "medium", "high"] : [];
+  return Object.freeze({
+    id: CUSTOM_AI_PROVIDER_ID,
+    custom: true,
+    label,
+    baseUrl,
+    claudeBaseUrl: baseUrl,
+    claudeAutoCompactWindow: contextWindow,
+    webSearch: false,
+    models: Object.freeze([model(modelId, contextWindow, variants, {
+      label: modelId, defaultThinking: variants.length ? "medium" : "", parallelToolCalls: false,
+      codexHistoryRouting: true
+    })])
+  });
+}
+
+/** The provider of a resolved connection: a fixed route, or the custom endpoint it carries. */
+function connectionAiProvider(providerId, connection) {
+  if (providerId === CUSTOM_AI_PROVIDER_ID) return connection?.provider?.custom === true ? connection.provider : null;
+  return nativeAiProvider(providerId);
+}
+
 function nativeAiProvider(id) {
   return NATIVE_AI_PROVIDERS.find(provider => provider.id === id) || null;
 }
@@ -42,4 +79,13 @@ function nativeAiModel(id, providerId = "") {
   return null;
 }
 
-export { NATIVE_AI_PROVIDERS, nativeAiProvider, nativeAiModel };
+export {
+  CUSTOM_AI_MINIMUM_CONTEXT,
+  CUSTOM_AI_PLACEHOLDER_TOKEN,
+  CUSTOM_AI_PROVIDER_ID,
+  NATIVE_AI_PROVIDERS,
+  connectionAiProvider,
+  customAiProvider,
+  nativeAiProvider,
+  nativeAiModel
+};

package/test/codexTurn.test.js

@@ -1910,6 +1910,51 @@ test("original dispatch steering preserves deferred versus new-turn recovery and
   }
 });
 
+// Codex answers turn/start before it starts the turn. Until its turn/started notification, codex-cli 0.163.0 reads
+// the thread as idle and lists the new turn as interrupted, so neither read means the turn ended. On 2026-11-06 the
+// starting watchdog's status read landed in that gap: the turn was marked finished 0.46 s after delivery, and Codex's
+// answer 33 s later was dropped behind "Codex finished, but Vibe64 could not recover its final response".
+for (const read of ["starting watchdog", "status check"]) {
+  test(`a delivered turn Codex has not started stays active through a ${read} and keeps its answer`, async t => {
+    const notices = [];
+    const f = await receiptFixture({
+      finalizingGraceMs: 30,
+      outcomeNotice(_runtime, _sessionId, _threadId, _turnId, outcome) { notices.push(outcome); }
+    });
+    t.after(() => f.owner.clearSessionRecoveryTimers(f.sessionId));
+    const context = dispatchContext(f);
+    let codexStatus = "idle";
+    f.run = { ...f.run, state: "starting", providerTurnId: "", providerStatus: "", outerTurnId: context.messageId };
+    f.provider.sendTurn = async () => ({ id: f.turnId, status: "inProgress" });
+    f.provider.readThreadStatus = async () => ({ raw: { status: { type: codexStatus } } });
+    f.history = [turn(f.turnId, "interrupted")];
+    f.observe();
+    assert.equal((await f.owner.startTurn(f.sessionId, {}, context)).providerFailure, "");
+    assert.equal(f.run.state, "active");
+    if (read === "starting watchdog") {
+      await f.owner.recoverActiveTurn(f.sessionId, { provider: f.provider, retryOnError: false });
+    } else {
+      await f.owner.reconcileThreadStatus(f.sessionId, f.provider, f.threadId, {
+        observeLatestTurn: true, source: "wellbeing"
+      });
+    }
+    await f.drain();
+    assert.equal(f.run.state, "active", "An idle read before turn/started does not end the turn");
+    assert.equal(f.run.providerTurnId, f.turnId);
+    codexStatus = "active";
+    f.history = [turn(f.turnId, "inProgress")];
+    f.emit({ method: "turn/started", params: { threadId: f.threadId, turn: { id: f.turnId, status: "inProgress" } } });
+    await f.drain();
+    codexStatus = "idle";
+    f.history = [turn(f.turnId, "completed", "The complete reply.")];
+    f.emit({ method: "turn/completed", params: { threadId: f.threadId, turn: { id: f.turnId, status: "completed" } } });
+    await f.drain();
+    assert.equal(f.run.state, "completed");
+    assert.deepEqual((await f.replies()).map(row => row.assistant.text), ["The complete reply."]);
+    assert.deepEqual(notices, []);
+  });
+}
+
 function controlContext(f, overrides = {}) {
   return {
     runtime: f.runtime,

package/test/customEndpoint.test.js

@@ -0,0 +1,218 @@
+import assert from "node:assert/strict";
+import { randomUUID } from "node:crypto";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { CUSTOM_AI_PLACEHOLDER_TOKEN, customAiProvider } from "../src/shared/nativeProviders.js";
+import {
+  codexProviderConfiguration,
+  codexProviderFileConfiguration,
+  codexProviderModelCatalog,
+  readCodexCustomModels
+} from "../src/server/conversation/codexConfiguration.js";
+import { claudeModelConfiguration } from "../src/server/conversation/claudeProcess.js";
+import { prepareCodexHistory, startCodexHistoryAdapter } from "../src/server/conversation/codexHistoryAdapter.js";
+import { checkCustomEndpoint, probeCustomEndpoint, verifyCustomEndpoint } from "../src/server/conversation/customEndpoint.js";
+
+const recorded = JSON.parse(await readFile(new URL("./fixtures/customEndpoint/ollama-0.40.15.json", import.meta.url), "utf8"));
+const MODEL = recorded.model;
+
+/** A stub model server replaying Ollama 0.40.15's answers on all three engine APIs. */
+async function startOllamaStub(t, { context = 65536, status = 200, missingModel = false } = {}) {
+  const requests = [];
+  const server = createServer(async (request, response) => {
+    const chunks = [];
+    for await (const chunk of request) chunks.push(chunk);
+    const body = chunks.length ? JSON.parse(Buffer.concat(chunks).toString("utf8")) : null;
+    requests.push({ method: request.method, url: request.url, headers: request.headers, body });
+    const send = (code, value) => response.writeHead(code, { "content-type": "application/json" }).end(JSON.stringify(value));
+    if (status !== 200) return send(status, { error: "denied" });
+    if (request.method === "GET" && request.url === "/api/ps") {
+      return send(200, context === 65536 ? recorded.psRaisedContext : recorded.psDefaultContext);
+    }
+    if (body?.model !== MODEL || missingModel) return send(404, recorded.modelMissing);
+    if (request.url === "/v1/responses") return send(200, recorded.response);
+    if (request.url === "/v1/messages") return send(200, recorded.messages);
+    if (request.url === "/v1/chat/completions") return send(200, recorded.chatCompletion);
+    return send(404, { error: "404 page not found" });
+  });
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  t.after(() => new Promise((resolve) => server.close(resolve)));
+  return { root: `http://127.0.0.1:${server.address().port}`, requests };
+}
+
+test("a custom endpoint has one model, no freeform patching and no parallel tool calls", () => {
+  const codex = customAiProvider({ engineId: "codex", baseUrl: "http://127.0.0.1:11434/v1", model: MODEL, contextWindow: 65536 });
+  assert.equal(codex.id, "custom");
+  assert.equal(codex.custom, true);
+  assert.deepEqual(codex.models.map(({ id }) => id), [MODEL]);
+  assert.deepEqual(codex.models[0].variants, ["low", "medium", "high"]);
+  assert.equal(codex.models[0].freeformPatch, undefined);
+  const [row] = codexProviderModelCatalog({ models: codex.models }).models;
+  assert.equal(row.slug, MODEL);
+  assert.equal(row.context_window, 65536);
+  assert.equal(row.supports_parallel_tool_calls, false);
+  assert.equal(Object.hasOwn(row, "apply_patch_tool_type"), false);
+  const claude = customAiProvider({ engineId: "claude", baseUrl: "http://127.0.0.1:11434", model: MODEL, contextWindow: 65536 });
+  assert.deepEqual(claude.models[0].variants, []);
+  assert.equal(claude.claudeBaseUrl, "http://127.0.0.1:11434");
+});
+
+test("Codex sends no bearer token to a custom endpoint without a key, and its home names the endpoint", async (t) => {
+  const provider = customAiProvider({ engineId: "codex", baseUrl: "http://127.0.0.1:11434/v1", model: MODEL, contextWindow: 65536 });
+  const config = codexProviderConfiguration(provider, "")["model_providers.custom"];
+  assert.equal(config.base_url, "http://127.0.0.1:11434/v1");
+  assert.equal(config.requires_openai_auth, false);
+  assert.equal(Object.hasOwn(config, "experimental_bearer_token"), false);
+  assert.equal(codexProviderConfiguration(provider, "their-key")["model_providers.custom"].experimental_bearer_token, "their-key");
+  const home = await mkdtemp(path.join(os.tmpdir(), "custom-endpoint-home-"));
+  t.after(() => rm(home, { recursive: true, force: true }));
+  const file = codexProviderFileConfiguration(provider, "", home);
+  assert.doesNotMatch(file, /experimental_bearer_token/u);
+  assert.match(file, /^model_provider = "custom"$/mu);
+  assert.match(file, /^model_reasoning_effort = "medium"$/mu);
+  await writeFile(path.join(home, "config.toml"), file);
+  await writeFile(path.join(home, "models.json"), JSON.stringify(codexProviderModelCatalog({ models: provider.models })));
+  assert.deepEqual((await readCodexCustomModels(home)).map(({ slug }) => slug), [MODEL]);
+  const deepseek = await mkdtemp(path.join(os.tmpdir(), "curated-home-"));
+  t.after(() => rm(deepseek, { recursive: true, force: true }));
+  await writeFile(path.join(deepseek, "config.toml"), 'model_provider = "deepseek"\n[model_providers.deepseek]\nbase_url = "https://api.deepseek.com/"\n');
+  assert.deepEqual(await readCodexCustomModels(deepseek), []);
+});
+
+test("Claude Code always sends a token to a custom endpoint, so the saved claude.ai login never goes there", () => {
+  const provider = customAiProvider({ engineId: "claude", baseUrl: "http://127.0.0.1:11434", model: MODEL, contextWindow: 65536 });
+  const keyless = claudeModelConfiguration({ providerId: "custom", model: MODEL }, { provider, apiKey: "", baseUrl: provider.claudeBaseUrl });
+  assert.equal(keyless.model, MODEL);
+  assert.equal(keyless.env.ANTHROPIC_BASE_URL, "http://127.0.0.1:11434");
+  assert.equal(keyless.env.ANTHROPIC_AUTH_TOKEN, CUSTOM_AI_PLACEHOLDER_TOKEN);
+  assert.equal(keyless.env.ANTHROPIC_API_KEY, "");
+  assert.equal(keyless.env.CLAUDE_CODE_OAUTH_TOKEN, "");
+  for (const name of ["ANTHROPIC_MODEL", "ANTHROPIC_DEFAULT_OPUS_MODEL", "ANTHROPIC_DEFAULT_SONNET_MODEL",
+    "ANTHROPIC_DEFAULT_HAIKU_MODEL", "ANTHROPIC_DEFAULT_FABLE_MODEL", "CLAUDE_CODE_SUBAGENT_MODEL"]) {
+    assert.equal(keyless.env[name], MODEL, name);
+  }
+  assert.equal(keyless.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW, "65536");
+  assert.equal(keyless.env.CLAUDE_CODE_MAX_OUTPUT_TOKENS, "16384");
+  const keyed = claudeModelConfiguration({ providerId: "custom", model: MODEL }, { provider, apiKey: "their-key", baseUrl: provider.claudeBaseUrl });
+  assert.equal(keyed.env.ANTHROPIC_AUTH_TOKEN, "their-key");
+  assert.throws(() => claudeModelConfiguration({ providerId: "custom", model: MODEL }, { apiKey: "", baseUrl: "http://127.0.0.1:11434" }),
+    /Choose a connected Claude Code model/u);
+  assert.throws(() => claudeModelConfiguration({ providerId: "custom", model: "another" }, { provider, apiKey: "" }),
+    /Choose a connected Claude Code model/u);
+  assert.equal(claudeModelConfiguration({ providerId: "anthropic", model: "opus" }, null).env.CLAUDE_CODE_MAX_OUTPUT_TOKENS, "");
+});
+
+test("the connection check sends one request on each engine's own API and accepts Ollama's recorded answers", async (t) => {
+  const stub = await startOllamaStub(t);
+  await checkCustomEndpoint({ engineId: "codex", baseUrl: `${stub.root}/v1`, model: MODEL, contextWindow: 65536 });
+  await checkCustomEndpoint({ engineId: "opencode", baseUrl: `${stub.root}/v1/`, model: MODEL, contextWindow: 65536 });
+  const claude = await checkCustomEndpoint({ engineId: "claude", baseUrl: stub.root, model: MODEL, contextWindow: 65536 });
+  assert.equal(claude.loadedContext, 65536);
+  const posts = stub.requests.filter(({ method }) => method === "POST");
+  assert.deepEqual(posts.map(({ url }) => url), ["/v1/responses", "/v1/chat/completions", "/v1/messages"]);
+  assert.equal(posts[0].headers.authorization, undefined);
+  assert.equal(posts[1].headers.authorization, undefined);
+  assert.equal(posts[2].headers.authorization, `Bearer ${CUSTOM_AI_PLACEHOLDER_TOKEN}`);
+  assert.equal(posts[2].headers["anthropic-version"], "2023-06-01");
+  await verifyCustomEndpoint({ engineId: "codex", baseUrl: `${stub.root}/v1`, model: MODEL, apiKey: "their-key" });
+  assert.equal(stub.requests.at(-1).headers.authorization, "Bearer their-key");
+});
+
+test("the connection check refuses Ollama's silent 4,096-token default context", async (t) => {
+  const stub = await startOllamaStub(t, { context: 4096 });
+  await assert.rejects(checkCustomEndpoint({ engineId: "claude", baseUrl: stub.root, model: MODEL, contextWindow: 65536 }), (error) => {
+    assert.equal(error.code, "custom_endpoint_context_too_small");
+    assert.match(error.message, /Ollama loaded qwen3\.5:4b-q4_K_M with 4,096 tokens of context, less than the 65,536 entered/u);
+    assert.match(error.message, /OLLAMA_CONTEXT_LENGTH=65536/u);
+    return true;
+  });
+  // The entered length is what the engines compact by; a server loaded with more passes.
+  await checkCustomEndpoint({ engineId: "claude", baseUrl: stub.root, model: MODEL, contextWindow: 4096 });
+});
+
+test("the connection check names the fix for each failure", async (t) => {
+  const stub = await startOllamaStub(t);
+  const rejects = (input, code, pattern) => assert.rejects(verifyCustomEndpoint({ model: MODEL, ...input }), (error) => {
+    assert.equal(error.code, code);
+    assert.match(error.message, pattern);
+    return true;
+  });
+  await rejects({ engineId: "claude", baseUrl: `${stub.root}/v1` }, "custom_endpoint_path_missing",
+    /\/v1\/v1\/messages was not found\. Claude Code needs an Anthropic-compatible base URL without \/v1\./u);
+  await rejects({ engineId: "codex", baseUrl: stub.root }, "custom_endpoint_path_missing",
+    /Codex needs an OpenAI Responses-compatible base URL, which usually ends in \/v1\./u);
+  await rejects({ engineId: "opencode", baseUrl: `${stub.root}/v1`, model: "qwen9:1b" }, "custom_endpoint_model_missing",
+    /has no model named qwen9:1b\./u);
+  const denied = await startOllamaStub(t, { status: 401 });
+  await rejects({ engineId: "codex", baseUrl: `${denied.root}/v1` }, "custom_endpoint_key_rejected", /rejected the key/u);
+  const failing = await startOllamaStub(t, { status: 500 });
+  await rejects({ engineId: "codex", baseUrl: `${failing.root}/v1` }, "custom_endpoint_request_failed", /\(HTTP 500\)/u);
+  const closed = createServer();
+  await new Promise((resolve) => closed.listen(0, "127.0.0.1", resolve));
+  const { port } = closed.address();
+  await new Promise((resolve) => closed.close(resolve));
+  await rejects({ engineId: "opencode", baseUrl: `http://127.0.0.1:${port}/v1` }, "custom_endpoint_unreachable",
+    new RegExp(`Nothing answers at http://127\\.0\\.0\\.1:${port}/v1\\. Start your model server`, "u"));
+  const redirect = createServer((_request, response) => response.writeHead(302, { location: "http://example.test/" }).end());
+  await new Promise((resolve) => redirect.listen(0, "127.0.0.1", resolve));
+  t.after(() => new Promise((resolve) => redirect.close(resolve)));
+  await rejects({ engineId: "codex", baseUrl: `http://127.0.0.1:${redirect.address().port}/v1` }, "custom_endpoint_unreachable", /Nothing answers/u);
+});
+
+test("the Codex history adapter routes a custom endpoint to the base URL its thread names, in any runtime", async (t) => {
+  const calls = [];
+  const adapter = await startCodexHistoryAdapter({ token: randomUUID(),
+    fetchImpl: async (url, options) => {
+      calls.push({ url, ...options });
+      return new Response(JSON.stringify(recorded.response), { status: 200, headers: { "content-type": "application/json" } });
+    } });
+  t.after(() => adapter.close());
+  const config = { "model_providers.custom": { base_url: "http://127.0.0.1:11434/v1/", wire_api: "responses" } };
+  const prepared = await prepareCodexHistory({ modelProvider: "custom", config }, null, { baseUrl: adapter.baseUrl });
+  const routedUrl = prepared.config["model_providers.custom"].base_url;
+  assert.equal(routedUrl, `${adapter.baseUrl}/custom~${Buffer.from("http://127.0.0.1:11434/v1").toString("base64url")}`);
+  assert.equal(prepared.config["model_providers.custom"].wire_api, "responses");
+  const routed = await fetch(`${routedUrl}/responses`, { method: "POST", body: JSON.stringify({ model: MODEL, input: [] }) });
+  assert.equal(routed.status, 200);
+  assert.equal((await routed.json()).id, recorded.response.id);
+  assert.equal(calls.at(-1).url, "http://127.0.0.1:11434/v1/responses");
+  assert.equal(calls.at(-1).redirect, "error");
+  // A resumed thread keeps its route and gains its history path.
+  const resumed = await prepareCodexHistory(prepared, null, { baseUrl: adapter.baseUrl, historyPath: "/history.jsonl" });
+  assert.equal(resumed.config["model_providers.custom"].base_url,
+    `${routedUrl}/history/${Buffer.from("/history.jsonl").toString("base64url")}`);
+  // Only an http(s) base URL without credentials is routed.
+  for (const target of ["file:///etc/passwd", "http://user:secret@127.0.0.1:11434/v1", "not a url"]) {
+    const response = await fetch(`${adapter.baseUrl}/custom~${Buffer.from(target).toString("base64url")}/responses`,
+      { method: "POST", body: "{}" });
+    assert.equal(response.status, 404, target);
+  }
+  assert.equal((await fetch(`${adapter.baseUrl}/custom/responses`, { method: "POST", body: "{}" })).status, 404);
+  assert.equal(calls.length, 1);
+  // A stopped server: Codex shows the adapter's answer as the turn's error.
+  const down = await startCodexHistoryAdapter({ token: randomUUID(), fetchImpl: async () => { throw new TypeError("fetch failed"); } });
+  t.after(() => down.close());
+  const downUrl = (await prepareCodexHistory({ modelProvider: "custom", config }, null, { baseUrl: down.baseUrl }))
+    .config["model_providers.custom"].base_url;
+  const refused = await fetch(`${downUrl}/responses`, { method: "POST", body: JSON.stringify({ model: MODEL, input: [] }) });
+  assert.equal(refused.status, 502);
+  assert.equal((await refused.json()).error.message,
+    "Your model server at http://127.0.0.1:11434/v1 isn't answering. Start it, then send your message again.");
+  const untouched = { modelProvider: "custom", config: {} };
+  assert.equal(await prepareCodexHistory(untouched, null, { baseUrl: adapter.baseUrl }), untouched);
+});
+
+test("Health's reachability read asks only for the model list and counts any answer", async (t) => {
+  const stub = await startOllamaStub(t);
+  assert.equal(await probeCustomEndpoint({ engineId: "codex", baseUrl: `${stub.root}/v1` }), true);
+  assert.equal(await probeCustomEndpoint({ engineId: "claude", baseUrl: stub.root }), true);
+  assert.deepEqual(stub.requests.map(({ method, url }) => `${method} ${url}`), ["GET /v1/models", "GET /v1/models"]);
+  const closed = createServer();
+  await new Promise((resolve) => closed.listen(0, "127.0.0.1", resolve));
+  const { port } = closed.address();
+  await new Promise((resolve) => closed.close(resolve));
+  assert.equal(await probeCustomEndpoint({ engineId: "opencode", baseUrl: `http://127.0.0.1:${port}/v1` }), false);
+});

package/test/fixtures/customEndpoint/ollama-0.40.15.json

@@ -0,0 +1,90 @@
+{
+  "source": "Ollama 0.40.15 serving qwen3.5:4b-q4_K_M on 2026-11-06. Recorded: the Messages reply Claude Code 2.1.317 saved in its proof run, the chat completion and both /api/ps replies (read with curl before and after OLLAMA_CONTEXT_LENGTH=65536), and OpenCode 1.18.31's error once the server had stopped. Constructed: the Responses reply (the fields Codex 0.163.0 reads) and the model-missing 404 body.",
+  "model": "qwen3.5:4b-q4_K_M",
+  "messages": {
+    "id": "msg_ac8a55117ab9c4d3ec25734f",
+    "type": "message",
+    "role": "assistant",
+    "model": "qwen3.5:4b-q4_K_M",
+    "content": [
+      {
+        "type": "tool_use",
+        "id": "call_4wnyqz70",
+        "name": "Bash",
+        "input": {
+          "command": "cat greeting.txt && echo SHELL-OK"
+        }
+      }
+    ],
+    "stop_reason": "tool_use",
+    "usage": {
+      "input_tokens": 11114,
+      "output_tokens": 138
+    }
+  },
+  "chatCompletion": {
+    "id": "chatcmpl-128",
+    "object": "chat.completion",
+    "created": 1793950047,
+    "model": "qwen3.5:4b-q4_K_M",
+    "system_fingerprint": "fp_ollama",
+    "choices": [
+      {
+        "index": 0,
+        "message": {
+          "role": "assistant",
+          "content": "OK",
+          "reasoning": "Thinking Process:\n\n1.  **Analyze the Request:**"
+        },
+        "finish_reason": "stop"
+      }
+    ]
+  },
+  "response": {
+    "id": "resp_128",
+    "object": "response",
+    "status": "completed",
+    "model": "qwen3.5:4b-q4_K_M",
+    "output": [
+      {
+        "type": "message",
+        "role": "assistant",
+        "content": [
+          {
+            "type": "output_text",
+            "text": "OK"
+          }
+        ]
+      }
+    ]
+  },
+  "psDefaultContext": {
+    "models": [
+      {
+        "name": "qwen3.5:4b-q4_K_M",
+        "model": "qwen3.5:4b-q4_K_M",
+        "size": 3085046905,
+        "size_vram": 3085046905,
+        "context_length": 4096
+      }
+    ]
+  },
+  "psRaisedContext": {
+    "models": [
+      {
+        "name": "qwen3.5:4b-q4_K_M",
+        "model": "qwen3.5:4b-q4_K_M",
+        "size": 4466021497,
+        "size_vram": 4466021497,
+        "context_length": 65536
+      }
+    ]
+  },
+  "modelMissing": {
+    "error": {
+      "message": "model 'qwen9:1b' not found",
+      "type": "not_found_error"
+    }
+  },
+  "openCodeServerDown": "Cannot connect to API: Unable to connect. Is the computer able to access the url?"
+}