@kodelyth/codex 2026.5.42 → 2026.6.2

package/src/app-server/thread-lifecycle.ts

@@ -1,939 +0,0 @@
-import {
-  embeddedAgentLog,
-  isActiveHarnessContextEngine,
-  type EmbeddedRunAttemptParams,
-} from "klaw/plugin-sdk/agent-harness-runtime";
-import { buildCodexUserMcpServersThreadConfigPatch } from "klaw/plugin-sdk/codex-mcp-projection";
-import { listRegisteredPluginAgentPromptGuidance } from "klaw/plugin-sdk/plugin-runtime";
-import { CODEX_GPT5_HEARTBEAT_PROMPT_OVERLAY } from "../../prompt-overlay.js";
-import { isModernCodexModel } from "../../provider.js";
-import { isCodexAppServerConnectionClosedError, type CodexAppServerClient } from "./client.js";
-import { codexSandboxPolicyForTurn, type CodexAppServerRuntimeOptions } from "./config.js";
-import {
-  resolveCodexContextEngineProjectionMaxChars,
-  resolveCodexContextEngineProjectionReserveTokens,
-} from "./context-engine-projection.js";
-import { invalidInlineImageText, sanitizeInlineImageDataUrl } from "./image-payload-sanitizer.js";
-import {
-  isCodexPluginThreadBindingStale,
-  mergeCodexThreadConfigs,
-  type CodexPluginThreadConfig,
-} from "./plugin-thread-config.js";
-import {
-  assertCodexThreadResumeResponse,
-  assertCodexThreadStartResponse,
-} from "./protocol-validators.js";
-import {
-  isJsonObject,
-  type CodexDynamicToolSpec,
-  type CodexSandboxPolicy,
-  type CodexThreadResumeParams,
-  type CodexThreadStartParams,
-  type CodexTurnStartParams,
-  type JsonObject,
-  type CodexUserInput,
-  type JsonValue,
-} from "./protocol.js";
-import {
-  clearCodexAppServerBinding,
-  isCodexAppServerNativeAuthProfile,
-  readCodexAppServerBinding,
-  writeCodexAppServerBinding,
-  type CodexAppServerAuthProfileLookup,
-  type CodexAppServerContextEngineBinding,
-  type CodexAppServerContextEngineProjectionBinding,
-  type CodexAppServerThreadBinding,
-} from "./session-binding.js";
-
-export type CodexAppServerThreadLifecycle = {
-  action: "started" | "resumed";
-  rotatedContextEngineBinding?: boolean;
-};
-
-export type CodexAppServerThreadLifecycleBinding = CodexAppServerThreadBinding & {
-  lifecycle: CodexAppServerThreadLifecycle;
-};
-
-export type CodexContextEngineThreadBootstrapProjection = {
-  mode: "thread_bootstrap";
-  epoch: string;
-  fingerprint?: string;
-};
-
-export type CodexPluginThreadConfigProvider = {
-  enabled: boolean;
-  inputFingerprint?: string;
-  enabledPluginConfigKeys?: readonly string[];
-  build: () => Promise<CodexPluginThreadConfig>;
-};
-
-export const CODEX_CODE_MODE_THREAD_CONFIG: JsonObject = {
-  "features.code_mode": true,
-  "features.code_mode_only": false,
-};
-
-export const CODEX_CODE_MODE_DISABLED_THREAD_CONFIG: JsonObject = {
-  "features.code_mode": false,
-  "features.code_mode_only": false,
-};
-
-const CODEX_LIGHTWEIGHT_CONTEXT_THREAD_CONFIG: JsonObject = {
-  project_doc_max_bytes: 0,
-};
-
-export async function startOrResumeThread(params: {
-  client: CodexAppServerClient;
-  params: EmbeddedRunAttemptParams;
-  agentId?: string;
-  cwd: string;
-  dynamicTools: CodexDynamicToolSpec[];
-  appServer: CodexAppServerRuntimeOptions;
-  developerInstructions?: string;
-  config?: JsonObject;
-  finalConfigPatch?: JsonObject;
-  nativeCodeModeEnabled?: boolean;
-  nativeCodeModeOnlyEnabled?: boolean;
-  userMcpServersEnabled?: boolean;
-  mcpServersFingerprint?: string;
-  mcpServersFingerprintEvaluated?: boolean;
-  pluginThreadConfig?: CodexPluginThreadConfigProvider;
-  contextEngineProjection?: CodexContextEngineThreadBootstrapProjection;
-}): Promise<CodexAppServerThreadLifecycleBinding> {
-  const dynamicToolsFingerprint = fingerprintDynamicTools(params.dynamicTools);
-  const contextEngineBinding = buildContextEngineBinding(
-    params.params,
-    params.contextEngineProjection,
-  );
-  const userMcpServersConfigPatch =
-    params.userMcpServersEnabled === false
-      ? undefined
-      : buildCodexUserMcpServersThreadConfigPatch(params.params.config, {
-          agentId: params.agentId ?? params.params.agentId,
-        });
-  const userMcpServersFingerprint = fingerprintUserMcpServersConfigPatch(userMcpServersConfigPatch);
-  let binding = await readCodexAppServerBinding(params.params.sessionFile, {
-    authProfileStore: params.params.authProfileStore,
-    agentDir: params.params.agentDir,
-    config: params.params.config,
-  });
-  let preserveExistingBinding = false;
-  let rotatedContextEngineBinding = false;
-  let prebuiltPluginThreadConfig: CodexPluginThreadConfig | undefined;
-  if (binding?.threadId && params.nativeCodeModeEnabled === false) {
-    embeddedAgentLog.debug(
-      "codex app-server native tool surface disabled for turn; starting transient thread",
-      {
-        threadId: binding.threadId,
-      },
-    );
-    preserveExistingBinding = true;
-    binding = undefined;
-  }
-  if (binding?.threadId && (binding.contextEngine || contextEngineBinding)) {
-    if (
-      !contextEngineBinding ||
-      !isContextEngineBindingCompatible(binding.contextEngine, contextEngineBinding)
-    ) {
-      embeddedAgentLog.debug(
-        "codex app-server context-engine binding changed; starting a new thread",
-        {
-          threadId: binding.threadId,
-          engineId: contextEngineBinding?.engineId,
-          previousEngineId: binding.contextEngine?.engineId,
-          epoch: contextEngineBinding?.projection?.epoch,
-          previousEpoch: binding.contextEngine?.projection?.epoch,
-          fingerprint: contextEngineBinding?.projection?.fingerprint,
-          previousFingerprint: binding.contextEngine?.projection?.fingerprint,
-          policyFingerprint: contextEngineBinding?.policyFingerprint,
-          previousPolicyFingerprint: binding.contextEngine?.policyFingerprint,
-        },
-      );
-      await clearCodexAppServerBinding(params.params.sessionFile);
-      binding = undefined;
-      rotatedContextEngineBinding = true;
-    }
-  }
-  if (binding?.threadId && binding.userMcpServersFingerprint !== userMcpServersFingerprint) {
-    embeddedAgentLog.debug("codex app-server user MCP config changed; starting a new thread", {
-      threadId: binding.threadId,
-    });
-    await clearCodexAppServerBinding(params.params.sessionFile);
-    binding = undefined;
-  }
-  if (
-    binding?.threadId &&
-    params.mcpServersFingerprintEvaluated === true &&
-    binding.mcpServersFingerprint !== params.mcpServersFingerprint
-  ) {
-    embeddedAgentLog.debug("codex app-server MCP config changed; starting a new thread", {
-      threadId: binding.threadId,
-    });
-    await clearCodexAppServerBinding(params.params.sessionFile);
-    binding = undefined;
-  }
-  if (binding?.threadId) {
-    let pluginBindingStale = isCodexPluginThreadBindingStale({
-      codexPluginsEnabled: params.pluginThreadConfig?.enabled ?? false,
-      bindingFingerprint: binding.pluginAppsFingerprint,
-      bindingInputFingerprint: binding.pluginAppsInputFingerprint,
-      currentInputFingerprint: params.pluginThreadConfig?.inputFingerprint,
-      hasBindingPolicyContext: Boolean(binding.pluginAppPolicyContext),
-    });
-    if (
-      !pluginBindingStale &&
-      shouldRecheckRecoverablePluginBinding({
-        binding,
-        pluginThreadConfig: params.pluginThreadConfig,
-      })
-    ) {
-      try {
-        prebuiltPluginThreadConfig = await params.pluginThreadConfig?.build();
-        pluginBindingStale =
-          prebuiltPluginThreadConfig?.fingerprint !== binding.pluginAppsFingerprint;
-      } catch (error) {
-        embeddedAgentLog.warn("codex app-server plugin app config recovery check failed", {
-          error,
-          threadId: binding.threadId,
-        });
-      }
-    }
-    if (pluginBindingStale) {
-      embeddedAgentLog.debug("codex app-server plugin app config changed; starting a new thread", {
-        threadId: binding.threadId,
-      });
-      await clearCodexAppServerBinding(params.params.sessionFile);
-      binding = undefined;
-    }
-  }
-  if (
-    binding?.threadId &&
-    params.mcpServersFingerprintEvaluated === true &&
-    binding.mcpServersFingerprint !== params.mcpServersFingerprint
-  ) {
-    embeddedAgentLog.debug("codex app-server MCP config changed; starting a new thread", {
-      threadId: binding.threadId,
-    });
-    await clearCodexAppServerBinding(params.params.sessionFile);
-    binding = undefined;
-  }
-  if (binding?.threadId) {
-    // `/codex resume <thread>` writes a binding before the next turn can know
-    // the dynamic tool catalog, so only invalidate fingerprints we actually have.
-    if (
-      binding.dynamicToolsFingerprint &&
-      !areDynamicToolFingerprintsCompatible(
-        binding.dynamicToolsFingerprint,
-        dynamicToolsFingerprint,
-      )
-    ) {
-      preserveExistingBinding = shouldStartTransientNoToolThread({
-        previous: binding.dynamicToolsFingerprint,
-        next: dynamicToolsFingerprint,
-      });
-      if (preserveExistingBinding) {
-        embeddedAgentLog.debug(
-          "codex app-server dynamic tools unavailable for turn; starting transient thread",
-          {
-            threadId: binding.threadId,
-          },
-        );
-      } else {
-        embeddedAgentLog.debug(
-          "codex app-server dynamic tool catalog changed; starting a new thread",
-          {
-            threadId: binding.threadId,
-          },
-        );
-        await clearCodexAppServerBinding(params.params.sessionFile);
-      }
-    } else {
-      try {
-        const authProfileId = params.params.authProfileId ?? binding.authProfileId;
-        const resumeConfig = mergeCodexThreadConfigs(
-          params.config,
-          userMcpServersConfigPatch,
-          params.finalConfigPatch,
-        );
-        const response = assertCodexThreadResumeResponse(
-          await params.client.request(
-            "thread/resume",
-            buildThreadResumeParams(params.params, {
-              threadId: binding.threadId,
-              authProfileId,
-              appServer: params.appServer,
-              dynamicTools: params.dynamicTools,
-              developerInstructions: params.developerInstructions,
-              config: resumeConfig,
-              nativeCodeModeEnabled: params.nativeCodeModeEnabled,
-              nativeCodeModeOnlyEnabled: params.nativeCodeModeOnlyEnabled,
-            }),
-          ),
-        );
-        const boundAuthProfileId = authProfileId;
-        const fallbackModelProvider = resolveCodexAppServerModelProvider({
-          provider: params.params.provider,
-          authProfileId: boundAuthProfileId,
-          authProfileStore: params.params.authProfileStore,
-          agentDir: params.params.agentDir,
-          config: params.params.config,
-        });
-        const nextMcpServersFingerprint =
-          params.mcpServersFingerprintEvaluated === true
-            ? params.mcpServersFingerprint
-            : binding.mcpServersFingerprint;
-        await writeCodexAppServerBinding(
-          params.params.sessionFile,
-          {
-            threadId: response.thread.id,
-            cwd: params.cwd,
-            authProfileId: boundAuthProfileId,
-            model: params.params.modelId,
-            modelProvider: response.modelProvider ?? fallbackModelProvider,
-            dynamicToolsFingerprint,
-            userMcpServersFingerprint,
-            mcpServersFingerprint: nextMcpServersFingerprint,
-            pluginAppsFingerprint: binding.pluginAppsFingerprint,
-            pluginAppsInputFingerprint: binding.pluginAppsInputFingerprint,
-            pluginAppPolicyContext: binding.pluginAppPolicyContext,
-            contextEngine: contextEngineBinding,
-            createdAt: binding.createdAt,
-          },
-          {
-            authProfileStore: params.params.authProfileStore,
-            agentDir: params.params.agentDir,
-            config: params.params.config,
-          },
-        );
-        if (contextEngineBinding) {
-          embeddedAgentLog.info("codex app-server wrote context-engine thread binding", {
-            sessionId: params.params.sessionId,
-            sessionKey: params.params.sessionKey,
-            threadId: response.thread.id,
-            engineId: contextEngineBinding.engineId,
-            epoch: contextEngineBinding.projection?.epoch,
-            fingerprint: contextEngineBinding.projection?.fingerprint,
-            action: "resumed",
-          });
-        }
-        return {
-          ...binding,
-          threadId: response.thread.id,
-          cwd: params.cwd,
-          authProfileId: boundAuthProfileId,
-          model: params.params.modelId,
-          modelProvider: response.modelProvider ?? fallbackModelProvider,
-          dynamicToolsFingerprint,
-          userMcpServersFingerprint,
-          mcpServersFingerprint: nextMcpServersFingerprint,
-          pluginAppsFingerprint: binding.pluginAppsFingerprint,
-          pluginAppsInputFingerprint: binding.pluginAppsInputFingerprint,
-          pluginAppPolicyContext: binding.pluginAppPolicyContext,
-          contextEngine: contextEngineBinding,
-          lifecycle: { action: "resumed" },
-        };
-      } catch (error) {
-        if (isCodexAppServerConnectionClosedError(error)) {
-          throw error;
-        }
-        embeddedAgentLog.warn("codex app-server thread resume failed; starting a new thread", {
-          error,
-        });
-        await clearCodexAppServerBinding(params.params.sessionFile);
-      }
-    }
-  }
-
-  const pluginThreadConfig = params.pluginThreadConfig?.enabled
-    ? (prebuiltPluginThreadConfig ?? (await params.pluginThreadConfig.build()))
-    : undefined;
-  const config = mergeCodexThreadConfigs(
-    params.config,
-    userMcpServersConfigPatch,
-    pluginThreadConfig?.configPatch,
-    params.finalConfigPatch,
-  );
-  const response = assertCodexThreadStartResponse(
-    await params.client.request(
-      "thread/start",
-      buildThreadStartParams(params.params, {
-        cwd: params.cwd,
-        dynamicTools: params.dynamicTools,
-        appServer: params.appServer,
-        developerInstructions: params.developerInstructions,
-        config,
-        nativeCodeModeEnabled: params.nativeCodeModeEnabled,
-        nativeCodeModeOnlyEnabled: params.nativeCodeModeOnlyEnabled,
-      }),
-    ),
-  );
-  const modelProvider = resolveCodexAppServerModelProvider({
-    provider: params.params.provider,
-    authProfileId: params.params.authProfileId,
-    authProfileStore: params.params.authProfileStore,
-    agentDir: params.params.agentDir,
-    config: params.params.config,
-  });
-  const createdAt = new Date().toISOString();
-  const nextMcpServersFingerprint =
-    params.mcpServersFingerprintEvaluated === true ? params.mcpServersFingerprint : undefined;
-  if (!preserveExistingBinding) {
-    await writeCodexAppServerBinding(
-      params.params.sessionFile,
-      {
-        threadId: response.thread.id,
-        cwd: params.cwd,
-        authProfileId: params.params.authProfileId,
-        model: response.model ?? params.params.modelId,
-        modelProvider: response.modelProvider ?? modelProvider,
-        dynamicToolsFingerprint,
-        userMcpServersFingerprint,
-        mcpServersFingerprint: nextMcpServersFingerprint,
-        pluginAppsFingerprint: pluginThreadConfig?.fingerprint,
-        pluginAppsInputFingerprint: pluginThreadConfig?.inputFingerprint,
-        pluginAppPolicyContext: pluginThreadConfig?.policyContext,
-        contextEngine: contextEngineBinding,
-        createdAt,
-      },
-      {
-        authProfileStore: params.params.authProfileStore,
-        agentDir: params.params.agentDir,
-        config: params.params.config,
-      },
-    );
-    if (contextEngineBinding) {
-      embeddedAgentLog.info("codex app-server wrote context-engine thread binding", {
-        sessionId: params.params.sessionId,
-        sessionKey: params.params.sessionKey,
-        threadId: response.thread.id,
-        engineId: contextEngineBinding.engineId,
-        epoch: contextEngineBinding.projection?.epoch,
-        fingerprint: contextEngineBinding.projection?.fingerprint,
-        action: rotatedContextEngineBinding ? "rotated" : "started",
-      });
-    }
-  }
-  return {
-    schemaVersion: 1,
-    threadId: response.thread.id,
-    sessionFile: params.params.sessionFile,
-    cwd: params.cwd,
-    authProfileId: params.params.authProfileId,
-    model: response.model ?? params.params.modelId,
-    modelProvider: response.modelProvider ?? modelProvider,
-    dynamicToolsFingerprint,
-    userMcpServersFingerprint,
-    mcpServersFingerprint: nextMcpServersFingerprint,
-    pluginAppsFingerprint: pluginThreadConfig?.fingerprint,
-    pluginAppsInputFingerprint: pluginThreadConfig?.inputFingerprint,
-    pluginAppPolicyContext: pluginThreadConfig?.policyContext,
-    contextEngine: contextEngineBinding,
-    createdAt,
-    updatedAt: createdAt,
-    lifecycle: {
-      action: "started",
-      ...(rotatedContextEngineBinding ? { rotatedContextEngineBinding } : {}),
-    },
-  };
-}
-
-export function buildContextEngineBinding(
-  params: EmbeddedRunAttemptParams,
-  projection?: CodexContextEngineThreadBootstrapProjection,
-): CodexAppServerContextEngineBinding | undefined {
-  const contextEngine = isActiveHarnessContextEngine(params.contextEngine)
-    ? params.contextEngine
-    : undefined;
-  const engineId = contextEngine?.info?.id?.trim();
-  if (!contextEngine || !engineId) {
-    return undefined;
-  }
-  return {
-    schemaVersion: 1,
-    engineId,
-    policyFingerprint: JSON.stringify({
-      schemaVersion: 1,
-      engineId,
-      engineVersion: contextEngine.info.version,
-      ownsCompaction: contextEngine.info.ownsCompaction === true,
-      turnMaintenanceMode: contextEngine.info.turnMaintenanceMode,
-      citationsMode: resolveContextEngineCitationsMode(params.config),
-      contextTokenBudget: params.contextTokenBudget,
-      projectionMaxChars: resolveCodexContextEngineProjectionMaxChars({
-        contextTokenBudget: params.contextTokenBudget,
-        reserveTokens: resolveCodexContextEngineProjectionReserveTokens({
-          config: params.config,
-        }),
-      }),
-    }),
-    projection: projection ? buildContextEngineProjectionBinding(projection) : undefined,
-  };
-}
-
-function buildContextEngineProjectionBinding(
-  projection: CodexContextEngineThreadBootstrapProjection,
-): CodexAppServerContextEngineProjectionBinding {
-  return {
-    schemaVersion: 1,
-    mode: "thread_bootstrap",
-    epoch: projection.epoch,
-    fingerprint: projection.fingerprint,
-  };
-}
-
-export function isContextEngineBindingCompatible(
-  previous: CodexAppServerContextEngineBinding | undefined,
-  next: CodexAppServerContextEngineBinding,
-): boolean {
-  return (
-    previous?.schemaVersion === next.schemaVersion &&
-    previous.engineId === next.engineId &&
-    previous.policyFingerprint === next.policyFingerprint &&
-    areContextEngineProjectionBindingsCompatible(previous.projection, next.projection)
-  );
-}
-
-function areContextEngineProjectionBindingsCompatible(
-  previous: CodexAppServerContextEngineProjectionBinding | undefined,
-  next: CodexAppServerContextEngineProjectionBinding | undefined,
-): boolean {
-  if (!next) {
-    return previous === undefined;
-  }
-  return (
-    previous?.schemaVersion === next.schemaVersion &&
-    previous.mode === next.mode &&
-    previous.epoch === next.epoch &&
-    previous.fingerprint === next.fingerprint
-  );
-}
-
-function resolveContextEngineCitationsMode(config: unknown): JsonValue | undefined {
-  const rootConfig = isUnknownRecord(config) ? config : undefined;
-  const memoryConfig = isUnknownRecord(rootConfig?.memory) ? rootConfig.memory : undefined;
-  const citations = memoryConfig?.citations;
-  return isJsonConfigValue(citations) ? citations : undefined;
-}
-
-function isUnknownRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}
-
-function isJsonConfigValue(value: unknown): value is JsonValue {
-  if (value === null || typeof value === "string" || typeof value === "boolean") {
-    return true;
-  }
-  if (typeof value === "number") {
-    return Number.isFinite(value);
-  }
-  if (Array.isArray(value)) {
-    return value.every(isJsonConfigValue);
-  }
-  return isUnknownRecord(value) && Object.values(value).every(isJsonConfigValue);
-}
-
-function shouldRecheckRecoverablePluginBinding(params: {
-  binding: CodexAppServerThreadBinding;
-  pluginThreadConfig?: CodexPluginThreadConfigProvider;
-}): boolean {
-  if (!params.pluginThreadConfig?.enabled) {
-    return false;
-  }
-  if (
-    !params.binding.pluginAppsFingerprint ||
-    !params.binding.pluginAppsInputFingerprint ||
-    params.binding.pluginAppsInputFingerprint !== params.pluginThreadConfig.inputFingerprint
-  ) {
-    return false;
-  }
-  const policyContext = params.binding.pluginAppPolicyContext;
-  if (!policyContext) {
-    return false;
-  }
-  const expectedPluginConfigKeys = params.pluginThreadConfig.enabledPluginConfigKeys ?? [];
-  return Object.keys(policyContext.apps).length === 0 || expectedPluginConfigKeys.length > 0;
-}
-
-export function buildThreadStartParams(
-  params: EmbeddedRunAttemptParams,
-  options: {
-    cwd: string;
-    dynamicTools: CodexDynamicToolSpec[];
-    appServer: CodexAppServerRuntimeOptions;
-    developerInstructions?: string;
-    config?: JsonObject;
-    nativeCodeModeEnabled?: boolean;
-    nativeCodeModeOnlyEnabled?: boolean;
-  },
-): CodexThreadStartParams {
-  const modelProvider = resolveCodexAppServerModelProvider({
-    provider: params.provider,
-    authProfileId: params.authProfileId,
-    authProfileStore: params.authProfileStore,
-    agentDir: params.agentDir,
-    config: params.config,
-  });
-  return {
-    model: params.modelId,
-    ...(modelProvider ? { modelProvider } : {}),
-    cwd: options.cwd,
-    approvalPolicy: options.appServer.approvalPolicy,
-    approvalsReviewer: options.appServer.approvalsReviewer,
-    sandbox: options.appServer.sandbox,
-    ...(options.appServer.serviceTier ? { serviceTier: options.appServer.serviceTier } : {}),
-    serviceName: "Klaw",
-    config: buildCodexRuntimeThreadConfigForRun(params, options.config, {
-      nativeCodeModeEnabled: options.nativeCodeModeEnabled,
-      nativeCodeModeOnlyEnabled: options.nativeCodeModeOnlyEnabled,
-    }),
-    ...(options.nativeCodeModeEnabled === false ? { environments: [] } : {}),
-    developerInstructions:
-      options.developerInstructions ??
-      buildDeveloperInstructions(params, { dynamicTools: options.dynamicTools }),
-    dynamicTools: options.dynamicTools,
-    experimentalRawEvents: true,
-    persistExtendedHistory: true,
-  };
-}
-
-export function buildThreadResumeParams(
-  params: EmbeddedRunAttemptParams,
-  options: {
-    threadId: string;
-    authProfileId?: string;
-    appServer: CodexAppServerRuntimeOptions;
-    dynamicTools?: CodexDynamicToolSpec[];
-    developerInstructions?: string;
-    config?: JsonObject;
-    nativeCodeModeEnabled?: boolean;
-    nativeCodeModeOnlyEnabled?: boolean;
-  },
-): CodexThreadResumeParams {
-  const modelProvider = resolveCodexAppServerModelProvider({
-    provider: params.provider,
-    authProfileId: options.authProfileId ?? params.authProfileId,
-    authProfileStore: params.authProfileStore,
-    agentDir: params.agentDir,
-    config: params.config,
-  });
-  return {
-    threadId: options.threadId,
-    model: params.modelId,
-    ...(modelProvider ? { modelProvider } : {}),
-    approvalPolicy: options.appServer.approvalPolicy,
-    approvalsReviewer: options.appServer.approvalsReviewer,
-    sandbox: options.appServer.sandbox,
-    ...(options.appServer.serviceTier ? { serviceTier: options.appServer.serviceTier } : {}),
-    config: buildCodexRuntimeThreadConfigForRun(params, options.config, {
-      nativeCodeModeEnabled: options.nativeCodeModeEnabled,
-      nativeCodeModeOnlyEnabled: options.nativeCodeModeOnlyEnabled,
-    }),
-    developerInstructions:
-      options.developerInstructions ??
-      buildDeveloperInstructions(params, { dynamicTools: options.dynamicTools }),
-    persistExtendedHistory: true,
-  };
-}
-
-export function buildCodexRuntimeThreadConfig(
-  config: JsonObject | undefined,
-  options: { nativeCodeModeEnabled?: boolean; nativeCodeModeOnlyEnabled?: boolean } = {},
-): JsonObject {
-  const codeModeConfig: JsonObject = {
-    ...CODEX_CODE_MODE_THREAD_CONFIG,
-    "features.code_mode_only": options.nativeCodeModeOnlyEnabled === true,
-  };
-  if (options.nativeCodeModeEnabled === false) {
-    return (
-      mergeCodexThreadConfigs(codeModeConfig, config, CODEX_CODE_MODE_DISABLED_THREAD_CONFIG) ?? {
-        ...CODEX_CODE_MODE_DISABLED_THREAD_CONFIG,
-      }
-    );
-  }
-  if (options.nativeCodeModeOnlyEnabled === true) {
-    return (
-      mergeCodexThreadConfigs(codeModeConfig, config, {
-        "features.code_mode_only": true,
-      }) ?? {
-        ...codeModeConfig,
-        "features.code_mode_only": true,
-      }
-    );
-  }
-  return (
-    mergeCodexThreadConfigs(codeModeConfig, config) ?? {
-      ...codeModeConfig,
-    }
-  );
-}
-
-function buildCodexRuntimeThreadConfigForRun(
-  params: EmbeddedRunAttemptParams,
-  config: JsonObject | undefined,
-  options: { nativeCodeModeEnabled?: boolean; nativeCodeModeOnlyEnabled?: boolean } = {},
-): JsonObject {
-  const runtimeConfig = buildCodexRuntimeThreadConfig(config, options);
-  if (params.bootstrapContextMode !== "lightweight") {
-    return runtimeConfig;
-  }
-  return (
-    mergeCodexThreadConfigs(runtimeConfig, CODEX_LIGHTWEIGHT_CONTEXT_THREAD_CONFIG) ?? {
-      ...runtimeConfig,
-      ...CODEX_LIGHTWEIGHT_CONTEXT_THREAD_CONFIG,
-    }
-  );
-}
-
-export function buildTurnStartParams(
-  params: EmbeddedRunAttemptParams,
-  options: {
-    threadId: string;
-    cwd: string;
-    appServer: CodexAppServerRuntimeOptions;
-    promptText?: string;
-    sandboxPolicy?: CodexSandboxPolicy;
-  },
-): CodexTurnStartParams {
-  return {
-    threadId: options.threadId,
-    input: buildUserInput(params, options.promptText),
-    cwd: options.cwd,
-    approvalPolicy: options.appServer.approvalPolicy,
-    approvalsReviewer: options.appServer.approvalsReviewer,
-    sandboxPolicy:
-      options.sandboxPolicy ?? codexSandboxPolicyForTurn(options.appServer.sandbox, options.cwd),
-    model: params.modelId,
-    ...(options.appServer.serviceTier ? { serviceTier: options.appServer.serviceTier } : {}),
-    effort: resolveReasoningEffort(params.thinkLevel, params.modelId),
-    collaborationMode: buildTurnCollaborationMode(params),
-  };
-}
-
-type CodexTurnCollaborationMode = NonNullable<CodexTurnStartParams["collaborationMode"]>;
-
-export function buildTurnCollaborationMode(
-  params: EmbeddedRunAttemptParams,
-): CodexTurnCollaborationMode {
-  return {
-    mode: "default",
-    settings: {
-      model: params.modelId,
-      reasoning_effort: resolveReasoningEffort(params.thinkLevel, params.modelId),
-      developer_instructions: buildTurnScopedCollaborationInstructions(params),
-    },
-  };
-}
-
-function buildTurnScopedCollaborationInstructions(params: EmbeddedRunAttemptParams): string | null {
-  if (params.trigger === "cron") {
-    return buildCronCollaborationInstructions();
-  }
-  if (params.trigger === "heartbeat") {
-    return buildHeartbeatCollaborationInstructions();
-  }
-  return null;
-}
-
-function buildCronCollaborationInstructions(): string {
-  return [
-    "This is an Klaw cron automation turn. Apply these instructions only to this scheduled job; ordinary chat turns should stay in Codex Default mode.",
-    "Execute the cron payload directly. If it asks you to run an exact command, run that command before doing any investigation, planning, memory review, or workspace bootstrap.",
-    "Use context already provided by the runtime, but do not spend time loading or re-reading workspace bootstrap, memory, or project-doc files before executing the cron payload. Inspect those files only if the payload asks for them or the command fails and they are needed to diagnose it.",
-    "Keep output concise and automation-oriented. Prefer the final command result or a short failure summary over status narration.",
-  ].join("\n\n");
-}
-
-function buildHeartbeatCollaborationInstructions(): string {
-  return [
-    "This is an Klaw heartbeat turn. Apply these instructions only to this heartbeat wake; ordinary chat turns should stay in Codex Default mode.",
-    "When you are ready to end the heartbeat, prefer the structured `heartbeat_respond` tool so Klaw can record the wake outcome and notification decision. If `heartbeat_respond` is not already available and `tool_search` is available, search for `heartbeat_respond`, load it, then call it. Use `notify=false` when nothing should visibly interrupt the user.",
-    CODEX_GPT5_HEARTBEAT_PROMPT_OVERLAY,
-  ].join("\n\n");
-}
-
-export function codexDynamicToolsFingerprint(dynamicTools: CodexDynamicToolSpec[]): string {
-  return fingerprintDynamicTools(dynamicTools);
-}
-
-export function areCodexDynamicToolFingerprintsCompatible(params: {
-  previous?: string;
-  next: string;
-}): boolean {
-  return areDynamicToolFingerprintsCompatible(params.previous, params.next);
-}
-
-function fingerprintDynamicTools(dynamicTools: CodexDynamicToolSpec[]): string {
-  return JSON.stringify(
-    dynamicTools.map(fingerprintDynamicToolSpec).toSorted(compareJsonFingerprint),
-  );
-}
-
-function fingerprintUserMcpServersConfigPatch(
-  configPatch: JsonObject | undefined,
-): string | undefined {
-  return configPatch ? JSON.stringify(stabilizeJsonValue(configPatch)) : undefined;
-}
-
-function fingerprintDynamicToolSpec(tool: JsonValue): JsonValue {
-  if (!isJsonObject(tool)) {
-    return stabilizeJsonValue(tool);
-  }
-  const stable: JsonObject = {};
-  for (const [key, child] of Object.entries(tool).toSorted(([left], [right]) =>
-    left.localeCompare(right),
-  )) {
-    if (key === "description") {
-      continue;
-    }
-    stable[key] = stabilizeJsonValue(child);
-  }
-  return stable;
-}
-
-function stabilizeJsonValue(value: JsonValue): JsonValue {
-  if (Array.isArray(value)) {
-    return value.map(stabilizeJsonValue);
-  }
-  if (!isJsonObject(value)) {
-    return value;
-  }
-  const stable: JsonObject = {};
-  for (const [key, child] of Object.entries(value).toSorted(([left], [right]) =>
-    left.localeCompare(right),
-  )) {
-    stable[key] = stabilizeJsonValue(child);
-  }
-  return stable;
-}
-
-const EMPTY_DYNAMIC_TOOLS_FINGERPRINT = JSON.stringify([]);
-
-function areDynamicToolFingerprintsCompatible(previous: string | undefined, next: string): boolean {
-  return !previous || previous === next;
-}
-
-function shouldStartTransientNoToolThread(params: {
-  previous: string | undefined;
-  next: string;
-}): boolean {
-  return Boolean(
-    params.previous &&
-    params.previous !== EMPTY_DYNAMIC_TOOLS_FINGERPRINT &&
-    params.next === EMPTY_DYNAMIC_TOOLS_FINGERPRINT,
-  );
-}
-
-function compareJsonFingerprint(left: JsonValue, right: JsonValue): number {
-  return JSON.stringify(left).localeCompare(JSON.stringify(right));
-}
-
-export function buildDeveloperInstructions(
-  params: EmbeddedRunAttemptParams,
-  options: { dynamicTools?: readonly CodexDynamicToolSpec[] } = {},
-): string {
-  const nativeCommandGuidance = listRegisteredPluginAgentPromptGuidance({
-    surface: "codex_app_server",
-    includeLegacyGlobalGuidance: false,
-  }).join("\n");
-  const sections = [
-    "Running inside Klaw. Use Klaw dynamic tools for Klaw-owned messaging, cron, sessions, media, gateway, and nodes capabilities when available.",
-    buildDeferredDynamicToolManifest(options.dynamicTools),
-    "Use Codex native `spawn_agent` for Codex subagents. Use Klaw `sessions_spawn` only for Klaw or ACP delegation; if it is not already loaded, search for `sessions_spawn` in the `klaw` dynamic tool namespace before calling it.",
-    buildVisibleReplyInstruction(params),
-    nativeCommandGuidance,
-    params.extraSystemPrompt,
-  ];
-  return sections.filter((section) => typeof section === "string" && section.trim()).join("\n\n");
-}
-
-function buildDeferredDynamicToolManifest(
-  dynamicTools: readonly CodexDynamicToolSpec[] | undefined,
-): string | undefined {
-  const deferredToolNames = [
-    ...new Set(
-      (dynamicTools ?? [])
-        .filter((tool) => tool.deferLoading === true)
-        .map((tool) => tool.name.trim())
-        .filter(Boolean),
-    ),
-  ].toSorted((left, right) => left.localeCompare(right));
-  if (deferredToolNames.length === 0) {
-    return undefined;
-  }
-  return `Deferred searchable Klaw dynamic tools available: ${deferredToolNames.join(", ")}. Use \`tool_search\` to load exact callable specs before use.`;
-}
-
-function buildVisibleReplyInstruction(params: EmbeddedRunAttemptParams): string {
-  if (params.sourceReplyDeliveryMode === "message_tool_only") {
-    return "Preserve channel/session context. Visible channel replies: use `message`, do not describe would-reply.";
-  }
-  return "Preserve channel/session context. Visible channel replies should use the active Codex delivery path; do not describe would-reply.";
-}
-
-function buildUserInput(
-  params: EmbeddedRunAttemptParams,
-  promptText: string = params.prompt,
-): CodexUserInput[] {
-  const imageInputs = (params.images ?? []).map((image): CodexUserInput => {
-    const imageUrl = sanitizeInlineImageDataUrl(`data:${image.mimeType};base64,${image.data}`);
-    return imageUrl
-      ? { type: "image", url: imageUrl }
-      : {
-          type: "text",
-          text: invalidInlineImageText("codex user input"),
-          text_elements: [],
-        };
-  });
-  return [{ type: "text", text: promptText, text_elements: [] }, ...imageInputs];
-}
-
-export function resolveCodexAppServerModelProvider(params: {
-  provider: string;
-  authProfileId?: string;
-  authProfileStore?: CodexAppServerAuthProfileLookup["authProfileStore"];
-  agentDir?: string;
-  config?: CodexAppServerAuthProfileLookup["config"];
-}): string | undefined {
-  const normalized = params.provider.trim();
-  const normalizedLower = normalized.toLowerCase();
-  if (!normalized || normalizedLower === "codex") {
-    // `codex` is Klaw's virtual provider; let Codex app-server keep its
-    // native provider/auth selection instead of forcing the legacy OpenAI path.
-    return undefined;
-  }
-  if (
-    isCodexAppServerNativeAuthProfile(params) &&
-    (normalizedLower === "openai" || normalizedLower === "openai-codex")
-  ) {
-    // When Klaw is forwarding ChatGPT/Codex OAuth, `openai` is Codex's
-    // native provider id, not a public OpenAI API-key choice. Omit the override
-    // so app-server keeps its configured provider/auth pair for this session.
-    return undefined;
-  }
-  return normalizedLower === "openai-codex" ? "openai" : normalized;
-}
-
-// Modern Codex models (gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.2) use the
-// none/low/medium/high/xhigh effort enum and reject "minimal". The CLI
-// defaults thinkLevel to "minimal", so without translation EVERY agent turn
-// on those models pays a wasted first request + retry-with-low fallback in
-// pi-embedded-runner. Map "minimal" -> "low" upfront for modern models so the
-// first request is accepted. Older Codex models still accept "minimal"
-// directly. (#71946)
-// Exported for unit-test coverage of the model-aware translation path.
-export function resolveReasoningEffort(
-  thinkLevel: EmbeddedRunAttemptParams["thinkLevel"],
-  modelId: string,
-): "minimal" | "low" | "medium" | "high" | "xhigh" | null {
-  if (thinkLevel === "minimal") {
-    return isModernCodexModel(modelId) ? "low" : "minimal";
-  }
-  if (
-    thinkLevel === "low" ||
-    thinkLevel === "medium" ||
-    thinkLevel === "high" ||
-    thinkLevel === "xhigh"
-  ) {
-    return thinkLevel;
-  }
-  return null;
-}