@jskit-ai/assistant-core 0.1.239 → 0.1.241

package/src/server/conversation/claudeHistory.js

@@ -5,18 +5,30 @@ import { readClaudeJsonFrames } from "./claudeClient.js";
 import { createNativeHistoryExport, retireNativeConversation } from "./nativeHistoryExport.js";
 
 const UUID_PATTERN = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/iu;
+const TRANSCRIPT_PATH_PATTERN = /\.jsonl(?:\.(?:superseded|orphaned)-.*)?$/u;
 
 function requireClaudeSessionId(id) {
   if (!UUID_PATTERN.test(id)) throw new TypeError("Invalid Claude conversation id.");
   return id;
 }
 
+// Claude's project directory name for a canonical working directory.
+function claudeProjectDirectoryName(canonical) {
+  return canonical.normalize("NFC").replace(/[^a-zA-Z0-9]/gu, "-");
+}
+
+// Text the person authored in a user frame: plain content or its text blocks.
+function claudeUserText(content) {
+  return typeof content === "string" ? content : (Array.isArray(content) ? content : [])
+    .filter((block) => block.type === "text" && typeof block.text === "string").map((block) => block.text).join("\n\n");
+}
+
 async function archivedClaudeProjectDirectory(workdir) {
   const canonical = await realpath(workdir).catch((error) => {
     if (error.code === "ENOENT") return workdir;
     throw error;
   });
-  return canonical.normalize("NFC").replace(/[^a-zA-Z0-9]/gu, "-");
+  return claudeProjectDirectoryName(canonical);
 }
 
 function matchingClaudeProjectDirectories(names, directory) {
@@ -37,7 +49,7 @@ export async function listClaudeConversationStorage({ configRoot, binding }) {
     const entries = await readdir(path.join(projects, name), { withFileTypes: true });
     if (entries.length > 10000) throw new Error("Claude conversation inventory exceeds its limit.");
     for (const entry of entries) {
-      const id = entry.name.replace(/\.jsonl(?:\.(?:superseded|orphaned)-.*)?$/u, "");
+      const id = entry.name.replace(TRANSCRIPT_PATH_PATTERN, "");
       if (UUID_PATTERN.test(id) && entry.isFile()) ids.add(id);
     }
   }
@@ -49,14 +61,13 @@ export async function listClaudeConversationStorage({ configRoot, binding }) {
 // lookup because its native and Node builds use different hash suffixes.
 async function claudeHistoryPath({ configRoot, workdir, conversationId }) {
   requireClaudeSessionId(conversationId);
-  const canonical = (await realpath(workdir)).normalize("NFC");
-  const directory = canonical.replace(/[^a-zA-Z0-9]/gu, "-");
+  const directory = claudeProjectDirectoryName(await realpath(workdir));
   const projects = path.join(configRoot, "projects");
-  const candidates = directory.length <= 200 ? [directory] :
-    (await readdir(projects).catch((error) => {
+  const candidates = directory.length <= 200 ? [directory] : matchingClaudeProjectDirectories(
+    await readdir(projects).catch((error) => {
       if (error.code === "ENOENT") return [];
       throw error;
-    })).filter((name) => name.startsWith(`${directory.slice(0, 200)}-`));
+    }), directory);
   for (const name of candidates) {
     const candidate = path.join(projects, name, `${conversationId}.jsonl`);
     const info = await stat(candidate).catch((error) => {
@@ -283,10 +294,7 @@ async function readClaudeHistory(options) {
       userIds.push(frame.uuid);
       lastUserId = frame.uuid;
       if (options.includeUserMessages && !frame.parent_tool_use_id) {
-        const content = frame.message.content;
-        const text = typeof content === "string" ? content : content
-          .filter(block => block.type === "text" && typeof block.text === "string").map(block => block.text).join("\n\n");
-        inspected.userMessages.push({ id: frame.uuid, text });
+        inspected.userMessages.push({ id: frame.uuid, text: claudeUserText(frame.message.content) });
       }
     }
     if (options.includeFinalCarriers && !frame.parent_tool_use_id && !frame.isMeta) {
@@ -333,8 +341,6 @@ export async function deleteClaudeConversationHistory({ configRoot, workdir, con
 
 export { claudeHistoryPath, claudeMessageBlocks, readClaudeHistory, requireClaudeSessionId, archivedClaudeProjectDirectory, matchingClaudeProjectDirectories };
 
-const TRANSCRIPT_PATH_PATTERN = /\.jsonl(?:\.(?:superseded|orphaned)-.*)?$/u;
-
 export async function retireClaudeConversationHistory({ configRoot, binding, beforeDelete, requireIdle, signal }) {
   const id = requireClaudeSessionId(binding.conversationId);
   if (!path.isAbsolute(configRoot)) throw new TypeError("Claude retirement requires an absolute configuration root.");
@@ -411,9 +417,7 @@ export async function retireClaudeConversationHistory({ configRoot, binding, bef
             .filter((message) => message.role !== "thinking")
             .map((message) => ({ ...provenance, role: "assistant", text: message.text }));
           if (frame.type === "user") {
-            const content = frame.message?.content;
-            const user = typeof content === "string" ? content : (Array.isArray(content) ? content : [])
-              .filter((block) => block.type === "text" && typeof block.text === "string").map((block) => block.text).join("\n\n");
+            const user = claudeUserText(frame.message?.content);
             if (user) text.push({ ...provenance, role: "user", text: user });
           }
           if (frame.attachment?.type === "goal_status" && typeof frame.attachment.condition === "string") {

package/src/server/conversation/claudeProcess.js

@@ -1,4 +1,4 @@
-import { createHash } from "node:crypto";
+import { jsonHash } from "./normalize.js";
 import { nativeAiProvider } from "../../shared/nativeProviders.js";
 import { Duplex } from "node:stream";
 import { stat } from "node:fs/promises";
@@ -83,7 +83,7 @@ async function readNativeClaudeCodeAuthStatus({ env, credentialHome, command, co
 
 /** Exact existing native connection pin, shared with stopped metadata conversion. */
 export function claudeConnectionIdentity(configRoot, providerId, baseUrl, apiKey) {
-  return createHash("sha256").update(JSON.stringify([configRoot, providerId, baseUrl, apiKey])).digest("hex");
+  return jsonHash([configRoot, providerId, baseUrl, apiKey]);
 }
 
 /** Native provider routing; the application supplies only its authorized selection. */

package/src/server/conversation/claudeTurn.js

@@ -5,13 +5,14 @@ import { setTimeout as delay } from "node:timers/promises";
 import { claudeMessageBlocks, deleteClaudeConversationHistory, readClaudeHistory, requireClaudeSessionId, retireClaudeConversationHistory } from "./claudeHistory.js";
 import { bindClaudeConversationAccount, claudeCodeArguments, createClaudeAccountQueries, createClaudeCodeProcess, stopClaudeCodeProcess } from "./claudeProcess.js";
 import { claudeApplicationToolResponse } from "./claudeTools.js";
+import { normalizeNullableText } from "./normalize.js";
 import { createClaudeConversationAdapter } from "./providers/claude.js";
 
 function failure(message, code = "assistant_claude_turn_failed") {
   return Object.assign(new Error(message), { code });
 }
 
-const text = value => String(value ?? "").trim();
+const text = normalizeNullableText;
 const now = () => new Date().toISOString();
 
 function hasPendingClaudeStartup(entry) {
@@ -166,6 +167,11 @@ export function createClaudeConversationOwner({
   let closing = false;
   const createProcess = process.create || createClaudeCodeProcess;
   const saveAccount = store.save;
+  // Two hosts share this owner. A bound store (one with releaseExecution) is a
+  // runtime binding: the native turn owns activity and execution release.
+  // Otherwise the host retains entries and their original checkpoint order.
+  const bound = Boolean(store.releaseExecution);
+  const isTurnActive = entry => bound ? entry.nativeTurn.read().active : Boolean(entry.turn?.active);
 
   function createAccountQueries({ accountIdentity, createProcess }) {
     return createClaudeAccountQueries({ accountIdentity,
@@ -249,13 +255,13 @@ export function createClaudeConversationOwner({
       }
     }
     if (entry.pausedGoal && entry.blockedGoal) throw createError("The saved Claude goal cannot be both paused and blocked.");
-    entry.nativeTurn = createClaudeConversationTurn({ conversationId: id, entry,
+    entry.nativeTurn = createClaudeConversationTurn({ conversationId: id, entry, bound,
       onEvent: event => onEvent(entry, event),
       process: {
         stopExecution: process.stopExecution,
-        ...(store.releaseExecution ? { releaseExecution: () => store.releaseExecution(entry) } : {}),
+        ...(bound ? { releaseExecution: () => store.releaseExecution(entry) } : {}),
         getProcess: () => entry.stopping ? null : entry.process,
-        isActive: () => store.releaseExecution ? entry.nativeTurn.read().active : Boolean(entry.turn?.active),
+        isActive: () => isTurnActive(entry),
         startProcess: input => startProcess(entry, input),
         stopProcess: reason => entry.process || entry.executionId
           ? entry.nativeTurn.stopProcess(reason, { preparing: true }) : Promise.resolve()
@@ -271,7 +277,7 @@ export function createClaudeConversationOwner({
         try { await store.save(entry); }
         catch (error) { Object.assign(entry, previous); throw error; }
       },
-      readState: () => ({ running: Boolean(entry.process), active: store.releaseExecution ? entry.nativeTurn.read().active : Boolean(entry.turn?.active) }),
+      readState: () => ({ running: Boolean(entry.process), active: isTurnActive(entry) }),
       interrupt: () => interrupt(entry), send: input => send(entry, input) });
     entries.set(key, entry);
     await store.save(entry);
@@ -312,7 +318,7 @@ export function createClaudeConversationOwner({
   async function ensureReady(entry) {
     if (entry.process) {
       // Status reads retain active instructions; apply changes at idle admission.
-      if (store.releaseExecution ? entry.nativeTurn.read().active : entry.turn?.active) await bindAccount(entry);
+      if (isTurnActive(entry)) await bindAccount(entry);
       else await ensureProcess(entry);
     } else {
       await bindAccount(entry);
@@ -441,10 +447,10 @@ export function createClaudeConversationOwner({
         }
         await entry.nativeTurn.receive(frame);
       },
-      ...(store.releaseExecution || options.applicationTools || entry.command?.tools ? {
+      ...(bound || options.applicationTools || entry.command?.tools ? {
         async onControlRequest(request, { signal }) {
           const active = entry.command;
-          const suppliedTools = !store.releaseExecution && active?.tools;
+          const suppliedTools = !bound && active?.tools;
           const owner = active?.nativeOwner;
           const work = applicationCall.run({ entry, command: active, owner,
             toolUseId: request.message?.params?._meta?.["claudecode/toolUseId"] },
@@ -471,7 +477,7 @@ export function createClaudeConversationOwner({
       } : {}),
       onFailure: async error => {
         if (entry.localCommand?.processToken === processToken) entry.localCommand.reject(error);
-        if (store.releaseExecution) {
+        if (bound) {
           entry.nativeTurn.invalidateInstructions();
           try { await entry.nativeTurn.stopProcess(error.message); }
           catch (cleanupError) { error = cleanupError; await context.reportFailure(cleanupError); }
@@ -492,7 +498,7 @@ export function createClaudeConversationOwner({
           await onEvent(entry, { type: "execution", context, executionId: entry.executionId });
         } catch (bindingError) { error.bindingError = bindingError; }
       }
-      if (store.releaseExecution && error.stopProof?.scopeEmpty) {
+      if (bound && error.stopProof?.scopeEmpty) {
         await store.releaseExecution(entry);
         if (entry.startupCleanup?.executionId === error.executionId) entry.startupCleanup = null;
       }
@@ -893,6 +899,14 @@ export function createClaudeConversationOwner({
     return { status: "available", threadId: entry.id, goal: await entry.goals.read(history), goalCommandId: history.goalCommandId || null };
   }
 
+  // A native Set, Resume or Cancel supersedes a retained Pause or blocker.
+  async function releaseRetainedGoal(entry) {
+    if (!entry.pausedGoal && !entry.blockedGoal) return;
+    entry.pausedGoal = null;
+    entry.blockedGoal = null;
+    await store.save(entry);
+  }
+
   async function updateGoal(entry, input, operations) {
     await bindAccount(entry);
     const call = applicationCall.getStore();
@@ -928,7 +942,7 @@ export function createClaudeConversationOwner({
       for (;;) {
         const history = await readHistory(entry);
         if (history.goalCommandId === claudeNativeMessageId(messageId)) {
-          if (entry.pausedGoal || entry.blockedGoal) { entry.pausedGoal = null; entry.blockedGoal = null; await store.save(entry); }
+          await releaseRetainedGoal(entry);
           result = { status: "available", threadId: entry.id, goal: await entry.goals.read(history), goalCommandId: history.goalCommandId };
           break;
         }
@@ -952,7 +966,7 @@ export function createClaudeConversationOwner({
   }
 
   async function cancel(control, { context, acquire, reportFailure, entry }) {
-    if (store.releaseExecution) {
+    if (bound) {
       await entry.nativeTurn.stopProcess("Work stopped.");
       return;
     }
@@ -973,7 +987,7 @@ export function createClaudeConversationOwner({
   }
 
   async function dispatch(control, command, { acquire, entry: selectedEntry, dispatch: nativeDispatch }) {
-    if (store.releaseExecution) {
+    if (bound) {
       await send(selectedEntry, command.input, { command: nativeDispatch });
       return;
     }
@@ -1001,14 +1015,13 @@ export function createClaudeConversationOwner({
   }
 
   function steer(control, command, options) {
-    if (!store.releaseExecution) return dispatch(control, command, options).then(delivered => ({ value: delivered.value }));
+    if (!bound) return dispatch(control, command, options).then(delivered => ({ value: delivered.value }));
     if (!control.current?.steer || !control.current.entry.nativeTurn.read().active) throw new Error("Claude has no active turn to steer.");
     return control.current.steer(command);
   }
 
   async function run(control, command, { acquire, reportFailure, entry: selectedEntry, maximumOutput, maximumToolCalls = 32, timeoutMs } = {}) {
     if (control.disposed || control.current) throw new Error("This Claude conversation is closed or already working.");
-    const binding = Boolean(store.releaseExecution);
     const { configuration, context, input, tools, signal, beforeDispatch, accept, onMessage, onEvent, onNativeToolUse } = command;
     const completion = Promise.withResolvers();
     completion.promise.catch(() => {});
@@ -1039,7 +1052,7 @@ export function createClaudeConversationOwner({
     let delivered;
     function abort() {
       if (cancellation) return;
-      if (binding) {
+      if (bound) {
         cancellation = entry.nativeTurn.cancel(entry.process?.client, () => entry.nativeTurn.stopProcess("Work stopped."));
         cancellation.then(() => completion.reject(signal.reason), error => completion.reject(error));
       } else {
@@ -1048,7 +1061,7 @@ export function createClaudeConversationOwner({
       }
     }
     try {
-      if (binding) {
+      if (bound) {
         entry = selectedEntry;
         if (entry.disposed || entry.command) throw new Error("This Claude conversation is closed or already working.");
         active.entry = entry;
@@ -1062,7 +1075,7 @@ export function createClaudeConversationOwner({
       let dispatchFailure;
       try {
         delivered = await dispatch(control, command, { acquire, entry, dispatch: nativeDispatch });
-        if (binding) ready.resolve();
+        if (bound) ready.resolve();
       } catch (error) { dispatchFailure = error; }
       for (;;) {
         const settling = active.delivery;
@@ -1078,15 +1091,15 @@ export function createClaudeConversationOwner({
           catch (error) { problem = error; }
         }
         problem = dispatchFailure || failure || problem;
-        if (!problem && settling?.completion && (binding ? result.status !== "completed" : !result.ok)) {
-          problem = Object.assign(new Error(result.error || (binding ? "Claude interrupted this answer." : `Claude turn ${result.status}.`)), { status: result.status });
+        if (!problem && settling?.completion && (bound ? result.status !== "completed" : !result.ok)) {
+          problem = Object.assign(new Error(result.error || (bound ? "Claude interrupted this answer." : `Claude turn ${result.status}.`)), { status: result.status });
         }
         break;
       }
     } catch (error) { problem = error; }
     ready.reject(problem || new Error("Claude work ended."));
     signal.removeEventListener("abort", abort);
-    if (binding) {
+    if (bound) {
       try {
         if (problem || signal.aborted) await (cancellation || entry.nativeTurn.stopProcess(problem?.message || "Work stopped."));
       } catch (error) {
@@ -1118,19 +1131,19 @@ export function createClaudeConversationOwner({
     }
     if (control.current === active) control.current = null;
     if (problem) {
-      if (binding && nativeDispatch.attempted && !nativeDispatch.admitted && problem.delivery !== "not-sent") problem.delivery = "uncertain";
+      if (bound && nativeDispatch.attempted && !nativeDispatch.admitted && problem.delivery !== "not-sent") problem.delivery = "uncertain";
       throw problem;
     }
-    if (!binding) return { value: delivered.value };
+    if (!bound) return { value: delivered.value };
   }
 
-  return Object.freeze({ applicationToolsSupported: true, entries, closingSessions, get closing() { return closing; }, createAccountQueries, open, acquire, createConversation, snapshot, readRetainedTurn, readFinalAssistantResult, readHistory, ensureReady, ensureProcess, readContextUsage, compactContext, stopForTerminal, prepareTerminal, send, startTurn,
+  return Object.freeze({ applicationToolsSupported: true, entries, closingSessions, get closing() { return closing; }, createAccountQueries, open, acquire, createConversation, snapshot, readRetainedTurn, readFinalAssistantResult, readHistory, ensureReady, ensureProcess, readContextUsage, compactContext, releaseRetainedGoal, stopForTerminal, prepareTerminal, send, startTurn,
     interrupt, read, inspectAdmission, hasActiveTemporaryConversation, hasActiveConversation, retireConversationHistory, reconcileSessions, restoreSessionEntries, closeSession, closeProject, invalidateRuntimes, drain, forget, close, deleteConversation, recover, stopSelected, wait, stopConversation,
     readGoal, updateGoal, renewal, run, steer, cancel });
 }
 
 /** Native turn handling moved from the production session provider; hosts persist its events. */
-export function createClaudeConversationTurn({ conversationId, onEvent = async () => {}, process, entry } = {}) {
+export function createClaudeConversationTurn({ conversationId, onEvent = async () => {}, process, entry, bound = false } = {}) {
   if (!conversationId) throw new TypeError("A Claude conversation id is required.");
   const instructions = process ? createClaudeConversationAdapter(process) : null;
   const publish = entry ? publishEntryEvent : onEvent;
@@ -1241,31 +1254,30 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
     invalidateFinalAssistantResult();
     // Runtime bindings commit execution release before dropping the handle.
     // Retained host entries keep their original post-proof checkpoint order.
-    const binding = Boolean(process.releaseExecution);
     if (entry.stopPending) return entry.stopPending;
     const active = read().active;
-    if (!binding) entry.stopping = true;
+    if (!bound) entry.stopping = true;
     const operation = async () => {
       const startup = entry.startupCleanup?.executionId === entry.executionId ? entry.startupCleanup : null;
       let proof;
       try {
-        if (!binding || entry.process || entry.executionId) {
+        if (!bound || entry.process || entry.executionId) {
           proof = await stopClaudeCodeProcess({ process: entry.process || startup, executionId: entry.executionId,
             stopExecution: process.stopExecution });
         }
       } catch (error) {
-        if (binding || error.code !== "claude_stop_unconfirmed") throw error;
+        if (bound || error.code !== "claude_stop_unconfirmed") throw error;
         entry.observationError = reason || "Claude process exit has not been confirmed. Try Stop again.";
         await onEvent({ type: "save" });
         await onEvent({ type: "stop-unconfirmed" });
         throw error;
       }
-      if (binding && (entry.process || entry.executionId)) await process.releaseExecution();
+      if (bound && (entry.process || entry.executionId)) await process.releaseExecution();
       entry.process = null;
       entry.executionId = "";
       entry.exitProof = proof;
-      stop(binding ? reason : reason || "Claude stopped before acknowledging the prompt.");
-      if (binding) {
+      stop(bound ? reason : reason || "Claude stopped before acknowledging the prompt.");
+      if (bound) {
         if (entry.startupCleanup === startup) entry.startupCleanup = null;
         if (active) entry.completion?.resolve({ status: "interrupted", error: reason || "Work stopped." });
         return;
@@ -1287,7 +1299,7 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
       if (entry.startupCleanup === startup) entry.startupCleanup = null;
       return entry.exitProof;
     };
-    entry.stopPending = operation().catch(error => { if (binding) error.cleanupFailed = true; throw error; })
+    entry.stopPending = operation().catch(error => { if (bound) error.cleanupFailed = true; throw error; })
       .finally(() => { entry.stopPending = null; });
     return entry.stopPending;
   }
@@ -1295,9 +1307,8 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
   async function publishEntryEvent(event, deferred = false) {
     if (entry.stopping) return;
     if (event.type === "settled" && event.generation !== generation) return;
-    const binding = Boolean(process.releaseExecution);
     const command = entry.command;
-    if (event.type === "settled" && !binding && !deferred && command?.finishIfCurrent && command !== checkpointedCommand) {
+    if (event.type === "settled" && !bound && !deferred && command?.finishIfCurrent && command !== checkpointedCommand) {
       const delivery = command.delivery;
       const completion = entry.completion;
       const owner = acceptedInput;
@@ -1328,17 +1339,17 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
     }
     if (event.type === "continued") {
       if (entry.completion === resolvedCompletion) entry.completion = Promise.withResolvers();
-      if (binding) setState("active");
+      if (bound) setState("active");
       else await updateState("active");
     } else if (event.type === "admitted") {
       if (event.userEcho) entry.sent = true;
-      if (!binding) await onEvent({ type: "save" });
+      if (!bound) await onEvent({ type: "save" });
     } else if (event.type === "phase") {
       entry.turn.phase = event.phase;
-      if (!binding) await updateState(entry.turn.state);
+      if (!bound) await updateState(entry.turn.state);
     } else if (event.type === "settled") {
       const state = event.status === "interrupted" ? "interrupted" : event.status === "failed" ? "failed" : "completed";
-      if (binding) setState(state, event.error);
+      if (bound) setState(state, event.error);
       else if (!await updateState(state, event.error, event.generation)) return;
     }
     const published = await onEvent(event);
@@ -1350,7 +1361,7 @@ export function createClaudeConversationTurn({ conversationId, onEvent = async (
     if (event.type === "settled") {
       if (event.generation !== generation) return;
       if (event.source === "result") await onEvent({ type: "provider-update", change: "goal" });
-      resolveCompletion(binding ? event : readResult());
+      resolveCompletion(bound ? event : readResult());
     }
     return published;
   }

package/src/server/conversation/codexAuthPreflight.js

@@ -0,0 +1,104 @@
+import path from "node:path";
+import { codexAuthOutputRequiresReconnect } from "./codexConfiguration.js";
+import {
+  assertExistingDirectory, codexAppServerCommandBaseEnv, codexAppServerCredentialHome,
+  codexAppServerProcessCwd, ensureWritablePrivateDirectory
+} from "./codexProcess.js";
+import { normalizePositiveInteger } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeNullableText as normalizeAgentText } from "./normalize.js";
+
+// Codex auth preflight: one bounded `codex debug models` run whose
+// reconnect-required output marks the stored credentials invalid.
+const CODEX_AUTH_PREFLIGHT_TIMEOUT_MS = 15000;
+const CODEX_AUTH_PREFLIGHT_OUTPUT_TAIL_BYTES = 4096;
+
+function tailAppend(text = "", chunk = "", maxBytes = CODEX_AUTH_PREFLIGHT_OUTPUT_TAIL_BYTES) {
+  const next = `${String(text || "")}${String(chunk || "")}`;
+  return next.length > maxBytes ? next.slice(-maxBytes) : next;
+}
+
+function codexAuthPreflightArgs() {
+  return [
+    "-c",
+    "check_for_update_on_startup=false",
+    "debug",
+    "models"
+  ];
+}
+
+async function runCodexAuthPreflight({
+  codexCommand = "codex",
+  env = process.env,
+  executionRoot = "",
+  runtimeDir = "",
+  terminalEnv = {},
+  timeoutMs = CODEX_AUTH_PREFLIGHT_TIMEOUT_MS,
+  toolHomeSource = "",
+  workdir = ""
+} = {}, execution) {
+  const normalizedToolHomeSource = normalizeAgentText(toolHomeSource);
+  if (normalizedToolHomeSource) {
+    await assertExistingDirectory(normalizedToolHomeSource, "Codex credential home");
+  }
+  const normalizedRuntimeDir = normalizeAgentText(runtimeDir);
+  if (normalizedRuntimeDir) {
+    await ensureWritablePrivateDirectory(path.resolve(normalizedRuntimeDir));
+  }
+  const baseEnv = codexAppServerCommandBaseEnv({
+    env,
+    terminalEnv
+  });
+  const processCwd = codexAppServerProcessCwd({
+    executionRoot,
+    runtimeDir,
+    workdir
+  });
+  try {
+    const result = await execution.run({
+      args: codexAuthPreflightArgs(),
+      baseEnv,
+      command: codexCommand,
+      credentialHome: codexAppServerCredentialHome(normalizedToolHomeSource, baseEnv),
+      cwd: processCwd,
+      inheritProcessEnv: false,
+      mode: "capture",
+      timeout: normalizePositiveInteger(timeoutMs, { fallback: CODEX_AUTH_PREFLIGHT_TIMEOUT_MS })
+    });
+    return {
+      code: result.exitCode,
+      ok: result.ok === true,
+      output: tailAppend("", result.output || [
+        result.stderr,
+        result.stdout
+      ].filter(Boolean).join("\n")),
+      signal: result.signal,
+      timedOut: result.timedOut === true
+    };
+  } catch (error) {
+    return {
+      error,
+      ok: false,
+      output: normalizeAgentText(error?.message || error)
+    };
+  }
+}
+
+export async function assertCodexAuthPreflightReady(options = {}, {
+  reason = "codex-auth-preflight", execution, credentials
+} = {}) {
+  const result = await runCodexAuthPreflight(options, execution);
+  if (result.ok && !codexAuthOutputRequiresReconnect(result.output)) {
+    return result;
+  }
+  const observed = normalizeAgentText(result.output || result.error?.message || "Codex auth preflight failed.");
+  if (codexAuthOutputRequiresReconnect(observed)) {
+    await credentials.markInvalid( {
+      reason
+    });
+    throw credentials.reconnectError({
+      modelProviderId: "",
+      observed
+    });
+  }
+  throw new Error(observed || "Codex auth preflight failed.");
+}

package/src/server/conversation/codexClient.js

@@ -1,10 +1,13 @@
 import { createConnection } from "node:net";
 import WebSocket from "ws";
-import { normalizeText as normalizeAgentText } from "./normalize.js";
+import { normalizePositiveInteger } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeNullableText as normalizeAgentText } from "./normalize.js";
 const CODEX_APP_SERVER_REQUEST_TIMEOUT_MS = 60_000;
-function normalizePositiveInteger(value, fallback) {
-  const number = Number(value);
-  return Number.isSafeInteger(number) && number > 0 ? number : fallback;
+
+function messageTooLargeError() {
+  const error = new Error("Codex app-server message exceeded the configured transport limit.");
+  error.code = "assistant_codex_app_server_message_too_large";
+  return error;
 }
 
 function socketPathFromCodexAppServerEndpoint(endpoint = "") {
@@ -56,10 +59,8 @@ class CodexAppServerJsonRpcClient {
     WebSocketImpl = WebSocket
   } = {}) {
     this.endpoint = normalizeAgentText(endpoint);
-    this.maxMessageBytes = Number.isSafeInteger(maxMessageBytes) && maxMessageBytes > 0
-      ? maxMessageBytes
-      : Number.POSITIVE_INFINITY;
-    this.requestTimeoutMs = normalizePositiveInteger(requestTimeoutMs, CODEX_APP_SERVER_REQUEST_TIMEOUT_MS);
+    this.maxMessageBytes = normalizePositiveInteger(maxMessageBytes, { fallback: Number.POSITIVE_INFINITY });
+    this.requestTimeoutMs = normalizePositiveInteger(requestTimeoutMs, { fallback: CODEX_APP_SERVER_REQUEST_TIMEOUT_MS });
     this.WebSocketImpl = WebSocketImpl;
     this.onDisconnect = onDisconnect;
     this.nextRequestId = 1;
@@ -233,11 +234,7 @@ class CodexAppServerJsonRpcClient {
       throw new Error("Codex app-server connection is not open.");
     }
     const serialized = JSON.stringify(payload);
-    if (Buffer.byteLength(serialized, "utf8") > this.maxMessageBytes) {
-      const error = new Error("Codex app-server message exceeded the configured transport limit.");
-      error.code = "assistant_codex_app_server_message_too_large";
-      throw error;
-    }
+    if (Buffer.byteLength(serialized, "utf8") > this.maxMessageBytes) throw messageTooLargeError();
     this.socket.send(serialized);
   }
 
@@ -246,9 +243,7 @@ class CodexAppServerJsonRpcClient {
     try {
       const text = socketMessageText(event, this.maxMessageBytes);
       if (text === null) {
-        const error = new Error("Codex app-server message exceeded the configured transport limit.");
-        error.code = "assistant_codex_app_server_message_too_large";
-        this.disconnect(error);
+        this.disconnect(messageTooLargeError());
         return;
       }
       message = JSON.parse(text);