@ai-sdk/harness-codex 1.0.93 → 1.0.95

package/src/codex-auth.ts

@@ -1,10 +1,12 @@
 import type {
+  HarnessV1Authentication,
   HarnessV1RequestTransformation,
   HarnessV1RequestTransformationSources,
 } from '@ai-sdk/harness';
 import {
   createCredentialRequestTransformation,
   getAiGatewayAuthFromEnv,
+  isHarnessAuthenticationEnvironment,
 } from '@ai-sdk/harness/utils';
 
 const DEFAULT_AI_GATEWAY_BASE_URL = 'https://ai-gateway.vercel.sh/v1';
@@ -42,83 +44,48 @@ export function createCodexRequestTransformations({
 
 export type CodexResolvedAuthenticationMode = 'direct' | 'ai-gateway';
 
-export type CodexAuthenticationMode = CodexResolvedAuthenticationMode | 'auto';
-
-/**
- * @deprecated Passing an object to auth options is deprecated. Use a `CodexAuthenticationMode` string value ("auto" | "direct" | "ai-gateway") instead, and pass credentials via environment variables.
- */
-export type LegacyCodexAuthOptions = {
-  readonly openaiCompatible?: {
-    readonly apiKey?: string;
-    readonly baseUrl?: string;
-    readonly modelProviderName?: string;
-    readonly queryParamsJson?: string;
-  };
-  readonly openai?: {
-    readonly apiKey?: string;
-    readonly baseUrl?: string;
-    readonly organization?: string;
-    readonly project?: string;
-  };
-  readonly gateway?: {
-    readonly apiKey?: string;
-    readonly baseUrl?: string;
-  };
-};
-
-export type CodexAuthOptions = CodexAuthenticationMode | LegacyCodexAuthOptions;
+export type CodexAuthenticationMode = HarnessV1Authentication;
 
 /**
  * Resolve the environment-variable blob the codex bridge needs. Precedence:
  *
- *   1. Explicit `auth.openaiCompatible` — pin to a custom OpenAI-compatible endpoint.
- *   2. Explicit `auth.openai` — pin to direct OpenAI auth.
- *   3. Explicit `auth.gateway` — pin to Vercel AI Gateway.
- *   4. Auto-detect from the host process env: gateway first
+ *   1. An explicit authentication mode pins the selected route.
+ *   2. Auto-detect from the host process env: gateway first
  *      (`AI_GATEWAY_API_KEY` / `VERCEL_OIDC_TOKEN`), then `CODEX_API_KEY` /
  *      `OPENAI_API_KEY`.
  */
 export function resolveCodexEnv(
-  auth: CodexAuthOptions | undefined,
+  auth: CodexAuthenticationMode | undefined,
   processEnv: Record<string, string | undefined> = process.env,
 ): Record<string, string> {
-  const normalizedAuth = normalizeCodexAuthToLegacyAuth(auth);
-
-  if (normalizedAuth?.openaiCompatible) {
-    return pickOpenAICompatible(normalizedAuth.openaiCompatible, processEnv);
-  }
-  if (normalizedAuth?.openai) {
-    return pickOpenAI({ explicit: normalizedAuth.openai, processEnv });
+  const suppliedEnvironment = isHarnessAuthenticationEnvironment(auth);
+  const authenticationEnvironment = suppliedEnvironment ? auth : processEnv;
+  if (auth === 'direct') {
+    return pickOpenAI({ processEnv: authenticationEnvironment });
   }
+
   const gatewayAuthFromEnv = getAiGatewayAuthFromEnv({
-    env: processEnv,
+    env: authenticationEnvironment,
   });
-  if (normalizedAuth?.gateway) {
-    return pickGateway({
-      explicit: normalizedAuth.gateway,
-      gatewayAuthFromEnv,
-    });
-  }
-  if (gatewayAuthFromEnv.apiKey) {
-    return pickGateway({
-      explicit: {},
-      gatewayAuthFromEnv,
-    });
+  if (auth === 'ai-gateway' || gatewayAuthFromEnv.apiKey) {
+    return pickGateway({ gatewayAuthFromEnv });
   }
-  return pickOpenAI({ processEnv });
+  return pickOpenAI({ processEnv: authenticationEnvironment });
 }
 
 export function resolveCodexAuthenticationMode(
-  auth: CodexAuthOptions | undefined,
+  auth: CodexAuthenticationMode | undefined,
   processEnv: Record<string, string | undefined> = process.env,
 ): CodexResolvedAuthenticationMode {
-  if (typeof auth !== 'string' && auth?.openaiCompatible) {
-    return 'direct';
+  if (isHarnessAuthenticationEnvironment(auth)) {
+    return getAiGatewayAuthFromEnv({ env: auth }).apiKey
+      ? 'ai-gateway'
+      : 'direct';
   }
-  if (auth === 'direct' || (typeof auth !== 'string' && auth?.openai)) {
+  if (auth === 'direct') {
     return 'direct';
   }
-  if (auth === 'ai-gateway' || (typeof auth !== 'string' && auth?.gateway)) {
+  if (auth === 'ai-gateway') {
     return 'ai-gateway';
   }
   return getAiGatewayAuthFromEnv({ env: processEnv }).apiKey
@@ -126,76 +93,30 @@ export function resolveCodexAuthenticationMode(
     : 'direct';
 }
 
-function normalizeCodexAuthToLegacyAuth(
-  auth: CodexAuthOptions | undefined,
-): LegacyCodexAuthOptions | undefined {
-  if (auth == null || auth === 'auto') {
-    return undefined;
-  }
-  if (typeof auth === 'string') {
-    switch (auth) {
-      case 'direct':
-        return { openai: {} };
-      case 'ai-gateway':
-        return { gateway: {} };
-      default:
-        return undefined;
-    }
-  }
-
-  console.warn(
-    '[codex] Passing an object to auth options is deprecated. Use a string mode ("auto" | "direct" | "ai-gateway") instead, and pass credentials via environment variables.',
-  );
-  return auth;
-}
-
-function pickOpenAICompatible(
-  explicit: NonNullable<LegacyCodexAuthOptions['openaiCompatible']>,
-  processEnv: Record<string, string | undefined>,
-): Record<string, string> {
-  const env: Record<string, string> = {};
-  const apiKey =
-    explicit.apiKey ?? processEnv.OPENAI_API_KEY ?? processEnv.CODEX_API_KEY;
-  if (apiKey) env.CODEX_API_KEY = apiKey;
-  if (explicit.baseUrl) env.OPENAI_BASE_URL = explicit.baseUrl;
-  if (explicit.modelProviderName)
-    env.CODEX_MODEL_PROVIDER_NAME = explicit.modelProviderName;
-  if (explicit.queryParamsJson)
-    env.OPENAI_QUERY_PARAMS_JSON = explicit.queryParamsJson;
-  return env;
-}
-
 function pickOpenAI({
-  explicit,
   processEnv,
 }: {
-  explicit?: NonNullable<LegacyCodexAuthOptions['openai']>;
   processEnv: Record<string, string | undefined>;
 }): Record<string, string> {
   const env: Record<string, string> = {};
-  const apiKey =
-    explicit?.apiKey ?? processEnv.OPENAI_API_KEY ?? processEnv.CODEX_API_KEY;
+  const apiKey = processEnv.OPENAI_API_KEY ?? processEnv.CODEX_API_KEY;
   if (apiKey) env.CODEX_API_KEY = apiKey;
-  const baseUrl = explicit?.baseUrl ?? processEnv.OPENAI_BASE_URL;
+  const baseUrl = processEnv.OPENAI_BASE_URL;
   if (baseUrl) env.OPENAI_BASE_URL = baseUrl;
-  const organization = explicit?.organization ?? processEnv.OPENAI_ORGANIZATION;
+  const organization = processEnv.OPENAI_ORGANIZATION;
   if (organization) env.OPENAI_ORGANIZATION = organization;
-  const project = explicit?.project ?? processEnv.OPENAI_PROJECT;
+  const project = processEnv.OPENAI_PROJECT;
   if (project) env.OPENAI_PROJECT = project;
   return env;
 }
 
 function pickGateway({
-  explicit,
   gatewayAuthFromEnv,
 }: {
-  explicit: NonNullable<LegacyCodexAuthOptions['gateway']>;
   gatewayAuthFromEnv: ReturnType<typeof getAiGatewayAuthFromEnv>;
 }): Record<string, string> {
-  const apiKey = explicit.apiKey ?? gatewayAuthFromEnv.apiKey;
-  const baseUrl = toCodexGatewayBaseUrl(
-    explicit.baseUrl ?? gatewayAuthFromEnv.baseUrl,
-  );
+  const apiKey = gatewayAuthFromEnv.apiKey;
+  const baseUrl = toCodexGatewayBaseUrl(gatewayAuthFromEnv.baseUrl);
   const env: Record<string, string> = {};
   if (apiKey) {
     env.AI_GATEWAY_API_KEY = apiKey;

package/src/codex-bridge-protocol.ts

@@ -27,6 +27,7 @@ export const startMessageSchema = harnessV1BridgeStartBaseSchema.extend({
   // The host sources the id from lifecycle state `data` cached from a prior
   // `agent.detach`.
   resumeThreadId: z.string().optional(),
+  restartThread: z.boolean().optional(),
 });
 
 export type StartMessage = z.infer<typeof startMessageSchema>;

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,
@@ -53,7 +54,7 @@ import {
   DEFAULT_OPENAI_BASE_URL,
   resolveCodexAuthenticationMode,
   resolveCodexEnv,
-  type CodexAuthOptions,
+  type CodexAuthenticationMode,
 } from './codex-auth';
 import {
   outboundMessageSchema,
@@ -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
@@ -89,7 +85,7 @@ const DEFAULT_CODEX_MODEL = 'gpt-5.5';
 const CODEX_CLIENT_APP = `ai-sdk/harness-codex/${VERSION}`;
 
 export type CodexHarnessSettings = {
-  readonly auth?: CodexAuthOptions;
+  readonly auth?: CodexAuthenticationMode;
   /**
    * Customizes each credential value before it is forwarded into a sandbox
    * process. This does not restrict which credentials the harness adapter can
@@ -110,6 +106,8 @@ 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;
   /**
@@ -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 = startOpts.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;
@@ -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
@@ -928,16 +970,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({
@@ -972,6 +1020,7 @@ function createSession({
         ...(pendingResumeThreadId
           ? { resumeThreadId: pendingResumeThreadId }
           : {}),
+        ...(restartThread ? { restartThread: true } : {}),
         ...(debug ? { debug } : {}),
       };
       pendingResumeThreadId = undefined;
@@ -990,6 +1039,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,11 +1081,7 @@ 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 }),
@@ -1039,6 +1095,7 @@ function createSession({
             ...(mcpServers == null ? {} : { mcpServers }),
             ...(permissionMode ? { permissionMode } : {}),
             ...(threadId ? { resumeThreadId: threadId } : {}),
+            ...(restartThread ? { restartThread: true } : {}),
             ...(debug ? { debug } : {}),
           }),
         );
@@ -1074,6 +1131,12 @@ function createSession({
         specificationVersion: 'harness-v1',
         data: {
           ...(latestThreadId ? { threadId: latestThreadId } : {}),
+          ...(latestTurnConfigurationFingerprint
+            ? {
+                turnConfigurationFingerprint:
+                  latestTurnConfigurationFingerprint,
+              }
+            : {}),
           ...(sandboxCredentialEnvironment == null
             ? {}
             : { sandboxCredentialEnvironment }),
@@ -1195,6 +1258,12 @@ function createSession({
         specificationVersion: 'harness-v1',
         data: {
           ...lifecycleData,
+          ...(latestTurnConfigurationFingerprint
+            ? {
+                turnConfigurationFingerprint:
+                  latestTurnConfigurationFingerprint,
+              }
+            : {}),
           ...(sandboxCredentialEnvironment == null
             ? {}
             : { sandboxCredentialEnvironment }),
@@ -1224,6 +1293,12 @@ function createSession({
         specificationVersion: 'harness-v1',
         data: {
           ...(latestThreadId ? { threadId: latestThreadId } : {}),
+          ...(latestTurnConfigurationFingerprint
+            ? {
+                turnConfigurationFingerprint:
+                  latestTurnConfigurationFingerprint,
+              }
+            : {}),
           ...(sandboxCredentialEnvironment == null
             ? {}
             : { sandboxCredentialEnvironment }),
@@ -1240,6 +1315,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

package/src/index.ts

@@ -10,4 +10,4 @@ export const codex = createCodex();
 export { createCodex } from './codex-harness';
 export { VERSION } from './version';
 export type { CodexHarnessSettings } from './codex-harness';
-export type { CodexAuthenticationMode, CodexAuthOptions } from './codex-auth';
+export type { CodexAuthenticationMode } from './codex-auth';