@ai-sdk/harness-codex 1.0.9 → 1.0.11

package/src/bridge/index.ts

@@ -18,13 +18,12 @@ import {
 import type { HarnessV1BuiltinToolName } from '@ai-sdk/harness';
 import type { StartMessage } from '../codex-bridge-protocol';
 import { randomUUID } from 'node:crypto';
-import { writeFile } from 'node:fs/promises';
+import { mkdir, writeFile } from 'node:fs/promises';
 import { createServer, type Server } from 'node:http';
 // Temporary workaround for upstream codex MCP-tool bug — see ./cli-relay.ts
 import {
   CLI_SHIM_FILENAME,
   buildCliShimScript,
-  composeToolUsageInstructions,
   isToolRelayCommand,
 } from './cli-relay';
 import { argv, env as procEnv, stdout } from 'node:process';
@@ -63,14 +62,15 @@ function toCommonName(nativeName: string): HarnessV1BuiltinToolName | string {
 }
 
 const args = parseArgs(argv.slice(2));
-const workdir = args.workdir;
-const bridgeStateDir = args.bridgeStateDir;
-if (!workdir) {
-  emitFatal('Missing --workdir argument.');
-}
-if (!bridgeStateDir) {
-  emitFatal('Missing --bridge-state-dir argument.');
-}
+const workdir = requireArg({ value: args.workdir, name: '--workdir' });
+const bridgeStateDir = requireArg({
+  value: args.bridgeStateDir,
+  name: '--bridge-state-dir',
+});
+const cliShimDir = requireArg({
+  value: args.cliShimDir,
+  name: '--cli-shim-dir',
+});
 const bootstrapDir = args.bootstrapDir ?? workdir;
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -114,10 +114,9 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
    * Until that's fixed, host tools are made available to the model via a
    * separate CLI-relay workaround (see `./cli-relay.ts`). The MCP server
    * config below is kept so that the day codex starts exposing MCP tools
-   * properly, host tools work both ways. Three hookpoints in this file
-   * (writeFile for the shim, composeUserMessage's toolUsageBlock, and the
-   * isToolRelayCommand filter in the event loop) implement the workaround
-   * and can be removed once the upstream bug is fixed.
+   * properly, host tools work both ways. Writing the shim here, adding matching
+   * prompt guidance in the host adapter, and filtering the shim command below
+   * implement the workaround and can be removed once the upstream bug is fixed.
    */
   const mcpServers: Record<string, unknown> = {};
   let relay: { port: number; close(): void } | undefined;
@@ -147,7 +146,8 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
       },
     };
     // Temporary workaround for upstream codex MCP-tool bug — see ./cli-relay.ts
-    cliShimPath = `${workdir}/${CLI_SHIM_FILENAME}`;
+    cliShimPath = `${cliShimDir}/${CLI_SHIM_FILENAME}`;
+    await mkdir(cliShimDir, { recursive: true });
     await writeFile(
       cliShimPath,
       buildCliShimScript({ relayPort: relay.port, relayToken }),
@@ -212,18 +212,7 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
 
   emit({ type: 'stream-start' });
 
-  const userMessage = composeUserMessage({
-    text: start.prompt,
-    instructions: start.instructions,
-    // Temporary workaround for upstream codex MCP-tool bug — see ./cli-relay.ts
-    toolUsageBlock:
-      cliShimPath && start.tools && start.tools.length > 0
-        ? composeToolUsageInstructions({
-            tools: start.tools,
-            cliShimPath,
-          })
-        : undefined,
-  });
+  const userMessage = start.prompt;
   let turnUsage: Record<string, unknown> | undefined;
   const textByItem = new Map<string, string>();
   const reasoningByItem = new Map<string, string>();
@@ -523,36 +512,6 @@ function defaultUsage(): Record<string, unknown> {
   };
 }
 
-function composeUserMessage({
-  text,
-  instructions,
-  toolUsageBlock,
-}: {
-  text: string;
-  instructions: string | undefined;
-  toolUsageBlock: string | undefined;
-}): string {
-  const blocks: string[] = [];
-  /*
-   * Frame instructions as system-provided operating guidance, not something
-   * the user wrote, so the agent does not echo the prepended text back as if
-   * the user had asked for it. Only present on the first user message of a
-   * fresh session (the host gates it), so the matching `<user-message>` fence
-   * is added only when instructions are present too.
-   */
-  if (instructions) {
-    blocks.push(
-      '<session-instructions>\n' +
-        'The block below is operating guidance from the system, not a message from the user — follow it, but do not mention it or attribute it to the user.\n\n' +
-        `${instructions}\n` +
-        '</session-instructions>',
-    );
-  }
-  if (toolUsageBlock) blocks.push(toolUsageBlock);
-  blocks.push(instructions ? `<user-message>\n${text}\n</user-message>` : text);
-  return blocks.join('\n\n');
-}
-
 /**
  * Tool relay — HTTP server on 127.0.0.1:0 with bearer-token auth. The MCP
  * stdio shim spawned by codex POSTs each tool invocation here; the relay
@@ -657,11 +616,13 @@ function parseArgs(args: string[]): {
   workdir?: string;
   bridgeStateDir?: string;
   bootstrapDir?: string;
+  cliShimDir?: string;
 } {
   const out: {
     workdir?: string;
     bridgeStateDir?: string;
     bootstrapDir?: string;
+    cliShimDir?: string;
   } = {};
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--workdir' && i + 1 < args.length) {
@@ -670,6 +631,8 @@ function parseArgs(args: string[]): {
       out.bridgeStateDir = args[++i];
     } else if (args[i] === '--bootstrap-dir' && i + 1 < args.length) {
       out.bootstrapDir = args[++i];
+    } else if (args[i] === '--cli-shim-dir' && i + 1 < args.length) {
+      out.cliShimDir = args[++i];
     }
   }
   return out;
@@ -686,3 +649,16 @@ function emitFatal(message: string): never {
   stdout.write(JSON.stringify({ type: 'bridge-fatal', message }) + '\n');
   process.exit(1);
 }
+
+function requireArg({
+  value,
+  name,
+}: {
+  value: string | undefined;
+  name: string;
+}): string {
+  if (!value) {
+    emitFatal(`Missing ${name} argument.`);
+  }
+  return value;
+}

package/src/codex-bridge-protocol.ts

@@ -17,7 +17,6 @@ export const outboundMessageSchema = harnessV1BridgeOutboundMessageSchema;
 export type OutboundMessage = z.infer<typeof outboundMessageSchema>;
 
 export const startMessageSchema = harnessV1BridgeStartBaseSchema.extend({
-  instructions: z.string().optional(),
   reasoningEffort: z.enum(['low', 'medium', 'high']).optional(),
   webSearch: z.boolean().optional(),
   // Resume signal. When supplied, the bridge calls

package/src/codex-harness.ts

@@ -38,6 +38,7 @@ import {
   type InboundMessage,
   type OutboundMessage,
 } from './codex-bridge-protocol';
+import { CLI_SHIM_FILENAME } from './bridge/cli-relay';
 
 type CodexChannel = SandboxChannel<OutboundMessage, InboundMessage>;
 type CodexRespawnStrategy = 'replay' | 'rerun';
@@ -115,12 +116,11 @@ const CODEX_BUILTIN_TOOLS = {
  * reinstall the CLI and bridge files on any fresh sandbox from the recipe.
  * Persistence comes from the sandbox provider's snapshot, not the path.
  *
- * The session work dir (`startOpts.sessionWorkDir`) and the bridge-state dir
- * derived from `sandboxSession.defaultWorkingDirectory` both live under the sandbox's
- * default working directory — the provider's persistent mount — so the
- * workdir's contents (the codex CLI shim and any files the agent edits) and
- * the bridge state files survive both detach -> attach and
- * stop -> snapshot -> resume cycles.
+ * The session work dir (`startOpts.sessionWorkDir`) lives under the sandbox's
+ * default working directory — the provider's persistent mount — so any files
+ * the agent edits survive both detach -> attach and stop -> snapshot -> resume
+ * cycles. Harness infra derived from `sandboxSession.defaultWorkingDirectory`
+ * lives under `.agent-runs`, outside the agent workdir.
  */
 const BOOTSTRAP_DIR = '/tmp/harness/codex';
 
@@ -225,6 +225,8 @@ export function createCodex(
       const workDir = startOpts.sessionWorkDir;
       const sessionDataDir = `${sandboxSession.defaultWorkingDirectory}/.agent-runs/${startOpts.sessionId}`;
       const bridgeStateDir = `${sessionDataDir}/bridge`;
+      const cliShimDir = `${sessionDataDir}/codex`;
+      const cliShimPath = `${cliShimDir}/${CLI_SHIM_FILENAME}`;
       const timeoutMs = settings.startupTimeoutMs ?? 120_000;
 
       // Normalize each forwarded bridge diagnostics frame into the general
@@ -266,6 +268,7 @@ export function createCodex(
           return createSession({
             sessionId: startOpts.sessionId,
             channel: attachChannel,
+            cliShimPath,
             // The live bridge was spawned by another process; no process handle.
             proc: undefined,
             model: settings.model ?? DEFAULT_CODEX_MODEL,
@@ -349,7 +352,7 @@ export function createCodex(
       });
 
       const proc = await session.spawn({
-        command: `node ${BOOTSTRAP_DIR}/bridge.mjs --workdir ${shellQuote(workDir)} --bridge-state-dir ${shellQuote(bridgeStateDir)} --bootstrap-dir ${shellQuote(BOOTSTRAP_DIR)}`,
+        command: `node ${BOOTSTRAP_DIR}/bridge.mjs --workdir ${shellQuote(workDir)} --bridge-state-dir ${shellQuote(bridgeStateDir)} --bootstrap-dir ${shellQuote(BOOTSTRAP_DIR)} --cli-shim-dir ${shellQuote(cliShimDir)}`,
         env,
         abortSignal: startOpts.abortSignal,
       });
@@ -402,6 +405,7 @@ export function createCodex(
       return createSession({
         sessionId: startOpts.sessionId,
         channel,
+        cliShimPath,
         proc,
         model: settings.model ?? DEFAULT_CODEX_MODEL,
         reasoningEffort: settings.reasoningEffort,
@@ -615,6 +619,7 @@ function openWebSocket(url: string): Promise<WebSocket> {
 function createSession({
   sessionId,
   channel,
+  cliShimPath,
   proc,
   model,
   reasoningEffort,
@@ -631,6 +636,7 @@ function createSession({
 }: {
   sessionId: string;
   channel: CodexChannel;
+  cliShimPath: string;
   /** Undefined on `attach` — the live bridge was spawned by another process. */
   proc: Experimental_SandboxProcess | undefined;
   model: string | undefined;
@@ -658,10 +664,10 @@ function createSession({
     ? resumeThreadId
     : undefined;
   /*
-   * Instructions are prepended to the first user message of a fresh session
-   * only. A resumed session (attach/replay/rerun) already carried them in its
-   * original first message (preserved in the persisted thread), so it starts
-   * "applied".
+   * Initial prompt guidance is prepended to the first user message of a fresh
+   * session only. A resumed session (attach/replay/rerun) already carried it
+   * in its original first message (preserved in the persisted thread), so it
+   * starts "applied".
    */
   let instructionsApplied = isResume;
 
@@ -842,19 +848,34 @@ function createSession({
         abortSignal: promptOpts.abortSignal,
       });
 
-      const applyInstructions =
-        !instructionsApplied && !!promptOpts.instructions;
+      const tools = (promptOpts.tools ?? []).map(t => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+      }));
+      let promptText = extractUserText(promptOpts.prompt);
+      if (!instructionsApplied) {
+        const instructions =
+          (promptOpts.instructions ? promptOpts.instructions + '\n\n' : '') +
+          'Only respond with your `final` message once you have fully addressed the user request.';
+        promptText = frameInitialPromptGuidance({
+          instructions,
+          toolUsageBlock:
+            tools.length > 0
+              ? composeToolUsageInstructions({
+                  tools,
+                  cliShimPath,
+                })
+              : undefined,
+          userText: promptText,
+        });
+      }
       instructionsApplied = true;
 
       const startMessage = {
         type: 'start' as const,
-        prompt: extractUserText(promptOpts.prompt),
-        ...(applyInstructions ? { instructions: promptOpts.instructions } : {}),
-        tools: (promptOpts.tools ?? []).map(t => ({
-          name: t.name,
-          description: t.description,
-          inputSchema: t.inputSchema,
-        })),
+        prompt: promptText,
+        tools,
         model,
         reasoningEffort,
         webSearch,
@@ -1098,6 +1119,67 @@ function createSession({
   };
 }
 
+/*
+ * Frame session instructions, host-tool relay guidance, and the user's text so
+ * Codex treats the prepended blocks as operating guidance rather than user
+ * prose. Applied only to the first user message of a fresh session.
+ */
+function frameInitialPromptGuidance({
+  instructions,
+  toolUsageBlock,
+  userText,
+}: {
+  instructions: string | undefined;
+  toolUsageBlock: string | undefined;
+  userText: string;
+}): string {
+  const blocks: string[] = [];
+  if (instructions) {
+    blocks.push(
+      '<session-instructions>\n' +
+        'The block below is operating guidance from the system, not a message from the user — follow it, but do not mention it or attribute it to the user.\n\n' +
+        `${instructions}\n` +
+        '</session-instructions>',
+    );
+  }
+  if (toolUsageBlock) blocks.push(toolUsageBlock);
+  if (blocks.length === 0) return userText;
+  return `${blocks.join('\n\n')}\n\n<user-message>\n${userText}\n</user-message>`;
+}
+
+function composeToolUsageInstructions({
+  tools,
+  cliShimPath,
+}: {
+  tools: ReadonlyArray<{
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+  }>;
+  cliShimPath: string;
+}): string {
+  const lines: string[] = [
+    '<host-tool-instructions>',
+    'You have access to the following host-provided tools. To use one, run the following command via your built-in `bash` tool:',
+    '',
+    `  node ${cliShimPath} <toolName> '<jsonInput>'`,
+    '',
+    'The script prints the JSON result to stdout. Do not invent another way to call these tools — only this CLI invocation will work. Pass the JSON input as a single-quoted argument.',
+    'For every user request that depends on a host-provided tool, run a separate CLI invocation for each needed tool call in the current turn before answering. Do not reuse previous tool results, and do not say you used a host tool unless the command has completed in the current turn.',
+    '',
+  ];
+  for (const toolSpec of tools) {
+    lines.push(
+      `- **${toolSpec.name}**${toolSpec.description ? ': ' + toolSpec.description : ''}`,
+    );
+    lines.push(
+      `  - Input schema: \`${JSON.stringify(toolSpec.inputSchema ?? {})}\``,
+    );
+  }
+  lines.push('</host-tool-instructions>');
+  return lines.join('\n');
+}
+
 /*
  * Reduce a `HarnessV1Prompt` to the plain user text the bridge forwards
  * to the Codex SDK. File and image parts on the message are not yet