@ai-sdk/harness-codex 1.0.94 → 1.0.96

package/src/codex-harness.ts

@@ -1,4 +1,4 @@
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import path from 'node:path';
 import {
   commonTool,
@@ -36,6 +36,7 @@ import {
   warnCredentialBrokeringUnavailable,
   waitForBridgeReady,
   writeSkills as writeHarnessSkills,
+  type WriteSkillsResult,
 } from '@ai-sdk/harness/utils';
 import {
   type Experimental_SandboxProcess,
@@ -66,11 +67,6 @@ import { VERSION } from './version';
 type CodexChannel = SandboxChannel<OutboundMessage, InboundMessage>;
 type CodexRespawnStrategy = 'replay' | 'rerun';
 
-type WriteSkillsResult = {
-  readonly homeDir: string;
-  readonly codexHomeDir: string;
-};
-
 /*
  * This intentionally is not the latest Codex model. Newer GPT-5.6 models use
  * Responses Lite, which does not expose their code-mode tools as callable
@@ -110,13 +106,15 @@ export type CodexHarnessSettings = {
   /**
    * OpenAI model id the underlying `codex` CLI should use. Leaving this unset
    * pins the adapter default (`DEFAULT_CODEX_MODEL`).
+   *
+   * @deprecated Use `model` on `HarnessAgent` instead.
    */
   readonly model?: string;
   /**
    * Reasoning effort for reasoning-capable models. Leaving this unset
    * defers to the CLI's default.
    */
-  readonly reasoningEffort?: 'low' | 'medium' | 'high';
+  readonly reasoningEffort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
   /**
    * When `true`, allow the underlying runtime to use live web search.
    */
@@ -189,6 +187,7 @@ const codexBridgeCoordsSchema = z.object({
  */
 const codexResumeStateSchema = z.object({
   threadId: z.string().optional(),
+  turnConfigurationFingerprint: z.string().optional(),
   bridge: codexBridgeCoordsSchema.optional(),
   sandboxCredentialEnvironment: z.record(z.string(), z.string()).optional(),
 });
@@ -206,6 +205,7 @@ export function createCodex(
     lifecycleStateSchema: codexResumeStateSchema,
     getBootstrap: getCodexBootstrap,
     doStart: async startOpts => {
+      const model = settings.model ?? DEFAULT_CODEX_MODEL;
       if (startOpts.builtinToolFiltering != null) {
         throw new HarnessCapabilityUnsupportedError({
           message:
@@ -251,6 +251,7 @@ export function createCodex(
         isResume && typeof lifecycleState?.data === 'object'
           ? (lifecycleState.data as {
               threadId?: unknown;
+              turnConfigurationFingerprint?: unknown;
               bridge?: CodexBridgeCoords;
               sandboxCredentialEnvironment?: Record<string, string>;
             })
@@ -260,6 +261,10 @@ export function createCodex(
         typeof resumeThreadId === 'string' && resumeThreadId.length > 0
           ? resumeThreadId
           : undefined;
+      const turnConfigurationFingerprint =
+        typeof resumeData?.turnConfigurationFingerprint === 'string'
+          ? resumeData.turnConfigurationFingerprint
+          : undefined;
       const coords = resumeData?.bridge;
       const authenticationMode = resolveCodexAuthenticationMode(settings.auth);
       const resolvedAuthEnvironment = resolveCodexEnv(settings.auth);
@@ -315,6 +320,10 @@ export function createCodex(
       );
 
       const workDir = startOpts.sessionWorkDir;
+      const sandboxHomeDir = await resolveSandboxHomeDir({
+        sandbox: toolSafeSandboxSession,
+        abortSignal: startOpts.abortSignal,
+      });
       const sessionDataDir = `${defaultWorkingDirectory}/.agent-runs/${startOpts.sessionId}`;
       const bridgeStateDir = `${sessionDataDir}/bridge`;
       const cliShimDir = `${sessionDataDir}/codex`;
@@ -372,7 +381,7 @@ export function createCodex(
             cliShimPath,
             // The live bridge was spawned by another process; no process handle.
             proc: undefined,
-            model: settings.model ?? DEFAULT_CODEX_MODEL,
+            model,
             reasoningEffort: settings.reasoningEffort,
             webSearch: settings.webSearch,
             codexConfig: settings.codexConfig,
@@ -387,6 +396,9 @@ export function createCodex(
             sandboxCredentialEnvironment,
             debug: startOpts.observability?.debug,
             permissionMode: startOpts.permissionMode,
+            sandbox: toolSafeSandboxSession,
+            sandboxHomeDir,
+            turnConfigurationFingerprint,
           });
         } catch {
           // Bridge no longer reachable — recover by respawning below.
@@ -432,25 +444,11 @@ export function createCodex(
               CODEX_CREDENTIAL_ENVIRONMENT_VARIABLES,
             credentialForwarding: settings.credentialForwarding,
           });
-      const codexSkillSetup =
-        startOpts.skills && startOpts.skills.length > 0
-          ? await writeCodexSkills({
-              sandbox: toolSafeSandboxSession,
-              skills: startOpts.skills,
-              abortSignal: startOpts.abortSignal,
-            })
-          : undefined;
       const env = {
         ...forwardedAuthEnvironment,
         AI_SDK_HARNESS_CLIENT_APP: CODEX_CLIENT_APP,
         BRIDGE_CHANNEL_TOKEN: token,
         BRIDGE_WS_PORT: String(port),
-        ...(codexSkillSetup
-          ? {
-              HOME: codexSkillSetup.homeDir,
-              CODEX_HOME: codexSkillSetup.codexHomeDir,
-            }
-          : {}),
         ...(respawnStrategy === 'replay'
           ? { BRIDGE_REPLAY_FROM_DISK: '1' }
           : {}),
@@ -537,7 +535,7 @@ export function createCodex(
         channel,
         cliShimPath,
         proc,
-        model: settings.model ?? DEFAULT_CODEX_MODEL,
+        model,
         reasoningEffort: settings.reasoningEffort,
         webSearch: settings.webSearch,
         codexConfig: settings.codexConfig,
@@ -552,6 +550,9 @@ export function createCodex(
         sandboxCredentialEnvironment,
         debug: startOpts.observability?.debug,
         permissionMode: startOpts.permissionMode,
+        sandbox: toolSafeSandboxSession,
+        sandboxHomeDir,
+        turnConfigurationFingerprint,
       });
     },
   };
@@ -624,22 +625,17 @@ async function resolveBridgeEndpoint({
 
 async function writeCodexSkills({
   sandbox,
+  sandboxHomeDir,
   skills,
   abortSignal,
 }: {
   sandbox: SandboxSession;
+  sandboxHomeDir: string;
   skills: ReadonlyArray<HarnessV1Skill>;
   abortSignal?: AbortSignal;
 }): Promise<WriteSkillsResult> {
-  const homeDir = await resolveSandboxHomeDir({ sandbox, abortSignal });
-  const codexHomeDir = path.posix.join(homeDir, '.codex');
-  await sandbox.run({
-    command: `mkdir -p ${shellQuote(codexHomeDir)}`,
-    abortSignal,
-  });
-
-  const rootDir = path.posix.join(homeDir, '.agents', 'skills');
-  await writeHarnessSkills({
+  const rootDir = path.posix.join(sandboxHomeDir, '.agents', 'skills');
+  return writeHarnessSkills({
     sandbox,
     rootDir,
     skills,
@@ -648,11 +644,6 @@ async function writeCodexSkills({
     invalidSkillFilePathMessage: ({ skillName, filePath }) =>
       `Invalid Codex skill file path for ${skillName}: ${filePath}`,
   });
-
-  return {
-    homeDir,
-    codexHomeDir,
-  };
 }
 
 function openWebSocket({
@@ -708,6 +699,9 @@ function createSession({
   sandboxCredentialEnvironment,
   debug,
   permissionMode,
+  sandbox,
+  sandboxHomeDir,
+  turnConfigurationFingerprint,
 }: {
   sessionId: string;
   channel: CodexChannel;
@@ -715,7 +709,7 @@ function createSession({
   /** Undefined on `attach` — the live bridge was spawned by another process. */
   proc: Experimental_SandboxProcess | undefined;
   model: string | undefined;
-  reasoningEffort: 'low' | 'medium' | 'high' | undefined;
+  reasoningEffort: 'low' | 'medium' | 'high' | 'xhigh' | 'max' | undefined;
   webSearch: boolean | undefined;
   codexConfig: Record<string, unknown> | undefined;
   mcpServers: Record<string, unknown> | undefined;
@@ -729,6 +723,9 @@ function createSession({
   sandboxCredentialEnvironment: Record<string, string> | undefined;
   debug: HarnessV1DebugConfig | undefined;
   permissionMode: HarnessV1PermissionMode | undefined;
+  sandbox: SandboxSession;
+  sandboxHomeDir: string;
+  turnConfigurationFingerprint: string | undefined;
 }): HarnessV1Session {
   let stopped = false;
   let stopPromise: Promise<void> | undefined;
@@ -755,10 +752,55 @@ function createSession({
    * can include a thread id even before this process has run a turn.
    */
   let latestThreadId = resumeThreadId;
+  let latestTurnConfigurationFingerprint = turnConfigurationFingerprint;
   channel.on('bridge-thread', msg => {
     latestThreadId = msg.threadId;
   });
 
+  const synchronizeTurnConfiguration = async ({
+    skills,
+    instructions,
+    tools,
+    abortSignal,
+  }: {
+    skills: ReadonlyArray<HarnessV1Skill>;
+    instructions: string | undefined;
+    tools: ReadonlyArray<{
+      name: string;
+      description?: string;
+      inputSchema: unknown;
+    }>;
+    abortSignal?: AbortSignal;
+  }): Promise<{ restartThread: boolean }> => {
+    const skillsResult = await writeCodexSkills({
+      sandbox,
+      sandboxHomeDir,
+      skills,
+      abortSignal,
+    });
+    const nextFingerprint = fingerprintCodexTurnConfiguration({
+      instructions,
+      tools,
+    });
+    const restartThread =
+      latestThreadId != null &&
+      (skillsResult.changed ||
+        (latestTurnConfigurationFingerprint != null &&
+          latestTurnConfigurationFingerprint !== nextFingerprint));
+    latestTurnConfigurationFingerprint = nextFingerprint;
+    if (restartThread) {
+      /*
+       * `codex exec resume` retains the native thread's original developer
+       * instructions and skill catalog. A fresh native thread is therefore
+       * required for replacement semantics. Host-tool guidance is framed
+       * again because that guidance also belongs to the new native thread.
+       */
+      initialPromptGuidanceApplied = false;
+      pendingResumeThreadId = undefined;
+    }
+    return { restartThread };
+  };
+
   /*
    * Wire the channel into one turn's worth of events and return the control
    * surface. Shared by `doPromptTurn` (which sends a `start` afterwards) and
@@ -916,7 +958,6 @@ function createSession({
   return {
     sessionId,
     isResume,
-    modelId: model,
     doPromptTurn: async promptOpts => {
       if (
         promptOpts.responseFormat?.type === 'json' &&
@@ -928,16 +969,22 @@ function createSession({
           harnessId: 'codex',
         });
       }
-      const turn = wireTurn({
-        emit: promptOpts.emit,
-        abortSignal: promptOpts.abortSignal,
-      });
-
       const tools = (promptOpts.tools ?? []).map(t => ({
         name: t.name,
         description: t.description,
         inputSchema: t.inputSchema,
       }));
+      const { restartThread } = await synchronizeTurnConfiguration({
+        skills: promptOpts.skills,
+        instructions: promptOpts.instructions,
+        tools,
+        abortSignal: promptOpts.abortSignal,
+      });
+      const turn = wireTurn({
+        emit: promptOpts.emit,
+        abortSignal: promptOpts.abortSignal,
+      });
+
       let promptText = extractUserText(promptOpts.prompt);
       if (!initialPromptGuidanceApplied) {
         promptText = frameInitialPromptGuidance({
@@ -963,7 +1010,7 @@ function createSession({
         ...(promptOpts.instructions
           ? { instructions: promptOpts.instructions }
           : {}),
-        model,
+        model: promptOpts.model ?? model,
         reasoningEffort,
         webSearch,
         ...(codexConfig == null ? {} : { codexConfig }),
@@ -972,6 +1019,7 @@ function createSession({
         ...(pendingResumeThreadId
           ? { resumeThreadId: pendingResumeThreadId }
           : {}),
+        ...(restartThread ? { restartThread: true } : {}),
         ...(debug ? { debug } : {}),
       };
       pendingResumeThreadId = undefined;
@@ -990,6 +1038,17 @@ function createSession({
           harnessId: 'codex',
         });
       }
+      const tools = (continueOpts.tools ?? []).map(t => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+      }));
+      const { restartThread } = await synchronizeTurnConfiguration({
+        skills: continueOpts.skills,
+        instructions: continueOpts.instructions,
+        tools,
+        abortSignal: continueOpts.abortSignal,
+      });
       const turn = wireTurn({
         emit: continueOpts.emit,
         abortSignal: continueOpts.abortSignal,
@@ -1021,24 +1080,21 @@ function createSession({
              * empty text block trips the Anthropic API's `cache_control` rule).
              */
             prompt: 'Continue.',
-            tools: (continueOpts.tools ?? []).map(t => ({
-              name: t.name,
-              description: t.description,
-              inputSchema: t.inputSchema,
-            })),
+            tools,
             ...(continueOpts.responseFormat == null
               ? {}
               : { responseFormat: continueOpts.responseFormat }),
             ...(continueOpts.instructions
               ? { instructions: continueOpts.instructions }
               : {}),
-            model,
+            model: continueOpts.model ?? model,
             reasoningEffort,
             webSearch,
             ...(codexConfig == null ? {} : { codexConfig }),
             ...(mcpServers == null ? {} : { mcpServers }),
             ...(permissionMode ? { permissionMode } : {}),
             ...(threadId ? { resumeThreadId: threadId } : {}),
+            ...(restartThread ? { restartThread: true } : {}),
             ...(debug ? { debug } : {}),
           }),
         );
@@ -1074,6 +1130,12 @@ function createSession({
         specificationVersion: 'harness-v1',
         data: {
           ...(latestThreadId ? { threadId: latestThreadId } : {}),
+          ...(latestTurnConfigurationFingerprint
+            ? {
+                turnConfigurationFingerprint:
+                  latestTurnConfigurationFingerprint,
+              }
+            : {}),
           ...(sandboxCredentialEnvironment == null
             ? {}
             : { sandboxCredentialEnvironment }),
@@ -1195,6 +1257,12 @@ function createSession({
         specificationVersion: 'harness-v1',
         data: {
           ...lifecycleData,
+          ...(latestTurnConfigurationFingerprint
+            ? {
+                turnConfigurationFingerprint:
+                  latestTurnConfigurationFingerprint,
+              }
+            : {}),
           ...(sandboxCredentialEnvironment == null
             ? {}
             : { sandboxCredentialEnvironment }),
@@ -1224,6 +1292,12 @@ function createSession({
         specificationVersion: 'harness-v1',
         data: {
           ...(latestThreadId ? { threadId: latestThreadId } : {}),
+          ...(latestTurnConfigurationFingerprint
+            ? {
+                turnConfigurationFingerprint:
+                  latestTurnConfigurationFingerprint,
+              }
+            : {}),
           ...(sandboxCredentialEnvironment == null
             ? {}
             : { sandboxCredentialEnvironment }),
@@ -1240,6 +1314,22 @@ function createSession({
   };
 }
 
+function fingerprintCodexTurnConfiguration({
+  instructions,
+  tools,
+}: {
+  instructions: string | undefined;
+  tools: ReadonlyArray<{
+    name: string;
+    description?: string;
+    inputSchema: unknown;
+  }>;
+}): string {
+  return createHash('sha256')
+    .update(JSON.stringify({ instructions: instructions ?? null, tools }))
+    .digest('hex');
+}
+
 /*
  * Frame host-tool relay guidance and the user's text so Codex treats the
  * prepended block as operating guidance rather than user prose. Applied only