@jskit-ai/assistant-core 0.1.240 → 0.1.241

package/src/server/conversation/codexOutput.js

@@ -10,11 +10,11 @@ import {
   codexAppServerRunInputSource
 } from "./codexTurnState.js";
 import crypto from "node:crypto";
-import { isPlainObject } from "./normalize.js";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
 import {
+  codexAppServerAgentMessageText,
   codexAppServerAssistantItemText,
   classifyCodexAppServerEvent,
-  codexAppServerContentText,
   codexAppServerNotificationEvent,
   codexAppServerNotificationEventType,
   codexAppServerNotificationEventPayload,
@@ -24,7 +24,7 @@ import {
   codexAppServerProviderThreadAssistantSegments
 } from "./codexEvents.js";
 
-// Original native output, reasoning persistence and exact-result identity.
+// Native output, reasoning persistence and exact-result identity.
 // One instance belongs to each retained run owner; its state is shared by reference.
 export function createCodexAppServerOutput({
   namespace,
@@ -73,7 +73,7 @@ export function createCodexAppServerOutput({
   function codexAppServerLiveProgressCandidate(notification = {}) {
     const method = normalizeCodexRunText(notification.method);
     const event = codexAppServerNotificationEvent(notification);
-    if (isPlainObject(event)) {
+    if (isRecord(event)) {
       const eventType = codexAppServerNotificationEventType(notification, event);
       const payload = codexAppServerNotificationEventPayload(notification, event);
       const payloadType = normalizeCodexRunText(payload.type);
@@ -83,11 +83,7 @@ export function createCodexAppServerOutput({
           explicit: Boolean(phase),
           phase,
           source: "event",
-          text: normalizeCodexRunText(
-            codexAppServerContentText(payload.message) ||
-            codexAppServerContentText(payload.text) ||
-            codexAppServerContentText(payload.content)
-          )
+          text: codexAppServerAgentMessageText(payload)
         };
       }
     }
@@ -557,15 +553,14 @@ export function createCodexAppServerOutput({
   }
 
   function codexAppServerStreamMessage(classification) {
+    const messageId = codexAppServerConversationMessageId(
+      classification.threadId, classification.turnId, "assistant-item", classification.itemId
+    );
     return {
       nativeIdentity: { threadId: classification.threadId, turnId: classification.turnId },
       turnId: `${classification.threadId}:${classification.turnId}`,
-      outputId: codexAppServerConversationMessageId(
-        classification.threadId, classification.turnId, "assistant-item", classification.itemId
-      ),
-      messageId: codexAppServerConversationMessageId(
-        classification.threadId, classification.turnId, "assistant-item", classification.itemId
-      ),
+      outputId: messageId,
+      messageId,
       role: classification.role,
       delta: classification.delta
     };
@@ -601,11 +596,9 @@ export function createCodexAppServerOutput({
     const store = await createStore(normalizedSessionId);
     const run = await readCodexAppServerAgentRunForSession(store, normalizedSessionId);
     const turn = turnStateFromAgentRun(run || {});
-    if (!codexAppServerTurnCanReceiveProviderActivity(
-      turn,
-      normalizedThreadId,
-      codexAppServerNotificationTurnId(notification)
-    )) {
+    const notificationTurnId = codexAppServerNotificationTurnId(notification);
+    const ownerTurnId = notificationTurnId || turn.turnId;
+    if (!codexAppServerTurnCanReceiveProviderActivity(turn, normalizedThreadId, notificationTurnId)) {
       return null;
     }
     const key = codexAppServerLiveProgressKey(normalizedSessionId, normalizedThreadId, notification);
@@ -615,11 +608,11 @@ export function createCodexAppServerOutput({
     const fingerprintKey = codexAppServerLiveProgressFingerprintKey(
       normalizedSessionId,
       normalizedThreadId,
-      codexAppServerNotificationTurnId(notification) || turn.turnId,
+      ownerTurnId,
       text
     );
     const streamMessageId = codexAppServerConversationMessageId(
-      normalizedThreadId, codexAppServerNotificationTurnId(notification),
+      normalizedThreadId, notificationTurnId,
       "assistant-item", codexAppServerNotificationItemId(notification)
     );
     if (
@@ -645,12 +638,12 @@ export function createCodexAppServerOutput({
           ...(streamMessageId ? { outputId: streamMessageId } : {}),
           messageId: codexAppServerConversationMessageId(
             normalizedThreadId,
-            codexAppServerNotificationTurnId(notification) || turn.turnId,
+            ownerTurnId,
             role,
             text
           ),
           requireOpenTurn: false,
-          nativeIdentity: { threadId: normalizedThreadId, turnId: codexAppServerNotificationTurnId(notification) || turn.turnId },
+          nativeIdentity: { threadId: normalizedThreadId, turnId: ownerTurnId },
           text
         });
         if (!written) {
@@ -660,7 +653,7 @@ export function createCodexAppServerOutput({
       }
       const payload = {
         conversationStream: await store.completeConversationStreamMessage(normalizedSessionId, streamMessageId, {
-          text, role, nativeIdentity: { threadId: normalizedThreadId, turnId: codexAppServerNotificationTurnId(notification) || turn.turnId }
+          text, role, nativeIdentity: { threadId: normalizedThreadId, turnId: ownerTurnId }
         })
       };
       if (written) {
@@ -794,7 +787,7 @@ export function createCodexAppServerOutput({
 
   function codexAppServerSnapshotCursor(run = {}) {
     const cursor = run?.providerSnapshotCursor;
-    if (!isPlainObject(cursor)) {
+    if (!isRecord(cursor)) {
       return {
         itemId: "",
         turnId: ""
@@ -847,7 +840,7 @@ export function createCodexAppServerOutput({
     const normalizedThreadId = normalizeCodexRunText(threadId);
     const normalizedTurnId = normalizeCodexRunText(observedTurn?.id);
     const items = (Array.isArray(observedTurn?.items) ? observedTurn.items : [])
-      .filter((item) => isPlainObject(item) && normalizeCodexRunText(item.id));
+      .filter((item) => isRecord(item) && normalizeCodexRunText(item.id));
     if (!normalizedSessionId || !normalizedThreadId || !normalizedTurnId || !items.length) {
       return;
     }

package/src/server/conversation/codexProcess.js

@@ -8,8 +8,9 @@ import path from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { CodexAppServerJsonRpcClient, socketPathFromCodexAppServerEndpoint } from "./codexClient.js";
 import { createConversationProcessIdentity } from "./localExecution.js";
-import { isPlainObject, normalizeText } from "./normalize.js";
-import { prepareCodexModelCatalog } from "./codexConfiguration.js";
+import { isRecord, normalizePositiveInteger } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeNullableText } from "./normalize.js";
+import { copyCodexProviderHome, prepareCodexModelCatalog } from "./codexConfiguration.js";
 import { startCodexHistoryAdapter } from "./codexHistoryAdapter.js";
 
 const CODEX_APP_SERVER_METADATA_FILE = "runtime.json";
@@ -100,34 +101,34 @@ function codexAppServerLockDir(runtimeDir = "") {
 }
 
 export function normalizeCodexAppServerMetadata(metadata = {}) {
-  const normalized = isPlainObject(metadata) ? metadata : {};
-  const endpoint = normalizeText(normalized.endpoint);
+  const normalized = isRecord(metadata) ? metadata : {};
+  const endpoint = normalizeNullableText(normalized.endpoint);
   return {
-    accountIdentitySignature: normalizeText(normalized.accountIdentitySignature),
-    attachmentHostRoot: normalizeText(normalized.attachmentHostRoot),
-    authStateSignature: normalizeText(normalized.authStateSignature),
+    accountIdentitySignature: normalizeNullableText(normalized.accountIdentitySignature),
+    attachmentHostRoot: normalizeNullableText(normalized.attachmentHostRoot),
+    authStateSignature: normalizeNullableText(normalized.authStateSignature),
     endpoint,
-    executionId: normalizeText(normalized.executionId),
-    executionMode: normalizeText(normalized.executionMode) || CODEX_APP_SERVER_EXECUTION_MODES.INTERACTIVE,
-    executionContextHash: normalizeText(normalized.executionContextHash),
-    healthz: normalizeText(normalized.healthz),
-    historyAdapterBaseUrl: normalizeText(normalized.historyAdapterBaseUrl),
-    logPath: normalizeText(normalized.logPath),
+    executionId: normalizeNullableText(normalized.executionId),
+    executionMode: normalizeNullableText(normalized.executionMode) || CODEX_APP_SERVER_EXECUTION_MODES.INTERACTIVE,
+    executionContextHash: normalizeNullableText(normalized.executionContextHash),
+    healthz: normalizeNullableText(normalized.healthz),
+    historyAdapterBaseUrl: normalizeNullableText(normalized.historyAdapterBaseUrl),
+    logPath: normalizeNullableText(normalized.logPath),
     pid: Number.isSafeInteger(Number(normalized.pid)) ? Number(normalized.pid) : null,
-    processCwd: normalizeText(normalized.processCwd),
-    processExitVerifiedAt: normalizeText(normalized.processExitVerifiedAt),
+    processCwd: normalizeNullableText(normalized.processCwd),
+    processExitVerifiedAt: normalizeNullableText(normalized.processExitVerifiedAt),
     processIdentity: runtimeProcessIdentity.normalize(normalized.processIdentity),
-    processState: normalizeText(normalized.processState),
-    provider: normalizeText(normalized.provider),
-    readyz: normalizeText(normalized.readyz),
-    runtimeDir: normalizeText(normalized.runtimeDir),
-    runtimesHash: normalizeText(normalized.runtimesHash),
+    processState: normalizeNullableText(normalized.processState),
+    provider: normalizeNullableText(normalized.provider),
+    readyz: normalizeNullableText(normalized.readyz),
+    runtimeDir: normalizeNullableText(normalized.runtimeDir),
+    runtimesHash: normalizeNullableText(normalized.runtimesHash),
     schemaVersion: Number(normalized.schemaVersion || 0),
-    socketPath: normalizeText(normalized.socketPath),
-    startedAt: normalizeText(normalized.startedAt),
-    terminalEnvHash: normalizeText(normalized.terminalEnvHash),
-    toolHomeSource: normalizeText(normalized.toolHomeSource),
-    transport: normalizeText(normalized.transport)
+    socketPath: normalizeNullableText(normalized.socketPath),
+    startedAt: normalizeNullableText(normalized.startedAt),
+    terminalEnvHash: normalizeNullableText(normalized.terminalEnvHash),
+    toolHomeSource: normalizeNullableText(normalized.toolHomeSource),
+    transport: normalizeNullableText(normalized.transport)
   };
 }
 
@@ -249,7 +250,7 @@ const CODEX_APP_SERVER_READY_TIMEOUT_MS = 60000;
 
 const CODEX_APP_SERVER_LIVENESS_TIMEOUT_MS = 2000;
 
-const CODEX_APP_SERVER_DESKTOP_BUS_ENV_NAMES = new Set([
+export const CODEX_APP_SERVER_DESKTOP_BUS_ENV_NAMES = new Set([
   "DBUS_SESSION_BUS_ADDRESS",
   "DBUS_STARTER_ADDRESS",
   "DBUS_STARTER_BUS_TYPE"
@@ -289,11 +290,6 @@ const CODEX_APP_SERVER_PROCESS_IDENTITY_STATUS = Object.freeze({
   MISMATCH: "mismatch"
 });
 
-function normalizePositiveInteger(value, fallback) {
-  const number = Number(value);
-  return Number.isSafeInteger(number) && number > 0 ? number : fallback;
-}
-
 function stableHash(value) {
   return createHash("sha256")
     .update(String(value || ""))
@@ -302,7 +298,7 @@ function stableHash(value) {
 }
 
 export function codexAppServerExecutionMode(options = {}) {
-  return normalizeText(options.executionMode) === CODEX_APP_SERVER_EXECUTION_MODES.HELPER
+  return normalizeNullableText(options.executionMode) === CODEX_APP_SERVER_EXECUTION_MODES.HELPER
     ? CODEX_APP_SERVER_EXECUTION_MODES.HELPER
     : CODEX_APP_SERVER_EXECUTION_MODES.INTERACTIVE;
 }
@@ -312,7 +308,7 @@ export function codexAppServerIsHelper(options = {}) {
 }
 
 export async function assertExistingDirectory(dirPath = "", label = "directory") {
-  const normalizedPath = normalizeText(dirPath);
+  const normalizedPath = normalizeNullableText(dirPath);
   if (!normalizedPath) {
     return;
   }
@@ -331,7 +327,7 @@ export function codexAppServerHelperWorkspaceDir(runtimeDir = "") {
 }
 
 function codexAppServerHelperCommandBaseEnv(env = process.env, codexHome = "") {
-  const source = isPlainObject(env) ? env : {};
+  const source = isRecord(env) ? env : {};
   const cleared = Object.fromEntries(Object.keys({
     ...process.env,
     ...source
@@ -377,7 +373,7 @@ function codexAppServerUnixEndpoint(socketPath = "") {
 }
 
 function codexAppServerProjectTrustOverride(workdir = "") {
-  const normalizedWorkdir = normalizeText(workdir);
+  const normalizedWorkdir = normalizeNullableText(workdir);
   if (!normalizedWorkdir) {
     return "";
   }
@@ -390,19 +386,19 @@ export function codexAppServerProcessCwd({
   runtimeDir = "",
   workdir = ""
 } = {}) {
-  const normalizedWorkdir = normalizeText(workdir) ? path.resolve(workdir) : "";
+  const normalizedWorkdir = normalizeNullableText(workdir) ? path.resolve(workdir) : "";
   if (normalizedWorkdir) {
     return normalizedWorkdir;
   }
-  const normalizedExecutionRoot = normalizeText(executionRoot) ? path.resolve(executionRoot) : "";
+  const normalizedExecutionRoot = normalizeNullableText(executionRoot) ? path.resolve(executionRoot) : "";
   if (normalizedExecutionRoot) {
     return normalizedExecutionRoot;
   }
-  return normalizeText(runtimeDir) ? path.resolve(runtimeDir) : "";
+  return normalizeNullableText(runtimeDir) ? path.resolve(runtimeDir) : "";
 }
 
 function codexAppServerRuntimeDirIsManaged(runtimeDir = "") {
-  const normalizedRuntimeDir = normalizeText(runtimeDir);
+  const normalizedRuntimeDir = normalizeNullableText(runtimeDir);
   if (!normalizedRuntimeDir) {
     return false;
   }
@@ -412,7 +408,7 @@ function codexAppServerRuntimeDirIsManaged(runtimeDir = "") {
 }
 
 async function removeCodexAppServerRuntimeDir(runtimeDir = "") {
-  const normalizedRuntimeDir = normalizeText(runtimeDir);
+  const normalizedRuntimeDir = normalizeNullableText(runtimeDir);
   if (!codexAppServerRuntimeDirIsManaged(normalizedRuntimeDir)) {
     return false;
   }
@@ -441,26 +437,26 @@ function codexAppServerRuntimeCleanupCanSkip(error) {
 
 export function codexAppServerRuntimeIdentity(runtime = {}) {
   return [
-    normalizeText(runtime.accountIdentitySignature),
-    normalizeText(runtime.authStateSignature),
-    normalizeText(runtime.endpoint),
-    normalizeText(runtime.executionId),
-    normalizeText(runtime.executionMode),
-    normalizeText(runtime.runtimesHash),
-    normalizeText(runtime.terminalEnvHash),
-    normalizeText(runtime.socketPath),
-    normalizeText(runtime.startedAt),
-    normalizeText(runtime.pid)
+    normalizeNullableText(runtime.accountIdentitySignature),
+    normalizeNullableText(runtime.authStateSignature),
+    normalizeNullableText(runtime.endpoint),
+    normalizeNullableText(runtime.executionId),
+    normalizeNullableText(runtime.executionMode),
+    normalizeNullableText(runtime.runtimesHash),
+    normalizeNullableText(runtime.terminalEnvHash),
+    normalizeNullableText(runtime.socketPath),
+    normalizeNullableText(runtime.startedAt),
+    normalizeNullableText(runtime.pid)
   ].join("\0");
 }
 
 export function normalizeCodexAppServerTerminalEnv(terminalEnv = {}) {
-  if (!isPlainObject(terminalEnv)) {
+  if (!isRecord(terminalEnv)) {
     return {};
   }
   return Object.fromEntries(Object.entries(terminalEnv)
     .map(([name, value]) => [
-      normalizeText(name),
+      normalizeNullableText(name),
       String(value ?? "")
     ])
     .filter(([name, value]) => (
@@ -485,13 +481,13 @@ export function codexAppServerCommandBaseEnv({
 }
 
 export function codexAppServerCredentialHome(toolHomeSource = "", baseEnv = {}) {
-  const home = normalizeText(toolHomeSource);
+  const home = normalizeNullableText(toolHomeSource);
   if (!home) {
     return {};
   }
   return {
     home,
-    username: normalizeText(baseEnv.USER || baseEnv.LOGNAME)
+    username: normalizeNullableText(baseEnv.USER || baseEnv.LOGNAME)
   };
 }
 
@@ -501,8 +497,9 @@ export function codexAppServerTerminalEnvHash(terminalEnv = {}) {
 }
 
 function codexHistoryAdapterUrlIsValid(baseUrl, token) {
-  // The previous adapter cannot serve thread-bound compaction recovery. Keep
-  // its process identity readable, but retire it through normal owned cleanup.
+  // Only this adapter URL shape serves thread-bound compaction recovery. Any
+  // other shape keeps its process identity readable but is retired through
+  // normal owned cleanup.
   const match = typeof baseUrl === "string" && /^http:\/\/127\.0\.0\.1:([1-9]\d{0,4})\/[0-9a-f-]{36}\/v2$/iu.exec(baseUrl);
   return Boolean(match && Number(match[1]) <= 65535 && baseUrl.endsWith(`/${token}/v2`));
 }
@@ -510,7 +507,7 @@ function codexHistoryAdapterUrlIsValid(baseUrl, token) {
 function codexAppServerLivenessTimeoutMs(options = {}) {
   return normalizePositiveInteger(
     options.livenessTimeoutMs,
-    normalizePositiveInteger(options.timeoutMs, CODEX_APP_SERVER_LIVENESS_TIMEOUT_MS)
+    { fallback: normalizePositiveInteger(options.timeoutMs, { fallback: CODEX_APP_SERVER_LIVENESS_TIMEOUT_MS }) }
   );
 }
 
@@ -523,10 +520,10 @@ function codexAppServerProcessCommandHash({
 } = {}) {
   return stableHash(JSON.stringify({
     codexArgs,
-    codexCommand: normalizeText(codexCommand),
+    codexCommand: normalizeNullableText(codexCommand),
     executionMode: codexAppServerExecutionMode({ executionMode }),
-    processCwd: normalizeText(processCwd),
-    runtimeDir: normalizeText(runtimeDir)
+    processCwd: normalizeNullableText(processCwd),
+    runtimeDir: normalizeNullableText(runtimeDir)
   }));
 }
 
@@ -535,16 +532,39 @@ const codexAppServerRuntimePreparations = new Map();
 /** The production shared runtime: one process owner per stable runtime directory.
  * Execution and credential facilities retain host policy; threads do not own this process.
  */
+/** Default environment names the runtime and its process leader share. */
+export const CODEX_APP_SERVER_DEFAULT_ENVIRONMENT = Object.freeze({
+  runtimeToken: "JSKIT_EXECUTION_RUNTIME_TOKEN",
+  modelCatalogSource: "JSKIT_CODEX_MODEL_CATALOG_SOURCE",
+  commandHash: "JSKIT_EXECUTION_COMMAND_HASH"
+});
+
+/** The PreToolUse hook that routes native Bash commands through the host's wrapper. */
+export function codexCommandHookDefinition(command) {
+  return [{ matcher: "^Bash$", hooks: [{ type: "command", command, timeout: 30 }] }];
+}
+
+// Inline TOML for `-c` overrides: bare keys, JSON-quoted strings.
+function tomlInlineValue(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map(tomlInlineValue).join(",")}]`;
+  }
+  if (isRecord(value)) {
+    return `{${Object.entries(value).map(([key, item]) => `${key}=${tomlInlineValue(item)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
 export function createCodexAppServerRuntime({ execution, credentials, configuration = {} }) {
   const {
     clientInfo = { name: "jskit", title: "JSKIT", version: "0.1.0" },
     commandHookCommand,
     errorPrefix = "",
-    modelCatalogEnvironmentName = "JSKIT_CODEX_MODEL_CATALOG_SOURCE",
+    modelCatalogEnvironmentName = CODEX_APP_SERVER_DEFAULT_ENVIRONMENT.modelCatalogSource,
     processLabel = "jskit-codex-app-server",
     processPath = fileURLToPath(new URL("./codexProcessLeader.js", import.meta.url)),
-    runtimeTokenEnvironmentName = "JSKIT_EXECUTION_RUNTIME_TOKEN",
-    commandHashEnvironmentName = "JSKIT_EXECUTION_COMMAND_HASH",
+    runtimeTokenEnvironmentName = CODEX_APP_SERVER_DEFAULT_ENVIRONMENT.runtimeToken,
+    commandHashEnvironmentName = CODEX_APP_SERVER_DEFAULT_ENVIRONMENT.commandHash,
     socketPathHelp = "Configure a shorter host runtime directory.",
     umask = "0007"
   } = configuration;
@@ -563,8 +583,7 @@ export function createCodexAppServerRuntime({ execution, credentials, configurat
   const assertCodexAuthGenerationCurrent = credentials.assertCurrent;
 
   function codexAppServerSessionCommandHookConfig() {
-    const command = commandHookCommand;
-    return `hooks.PreToolUse=[{matcher="^Bash$",hooks=[{type="command",command=${JSON.stringify(command)},timeout=30}]}]`;
+    return `hooks.PreToolUse=${tomlInlineValue(codexCommandHookDefinition(commandHookCommand))}`;
   }
 
   async function acquireRuntimeLock(runtimeDir = "", options = {}) {
@@ -573,7 +592,7 @@ export function createCodexAppServerRuntime({ execution, credentials, configurat
   }
 
   // An empty or null umask inherits the host's own; hosts that share files set one.
-  const startupUmask = normalizeText(umask);
+  const startupUmask = normalizeNullableText(umask);
   if (startupUmask && !/^[0-7]{3,4}$/u.test(startupUmask)) {
     throw new TypeError(`Codex app-server umask must be octal, not ${JSON.stringify(startupUmask)}.`);
   }
@@ -598,7 +617,7 @@ export function createCodexAppServerRuntime({ execution, credentials, configurat
   ].join("\n");
 
   function codexAppServerProcessMetadataIsIdentifiable(metadata = {}, runtimeDir = "") {
-    const normalizedRuntimeDir = normalizeText(runtimeDir);
+    const normalizedRuntimeDir = normalizeNullableText(runtimeDir);
     return Boolean(
       Number(metadata.schemaVersion) === CODEX_APP_SERVER_METADATA_SCHEMA_VERSION &&
       metadata.provider === CODEX_APP_SERVER_PROVIDER_ID &&
@@ -654,7 +673,7 @@ export function createCodexAppServerRuntime({ execution, credentials, configurat
     ) {
       return stopCodexAppServerProcessGroup(metadata, options);
     }
-    const executionId = normalizeText(metadata.executionId);
+    const executionId = normalizeNullableText(metadata.executionId);
     if (executionId) {
       const stopExecution = typeof options.stopExecution === "function"
         ? options.stopExecution
@@ -698,7 +717,7 @@ export function createCodexAppServerRuntime({ execution, credentials, configurat
   }
 
   async function stopCodexAppServerProcess(runtimeDir = "", options = {}) {
-    const normalizedRuntimeDir = normalizeText(runtimeDir);
+    const normalizedRuntimeDir = normalizeNullableText(runtimeDir);
     if (!normalizedRuntimeDir) {
       return {
         processExitVerified: false,
@@ -732,12 +751,12 @@ export function createCodexAppServerRuntime({ execution, credentials, configurat
     if (!neverStarted) {
       try {
         processStop = await stopOwnedCodexAppServerExecution({
-          executionId: normalizeText(executionId),
+          executionId: normalizeNullableText(executionId),
           pid: Number(pid),
           processIdentity,
           processState: CODEX_APP_SERVER_PROCESS_STATE.RUNNING,
           provider: CODEX_APP_SERVER_PROVIDER_ID,
-          runtimeDir: normalizeText(runtimeDir),
+          runtimeDir: normalizeNullableText(runtimeDir),
           schemaVersion: CODEX_APP_SERVER_METADATA_SCHEMA_VERSION
         }, options);
       } catch {
@@ -770,7 +789,7 @@ export function createCodexAppServerRuntime({ execution, credentials, configurat
   }
 
   async function stopCodexAppServerRuntime(options = {}) {
-    const runtimeDir = normalizeText(options.runtimeDir);
+    const runtimeDir = normalizeNullableText(options.runtimeDir);
     const preserveProcessExitProof = options.preserveProcessExitProof === true;
     if (!runtimeDir || !codexAppServerRuntimeDirIsManaged(runtimeDir)) {
       return {
@@ -806,7 +825,7 @@ export function createCodexAppServerRuntime({ execution, credentials, configurat
     };
     try {
       const existing = await readCodexAppServerMetadata(runtimeDir);
-      const expectedAccount = normalizeText(options.expectedAccountIdentitySignature);
+      const expectedAccount = normalizeNullableText(options.expectedAccountIdentitySignature);
       const ownedRuntime = options.ownedRuntime;
       if (
         ownedRuntime &&
@@ -831,7 +850,7 @@ export function createCodexAppServerRuntime({ execution, credentials, configurat
           ? await execution.stopOwned({
             kind: "assistant",
             operationId: "codex-app-server",
-            ownerId: normalizeText(options.ownerId) || stableHash(runtimeDir)
+            ownerId: normalizeNullableText(options.ownerId) || stableHash(runtimeDir)
           }, { reason: "codex-app-server-changeover" })
           : null;
         const ownerExitVerified = owned?.supported === true && owned?.ok === true && owned?.scopeEmpty === true;
@@ -896,9 +915,9 @@ export function createCodexAppServerRuntime({ execution, credentials, configurat
 
   function codexAppServerMetadataIsWellFormed(metadata = {}, options = {}) {
     const expectedAttachmentHostRoot = options.compatibility.attachmentHostRoot;
-    const expectedAccountIdentitySignature = normalizeText(options.accountIdentitySignature);
+    const expectedAccountIdentitySignature = normalizeNullableText(options.accountIdentitySignature);
     const expectedExecutionMode = codexAppServerExecutionMode(options);
-    const expectedToolHomeSource = codexAppServerIsHelper(options) ? "" : normalizeText(options.toolHomeSource);
+    const expectedToolHomeSource = codexAppServerIsHelper(options) ? "" : normalizeNullableText(options.toolHomeSource);
     const expectedTerminalEnvHash = codexAppServerTerminalEnvHash(codexAppServerIsHelper(options) ? {} : options.terminalEnv);
     const expectedRuntimesHash = options.compatibility.runtimesHash;
     const expectedExecutionContextHash = options.compatibility.executionContextHash;
@@ -933,41 +952,43 @@ export function createCodexAppServerRuntime({ execution, credentials, configurat
     timeoutMs = CODEX_APP_SERVER_LIVENESS_TIMEOUT_MS,
     WebSocketImpl = WebSocket
   } = {}) {
-    const normalizedEndpoint = normalizeText(endpoint);
+    const normalizedEndpoint = normalizeNullableText(endpoint);
     const socketPath = socketPathFromCodexAppServerEndpoint(normalizedEndpoint);
     if (!socketPath || !await fileExists(socketPath)) {
       return {
         status: CODEX_APP_SERVER_ENDPOINT_STATUS.MISSING
       };
     }
-    const normalizedTimeoutMs = normalizePositiveInteger(timeoutMs, CODEX_APP_SERVER_LIVENESS_TIMEOUT_MS);
+    const normalizedTimeoutMs = normalizePositiveInteger(timeoutMs, { fallback: CODEX_APP_SERVER_LIVENESS_TIMEOUT_MS });
+    return {
+      status: await probeCodexAppServer(normalizedEndpoint, normalizedTimeoutMs, WebSocketImpl)
+    };
+  }
+
+  // One bounded connect-and-initialize handshake: responsive, timeout or unreachable.
+  async function probeCodexAppServer(endpoint, timeoutMs, WebSocketImpl) {
     const client = new CodexAppServerJsonRpcClient({
-      endpoint: normalizedEndpoint,
-      requestTimeoutMs: normalizedTimeoutMs,
+      endpoint,
+      requestTimeoutMs: timeoutMs,
       WebSocketImpl
     });
     let timeout = null;
     const probe = (async () => {
       await client.connect();
-      await client.initialize({ clientInfo: clientInfo });
+      await client.initialize({ clientInfo });
       return CODEX_APP_SERVER_ENDPOINT_STATUS.RESPONSIVE;
     })();
     probe.catch(() => null);
     try {
-      const status = await Promise.race([
+      return await Promise.race([
         probe,
         new Promise((resolve) => {
-          timeout = setTimeout(() => resolve(CODEX_APP_SERVER_ENDPOINT_STATUS.TIMEOUT), normalizedTimeoutMs);
+          timeout = setTimeout(() => resolve(CODEX_APP_SERVER_ENDPOINT_STATUS.TIMEOUT), timeoutMs);
           timeout.unref?.();
         })
       ]);
-      return {
-        status
-      };
     } catch {
-      return {
-        status: CODEX_APP_SERVER_ENDPOINT_STATUS.UNREACHABLE
-      };
+      return CODEX_APP_SERVER_ENDPOINT_STATUS.UNREACHABLE;
     } finally {
       clearTimeout(timeout);
       client.close();
@@ -1089,35 +1110,10 @@ export function createCodexAppServerRuntime({ execution, credentials, configurat
       await delay(100);
     }
     const remainingMs = Math.max(1, timeoutMs - (Date.now() - startedAt));
-    if (!await fileExists(socketPath) || remainingMs <= 0) {
-      return false;
-    }
-    const client = new CodexAppServerJsonRpcClient({
-      endpoint,
-      requestTimeoutMs: remainingMs,
-      WebSocketImpl
-    });
-    let timeout = null;
-    const handshake = (async () => {
-      await client.connect();
-      await client.initialize({ clientInfo: clientInfo });
-      return true;
-    })();
-    handshake.catch(() => null);
-    try {
-      return await Promise.race([
-        handshake,
-        new Promise((resolve) => {
-          timeout = setTimeout(() => resolve(false), remainingMs);
-          timeout.unref?.();
-        })
-      ]);
-    } catch {
+    if (!await fileExists(socketPath)) {
       return false;
-    } finally {
-      clearTimeout(timeout);
-      client.close();
     }
+    return await probeCodexAppServer(endpoint, remainingMs, WebSocketImpl) === CODEX_APP_SERVER_ENDPOINT_STATUS.RESPONSIVE;
   }
 
   async function startCodexAppServerProcess({
@@ -1153,7 +1149,7 @@ export function createCodexAppServerRuntime({ execution, credentials, configurat
     await ensureWritablePrivateDirectory(runtimeDir);
     const helper = codexAppServerExecutionMode({ executionMode }) ===
       CODEX_APP_SERVER_EXECUTION_MODES.HELPER;
-    const normalizedToolHomeSource = normalizeText(toolHomeSource);
+    const normalizedToolHomeSource = normalizeNullableText(toolHomeSource);
     if (normalizedToolHomeSource) {
       await assertExistingDirectory(normalizedToolHomeSource, "Codex credential home");
     }
@@ -1177,13 +1173,13 @@ export function createCodexAppServerRuntime({ execution, credentials, configurat
       if (providerHome) {
         // The canonical home contains only our curated provider projection. Copy
         // it into the existing isolated helper home; never load OpenAI auth here.
-        const sourceHome = path.join(normalizedToolHomeSource, ".codex");
-        const catalogPath = path.join(helperHome, "models.json");
-        const config = await readFile(path.join(sourceHome, "config.toml"), "utf8");
-        await writeFile(catalogPath, await readFile(path.join(sourceHome, "models.json")), { mode: 0o600 });
-        await writeFile(path.join(helperHome, "config.toml"), config.replace(
-          JSON.stringify(path.join(sourceHome, "models.json")), JSON.stringify(catalogPath)
-        ), { mode: 0o600 });
+        try {
+          await copyCodexProviderHome(path.join(normalizedToolHomeSource, ".codex"), helperHome);
+        } catch (cause) {
+          const error = new Error("Codex isolated helper runtime could not copy the provider home.", { cause });
+          error.code = `${errorPrefix}codex_helper_runtime_start_failed`;
+          throw error;
+        }
       }
     }
     const processCwd = helper
@@ -1280,7 +1276,7 @@ export function createCodexAppServerRuntime({ execution, credentials, configurat
         label: "Codex assistant",
         lifecycle: "service",
         operationId: "codex-app-server",
-        ownerId: normalizeText(ownerId) || stableHash(runtimeDir)
+        ownerId: normalizeNullableText(ownerId) || stableHash(runtimeDir)
       },
       processProfile: profileBinary?.isFile() ? {
         command: codexCommand, helper, executionMode,
@@ -1413,11 +1409,11 @@ export function createCodexAppServerRuntime({ execution, credentials, configurat
     }
 
     return {
-      accountIdentitySignature: normalizeText(accountIdentitySignature),
+      accountIdentitySignature: normalizeNullableText(accountIdentitySignature),
       attachmentHostRoot: compatibility.attachmentHostRoot,
       authStateSignature: resolvedAuthStateSignature,
       endpoint,
-      executionId: normalizeText(startResult.execution?.id),
+      executionId: normalizeNullableText(startResult.execution?.id),
       executionMode: helper
         ? CODEX_APP_SERVER_EXECUTION_MODES.HELPER
         : CODEX_APP_SERVER_EXECUTION_MODES.INTERACTIVE,