@jskit-ai/assistant-core 0.2.19 → 0.2.21

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

@@ -1955,6 +1955,82 @@ for (const read of ["starting watchdog", "status check"]) {
   });
 }
 
+// A turn Codex has accepted and not yet reported; `sendTurn` runs before Codex's answer to turn/start.
+async function unstartedTurnFixture(t, { sendTurn } = {}) {
+  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);
+  f.codexStatus = "idle";
+  f.notices = notices;
+  f.started = { method: "turn/started", params: { threadId: f.threadId, turn: { id: f.turnId, status: "inProgress" } } };
+  f.run = { ...f.run, state: "starting", providerTurnId: "", providerStatus: "", outerTurnId: context.messageId };
+  f.provider.sendTurn = async () => {
+    await sendTurn?.(f);
+    return { id: f.turnId, status: "inProgress" };
+  };
+  f.provider.readThreadStatus = async () => ({ raw: { status: { type: f.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");
+  // Codex finishes the turn, and its turn/completed notification is lost: only its thread and history say so.
+  f.finish = () => {
+    f.codexStatus = "idle";
+    f.history = [turn(f.turnId, "completed", "The complete reply.")];
+  };
+  return f;
+}
+
+async function assertSettledWithReply(f) {
+  await f.drain();
+  assert.equal(f.run.state, "completed");
+  assert.deepEqual((await f.replies()).map(row => row.assistant.text), ["The complete reply."]);
+  assert.deepEqual(f.notices, []);
+}
+
+// Codex usually answers turn/start before its turn/started notification, but may send turn/started first. Either way
+// Codex has reported the turn, so a thread status check after it finishes settles the turn with its answer.
+for (const order of ["after", "before"]) {
+  test(`a turn Codex reports ${order} its turn/start answer is settled by a later idle status check`, async t => {
+    const f = await unstartedTurnFixture(t, {
+      sendTurn(fixture) { if (order === "before") fixture.emit(fixture.started); }
+    });
+    if (order === "after") f.emit(f.started);
+    await f.drain();
+    assert.equal(f.run.state, "active");
+    f.finish();
+    await f.owner.reconcileThreadStatus(f.sessionId, f.provider, f.threadId, { source: "wellbeing" });
+    await assertSettledWithReply(f);
+  });
+}
+
+// When turn/started is missed, the mark does not outlive Codex's next report about the turn: a later notification
+// naming it, or Codex listing it as completed, settles it like any other turn. No timer is involved.
+for (const report of ["a later notification naming the turn", "the starting watchdog reading it as completed",
+  "a status check reading it as completed"]) {
+  test(`a delivered turn whose turn/started is missed is settled by ${report}`, async t => {
+    const f = await unstartedTurnFixture(t);
+    await f.owner.reconcileThreadStatus(f.sessionId, f.provider, f.threadId, { observeLatestTurn: true, source: "wellbeing" });
+    await f.drain();
+    assert.equal(f.run.state, "active", "Codex's idle thread and interrupted listing before it reports the turn do not end it");
+    f.finish();
+    if (report === "a later notification naming the turn") {
+      f.emit({ method: "item/started", params: { threadId: f.threadId, turnId: f.turnId, item: { id: "thinking", type: "reasoning" } } });
+      await f.drain();
+      await f.owner.reconcileThreadStatus(f.sessionId, f.provider, f.threadId, { source: "wellbeing" });
+    } else if (report === "the starting watchdog reading it as completed") {
+      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 assertSettledWithReply(f);
+  });
+}
+
 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);
+});