@moxxy/plugin-provider-openai-codex 0.21.1

package/src/provider.ts

@@ -0,0 +1,360 @@
+import { webcrypto } from 'node:crypto';
+import type {
+  LLMProvider,
+  ProviderEvent,
+  ProviderRequest,
+} from '@moxxy/sdk';
+import { classifyHttpStatus, estimateTextTokens } from '@moxxy/sdk';
+import { isAuthRejection, withCredentialLock } from '@moxxy/plugin-oauth';
+import { CODEX_RESPONSES_URL, refreshTokens } from './oauth.js';
+import { codexModels, DEFAULT_CODEX_MODEL } from './models.js';
+import { toResponsesBody } from './translate.js';
+import { buildCodexHeaders } from './codex/headers.js';
+import { consumeResponsesSse, toErrorEvent } from './codex/stream-consumer.js';
+import type { CodexTokens } from './types.js';
+
+/**
+ * Internal idle timeout (ms). Guards the whole streaming path against a backend
+ * that accepts the POST but then stalls — pre-headers slow-loris, a dropped TCP
+ * with no RST, or a wedged proxy — when the caller supplied no AbortSignal. The
+ * watchdog is reset on every received byte, so a slow-but-alive reasoning stream
+ * is never killed; only a stream that goes silent for this long aborts.
+ */
+const CODEX_IDLE_TIMEOUT_MS = 120_000;
+
+/**
+ * Read the error-response body but cap how much we pull into memory: a hostile
+ * or broken backend (or MITM) could otherwise stream a multi-megabyte error body
+ * that we'd buffer in full and then interpolate into an error string.
+ */
+const MAX_ERROR_BODY_CHARS = 2048;
+
+/**
+ * Flat token estimate charged per non-text content block (image/document) in
+ * `countTokens`. A coarse stand-in for the provider's real multimodal token
+ * accounting — enough to keep pre-flight budgeting from treating a multimodal
+ * request as if it were nearly empty.
+ */
+const NON_TEXT_BLOCK_TOKENS = 256;
+
+export interface CodexProviderConfig {
+  readonly tokens?: CodexTokens;
+  /**
+   * Called with the new token bundle whenever an in-process refresh happens.
+   * The CLI's setup wires this to a vault writeback so the refreshed
+   * refresh_token (single-use, rotates on every refresh) is persisted
+   * before the next API call goes out.
+   */
+  readonly onTokensRefreshed?: (next: CodexTokens) => void | Promise<void>;
+  /**
+   * Re-reads the persisted token bundle (the vault) and returns it, or null
+   * when nothing is stored. The refresh token is SINGLE-USE and rotates on
+   * every refresh, so when another consumer/process refreshes first, this is
+   * how the provider picks up the rotated bundle instead of burning a dead
+   * token: it's consulted under the per-credential lock before refreshing,
+   * and once more to retry after an invalid_grant-style rejection.
+   */
+  readonly reloadTokens?: () => Promise<CodexTokens | null>;
+  readonly defaultModel?: string;
+  /**
+   * Reasoning effort sent with every request (`reasoning.effort`).
+   * Defaults to `'medium'`. Reaches here from `provider.config` in
+   * moxxy.config.ts (e.g. `{ reasoningEffort: 'high' }`); the CLI's
+   * credential resolution merges that config through to `createClient`.
+   */
+  readonly reasoningEffort?: 'low' | 'medium' | 'high';
+  /** Test seam — when omitted we use the global `fetch`. */
+  readonly fetch?: typeof fetch;
+  /** Test seam — when omitted we use crypto.randomUUID for the per-request session id. */
+  readonly sessionIdProvider?: () => string;
+  /**
+   * Idle timeout (ms) for the streaming request: the watchdog aborts the call if
+   * the backend goes silent for this long (stalled handshake or mid-stream
+   * silence). Reset on every received byte, so slow-but-alive streams survive.
+   * Defaults to {@link CODEX_IDLE_TIMEOUT_MS}; mainly a test seam.
+   */
+  readonly idleTimeoutMs?: number;
+}
+
+/**
+ * LLMProvider implementation against the ChatGPT-plan Codex backend. Auth is
+ * an OAuth bearer plus the optional ChatGPT-Account-Id header; the rest of
+ * the request body is the OpenAI Responses-API shape.
+ *
+ * Request-param support: `req.maxTokens` maps to the Responses
+ * `max_output_tokens` field; `req.temperature` is NOT forwarded — the Codex
+ * backend only serves gpt-5-family reasoning models, which reject sampling
+ * params with a 400, so it is dropped (with a one-shot MOXXY_DEBUG note)
+ * instead of breaking the request. Reasoning effort is configurable via
+ * `CodexProviderConfig.reasoningEffort` (default `'medium'`).
+ */
+export class CodexProvider implements LLMProvider {
+  readonly name = 'openai-codex';
+  readonly models = codexModels;
+
+  private tokens: CodexTokens | undefined;
+  private readonly onTokensRefreshed?: (next: CodexTokens) => void | Promise<void>;
+  private readonly reloadTokens?: () => Promise<CodexTokens | null>;
+  private readonly defaultModel: string;
+  private readonly reasoningEffort?: 'low' | 'medium' | 'high';
+  private readonly fetchImpl: typeof fetch;
+  private readonly sessionIdProvider: () => string;
+  private readonly idleTimeoutMs: number;
+
+  constructor(config: CodexProviderConfig = {}) {
+    if (config.tokens) this.tokens = config.tokens;
+    if (config.onTokensRefreshed) this.onTokensRefreshed = config.onTokensRefreshed;
+    if (config.reloadTokens) this.reloadTokens = config.reloadTokens;
+    this.defaultModel = config.defaultModel ?? DEFAULT_CODEX_MODEL;
+    if (config.reasoningEffort) this.reasoningEffort = config.reasoningEffort;
+    this.fetchImpl = config.fetch ?? fetch;
+    // Default to ONE id for the instance's lifetime, not a fresh uuid per call.
+    // The session id becomes the `prompt_cache_key`, so it must be stable
+    // across a session's turns for the Responses prefix cache to hit (and the
+    // `session_id` header should be stable for one logical session too).
+    const defaultSessionId = webcrypto.randomUUID();
+    this.sessionIdProvider = config.sessionIdProvider ?? (() => defaultSessionId);
+    this.idleTimeoutMs =
+      config.idleTimeoutMs && config.idleTimeoutMs > 0
+        ? config.idleTimeoutMs
+        : CODEX_IDLE_TIMEOUT_MS;
+  }
+
+  async *stream(req: ProviderRequest): AsyncIterable<ProviderEvent> {
+    const model = req.model || this.defaultModel;
+    yield { type: 'message_start', model };
+
+    try {
+      await this.ensureFresh();
+    } catch (err) {
+      yield toErrorEvent(err);
+      return;
+    }
+
+    const sessionId = this.sessionIdProvider();
+    // Reasoning preview is gated by the per-provider toggle (`req.reasoning`):
+    // when off we behave exactly as before (discard reasoning). The per-call
+    // effort, when set, overrides the instance default from provider config.
+    const emitReasoning = req.reasoning != null && req.reasoning !== false;
+    const reqEffort = typeof req.reasoning === 'object' ? req.reasoning.effort : undefined;
+    const reasoningEffort = reqEffort ?? this.reasoningEffort;
+    // Pass the session id as the Responses prefix-cache key so repeated turns
+    // in a session reuse the cached prefix (cheaper + faster). Codex DOES
+    // support this even though the Chat-Completions providers ignore cacheHints.
+    const body = toResponsesBody(
+      { ...req, model },
+      {
+        sessionHint: sessionId,
+        ...(reasoningEffort ? { reasoningEffort } : {}),
+      },
+    );
+
+    // Internal idle watchdog: aborts the request if the backend stalls (accepts
+    // the POST but never sends headers/body, or goes silent mid-stream) so the
+    // turn can't hang forever when the caller supplied no AbortSignal. Composed
+    // with `req.signal` so a caller cancellation still wins, and reset on every
+    // received byte by `consumeResponsesSse`'s onActivity callback.
+    const idleController = new AbortController();
+    let idleTimer: ReturnType<typeof setTimeout> | undefined;
+    const armIdle = (): void => {
+      if (idleTimer) clearTimeout(idleTimer);
+      idleTimer = setTimeout(
+        () => idleController.abort(new Error('Codex request timed out (no response from server)')),
+        this.idleTimeoutMs,
+      );
+      // A bare timer must not keep the event loop alive on its own.
+      idleTimer.unref?.();
+    };
+    const disarmIdle = (): void => {
+      if (idleTimer) clearTimeout(idleTimer);
+      idleTimer = undefined;
+    };
+    const signal = req.signal
+      ? AbortSignal.any([req.signal, idleController.signal])
+      : idleController.signal;
+
+    try {
+      armIdle();
+      let response: Response;
+      try {
+        response = await this.postCodex(body, sessionId, signal);
+      } catch (err) {
+        yield toErrorEvent(err);
+        return;
+      }
+
+      if (response.status === 401) {
+        // Token might've been revoked between our pre-check and send; try one
+        // forced refresh and replay. A second 401 is fatal.
+        try {
+          await this.refreshNow();
+          armIdle();
+          response = await this.postCodex(body, sessionId, signal);
+        } catch (err) {
+          yield toErrorEvent(err);
+          return;
+        }
+        // A 401 that survives a forced refresh means the OAuth grant itself was
+        // rejected (expired/revoked), not a transient skew. Surface the same
+        // actionable re-auth guidance as ensureFresh rather than the generic
+        // "returned 401" HTTP message below.
+        if (response.status === 401) {
+          yield {
+            type: 'error',
+            message:
+              'ChatGPT OAuth credentials were rejected after a token refresh. Run `moxxy login openai-codex` to re-authenticate.',
+            retryable: false,
+          };
+          return;
+        }
+      }
+
+      if (!response.ok || !response.body) {
+        // Cap the buffered error body: a hostile/broken backend could otherwise
+        // stream a huge body that we'd hold in full and then put into a string.
+        const text = await readCappedText(response, MAX_ERROR_BODY_CHARS);
+        // Derive the retryable verdict from the SDK's status classifier so it
+        // stays consistent with the rest of moxxy (429 + 5xx are retryable).
+        const classified = classifyHttpStatus(response.status);
+        const retryable =
+          classified?.code === 'PROVIDER_RATE_LIMITED' ||
+          classified?.code === 'PROVIDER_SERVER_ERROR';
+        yield {
+          type: 'error',
+          message: `Codex /responses returned ${response.status}: ${text || response.statusText}`,
+          retryable,
+        };
+        return;
+      }
+
+      yield* consumeResponsesSse(response.body, signal, emitReasoning, armIdle);
+    } finally {
+      disarmIdle();
+    }
+  }
+
+  async countTokens(
+    req: Pick<ProviderRequest, 'model' | 'messages' | 'system' | 'tools'>,
+  ): Promise<number> {
+    // Only sum text. For non-text blocks (image/document) we add a flat per-block
+    // estimate instead of JSON.stringify-ing the base64 `data`, which would be a
+    // multi-megabyte transient allocation AND a meaningless token count (base64
+    // char length, not visual tokens) that skews any pre-flight budgeting.
+    let blob = req.system ?? '';
+    let nonTextBlocks = 0;
+    for (const m of req.messages) {
+      for (const c of m.content) {
+        if ('text' in c && typeof c.text === 'string') blob += c.text;
+        else nonTextBlocks += 1;
+      }
+    }
+    blob += (req.tools ?? []).map((t) => t.name + t.description).join('');
+    return estimateTextTokens(blob) + nonTextBlocks * NON_TEXT_BLOCK_TOKENS;
+  }
+
+  private postCodex(body: unknown, sessionId: string, signal: AbortSignal | undefined): Promise<Response> {
+    if (!this.tokens) throw new Error('No tokens');
+    return this.fetchImpl(CODEX_RESPONSES_URL, {
+      method: 'POST',
+      headers: buildCodexHeaders(this.tokens, sessionId),
+      body: JSON.stringify(body),
+      ...(signal ? { signal } : {}),
+    });
+  }
+
+  private async ensureFresh(): Promise<void> {
+    if (!this.tokens) {
+      throw new Error(
+        'No ChatGPT OAuth credentials available. Run `moxxy login openai-codex` to sign in.',
+      );
+    }
+    // 60s skew window — refresh proactively if the token will die very soon.
+    if (this.tokens.expires > Date.now() + 60_000) return;
+    await this.refreshNow();
+  }
+
+  /**
+   * Refresh + persist under the per-credential lock. The refresh token is
+   * SINGLE-USE (rotated + invalidated on every refresh), so concurrent
+   * refreshers — a second stream in this process, the whisper-stt
+   * transcriber sharing this credential, or another moxxy process — must
+   * serialize and coalesce: whoever holds the lock refreshes once, everyone
+   * queued behind it adopts the rotated bundle instead of burning it.
+   */
+  private async refreshNow(): Promise<void> {
+    const entry = this.tokens;
+    if (!entry) {
+      throw new Error('Cannot refresh — no stored tokens.');
+    }
+    await withCredentialLock(`oauth-${this.name}`, async () => {
+      // Coalesce in-process: another stream refreshed while we waited.
+      if (this.tokens && this.tokens.access !== entry.access) return;
+      // Coalesce cross-process/cross-consumer: adopt a fresher persisted
+      // bundle (and at minimum its rotated refresh token) when available.
+      let attempt = this.tokens ?? entry;
+      if (this.reloadTokens) {
+        const latest = await this.reloadTokens().catch(() => null);
+        if (latest && latest.access !== attempt.access && latest.expires > Date.now() + 60_000) {
+          this.tokens = withAccountId(latest, latest.accountId ?? attempt.accountId);
+          return;
+        }
+        if (latest?.refresh) attempt = { ...attempt, refresh: latest.refresh };
+      }
+      let next: CodexTokens;
+      try {
+        next = await refreshTokens(attempt.refresh, this.fetchImpl);
+      } catch (err) {
+        // invalid_grant-style rejection: someone rotated our refresh token
+        // away after the reload above. Re-read once and retry with the
+        // fresher token before surfacing the failure.
+        const latest = isAuthRejection(err) && this.reloadTokens
+          ? await this.reloadTokens().catch(() => null)
+          : null;
+        if (!latest?.refresh || latest.refresh === attempt.refresh) throw err;
+        next = await refreshTokens(latest.refresh, this.fetchImpl);
+      }
+      // Preserve a previously known accountId if the refresh response didn't
+      // re-issue an id_token. Without this we'd silently lose the
+      // ChatGPT-Account-Id header on every refresh.
+      const merged = withAccountId(next, next.accountId ?? attempt.accountId);
+      this.tokens = merged;
+      if (this.onTokensRefreshed) {
+        // Persist BEFORE the caller issues the API call so a crash here
+        // doesn't strand an unwritten refresh token in memory.
+        await this.onTokensRefreshed(merged);
+      }
+    });
+  }
+}
+
+function withAccountId(tokens: CodexTokens, accountId: string | undefined): CodexTokens {
+  return accountId
+    ? { access: tokens.access, refresh: tokens.refresh, expires: tokens.expires, accountId }
+    : { access: tokens.access, refresh: tokens.refresh, expires: tokens.expires };
+}
+
+/**
+ * Read an error-response body but stop once `maxChars` is reached, then release
+ * the socket. Avoids pulling a hostile/broken multi-megabyte error body fully
+ * into memory just to put a prefix of it in an error message. Decode failures or
+ * a missing body yield `''` so the caller falls back to `response.statusText`.
+ */
+async function readCappedText(response: Response, maxChars: number): Promise<string> {
+  const body = response.body;
+  if (!body) return '';
+  const reader = body.getReader();
+  const decoder = new TextDecoder('utf-8');
+  let out = '';
+  try {
+    while (out.length < maxChars) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      out += decoder.decode(value, { stream: true });
+    }
+    return out.slice(0, maxChars);
+  } catch {
+    return out.slice(0, maxChars);
+  } finally {
+    reader.cancel().catch(() => {});
+  }
+}

package/src/translate.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest';
+import { extractSystemText, toResponsesBody, toResponsesInput } from './translate.js';
+
+describe('toResponsesInput', () => {
+  it('translates an image block to an input_image data URL', () => {
+    const input = toResponsesInput([
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: 'what is this?' },
+          { type: 'image', mediaType: 'image/png', data: 'AAAA' },
+        ],
+      },
+    ]);
+    expect(input[0]).toEqual({
+      type: 'message',
+      role: 'user',
+      content: [
+        { type: 'input_text', text: 'what is this?' },
+        { type: 'input_image', image_url: 'data:image/png;base64,AAAA' },
+      ],
+    });
+  });
+
+  it('preserves a user message whose only blocks are untranslatable instead of dropping it', () => {
+    // A user message carrying solely block types contentBlocksToInputText doesn't
+    // emit (e.g. audio) must not silently vanish from the request — keep the turn
+    // with an empty input_text so conversational context isn't lost.
+    const input = toResponsesInput([
+      { role: 'user', content: [{ type: 'audio', mediaType: 'audio/wav', data: 'AAAA' }] },
+    ]);
+    expect(input).toEqual([
+      { type: 'message', role: 'user', content: [{ type: 'input_text', text: '' }] },
+    ]);
+  });
+
+  it('still drops a user message with no blocks at all', () => {
+    const input = toResponsesInput([{ role: 'user', content: [] }]);
+    expect(input).toEqual([]);
+  });
+
+  it('translates a document block to an input_file with data URL + filename', () => {
+    const input = toResponsesInput([
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: 'summarize this' },
+          { type: 'document', mediaType: 'application/pdf', data: 'JVBERi0=', name: 'report.pdf' },
+        ],
+      },
+    ]);
+    expect(input[0]).toEqual({
+      type: 'message',
+      role: 'user',
+      content: [
+        { type: 'input_text', text: 'summarize this' },
+        { type: 'input_file', filename: 'report.pdf', file_data: 'data:application/pdf;base64,JVBERi0=' },
+      ],
+    });
+  });
+});
+
+describe('extractSystemText', () => {
+  it('appends explicitSystem (req.system) AFTER the message-derived system prompt', () => {
+    const text = extractSystemText(
+      [
+        { role: 'system', content: [{ type: 'text', text: 'BASE PROMPT' }] },
+        { role: 'user', content: [{ type: 'text', text: 'hi' }] },
+      ],
+      '[memory note] consider consolidating',
+    );
+    expect(text).toBe('BASE PROMPT\n\n[memory note] consider consolidating');
+  });
+});
+
+describe('toResponsesBody', () => {
+  const req = {
+    model: 'gpt-5.3-codex',
+    messages: [
+      { role: 'system' as const, content: [{ type: 'text' as const, text: 'BASE' }] },
+      { role: 'user' as const, content: [{ type: 'text' as const, text: 'hi' }] },
+    ],
+  };
+
+  it('delivers hook-injected req.system in instructions', () => {
+    const body = toResponsesBody({ ...req, system: 'NUDGE' });
+    expect(body.instructions).toBe('BASE\n\nNUDGE');
+  });
+
+  it('drops both maxTokens and temperature (ChatGPT Codex backend rejects them)', () => {
+    const body = toResponsesBody({ ...req, maxTokens: 999, temperature: 0.5 });
+    expect(body).not.toHaveProperty('max_output_tokens');
+    expect(body).not.toHaveProperty('temperature');
+  });
+});

package/src/translate.ts

@@ -0,0 +1,224 @@
+import { zodToJsonSchema, type ProviderMessage, type ProviderRequest, type ToolDef } from '@moxxy/sdk';
+
+/**
+ * Responses-API "input" item shape. We only emit the subset codex uses:
+ * - `message` items with role + a string-or-rich content
+ * - `function_call` items (assistant tool invocations replayed back)
+ * - `function_call_output` items (tool results)
+ */
+type ResponsesInputItem =
+  | { type: 'message'; role: 'user' | 'assistant' | 'system'; content: ReadonlyArray<ResponsesContent> }
+  | { type: 'function_call'; call_id: string; name: string; arguments: string }
+  | { type: 'function_call_output'; call_id: string; output: string };
+
+type ResponsesContent =
+  | { type: 'input_text'; text: string }
+  | { type: 'output_text'; text: string }
+  | { type: 'input_image'; image_url: string }
+  | { type: 'input_file'; filename?: string; file_data: string };
+
+interface ResponsesTool {
+  type: 'function';
+  name: string;
+  description: string;
+  parameters: unknown;
+  strict?: boolean;
+}
+
+export interface ResponsesBody {
+  model: string;
+  instructions?: string;
+  input: ResponsesInputItem[];
+  tools?: ResponsesTool[];
+  parallel_tool_calls?: boolean;
+  reasoning?: { effort?: 'low' | 'medium' | 'high'; summary?: 'auto' | 'detailed' };
+  store?: boolean;
+  stream: true;
+  prompt_cache_key?: string;
+  include?: string[];
+  // NOTE: no `temperature` and no `max_output_tokens` — every model the Codex
+  // backend serves is a gpt-5-family reasoning model, and the ChatGPT-plan
+  // `/responses` endpoint rejects sampling params (`temperature`/`top_p`) AND
+  // `max_output_tokens` with a 400 ("Unsupported parameter"). See
+  // `noteTemperatureUnsupported`/`noteMaxTokensUnsupported` below.
+}
+
+function contentBlocksToInputText(
+  role: 'user' | 'assistant',
+  blocks: ProviderMessage['content'],
+): ResponsesContent[] {
+  const out: ResponsesContent[] = [];
+  for (const block of blocks) {
+    if (block.type === 'text') {
+      out.push(role === 'assistant' ? { type: 'output_text', text: block.text } : { type: 'input_text', text: block.text });
+    } else if (block.type === 'image') {
+      out.push({ type: 'input_image', image_url: `data:${block.mediaType};base64,${block.data}` });
+    } else if (block.type === 'document') {
+      out.push({
+        type: 'input_file',
+        ...(block.name ? { filename: block.name } : {}),
+        file_data: `data:${block.mediaType};base64,${block.data}`,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * Extract any system-role text from a message array. Used to hoist the
+ * system prompt into the top-level `instructions` field — the Responses
+ * API rejects requests with a missing/empty `instructions`, and our
+ * upstream loop helpers push the system prompt in as a `role: 'system'`
+ * message. `explicitSystem` (`ProviderRequest.system`) is the
+ * hook-injection side channel — extra per-request system text appended
+ * AFTER the message-derived prompt, matching how the other providers
+ * deliver it.
+ */
+export function extractSystemText(
+  messages: ReadonlyArray<ProviderMessage>,
+  explicitSystem?: string,
+): string {
+  const parts: string[] = [];
+  for (const msg of messages) {
+    if (msg.role !== 'system') continue;
+    for (const block of msg.content) {
+      if (block.type === 'text' && block.text) parts.push(block.text);
+    }
+  }
+  if (explicitSystem && explicitSystem.trim()) parts.push(explicitSystem);
+  return parts.join('\n\n');
+}
+
+export function toResponsesInput(messages: ReadonlyArray<ProviderMessage>): ResponsesInputItem[] {
+  const out: ResponsesInputItem[] = [];
+  for (const msg of messages) {
+    if (msg.role === 'system') {
+      // System prompt is hoisted to top-level `instructions` by
+      // `toResponsesBody`; don't duplicate it as an input message too.
+      continue;
+    }
+    if (msg.role === 'user') {
+      const content = contentBlocksToInputText('user', msg.content);
+      if (content.length > 0) {
+        out.push({ type: 'message', role: 'user', content });
+      } else if (msg.content.length > 0) {
+        // The message carried blocks but none translated (unhandled block types):
+        // keep the turn with an empty input_text so we don't silently drop it
+        // from the request and lose conversational context.
+        out.push({ type: 'message', role: 'user', content: [{ type: 'input_text', text: '' }] });
+      }
+      continue;
+    }
+    if (msg.role === 'assistant') {
+      const text = msg.content
+        .filter((c): c is { type: 'text'; text: string } => c.type === 'text')
+        .map((c) => c.text)
+        .join('');
+      if (text) out.push({ type: 'message', role: 'assistant', content: [{ type: 'output_text', text }] });
+      for (const block of msg.content) {
+        if (block.type === 'tool_use') {
+          out.push({
+            type: 'function_call',
+            call_id: block.id,
+            name: block.name,
+            arguments: JSON.stringify(block.input ?? {}),
+          });
+        }
+      }
+      continue;
+    }
+    if (msg.role === 'tool_result') {
+      for (const block of msg.content) {
+        if (block.type === 'tool_result') {
+          out.push({
+            type: 'function_call_output',
+            call_id: block.toolUseId,
+            output: block.content,
+          });
+        }
+      }
+    }
+  }
+  return out;
+}
+
+export function toResponsesTools(tools: ReadonlyArray<ToolDef>): ResponsesTool[] {
+  return tools.map((t) => ({
+    type: 'function' as const,
+    name: t.name,
+    description: t.description,
+    parameters: (t.inputJsonSchema ?? zodToJsonSchema(t.inputSchema)) as unknown,
+  }));
+}
+
+export interface BuildBodyOptions {
+  readonly sessionHint?: string;
+  readonly reasoningEffort?: 'low' | 'medium' | 'high';
+}
+
+/**
+ * Default `instructions` value used when the caller supplies neither
+ * `req.system` nor a system-role message. The Codex backend rejects
+ * requests with an empty `instructions` field (`400: Instructions are
+ * required`), so we always send something — falling back to a minimal
+ * agent identity matches what codex-rs does for plain `codex exec` runs.
+ */
+const DEFAULT_INSTRUCTIONS = 'You are a helpful coding assistant.';
+
+/**
+ * One-shot debug note for the unsupported `temperature` param. The Codex
+ * backend only serves gpt-5-family reasoning models, which reject
+ * sampling params with `400: Unsupported parameter: 'temperature'` — so
+ * rather than forward it and break every request, we drop it and (once
+ * per process, only with MOXXY_DEBUG set) say so instead of silently
+ * eating the option.
+ */
+let temperatureNoteShown = false;
+function noteTemperatureUnsupported(): void {
+  if (temperatureNoteShown) return;
+  temperatureNoteShown = true;
+  if (process.env.MOXXY_DEBUG) {
+    console.debug(
+      '[openai-codex] ProviderRequest.temperature is not supported by the Codex ' +
+        'Responses backend (gpt-5 reasoning models reject sampling params); ignoring it.',
+    );
+  }
+}
+
+/**
+ * One-shot debug note for the unsupported `maxTokens` param. Unlike the
+ * platform Responses API, the ChatGPT-plan Codex backend rejects
+ * `max_output_tokens` with `400: {"detail":"Unsupported parameter:
+ * max_output_tokens"}` — observed live when `workflow_create` passed a draft
+ * budget. Same policy as temperature: drop it instead of breaking the request.
+ */
+let maxTokensNoteShown = false;
+function noteMaxTokensUnsupported(): void {
+  if (maxTokensNoteShown) return;
+  maxTokensNoteShown = true;
+  if (process.env.MOXXY_DEBUG) {
+    console.debug(
+      '[openai-codex] ProviderRequest.maxTokens is not supported by the Codex ' +
+        'Responses backend (400 Unsupported parameter: max_output_tokens); ignoring it.',
+    );
+  }
+}
+
+export function toResponsesBody(req: ProviderRequest, opts: BuildBodyOptions = {}): ResponsesBody {
+  const instructions = extractSystemText(req.messages, req.system) || DEFAULT_INSTRUCTIONS;
+  const body: ResponsesBody = {
+    model: req.model,
+    instructions,
+    input: toResponsesInput(req.messages),
+    stream: true,
+    store: false,
+    parallel_tool_calls: true,
+    reasoning: { effort: opts.reasoningEffort ?? 'medium', summary: 'auto' },
+    include: ['reasoning.encrypted_content'],
+  };
+  if (req.tools && req.tools.length > 0) body.tools = toResponsesTools(req.tools);
+  if (opts.sessionHint) body.prompt_cache_key = opts.sessionHint;
+  if (req.maxTokens !== undefined) noteMaxTokensUnsupported();
+  if (req.temperature !== undefined) noteTemperatureUnsupported();
+  return body;
+}