feat(codex-local): add fast mode support

packages/adapters/codex-local/src/server/codex-args.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import { buildCodexExecArgs } from "./codex-args.js";
+
+describe("buildCodexExecArgs", () => {
+  it("enables Codex fast mode overrides for GPT-5.4", () => {
+    const result = buildCodexExecArgs({
+      model: "gpt-5.4",
+      search: true,
+      fastMode: true,
+    });
+
+    expect(result.fastModeRequested).toBe(true);
+    expect(result.fastModeApplied).toBe(true);
+    expect(result.fastModeIgnoredReason).toBeNull();
+    expect(result.args).toEqual([
+      "--search",
+      "exec",
+      "--json",
+      "--model",
+      "gpt-5.4",
+      "-c",
+      'service_tier="fast"',
+      "-c",
+      "features.fast_mode=true",
+      "-",
+    ]);
+  });
+
+  it("ignores fast mode for unsupported models", () => {
+    const result = buildCodexExecArgs({
+      model: "gpt-5.3-codex",
+      fastMode: true,
+    });
+
+    expect(result.fastModeRequested).toBe(true);
+    expect(result.fastModeApplied).toBe(false);
+    expect(result.fastModeIgnoredReason).toContain("currently only supported on gpt-5.4");
+    expect(result.args).toEqual([
+      "exec",
+      "--json",
+      "--model",
+      "gpt-5.3-codex",
+      "-",
+    ]);
+  });
+});

packages/adapters/codex-local/src/server/codex-args.ts

@@ -0,0 +1,74 @@
+import { asBoolean, asString, asStringArray } from "@paperclipai/adapter-utils/server-utils";
+import {
+  CODEX_LOCAL_FAST_MODE_SUPPORTED_MODELS,
+  isCodexLocalFastModeSupported,
+} from "../index.js";
+
+export type BuildCodexExecArgsResult = {
+  args: string[];
+  model: string;
+  fastModeRequested: boolean;
+  fastModeApplied: boolean;
+  fastModeIgnoredReason: string | null;
+};
+
+function readExtraArgs(config: unknown): string[] {
+  const fromExtraArgs = asStringArray(asRecord(config).extraArgs);
+  if (fromExtraArgs.length > 0) return fromExtraArgs;
+  return asStringArray(asRecord(config).args);
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function formatFastModeSupportedModels(): string {
+  return CODEX_LOCAL_FAST_MODE_SUPPORTED_MODELS.join(", ");
+}
+
+export function buildCodexExecArgs(
+  config: unknown,
+  options: { resumeSessionId?: string | null } = {},
+): BuildCodexExecArgsResult {
+  const record = asRecord(config);
+  const model = asString(record.model, "").trim();
+  const modelReasoningEffort = asString(
+    record.modelReasoningEffort,
+    asString(record.reasoningEffort, ""),
+  ).trim();
+  const search = asBoolean(record.search, false);
+  const fastModeRequested = asBoolean(record.fastMode, false);
+  const fastModeApplied = fastModeRequested && isCodexLocalFastModeSupported(model);
+  const bypass = asBoolean(
+    record.dangerouslyBypassApprovalsAndSandbox,
+    asBoolean(record.dangerouslyBypassSandbox, false),
+  );
+  const extraArgs = readExtraArgs(record);
+
+  const args = ["exec", "--json"];
+  if (search) args.unshift("--search");
+  if (bypass) args.push("--dangerously-bypass-approvals-and-sandbox");
+  if (model) args.push("--model", model);
+  if (modelReasoningEffort) {
+    args.push("-c", `model_reasoning_effort=${JSON.stringify(modelReasoningEffort)}`);
+  }
+  if (fastModeApplied) {
+    args.push("-c", 'service_tier="fast"', "-c", "features.fast_mode=true");
+  }
+  if (extraArgs.length > 0) args.push(...extraArgs);
+  if (options.resumeSessionId) args.push("resume", options.resumeSessionId, "-");
+  else args.push("-");
+
+  return {
+    args,
+    model,
+    fastModeRequested,
+    fastModeApplied,
+    fastModeIgnoredReason:
+      fastModeRequested && !fastModeApplied
+        ? `Configured fast mode is currently only supported on ${formatFastModeSupportedModels()}; Paperclip will ignore it for model ${model || "(default)"}.`
+        : null,
+  };
+}

packages/adapters/codex-local/src/server/execute.ts

@@ -5,8 +5,6 @@ import { inferOpenAiCompatibleBiller, type AdapterExecutionContext, type Adapter
 import {
   asString,
   asNumber,
-  asBoolean,
-  asStringArray,
   parseObject,
   buildPaperclipEnv,
   buildInvocationEnvForLogs,
@@ -26,6 +24,7 @@ import {
 import { parseCodexJsonl, isCodexUnknownSessionError } from "./parse.js";
 import { pathExists, prepareManagedCodexHome, resolveManagedCodexHomeDir, resolveSharedCodexHomeDir } from "./codex-home.js";
 import { resolveCodexDesiredSkillNames } from "./skills.js";
+import { buildCodexExecArgs } from "./codex-args.js";
 
 const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
 const CODEX_ROLLOUT_NOISE_RE =
@@ -223,15 +222,6 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   );
   const command = asString(config.command, "codex");
   const model = asString(config.model, "");
-  const modelReasoningEffort = asString(
-    config.modelReasoningEffort,
-    asString(config.reasoningEffort, ""),
-  );
-  const search = asBoolean(config.search, false);
-  const bypass = asBoolean(
-    config.dangerouslyBypassApprovalsAndSandbox,
-    asBoolean(config.dangerouslyBypassSandbox, false),
-  );
 
   const workspaceContext = parseObject(context.paperclipWorkspace);
   const workspaceCwd = asString(workspaceContext.cwd, "");
@@ -399,11 +389,6 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
 
   const timeoutSec = asNumber(config.timeoutSec, 0);
   const graceSec = asNumber(config.graceSec, 20);
-  const extraArgs = (() => {
-    const fromExtraArgs = asStringArray(config.extraArgs);
-    if (fromExtraArgs.length > 0) return fromExtraArgs;
-    return asStringArray(config.args);
-  })();
 
   const runtimeSessionParams = parseObject(runtime.sessionParams);
   const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");
@@ -499,26 +484,19 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     heartbeatPromptChars: renderedPrompt.length,
   };
 
-  const buildArgs = (resumeSessionId: string | null) => {
-    const args = ["exec", "--json"];
-    if (search) args.unshift("--search");
-    if (bypass) args.push("--dangerously-bypass-approvals-and-sandbox");
-    if (model) args.push("--model", model);
-    if (modelReasoningEffort) args.push("-c", `model_reasoning_effort=${JSON.stringify(modelReasoningEffort)}`);
-    if (extraArgs.length > 0) args.push(...extraArgs);
-    if (resumeSessionId) args.push("resume", resumeSessionId, "-");
-    else args.push("-");
-    return args;
-  };
-
   const runAttempt = async (resumeSessionId: string | null) => {
-    const args = buildArgs(resumeSessionId);
+    const execArgs = buildCodexExecArgs(config, { resumeSessionId });
+    const args = execArgs.args;
+    const commandNotesWithFastMode =
+      execArgs.fastModeIgnoredReason == null
+        ? commandNotes
+        : [...commandNotes, execArgs.fastModeIgnoredReason];
     if (onMeta) {
       await onMeta({
         adapterType: "codex_local",
         command: resolvedCommand,
         cwd,
-        commandNotes,
+        commandNotes: commandNotesWithFastMode,
         commandArgs: args.map((value, idx) => {
           if (idx === args.length - 1 && value !== "-") return `<prompt ${prompt.length} chars>`;
           return value;

packages/adapters/codex-local/src/server/test.ts

@@ -5,8 +5,6 @@ import type {
 } from "@paperclipai/adapter-utils";
 import {
   asString,
-  asBoolean,
-  asStringArray,
   parseObject,
   ensureAbsoluteDirectory,
   ensureCommandResolvable,
@@ -16,6 +14,7 @@ import {
 import path from "node:path";
 import { parseCodexJsonl } from "./parse.js";
 import { codexHomeDir, readCodexAuthInfo } from "./quota.js";
+import { buildCodexExecArgs } from "./codex-args.js";
 
 function summarizeStatus(checks: AdapterEnvironmentCheck[]): AdapterEnvironmentTestResult["status"] {
   if (checks.some((check) => check.level === "error")) return "fail";
@@ -140,31 +139,16 @@ export async function testEnvironment(
         hint: "Use the `codex` CLI command to run the automatic login and installation probe.",
       });
     } else {
-      const model = asString(config.model, "").trim();
-      const modelReasoningEffort = asString(
-        config.modelReasoningEffort,
-        asString(config.reasoningEffort, ""),
-      ).trim();
-      const search = asBoolean(config.search, false);
-      const bypass = asBoolean(
-        config.dangerouslyBypassApprovalsAndSandbox,
-        asBoolean(config.dangerouslyBypassSandbox, false),
-      );
-      const extraArgs = (() => {
-        const fromExtraArgs = asStringArray(config.extraArgs);
-        if (fromExtraArgs.length > 0) return fromExtraArgs;
-        return asStringArray(config.args);
-      })();
-
-      const args = ["exec", "--json"];
-      if (search) args.unshift("--search");
-      if (bypass) args.push("--dangerously-bypass-approvals-and-sandbox");
-      if (model) args.push("--model", model);
-      if (modelReasoningEffort) {
-        args.push("-c", `model_reasoning_effort=${JSON.stringify(modelReasoningEffort)}`);
+      const execArgs = buildCodexExecArgs(config);
+      const args = execArgs.args;
+      if (execArgs.fastModeIgnoredReason) {
+        checks.push({
+          code: "codex_fast_mode_unsupported_model",
+          level: "warn",
+          message: execArgs.fastModeIgnoredReason,
+          hint: "Switch the agent model to GPT-5.4 to enable Codex Fast mode.",
+        });
       }
-      if (extraArgs.length > 0) args.push(...extraArgs);
-      args.push("-");
 
       const probe = await runChildProcess(
         `codex-envtest-${Date.now()}-${Math.random().toString(16).slice(2)}`,