@openclaw/codex 2026.5.1-beta.1

package/src/app-server/auth-bridge.ts

@@ -0,0 +1,345 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  ensureAuthProfileStore,
+  loadAuthProfileStoreForSecretsRuntime,
+  resolveProviderIdForAuth,
+  resolveApiKeyForProfile,
+  resolvePersistedAuthProfileOwnerAgentDir,
+  saveAuthProfileStore,
+  type AuthProfileCredential,
+  type OAuthCredential,
+} from "openclaw/plugin-sdk/agent-runtime";
+import type { CodexAppServerClient } from "./client.js";
+import type { CodexAppServerStartOptions } from "./config.js";
+import type { ChatgptAuthTokensRefreshResponse } from "./protocol-generated/typescript/v2/ChatgptAuthTokensRefreshResponse.js";
+import type { GetAccountResponse } from "./protocol-generated/typescript/v2/GetAccountResponse.js";
+import type { LoginAccountParams } from "./protocol-generated/typescript/v2/LoginAccountParams.js";
+import { resolveCodexAppServerSpawnEnv } from "./transport-stdio.js";
+
+const CODEX_APP_SERVER_AUTH_PROVIDER = "openai-codex";
+const OPENAI_CODEX_DEFAULT_PROFILE_ID = "openai-codex:default";
+const CODEX_HOME_ENV_VAR = "CODEX_HOME";
+const HOME_ENV_VAR = "HOME";
+const CODEX_APP_SERVER_HOME_DIRNAME = "codex-home";
+const CODEX_APP_SERVER_NATIVE_HOME_DIRNAME = "home";
+const CODEX_API_KEY_ENV_VAR = "CODEX_API_KEY";
+const OPENAI_API_KEY_ENV_VAR = "OPENAI_API_KEY";
+const CODEX_APP_SERVER_API_KEY_ENV_VARS = [CODEX_API_KEY_ENV_VAR, OPENAI_API_KEY_ENV_VAR];
+const CODEX_APP_SERVER_ISOLATION_ENV_VARS = [CODEX_HOME_ENV_VAR, HOME_ENV_VAR];
+
+export async function bridgeCodexAppServerStartOptions(params: {
+  startOptions: CodexAppServerStartOptions;
+  agentDir: string;
+  authProfileId?: string;
+}): Promise<CodexAppServerStartOptions> {
+  if (params.startOptions.transport !== "stdio") {
+    return params.startOptions;
+  }
+  const isolatedStartOptions = await withAgentCodexHomeEnvironment(
+    params.startOptions,
+    params.agentDir,
+  );
+  const store = ensureAuthProfileStore(params.agentDir, { allowKeychainPrompt: false });
+  const shouldClearInheritedOpenAiApiKey = shouldClearOpenAiApiKeyForCodexAuthProfile({
+    store,
+    authProfileId: params.authProfileId,
+  });
+  return shouldClearInheritedOpenAiApiKey
+    ? withClearedEnvironmentVariables(isolatedStartOptions, CODEX_APP_SERVER_API_KEY_ENV_VARS)
+    : isolatedStartOptions;
+}
+
+export function resolveCodexAppServerHomeDir(agentDir: string): string {
+  return path.join(path.resolve(agentDir), CODEX_APP_SERVER_HOME_DIRNAME);
+}
+
+export function resolveCodexAppServerNativeHomeDir(agentDir: string): string {
+  return path.join(resolveCodexAppServerHomeDir(agentDir), CODEX_APP_SERVER_NATIVE_HOME_DIRNAME);
+}
+
+async function withAgentCodexHomeEnvironment(
+  startOptions: CodexAppServerStartOptions,
+  agentDir: string,
+): Promise<CodexAppServerStartOptions> {
+  const codexHome = startOptions.env?.[CODEX_HOME_ENV_VAR]?.trim()
+    ? startOptions.env[CODEX_HOME_ENV_VAR]
+    : resolveCodexAppServerHomeDir(agentDir);
+  const nativeHome = startOptions.env?.[HOME_ENV_VAR]?.trim()
+    ? startOptions.env[HOME_ENV_VAR]
+    : path.join(codexHome, CODEX_APP_SERVER_NATIVE_HOME_DIRNAME);
+  await fs.mkdir(codexHome, { recursive: true });
+  await fs.mkdir(nativeHome, { recursive: true });
+  const nextStartOptions: CodexAppServerStartOptions = {
+    ...startOptions,
+    env: {
+      ...startOptions.env,
+      [CODEX_HOME_ENV_VAR]: codexHome,
+      [HOME_ENV_VAR]: nativeHome,
+    },
+  };
+  const clearEnv = withoutClearedCodexIsolationEnv(startOptions.clearEnv);
+  if (clearEnv) {
+    nextStartOptions.clearEnv = clearEnv;
+  } else {
+    delete nextStartOptions.clearEnv;
+  }
+  return nextStartOptions;
+}
+
+function withoutClearedCodexIsolationEnv(clearEnv: string[] | undefined): string[] | undefined {
+  if (!clearEnv) {
+    return undefined;
+  }
+  const reserved = new Set(CODEX_APP_SERVER_ISOLATION_ENV_VARS);
+  const filtered = clearEnv.filter((envVar) => !reserved.has(envVar.trim().toUpperCase()));
+  return filtered.length === clearEnv.length ? clearEnv : filtered;
+}
+
+export async function applyCodexAppServerAuthProfile(params: {
+  client: CodexAppServerClient;
+  agentDir: string;
+  authProfileId?: string;
+  startOptions?: CodexAppServerStartOptions;
+}): Promise<void> {
+  const loginParams = await resolveCodexAppServerAuthProfileLoginParams({
+    agentDir: params.agentDir,
+    authProfileId: params.authProfileId,
+  });
+  if (!loginParams) {
+    if (params.startOptions?.transport !== "stdio") {
+      return;
+    }
+    const env = resolveCodexAppServerSpawnEnv(params.startOptions, process.env);
+    const fallbackLoginParams = await resolveCodexAppServerEnvApiKeyLoginParams({
+      client: params.client,
+      env,
+    });
+    if (fallbackLoginParams) {
+      await params.client.request("account/login/start", fallbackLoginParams);
+    }
+    return;
+  }
+  await params.client.request("account/login/start", loginParams);
+}
+
+function resolveCodexAppServerAuthProfileLoginParams(params: {
+  agentDir: string;
+  authProfileId?: string;
+}): Promise<LoginAccountParams | undefined> {
+  return resolveCodexAppServerAuthProfileLoginParamsInternal(params);
+}
+
+export async function refreshCodexAppServerAuthTokens(params: {
+  agentDir: string;
+  authProfileId?: string;
+}): Promise<ChatgptAuthTokensRefreshResponse> {
+  const loginParams = await resolveCodexAppServerAuthProfileLoginParamsInternal({
+    ...params,
+    forceOAuthRefresh: true,
+  });
+  if (!loginParams || loginParams.type !== "chatgptAuthTokens") {
+    throw new Error("Codex app-server ChatGPT token refresh requires an OAuth auth profile.");
+  }
+  return {
+    accessToken: loginParams.accessToken,
+    chatgptAccountId: loginParams.chatgptAccountId,
+    chatgptPlanType: loginParams.chatgptPlanType ?? null,
+  };
+}
+
+async function resolveCodexAppServerAuthProfileLoginParamsInternal(params: {
+  agentDir: string;
+  authProfileId?: string;
+  forceOAuthRefresh?: boolean;
+}): Promise<LoginAccountParams | undefined> {
+  const profileId = params.authProfileId?.trim();
+  if (!profileId) {
+    return undefined;
+  }
+  const store = ensureAuthProfileStore(params.agentDir, { allowKeychainPrompt: false });
+  const credential = store.profiles[profileId];
+  if (!credential) {
+    throw new Error(`Codex app-server auth profile "${profileId}" was not found.`);
+  }
+  if (!isCodexAppServerAuthProvider(credential.provider)) {
+    throw new Error(
+      `Codex app-server auth profile "${profileId}" must belong to provider "openai-codex" or a supported alias.`,
+    );
+  }
+  const loginParams = await resolveLoginParamsForCredential(profileId, credential, {
+    agentDir: params.agentDir,
+    forceOAuthRefresh: params.forceOAuthRefresh === true,
+  });
+  if (!loginParams) {
+    throw new Error(
+      `Codex app-server auth profile "${profileId}" does not contain usable credentials.`,
+    );
+  }
+  return loginParams;
+}
+
+async function resolveCodexAppServerEnvApiKeyLoginParams(params: {
+  client: CodexAppServerClient;
+  env: NodeJS.ProcessEnv;
+}): Promise<LoginAccountParams | undefined> {
+  const apiKey = readFirstNonEmptyEnv(params.env, CODEX_APP_SERVER_API_KEY_ENV_VARS);
+  if (!apiKey) {
+    return undefined;
+  }
+  const response = await params.client.request<GetAccountResponse>("account/read", {
+    refreshToken: false,
+  });
+  if (response.account || !response.requiresOpenaiAuth) {
+    return undefined;
+  }
+  return { type: "apiKey", apiKey };
+}
+
+async function resolveLoginParamsForCredential(
+  profileId: string,
+  credential: AuthProfileCredential,
+  params: { agentDir: string; forceOAuthRefresh: boolean },
+): Promise<LoginAccountParams | undefined> {
+  if (credential.type === "api_key") {
+    const resolved = await resolveApiKeyForProfile({
+      store: ensureAuthProfileStore(params.agentDir, { allowKeychainPrompt: false }),
+      profileId,
+      agentDir: params.agentDir,
+    });
+    const apiKey = resolved?.apiKey?.trim();
+    return apiKey ? { type: "apiKey", apiKey } : undefined;
+  }
+  if (credential.type === "token") {
+    const resolved = await resolveApiKeyForProfile({
+      store: ensureAuthProfileStore(params.agentDir, { allowKeychainPrompt: false }),
+      profileId,
+      agentDir: params.agentDir,
+    });
+    const accessToken = resolved?.apiKey?.trim();
+    return accessToken
+      ? buildChatgptAuthTokensParams(profileId, credential, accessToken)
+      : undefined;
+  }
+  const resolvedCredential = await resolveOAuthCredentialForCodexAppServer(profileId, credential, {
+    agentDir: params.agentDir,
+    forceRefresh: params.forceOAuthRefresh,
+  });
+  const accessToken = resolvedCredential.access?.trim();
+  return accessToken
+    ? buildChatgptAuthTokensParams(profileId, resolvedCredential, accessToken)
+    : undefined;
+}
+
+async function resolveOAuthCredentialForCodexAppServer(
+  profileId: string,
+  credential: OAuthCredential,
+  params: { agentDir: string; forceRefresh: boolean },
+): Promise<OAuthCredential> {
+  const ownerAgentDir = resolvePersistedAuthProfileOwnerAgentDir({
+    agentDir: params.agentDir,
+    profileId,
+  });
+  const store = ensureAuthProfileStore(ownerAgentDir, { allowKeychainPrompt: false });
+  const ownerCredential = store.profiles[profileId];
+  const credentialForOwner =
+    ownerCredential?.type === "oauth" && isCodexAppServerAuthProvider(ownerCredential.provider)
+      ? ownerCredential
+      : credential;
+  if (params.forceRefresh) {
+    store.profiles[profileId] = { ...credentialForOwner, expires: 0 };
+    saveAuthProfileStore(store, ownerAgentDir);
+  }
+  const resolved = await resolveApiKeyForProfile({
+    store,
+    profileId,
+    agentDir: ownerAgentDir,
+  });
+  const refreshed = loadAuthProfileStoreForSecretsRuntime(ownerAgentDir).profiles[profileId];
+  const storedCredential = store.profiles[profileId];
+  const candidate =
+    refreshed?.type === "oauth" && isCodexAppServerAuthProvider(refreshed.provider)
+      ? refreshed
+      : storedCredential?.type === "oauth" &&
+          isCodexAppServerAuthProvider(storedCredential.provider)
+        ? storedCredential
+        : credential;
+  return resolved?.apiKey ? { ...candidate, access: resolved.apiKey } : candidate;
+}
+
+function isCodexAppServerAuthProvider(provider: string): boolean {
+  return resolveProviderIdForAuth(provider) === CODEX_APP_SERVER_AUTH_PROVIDER;
+}
+
+function shouldClearOpenAiApiKeyForCodexAuthProfile(params: {
+  store: ReturnType<typeof ensureAuthProfileStore>;
+  authProfileId?: string;
+}): boolean {
+  const profileId = params.authProfileId?.trim();
+  const credential = profileId
+    ? params.store.profiles[profileId]
+    : params.store.profiles[OPENAI_CODEX_DEFAULT_PROFILE_ID];
+  return isCodexSubscriptionCredential(credential);
+}
+
+function isCodexSubscriptionCredential(credential: AuthProfileCredential | undefined): boolean {
+  if (!credential || !isCodexAppServerAuthProvider(credential.provider)) {
+    return false;
+  }
+  return credential.type === "oauth" || credential.type === "token";
+}
+
+function withClearedEnvironmentVariables(
+  startOptions: CodexAppServerStartOptions,
+  envVars: readonly string[],
+): CodexAppServerStartOptions {
+  const clearEnv = startOptions.clearEnv ?? [];
+  const missingEnvVars = envVars.filter((envVar) => !clearEnv.includes(envVar));
+  if (missingEnvVars.length === 0) {
+    return startOptions;
+  }
+  return {
+    ...startOptions,
+    clearEnv: [...clearEnv, ...missingEnvVars],
+  };
+}
+
+function readFirstNonEmptyEnv(env: NodeJS.ProcessEnv, keys: readonly string[]): string | undefined {
+  for (const key of keys) {
+    const value = env[key]?.trim();
+    if (value) {
+      return value;
+    }
+  }
+  return undefined;
+}
+
+function buildChatgptAuthTokensParams(
+  profileId: string,
+  credential: AuthProfileCredential,
+  accessToken: string,
+): LoginAccountParams {
+  return {
+    type: "chatgptAuthTokens",
+    accessToken,
+    chatgptAccountId: resolveChatgptAccountId(profileId, credential),
+    chatgptPlanType: resolveChatgptPlanType(credential),
+  };
+}
+
+function resolveChatgptPlanType(credential: AuthProfileCredential): string | null {
+  const record = credential as Record<string, unknown>;
+  const planType = record.chatgptPlanType ?? record.planType;
+  return typeof planType === "string" && planType.trim() ? planType.trim() : null;
+}
+
+function resolveChatgptAccountId(profileId: string, credential: AuthProfileCredential): string {
+  if ("accountId" in credential && typeof credential.accountId === "string") {
+    const accountId = credential.accountId.trim();
+    if (accountId) {
+      return accountId;
+    }
+  }
+  const email = credential.email?.trim();
+  return email || profileId;
+}

package/src/app-server/auth-profile-runtime-contract.test.ts

@@ -0,0 +1,217 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import {
+  abortAgentHarnessRun,
+  type EmbeddedRunAttemptParams,
+} from "openclaw/plugin-sdk/agent-harness";
+import { AUTH_PROFILE_RUNTIME_CONTRACT } from "openclaw/plugin-sdk/agent-runtime-test-contracts";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { runCodexAppServerAttempt, __testing } from "./run-attempt.js";
+import { readCodexAppServerBinding, writeCodexAppServerBinding } from "./session-binding.js";
+import { createCodexTestModel } from "./test-support.js";
+
+function createParams(sessionFile: string, workspaceDir: string): EmbeddedRunAttemptParams {
+  return {
+    prompt: AUTH_PROFILE_RUNTIME_CONTRACT.workspacePrompt,
+    sessionId: AUTH_PROFILE_RUNTIME_CONTRACT.sessionId,
+    sessionKey: AUTH_PROFILE_RUNTIME_CONTRACT.sessionKey,
+    sessionFile,
+    workspaceDir,
+    runId: AUTH_PROFILE_RUNTIME_CONTRACT.runId,
+    provider: AUTH_PROFILE_RUNTIME_CONTRACT.codexHarnessProvider,
+    modelId: "gpt-5.4-codex",
+    model: createCodexTestModel(AUTH_PROFILE_RUNTIME_CONTRACT.codexHarnessProvider),
+    thinkLevel: "medium",
+    disableTools: true,
+    timeoutMs: 5_000,
+    authStorage: {} as never,
+    modelRegistry: {} as never,
+  } as EmbeddedRunAttemptParams;
+}
+
+function threadStartResult(threadId = "thread-auth-contract") {
+  return {
+    thread: {
+      id: threadId,
+      forkedFromId: null,
+      preview: "",
+      ephemeral: false,
+      modelProvider: "openai",
+      createdAt: 1,
+      updatedAt: 1,
+      status: { type: "idle" },
+      path: null,
+      cwd: "",
+      cliVersion: "0.125.0",
+      source: "unknown",
+      agentNickname: null,
+      agentRole: null,
+      gitInfo: null,
+      name: null,
+      turns: [],
+    },
+    model: "gpt-5.4-codex",
+    modelProvider: "openai",
+    serviceTier: null,
+    cwd: "",
+    instructionSources: [],
+    approvalPolicy: "never",
+    approvalsReviewer: "user",
+    sandbox: { type: "dangerFullAccess" },
+    permissionProfile: null,
+    reasoningEffort: null,
+  };
+}
+
+function turnStartResult(turnId = "turn-auth-contract") {
+  return {
+    turn: {
+      id: turnId,
+      status: "inProgress",
+      items: [],
+      error: null,
+      startedAt: null,
+      completedAt: null,
+      durationMs: null,
+    },
+  };
+}
+
+function createCodexAuthProfileHarness(params: { startMethod: "thread/start" | "thread/resume" }) {
+  const seenAuthProfileIds: Array<string | undefined> = [];
+  const seenAgentDirs: Array<string | undefined> = [];
+  const requests: Array<{ method: string; params: unknown }> = [];
+  let notify: (notification: unknown) => Promise<void> = async () => undefined;
+  __testing.setCodexAppServerClientFactoryForTests(
+    async (_startOptions, authProfileId, agentDir) => {
+      seenAuthProfileIds.push(authProfileId);
+      seenAgentDirs.push(agentDir);
+      return {
+        request: vi.fn(async (method: string, requestParams?: unknown) => {
+          requests.push({ method, params: requestParams });
+          if (method === params.startMethod) {
+            return threadStartResult();
+          }
+          if (method === "turn/start") {
+            return turnStartResult();
+          }
+          throw new Error(`unexpected method: ${method}`);
+        }),
+        addNotificationHandler: (handler: (notification: unknown) => Promise<void>) => {
+          notify = handler;
+          return () => undefined;
+        },
+        addRequestHandler: () => () => undefined,
+      } as never;
+    },
+  );
+  return {
+    seenAuthProfileIds,
+    seenAgentDirs,
+    async waitForMethod(method: string) {
+      await vi.waitFor(() => expect(requests.some((entry) => entry.method === method)).toBe(true), {
+        interval: 1,
+      });
+    },
+    async completeTurn() {
+      await notify({
+        method: "turn/completed",
+        params: {
+          threadId: "thread-auth-contract",
+          turnId: "turn-auth-contract",
+          turn: { id: "turn-auth-contract", status: "completed" },
+        },
+      });
+    },
+  };
+}
+
+describe("Auth profile runtime contract - Codex app-server adapter", () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-auth-contract-"));
+  });
+
+  afterEach(async () => {
+    abortAgentHarnessRun(AUTH_PROFILE_RUNTIME_CONTRACT.sessionId);
+    __testing.resetCodexAppServerClientFactoryForTests();
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("passes the exact OpenAI Codex auth profile into app-server startup", async () => {
+    const harness = createCodexAuthProfileHarness({ startMethod: "thread/start" });
+    const sessionFile = path.join(tmpDir, "session.jsonl");
+    const params = createParams(sessionFile, tmpDir);
+    params.authProfileId = AUTH_PROFILE_RUNTIME_CONTRACT.openAiCodexProfileId;
+    params.agentDir = tmpDir;
+
+    const run = runCodexAppServerAttempt(params);
+    await vi.waitFor(
+      () =>
+        expect(harness.seenAuthProfileIds).toEqual([
+          AUTH_PROFILE_RUNTIME_CONTRACT.openAiCodexProfileId,
+        ]),
+      { interval: 1 },
+    );
+    expect(harness.seenAgentDirs).toEqual([tmpDir]);
+    await harness.waitForMethod("turn/start");
+    await harness.completeTurn();
+    await run;
+  });
+
+  it("reuses a bound OpenAI Codex auth profile when resume params omit authProfileId", async () => {
+    const harness = createCodexAuthProfileHarness({ startMethod: "thread/resume" });
+    const sessionFile = path.join(tmpDir, "session.jsonl");
+    await writeCodexAppServerBinding(sessionFile, {
+      threadId: "thread-auth-contract",
+      cwd: tmpDir,
+      authProfileId: AUTH_PROFILE_RUNTIME_CONTRACT.openAiCodexProfileId,
+      dynamicToolsFingerprint: "[]",
+    });
+    // authProfileId is intentionally omitted to exercise the resume-bound profile path.
+    const params = createParams(sessionFile, tmpDir);
+
+    const run = runCodexAppServerAttempt(params);
+    await vi.waitFor(
+      () =>
+        expect(harness.seenAuthProfileIds).toEqual([
+          AUTH_PROFILE_RUNTIME_CONTRACT.openAiCodexProfileId,
+        ]),
+      { interval: 1 },
+    );
+    await harness.waitForMethod("turn/start");
+    await harness.completeTurn();
+    await run;
+  });
+
+  it("prefers an explicit runtime auth profile over a stale persisted binding", async () => {
+    const harness = createCodexAuthProfileHarness({ startMethod: "thread/resume" });
+    const sessionFile = path.join(tmpDir, "session.jsonl");
+    await writeCodexAppServerBinding(sessionFile, {
+      threadId: "thread-auth-contract",
+      cwd: tmpDir,
+      authProfileId: "openai-codex:stale",
+      dynamicToolsFingerprint: "[]",
+    });
+    const params = createParams(sessionFile, tmpDir);
+    params.authProfileId = AUTH_PROFILE_RUNTIME_CONTRACT.openAiCodexProfileId;
+
+    const run = runCodexAppServerAttempt(params);
+    await vi.waitFor(
+      () =>
+        expect(harness.seenAuthProfileIds).toEqual([
+          AUTH_PROFILE_RUNTIME_CONTRACT.openAiCodexProfileId,
+        ]),
+      { interval: 1 },
+    );
+    await harness.waitForMethod("turn/start");
+    await harness.completeTurn();
+    await run;
+
+    await expect(readCodexAppServerBinding(sessionFile)).resolves.toMatchObject({
+      authProfileId: AUTH_PROFILE_RUNTIME_CONTRACT.openAiCodexProfileId,
+    });
+  });
+});

package/src/app-server/capabilities.ts

@@ -0,0 +1,27 @@
+import { CodexAppServerRpcError } from "./client.js";
+
+export const CODEX_CONTROL_METHODS = {
+  account: "account/read",
+  compact: "thread/compact/start",
+  feedback: "feedback/upload",
+  listMcpServers: "mcpServerStatus/list",
+  listSkills: "skills/list",
+  listThreads: "thread/list",
+  rateLimits: "account/rateLimits/read",
+  resumeThread: "thread/resume",
+  review: "review/start",
+} as const;
+
+type CodexControlName = keyof typeof CODEX_CONTROL_METHODS;
+export type CodexControlMethod = (typeof CODEX_CONTROL_METHODS)[CodexControlName];
+
+export function describeControlFailure(error: unknown): string {
+  if (isUnsupportedControlError(error)) {
+    return "unsupported by this Codex app-server";
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+
+function isUnsupportedControlError(error: unknown): error is CodexAppServerRpcError {
+  return error instanceof CodexAppServerRpcError && error.code === -32601;
+}

package/src/app-server/client-factory.ts

@@ -0,0 +1,30 @@
+import type { CodexAppServerClient } from "./client.js";
+import type { CodexAppServerStartOptions } from "./config.js";
+
+export type CodexAppServerClientFactory = (
+  startOptions?: CodexAppServerStartOptions,
+  authProfileId?: string,
+  agentDir?: string,
+) => Promise<CodexAppServerClient>;
+
+export const defaultCodexAppServerClientFactory: CodexAppServerClientFactory = (
+  startOptions,
+  authProfileId,
+  agentDir,
+) =>
+  import("./shared-client.js").then(({ getSharedCodexAppServerClient }) =>
+    getSharedCodexAppServerClient({ startOptions, authProfileId, agentDir }),
+  );
+
+export function createCodexAppServerClientFactoryTestHooks(
+  setFactory: (factory: CodexAppServerClientFactory) => void,
+) {
+  return {
+    setCodexAppServerClientFactoryForTests(factory: CodexAppServerClientFactory): void {
+      setFactory(factory);
+    },
+    resetCodexAppServerClientFactoryForTests(): void {
+      setFactory(defaultCodexAppServerClientFactory);
+    },
+  } as const;
+}