@jskit-ai/assistant-core 0.2.19 → 0.2.21

package/CHANGELOG.md

@@ -2,12 +2,16 @@
 
 ## Unreleased
 
+- A delivered Codex turn is held as not yet started only until Codex reports it: a `turn/started` that arrives before the `turn/start` answer counts, and a thread read listing exactly that turn as completed or failed settles a turn whose notifications were missed, so its answer is no longer kept waiting for a notification that never comes.
 - The API driver's state note, which carries the current time, follows the conversation as its last message instead of ending the system prompt, so the provider's prompt cache keeps the whole history from one turn to the next instead of charging it uncached on each turn's first model call (`@jskit-ai/agent` `runLoop`).
 - Assistant failures that reach a person translate: 63 more undotted codes render from `jskit.errors.<code>`, and 98 sentences that share a code with others, or are sent without one, carry a `messageCode` (`assistant.claude.*`, `assistant.codex.*`, `assistant.opencode.*`, `assistant.conversation.*`, `assistant.turn.*`). The English messages are unchanged.
 - 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 +178,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 +351,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,7 +8,7 @@
     "build": "vite build"
   },
   "dependencies": {
-    "@jskit-ai/assistant-core": "0.2.19",
+    "@jskit-ai/assistant-core": "0.2.21",
     "@jskit-ai/http-runtime": "0.2.9",
     "@jskit-ai/kernel": "0.2.9",
     "@mdi/js": "^7.4.47",

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.19",
+  "version": "0.2.21",
   "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",
@@ -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, codexAppServerTurnKey, CODEX_APP_SERVER_AGENT_RUN_ID, CODEX_AGENT_PROVIDER, CODEX_APP_SERVER_RUN_STATE } from "./codexTurnState.js";
+import { codexAppServerTurnStatusIsActive, codexAppServerTurnStatusIsSuccessfulComplete, codexAppServerTurnStatusIsProviderFailure, 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,8 +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));
+      // Anything Codex reports about a turn means it has started that turn, even before its answer to turn/start.
+      journal.noteTurnReported(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 { codexAppServerTurnStatusIsComplete, codexAppServerTurnStatusIsSuccessfulComplete, codexAppServerTurnStatusIsProviderFailure, codexAppServerErrorMessage, codexAppServerSteerFailure, codexAppServerMessageRequiresNewTurn, codexAppServerMessageDeferred, codexAppServerTurnKey } from "./codexTurnState.js";
+import { codexAppServerTurnStatusIsComplete, codexAppServerTurnStatusIsSuccessfulComplete, codexAppServerTurnStatusIsProviderFailure, codexAppServerErrorMessage, codexAppServerSteerFailure, codexAppServerMessageRequiresNewTurn, codexAppServerMessageDeferred } 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,9 +74,9 @@ 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.
+    // Codex usually 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));
+      journal.markTurnUnstarted(threadId, deliveredTurnId);
     }
     delivery.pendingUserMessage(promptSessionId, clientUserMessageId)?.onNativeReceipt();
     await recovery.markTurnActive(sessionId, {

package/src/server/conversation/codexResultSettlement.js

@@ -1,4 +1,4 @@
-import { CODEX_APP_SERVER_AGENT_RUN_ID, CODEX_APP_SERVER_RESULT_PROCESSED_EVENT, codexAppServerTurnCanReceiveProviderCompletion, codexAppServerProcessedResultEvent, codexAppServerTurnAwaitsProviderIdentity, codexAppServerTurnCanAdoptSuccessor, codexAppServerAgentRun, CODEX_APP_SERVER_RUN_STATE, codexAppServerTurnKey } from "./codexTurnState.js";
+import { CODEX_APP_SERVER_AGENT_RUN_ID, CODEX_APP_SERVER_RESULT_PROCESSED_EVENT, codexAppServerTurnCanReceiveProviderCompletion, codexAppServerProcessedResultEvent, codexAppServerTurnAwaitsProviderIdentity, codexAppServerTurnCanAdoptSuccessor, codexAppServerAgentRun, CODEX_APP_SERVER_RUN_STATE } from "./codexTurnState.js";
 import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 
 /**
@@ -325,10 +325,7 @@ export function createCodexResultSettlement({ journal, output, createRuntime, pu
       normalizedThreadId,
       previousTurnId
     );
-    journal.completedTurns.add(codexAppServerTurnKey(
-      normalizedThreadId,
-      previousTurnId
-    ));
+    journal.markTurnCompleted(normalizedThreadId, previousTurnId);
     const previousResultKey = output.resultFinalizationKey(
       normalizedSessionId,
       normalizedThreadId,

package/src/server/conversation/codexRunJournal.js

@@ -3,6 +3,7 @@ import crypto from "node:crypto";
 import { isRecord, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 
 const CODEX_APP_SERVER_PROMPT_CLAIM_GRACE_MS = 15000;
+const CODEX_APP_SERVER_REPORTED_TURN_LIMIT = 256;
 const CODEX_APP_SERVER_STOPPED_BY_SHUTDOWN_EVENT = "codex-app-server-stopped-by-shutdown";
 
 /**
@@ -46,6 +47,55 @@ function codexAppServerDateValueMs(value = "") {
   return Number.isFinite(parsed) ? parsed : 0;
 }
 
+/**
+ * Which turns Codex accepted with turn/start but has not reported yet: until it reports one, its thread still reads
+ * idle, so an idle read cannot settle it. Codex's turn/started can also arrive before its answer to turn/start, so the
+ * turns it reported most recently are remembered and never marked as not started. Only a turn whose answer is still on
+ * its way needs that, so the newest few are enough.
+ * @param {Set<string>} completedTurns the journal's settled turn keys, which markTurnCompleted adds to
+ */
+function createCodexAppServerTurnStarts(completedTurns) {
+  const unstartedTurns = new Set();
+  // Oldest first.
+  const reportedTurns = new Set();
+
+  /** Codex reported this turn, in a notification or by listing it as finished, so it has started it. */
+  function noteTurnReported(threadId = "", turnId = "") {
+    if (!normalizeText(turnId)) return;
+    const key = codexAppServerTurnKey(threadId, turnId);
+    unstartedTurns.delete(key);
+    reportedTurns.delete(key);
+    reportedTurns.add(key);
+    if (reportedTurns.size > CODEX_APP_SERVER_REPORTED_TURN_LIMIT) {
+      reportedTurns.delete(reportedTurns.values().next().value);
+    }
+  }
+
+  /** A turn Codex accepted waits for its report before an idle read can settle it, unless Codex already reported it. */
+  function markTurnUnstarted(threadId = "", turnId = "") {
+    const key = codexAppServerTurnKey(threadId, turnId);
+    if (!reportedTurns.has(key)) unstartedTurns.add(key);
+  }
+
+  function turnIsUnstarted(threadId = "", turnId = "") {
+    return unstartedTurns.has(codexAppServerTurnKey(threadId, turnId));
+  }
+
+  /** The run owner settled this turn: nothing waits for Codex to start it any more. */
+  function markTurnCompleted(threadId = "", turnId = "") {
+    const key = codexAppServerTurnKey(threadId, turnId);
+    completedTurns.add(key);
+    unstartedTurns.delete(key);
+  }
+
+  return Object.freeze({
+    noteTurnReported,
+    markTurnUnstarted,
+    turnIsUnstarted,
+    markTurnCompleted
+  });
+}
+
 /**
  * Native run claims, guarded journal writes and status retirement. The containing run owner shares these exact Sets
  * and Maps by reference.
@@ -88,8 +138,7 @@ 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 turnStarts = createCodexAppServerTurnStarts(codexAppServerCompletedTurns);
   const codexAppServerProcessedTurns = new Set();
   const codexAppServerActiveTimers = new Map();
   const codexAppServerFinalizingTimers = new Map();
@@ -639,7 +688,10 @@ export function createCodexRunJournal({
 
   return Object.freeze({
     completedTurns: codexAppServerCompletedTurns,
-    unstartedTurns: codexAppServerUnstartedTurns,
+    noteTurnReported: turnStarts.noteTurnReported,
+    markTurnUnstarted: turnStarts.markTurnUnstarted,
+    turnIsUnstarted: turnStarts.turnIsUnstarted,
+    markTurnCompleted: turnStarts.markTurnCompleted,
     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, codexAppServerTurnKey } from "./codexTurnState.js";
+import { codexAppServerTurnStatusIsActive, codexAppServerTurnStatusIsComplete, codexAppServerTurnStatusIsSuccessfulComplete, codexAppServerTurnStatusIsProviderFailure, codexAppServerThreadStatus, codexAppServerObservedTurnFinished, codexAppServerReadThreadStatus, codexAppServerAgentRun, codexAppServerTurnCanReceiveProviderCompletion, codexAppServerTurnCanAdoptSuccessor, codexAppServerErrorMessage } 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,12 +200,16 @@ export function createCodexThreadStatus({ journal, settlement, recovery, output,
         turnId
       };
     }
+    // Codex lists the tracked turn as finished: it ran, even if its notifications about it were missed.
+    if (trackedProviderTurn && codexAppServerObservedTurnFinished(thread, trackedProviderTurn.turnId)) {
+      journal.noteTurnReported(trackedProviderTurn.threadId, trackedProviderTurn.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))
+      journal.turnIsUnstarted(trackedProviderTurn.threadId, trackedProviderTurn.turnId)
     ) {
       debugLog("appServerThread.reconcile.awaitingProviderStart", {
         sessionId: normalizedSessionId,

package/src/server/conversation/codexTurnEndings.js

@@ -1,4 +1,4 @@
-import { codexAppServerTurnStatusIsActive, codexAppServerThreadStatus, codexAppServerReadThreadStatus, codexAppServerAgentRun, codexAppServerTurnOwnsActiveGoal, codexAppServerTurnCanReceiveProviderCompletion, codexAppServerTurnAwaitsProviderIdentity, codexAppServerTurnCanReceiveProviderActivity, codexAppServerTurnKey } from "./codexTurnState.js";
+import { codexAppServerTurnStatusIsActive, codexAppServerThreadStatus, codexAppServerReadThreadStatus, codexAppServerAgentRun, codexAppServerTurnOwnsActiveGoal, codexAppServerTurnCanReceiveProviderCompletion, codexAppServerTurnAwaitsProviderIdentity, codexAppServerTurnCanReceiveProviderActivity } from "./codexTurnState.js";
 import { codexAppServerThreadTurnId } from "./codexThreadSnapshot.js";
 import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 
@@ -201,7 +201,7 @@ export function createCodexTurnEndings({
       };
     }
     if (journal.runInputSource(codexAppServerAgentRun(session)) === "terminal") {
-      journal.completedTurns.add(codexAppServerTurnKey(normalizedThreadId, normalizedTurnId));
+      journal.markTurnCompleted(normalizedThreadId, normalizedTurnId);
       output.cleanupUntrackedTurn(normalizedThreadId, normalizedTurnId);
       await journal.markTurnIdle(normalizedSessionId, {
         status: normalizedStatus,
@@ -217,7 +217,7 @@ export function createCodexTurnEndings({
     const alreadyFinalizing = existingTurn.state === "finalizing" &&
       existingTurn.threadId === normalizedThreadId &&
       existingTurn.turnId === normalizedTurnId;
-    journal.completedTurns.add(codexAppServerTurnKey(normalizedThreadId, normalizedTurnId));
+    journal.markTurnCompleted(normalizedThreadId, normalizedTurnId);
     if (!alreadyFinalizing) {
       await journal.markTurnFinalizing(normalizedSessionId, {
         status: normalizedStatus,

package/src/server/conversation/codexTurnRecovery.js

@@ -1,4 +1,4 @@
-import { codexAppServerTurnStatusIsActive, codexAppServerTurnStatusIsComplete, codexAppServerTurnStatusIsSuccessfulComplete, codexAppServerTurnStatusIsProviderFailure, codexAppServerThreadStatus, codexAppServerReadThreadStatus, codexAppServerAgentRun, codexAppServerPendingUserMessageOwnership, codexAppServerTurnCanAdoptSuccessor, codexAppServerTurnKey } from "./codexTurnState.js";
+import { codexAppServerTurnStatusIsActive, codexAppServerTurnStatusIsComplete, codexAppServerTurnStatusIsSuccessfulComplete, codexAppServerTurnStatusIsProviderFailure, codexAppServerThreadStatus, codexAppServerObservedTurnFinished, codexAppServerReadThreadStatus, codexAppServerAgentRun, codexAppServerPendingUserMessageOwnership, codexAppServerTurnCanAdoptSuccessor } from "./codexTurnState.js";
 import { codexAppServerProviderTurnForOperation, codexAppServerThreadTurnId, codexAppServerThreadError } from "./codexThreadSnapshot.js";
 import { createCodexTurnActivity } from "./codexTurnActivity.js";
 import { createCodexTurnEndings } from "./codexTurnEndings.js";
@@ -270,16 +270,21 @@ 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;
+    if (journal.turnIsUnstarted(currentTurn.threadId, currentTurn.turnId)) {
+      // Codex may have accepted this turn without starting it: its thread reads idle until it does. Only Codex's own
+      // listing of the turn as finished settles it before a notification about the turn arrives.
+      const observed = await codexAppServerReadThreadStatus(provider, currentTurn.threadId, { observeLatestTurn: true });
+      if (!codexAppServerObservedTurnFinished(observed, currentTurn.turnId)) {
+        debugLog("appServerTurn.reconcile.awaitingProviderStart", {
+          sessionId,
+          status,
+          threadId: currentTurn.threadId,
+          turnId: currentTurn.turnId
+        });
+        scheduleCodexAppServerActiveRecovery(sessionId);
+        return currentSession;
+      }
+      journal.noteTurnReported(currentTurn.threadId, currentTurn.turnId);
     }
     const completedTurnId = providerTurnId || currentTurn.turnId;
     debugLog("appServerTurn.reconcile.complete", {

package/src/server/conversation/codexTurnState.js

@@ -38,6 +38,19 @@ function codexAppServerThreadStatus(thread = {}) {
   return liveStatus;
 }
 
+/**
+ * Whether a thread read lists exactly this turn as finished, completed or failed. Codex lists a turn it has accepted
+ * but not yet started as interrupted, so only these two say that it ran.
+ * @param {Record<string, unknown> | null} thread a read with its latest turn observed
+ * @param {string} turnId
+ */
+function codexAppServerObservedTurnFinished(thread = null, turnId = "") {
+  const observed = isRecord(thread?.observedTurn) ? thread.observedTurn : null;
+  const normalizedTurnId = normalizeNullableText(turnId);
+  if (!observed || !normalizedTurnId || normalizeNullableText(observed.id) !== normalizedTurnId) return false;
+  return ["completed", "failed"].includes(normalizeNullableText(observed.status));
+}
+
 /**
  * Reads a native thread's status, and with observeLatestTurn its latest turn too.
  * @param {import("./codexProvider.js").CodexAppServerAgentProvider | null} provider
@@ -604,4 +617,4 @@ function codexPromptInputFromRequest(input = {}) {
   return codexAppServerMessageText(input);
 }
 
-export { codexAppServerRunInputSource, codexAppServerThreadStatus, codexAppServerReadThreadStatus, codexAppServerTurnStatusIsActive, codexAppServerTurnStatusIsComplete, codexAppServerTurnStatusIsSuccessfulComplete, codexAppServerTurnStatusIsProviderFailure, codexAppServerErrorMessage, codexAppServerMessageDeferred, codexPromptInputFromRequest, CODEX_APP_SERVER_AGENT_RUN_ID, CODEX_APP_SERVER_RESULT_PROCESSED_EVENT, CODEX_AGENT_PROVIDER, CODEX_APP_SERVER_ACTIVE_RUN_STATES };
+export { codexAppServerRunInputSource, codexAppServerThreadStatus, codexAppServerObservedTurnFinished, codexAppServerReadThreadStatus, codexAppServerTurnStatusIsActive, codexAppServerTurnStatusIsComplete, codexAppServerTurnStatusIsSuccessfulComplete, codexAppServerTurnStatusIsProviderFailure, codexAppServerErrorMessage, codexAppServerMessageDeferred, codexPromptInputFromRequest, CODEX_APP_SERVER_AGENT_RUN_ID, CODEX_APP_SERVER_RESULT_PROCESSED_EVENT, CODEX_AGENT_PROVIDER, CODEX_APP_SERVER_ACTIVE_RUN_STATES };