@full-self-developing/fsd 1.0.0

package/extensions/codex/src/conversation-binding.ts

@@ -0,0 +1,575 @@
+import { formatErrorMessage } from "openclaw/plugin-sdk/agent-harness-runtime";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
+import type {
+  PluginConversationBindingResolvedEvent,
+  PluginHookInboundClaimContext,
+  PluginHookInboundClaimEvent,
+} from "openclaw/plugin-sdk/plugin-entry";
+import type { ReplyPayload } from "openclaw/plugin-sdk/reply-payload";
+import { resolveCodexAppServerAuthProfileIdForAgent } from "./app-server/auth-bridge.js";
+import { CODEX_CONTROL_METHODS } from "./app-server/capabilities.js";
+import {
+  codexSandboxPolicyForTurn,
+  resolveCodexAppServerRuntimeOptions,
+  type CodexAppServerApprovalPolicy,
+  type CodexAppServerSandboxMode,
+} from "./app-server/config.js";
+import {
+  type CodexServiceTier,
+  type CodexThreadResumeResponse,
+  type CodexThreadStartResponse,
+  type CodexTurnStartResponse,
+  type JsonValue,
+} from "./app-server/protocol.js";
+import { resolveCodexNativeSandboxBlock } from "./app-server/sandbox-guard.js";
+import {
+  clearCodexAppServerBinding,
+  isCodexAppServerNativeAuthProfile,
+  normalizeCodexAppServerBindingModelProvider,
+  readCodexAppServerBinding,
+  writeCodexAppServerBinding,
+  type CodexAppServerAuthProfileLookup,
+} from "./app-server/session-binding.js";
+import { getSharedCodexAppServerClient } from "./app-server/shared-client.js";
+import { formatCodexDisplayText } from "./command-formatters.js";
+import {
+  createCodexConversationBindingData,
+  readCodexConversationBindingData,
+  readCodexConversationBindingDataRecord,
+  resolveCodexDefaultWorkspaceDir,
+  type CodexAppServerConversationBindingData,
+} from "./conversation-binding-data.js";
+import { trackCodexConversationActiveTurn } from "./conversation-control.js";
+import { createCodexConversationTurnCollector } from "./conversation-turn-collector.js";
+import { buildCodexConversationTurnInput } from "./conversation-turn-input.js";
+import { resumeCodexCliSessionOnNode } from "./node-cli-sessions.js";
+
+const DEFAULT_BOUND_TURN_TIMEOUT_MS = 20 * 60_000;
+
+export {
+  createCodexCliNodeConversationBindingData,
+  readCodexConversationBindingData,
+  resolveCodexDefaultWorkspaceDir,
+} from "./conversation-binding-data.js";
+
+type CodexConversationRunOptions = {
+  pluginConfig?: unknown;
+  config?: OpenClawConfig;
+  timeoutMs?: number;
+  resumeCodexCliSessionOnNode?: ResumeCodexCliSessionOnNodeFn;
+};
+
+type ResumeCodexCliSessionOnNodeFn = (
+  params: Omit<Parameters<typeof resumeCodexCliSessionOnNode>[0], "runtime">,
+) => ReturnType<typeof resumeCodexCliSessionOnNode>;
+
+type CodexConversationStartParams = {
+  pluginConfig?: unknown;
+  config?: Parameters<typeof resolveCodexAppServerAuthProfileIdForAgent>[0]["config"];
+  sessionFile: string;
+  workspaceDir?: string;
+  agentDir?: string;
+  threadId?: string;
+  model?: string;
+  modelProvider?: string;
+  authProfileId?: string;
+  approvalPolicy?: CodexAppServerApprovalPolicy;
+  sandbox?: CodexAppServerSandboxMode;
+  serviceTier?: CodexServiceTier;
+};
+
+type BoundTurnResult = {
+  reply: ReplyPayload;
+};
+
+type CodexConversationGlobalState = {
+  queues: Map<string, Promise<void>>;
+};
+
+const CODEX_CONVERSATION_GLOBAL_STATE = Symbol.for("openclaw.codex.conversationBinding");
+
+function getGlobalState(): CodexConversationGlobalState {
+  const globalState = globalThis as typeof globalThis & {
+    [CODEX_CONVERSATION_GLOBAL_STATE]?: CodexConversationGlobalState;
+  };
+  globalState[CODEX_CONVERSATION_GLOBAL_STATE] ??= { queues: new Map() };
+  return globalState[CODEX_CONVERSATION_GLOBAL_STATE];
+}
+
+export async function startCodexConversationThread(
+  params: CodexConversationStartParams,
+): Promise<CodexAppServerConversationBindingData> {
+  const workspaceDir =
+    params.workspaceDir?.trim() || resolveCodexDefaultWorkspaceDir(params.pluginConfig);
+  const agentDir = params.agentDir?.trim();
+  const agentLookup = buildAgentLookup({ agentDir, config: params.config });
+  const existingBinding = await readCodexAppServerBinding(params.sessionFile, {
+    ...agentLookup,
+  });
+  const authProfileId = resolveCodexAppServerAuthProfileIdForAgent({
+    authProfileId: params.authProfileId ?? existingBinding?.authProfileId,
+    ...agentLookup,
+  });
+  if (params.threadId?.trim()) {
+    await attachExistingThread({
+      pluginConfig: params.pluginConfig,
+      sessionFile: params.sessionFile,
+      threadId: params.threadId.trim(),
+      workspaceDir,
+      ...(agentDir ? { agentDir } : {}),
+      model: params.model,
+      modelProvider: params.modelProvider,
+      authProfileId,
+      approvalPolicy: params.approvalPolicy,
+      sandbox: params.sandbox,
+      serviceTier: params.serviceTier,
+      config: params.config,
+    });
+  } else {
+    await createThread({
+      pluginConfig: params.pluginConfig,
+      sessionFile: params.sessionFile,
+      workspaceDir,
+      ...(agentDir ? { agentDir } : {}),
+      model: params.model,
+      modelProvider: params.modelProvider,
+      authProfileId,
+      approvalPolicy: params.approvalPolicy,
+      sandbox: params.sandbox,
+      serviceTier: params.serviceTier,
+      config: params.config,
+    });
+  }
+  return createCodexConversationBindingData({
+    sessionFile: params.sessionFile,
+    workspaceDir,
+    ...(agentDir ? { agentDir } : {}),
+  });
+}
+
+export async function handleCodexConversationInboundClaim(
+  event: PluginHookInboundClaimEvent,
+  ctx: PluginHookInboundClaimContext,
+  options: CodexConversationRunOptions = {},
+): Promise<{ handled: boolean; reply?: ReplyPayload } | undefined> {
+  const data = readCodexConversationBindingData(ctx.pluginBinding);
+  if (!data) {
+    return undefined;
+  }
+  if (event.commandAuthorized !== true) {
+    return { handled: true };
+  }
+  const prompt = event.bodyForAgent?.trim() || event.content?.trim() || "";
+  if (!prompt) {
+    return { handled: true };
+  }
+  const sandboxBlock = resolveCodexNativeSandboxBlock({
+    config: options.config,
+    sessionKey: event.sessionKey ?? ctx.sessionKey,
+    surface:
+      data.kind === "codex-cli-node-session"
+        ? "Codex CLI node conversation binding"
+        : "Codex app-server conversation binding",
+  });
+  if (sandboxBlock) {
+    return { handled: true, reply: { text: sandboxBlock } };
+  }
+  if (data.kind === "codex-cli-node-session") {
+    const resume = options.resumeCodexCliSessionOnNode;
+    if (!resume) {
+      return {
+        handled: true,
+        reply: {
+          text: "Codex CLI node binding is unavailable because Gateway node runtime is not attached.",
+        },
+      };
+    }
+    try {
+      const result = await enqueueBoundTurn(`${data.nodeId}:${data.sessionId}`, async () => {
+        const resumed = await resume({
+          nodeId: data.nodeId,
+          sessionId: data.sessionId,
+          prompt,
+          cwd: data.cwd,
+          timeoutMs: options.timeoutMs,
+        });
+        return { reply: { text: resumed.text.trim() || "Codex completed without a text reply." } };
+      });
+      return { handled: true, reply: result.reply };
+    } catch (error) {
+      return {
+        handled: true,
+        reply: {
+          text: `Codex CLI node turn failed: ${formatCodexDisplayText(formatErrorMessage(error))}`,
+        },
+      };
+    }
+  }
+  try {
+    const result = await enqueueBoundTurn(data.sessionFile, () =>
+      runBoundTurnWithMissingThreadRecovery({
+        data,
+        prompt,
+        event,
+        pluginConfig: options.pluginConfig,
+        timeoutMs: options.timeoutMs,
+      }),
+    );
+    return { handled: true, reply: result.reply };
+  } catch (error) {
+    return {
+      handled: true,
+      reply: {
+        text: `Codex app-server turn failed: ${formatCodexDisplayText(formatErrorMessage(error))}`,
+      },
+    };
+  }
+}
+
+export async function handleCodexConversationBindingResolved(
+  event: PluginConversationBindingResolvedEvent,
+): Promise<void> {
+  if (event.status !== "denied") {
+    return;
+  }
+  const data = readCodexConversationBindingDataRecord(event.request.data ?? {});
+  if (!data || data.kind !== "codex-app-server-session") {
+    return;
+  }
+  await clearCodexAppServerBinding(data.sessionFile);
+}
+
+async function attachExistingThread(params: {
+  pluginConfig?: unknown;
+  sessionFile: string;
+  threadId: string;
+  workspaceDir: string;
+  agentDir?: string;
+  model?: string;
+  modelProvider?: string;
+  authProfileId?: string;
+  approvalPolicy?: CodexAppServerApprovalPolicy;
+  sandbox?: CodexAppServerSandboxMode;
+  serviceTier?: CodexServiceTier;
+  config?: CodexAppServerAuthProfileLookup["config"];
+}): Promise<void> {
+  const runtime = resolveCodexAppServerRuntimeOptions({
+    pluginConfig: params.pluginConfig,
+  });
+  const agentLookup = buildAgentLookup({ agentDir: params.agentDir, config: params.config });
+  const modelProvider = resolveThreadRequestModelProvider({
+    authProfileId: params.authProfileId,
+    modelProvider: params.modelProvider,
+    ...agentLookup,
+  });
+  const client = await getSharedCodexAppServerClient({
+    startOptions: runtime.start,
+    timeoutMs: runtime.requestTimeoutMs,
+    authProfileId: params.authProfileId,
+    ...agentLookup,
+  });
+  const response: CodexThreadResumeResponse = await client.request(
+    CODEX_CONTROL_METHODS.resumeThread,
+    {
+      threadId: params.threadId,
+      ...(params.model ? { model: params.model } : {}),
+      ...(modelProvider ? { modelProvider } : {}),
+      approvalPolicy: params.approvalPolicy ?? runtime.approvalPolicy,
+      approvalsReviewer: runtime.approvalsReviewer,
+      sandbox: params.sandbox ?? runtime.sandbox,
+      ...((params.serviceTier ?? runtime.serviceTier)
+        ? { serviceTier: params.serviceTier ?? runtime.serviceTier }
+        : {}),
+      persistExtendedHistory: true,
+    },
+    { timeoutMs: runtime.requestTimeoutMs },
+  );
+  const thread = response.thread;
+  const runtimeApprovalPolicy =
+    typeof runtime.approvalPolicy === "string" ? runtime.approvalPolicy : undefined;
+  await writeCodexAppServerBinding(
+    params.sessionFile,
+    {
+      threadId: thread.id,
+      cwd: thread.cwd ?? params.workspaceDir,
+      authProfileId: params.authProfileId,
+      model: response.model ?? params.model,
+      modelProvider: normalizeCodexAppServerBindingModelProvider({
+        authProfileId: params.authProfileId,
+        modelProvider: response.modelProvider ?? params.modelProvider,
+        ...agentLookup,
+      }),
+      approvalPolicy: params.approvalPolicy ?? runtimeApprovalPolicy,
+      sandbox: params.sandbox ?? runtime.sandbox,
+      serviceTier: params.serviceTier ?? runtime.serviceTier,
+    },
+    {
+      ...agentLookup,
+    },
+  );
+}
+
+async function createThread(params: {
+  pluginConfig?: unknown;
+  sessionFile: string;
+  workspaceDir: string;
+  agentDir?: string;
+  model?: string;
+  modelProvider?: string;
+  authProfileId?: string;
+  approvalPolicy?: CodexAppServerApprovalPolicy;
+  sandbox?: CodexAppServerSandboxMode;
+  serviceTier?: CodexServiceTier;
+  config?: CodexAppServerAuthProfileLookup["config"];
+}): Promise<void> {
+  const runtime = resolveCodexAppServerRuntimeOptions({
+    pluginConfig: params.pluginConfig,
+  });
+  const agentLookup = buildAgentLookup({ agentDir: params.agentDir, config: params.config });
+  const modelProvider = resolveThreadRequestModelProvider({
+    authProfileId: params.authProfileId,
+    modelProvider: params.modelProvider,
+    ...agentLookup,
+  });
+  const client = await getSharedCodexAppServerClient({
+    startOptions: runtime.start,
+    timeoutMs: runtime.requestTimeoutMs,
+    authProfileId: params.authProfileId,
+    ...agentLookup,
+  });
+  const response: CodexThreadStartResponse = await client.request(
+    "thread/start",
+    {
+      cwd: params.workspaceDir,
+      ...(params.model ? { model: params.model } : {}),
+      ...(modelProvider ? { modelProvider } : {}),
+      approvalPolicy: params.approvalPolicy ?? runtime.approvalPolicy,
+      approvalsReviewer: runtime.approvalsReviewer,
+      sandbox: params.sandbox ?? runtime.sandbox,
+      ...((params.serviceTier ?? runtime.serviceTier)
+        ? { serviceTier: params.serviceTier ?? runtime.serviceTier }
+        : {}),
+      developerInstructions:
+        "This Codex thread is bound to an OpenClaw conversation. Answer normally; OpenClaw will deliver your final response back to the conversation.",
+      experimentalRawEvents: true,
+      persistExtendedHistory: true,
+    },
+    { timeoutMs: runtime.requestTimeoutMs },
+  );
+  const runtimeApprovalPolicy =
+    typeof runtime.approvalPolicy === "string" ? runtime.approvalPolicy : undefined;
+  await writeCodexAppServerBinding(
+    params.sessionFile,
+    {
+      threadId: response.thread.id,
+      cwd: response.thread.cwd ?? params.workspaceDir,
+      authProfileId: params.authProfileId,
+      model: response.model ?? params.model,
+      modelProvider: normalizeCodexAppServerBindingModelProvider({
+        authProfileId: params.authProfileId,
+        modelProvider: response.modelProvider ?? params.modelProvider,
+        ...agentLookup,
+      }),
+      approvalPolicy: params.approvalPolicy ?? runtimeApprovalPolicy,
+      sandbox: params.sandbox ?? runtime.sandbox,
+      serviceTier: params.serviceTier ?? runtime.serviceTier,
+    },
+    {
+      ...agentLookup,
+    },
+  );
+}
+
+async function runBoundTurn(params: {
+  data: CodexAppServerConversationBindingData;
+  prompt: string;
+  event: PluginHookInboundClaimEvent;
+  pluginConfig?: unknown;
+  timeoutMs?: number;
+}): Promise<BoundTurnResult> {
+  const runtime = resolveCodexAppServerRuntimeOptions({
+    pluginConfig: params.pluginConfig,
+  });
+  const agentLookup = buildAgentLookup({ agentDir: params.data.agentDir });
+  const binding = await readCodexAppServerBinding(params.data.sessionFile, agentLookup);
+  const threadId = binding?.threadId;
+  if (!threadId) {
+    throw new Error("bound Codex conversation has no thread binding");
+  }
+
+  const client = await getSharedCodexAppServerClient({
+    startOptions: runtime.start,
+    timeoutMs: runtime.requestTimeoutMs,
+    authProfileId: binding.authProfileId,
+    ...agentLookup,
+  });
+  const collector = createCodexConversationTurnCollector(threadId);
+  const notificationCleanup = client.addNotificationHandler((notification) =>
+    collector.handleNotification(notification),
+  );
+  const requestCleanup = client.addRequestHandler(
+    async (request): Promise<JsonValue | undefined> => {
+      if (request.method === "item/tool/call") {
+        return {
+          contentItems: [
+            {
+              type: "inputText",
+              text: "OpenClaw native Codex conversation binding does not expose dynamic OpenClaw tools yet.",
+            },
+          ],
+          success: false,
+        };
+      }
+      if (
+        request.method === "item/commandExecution/requestApproval" ||
+        request.method === "item/fileChange/requestApproval"
+      ) {
+        return {
+          decision: "decline",
+          reason:
+            "OpenClaw native Codex conversation binding cannot route interactive approvals yet; use the Codex harness or explicit /acp spawn codex for that workflow.",
+        };
+      }
+      if (request.method === "item/permissions/requestApproval") {
+        return { permissions: {}, scope: "turn" };
+      }
+      if (request.method.includes("requestApproval")) {
+        return {
+          decision: "decline",
+          reason:
+            "OpenClaw native Codex conversation binding cannot route interactive approvals yet; use the Codex harness or explicit /acp spawn codex for that workflow.",
+        };
+      }
+      return undefined;
+    },
+  );
+  try {
+    const response: CodexTurnStartResponse = await client.request(
+      "turn/start",
+      {
+        threadId,
+        input: buildCodexConversationTurnInput({
+          prompt: params.prompt,
+          event: params.event,
+        }),
+        cwd: binding.cwd || params.data.workspaceDir,
+        approvalPolicy: binding.approvalPolicy ?? runtime.approvalPolicy,
+        approvalsReviewer: runtime.approvalsReviewer,
+        sandboxPolicy: codexSandboxPolicyForTurn(
+          binding.sandbox ?? runtime.sandbox,
+          binding.cwd || params.data.workspaceDir,
+        ),
+        ...(binding.model ? { model: binding.model } : {}),
+        ...((binding.serviceTier ?? runtime.serviceTier)
+          ? { serviceTier: binding.serviceTier ?? runtime.serviceTier }
+          : {}),
+      },
+      { timeoutMs: runtime.requestTimeoutMs },
+    );
+    const turnId = response.turn.id;
+    const activeCleanup = trackCodexConversationActiveTurn({
+      sessionFile: params.data.sessionFile,
+      threadId,
+      turnId,
+    });
+    collector.setTurnId(turnId);
+    const completion = await collector
+      .wait({
+        timeoutMs: params.timeoutMs ?? DEFAULT_BOUND_TURN_TIMEOUT_MS,
+      })
+      .finally(activeCleanup);
+    const replyText = completion.replyText.trim();
+    return {
+      reply: {
+        text: replyText || "Codex completed without a text reply.",
+      },
+    };
+  } finally {
+    notificationCleanup();
+    requestCleanup();
+  }
+}
+
+async function runBoundTurnWithMissingThreadRecovery(params: {
+  data: CodexAppServerConversationBindingData;
+  prompt: string;
+  event: PluginHookInboundClaimEvent;
+  pluginConfig?: unknown;
+  timeoutMs?: number;
+}): Promise<BoundTurnResult> {
+  try {
+    return await runBoundTurn(params);
+  } catch (error) {
+    if (!isCodexThreadNotFoundError(error)) {
+      throw error;
+    }
+    const agentLookup = buildAgentLookup({ agentDir: params.data.agentDir });
+    const binding = await readCodexAppServerBinding(params.data.sessionFile, agentLookup);
+    await startCodexConversationThread({
+      pluginConfig: params.pluginConfig,
+      sessionFile: params.data.sessionFile,
+      workspaceDir: binding?.cwd || params.data.workspaceDir,
+      ...agentLookup,
+      model: binding?.model,
+      modelProvider: binding?.modelProvider,
+      authProfileId: binding?.authProfileId,
+      approvalPolicy: binding?.approvalPolicy,
+      sandbox: binding?.sandbox,
+      serviceTier: binding?.serviceTier,
+    });
+    return await runBoundTurn(params);
+  }
+}
+
+function isCodexThreadNotFoundError(error: unknown): boolean {
+  return /\bthread not found:/iu.test(formatErrorMessage(error));
+}
+
+function enqueueBoundTurn<T>(key: string, run: () => Promise<T>): Promise<T> {
+  const state = getGlobalState();
+  const previous = state.queues.get(key) ?? Promise.resolve();
+  const next = previous.then(run, run);
+  const queued = next.then(
+    () => undefined,
+    () => undefined,
+  );
+  state.queues.set(key, queued);
+  void next
+    .finally(() => {
+      if (state.queues.get(key) === queued) {
+        state.queues.delete(key);
+      }
+    })
+    .catch(() => undefined);
+  return next;
+}
+
+function resolveThreadRequestModelProvider(params: {
+  authProfileId?: string;
+  modelProvider?: string;
+  agentDir?: string;
+  config?: CodexAppServerAuthProfileLookup["config"];
+}): string | undefined {
+  const modelProvider = params.modelProvider?.trim();
+  if (!modelProvider || modelProvider.toLowerCase() === "codex") {
+    return undefined;
+  }
+  if (
+    isCodexAppServerNativeAuthProfile(params) &&
+    (modelProvider.toLowerCase() === "openai" || modelProvider.toLowerCase() === "openai-codex")
+  ) {
+    return undefined;
+  }
+  return modelProvider.toLowerCase() === "openai-codex" ? "openai" : modelProvider;
+}
+
+function buildAgentLookup(params: {
+  agentDir?: string;
+  config?: CodexAppServerAuthProfileLookup["config"];
+}): Pick<CodexAppServerAuthProfileLookup, "agentDir" | "config"> {
+  const agentDir = params.agentDir?.trim();
+  return {
+    ...(agentDir ? { agentDir } : {}),
+    ...(params.config ? { config: params.config } : {}),
+  };
+}

package/extensions/codex/src/conversation-control.test.ts

@@ -0,0 +1,126 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { clearRuntimeAuthProfileStoreSnapshots } from "openclaw/plugin-sdk/agent-runtime";
+import { upsertAuthProfile } from "openclaw/plugin-sdk/provider-auth";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  readCodexAppServerBinding,
+  writeCodexAppServerBinding,
+} from "./app-server/session-binding.js";
+import {
+  setCodexConversationFastMode,
+  setCodexConversationModel,
+  setCodexConversationPermissions,
+} from "./conversation-control.js";
+
+let tempDir: string;
+
+const sharedClientMocks = vi.hoisted(() => ({
+  getSharedCodexAppServerClient: vi.fn(),
+}));
+
+vi.mock("./app-server/shared-client.js", () => sharedClientMocks);
+
+describe("codex conversation controls", () => {
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-control-"));
+    vi.stubEnv("OPENCLAW_STATE_DIR", tempDir);
+    sharedClientMocks.getSharedCodexAppServerClient.mockReset();
+  });
+
+  afterEach(async () => {
+    vi.unstubAllEnvs();
+    clearRuntimeAuthProfileStoreSnapshots();
+    await fs.rm(tempDir, { recursive: true, force: true });
+  });
+
+  it("persists fast mode and permissions for later bound turns", async () => {
+    const sessionFile = path.join(tempDir, "session.jsonl");
+    await writeCodexAppServerBinding(sessionFile, {
+      threadId: "thread-1",
+      cwd: tempDir,
+      model: "gpt-5.4",
+      modelProvider: "openai",
+      approvalPolicy: "never",
+      sandbox: "danger-full-access",
+    });
+
+    await expect(setCodexConversationFastMode({ sessionFile, enabled: true })).resolves.toBe(
+      "Codex fast mode enabled.",
+    );
+    await expect(setCodexConversationPermissions({ sessionFile, mode: "default" })).resolves.toBe(
+      "Codex permissions set to default.",
+    );
+
+    const binding = await readCodexAppServerBinding(sessionFile);
+    expect(binding?.threadId).toBe("thread-1");
+    expect(binding?.serviceTier).toBe("priority");
+    expect(binding?.approvalPolicy).toBe("on-request");
+    expect(binding?.sandbox).toBe("workspace-write");
+  });
+
+  it("does not persist public OpenAI provider after model changes on native auth bindings", async () => {
+    const sessionFile = path.join(tempDir, "session.jsonl");
+    const agentDir = path.join(tempDir, "agents", "bot-a", "agent");
+    upsertAuthProfile({
+      profileId: "work",
+      credential: {
+        type: "oauth",
+        provider: "openai-codex",
+        access: "access-token",
+        refresh: "refresh-token",
+        expires: Date.now() + 60_000,
+      },
+    });
+    await writeCodexAppServerBinding(sessionFile, {
+      threadId: "thread-1",
+      cwd: tempDir,
+      authProfileId: "work",
+      model: "gpt-5.4",
+      modelProvider: "openai",
+    });
+    sharedClientMocks.getSharedCodexAppServerClient.mockResolvedValue({
+      request: vi.fn(async () => ({
+        thread: { id: "thread-1", cwd: tempDir },
+        model: "gpt-5.5",
+        modelProvider: "openai",
+      })),
+    });
+
+    await expect(
+      setCodexConversationModel({ sessionFile, agentDir, model: "gpt-5.5" }),
+    ).resolves.toBe("Codex model set to gpt-5.5.");
+
+    const raw = await fs.readFile(`${sessionFile}.codex-app-server.json`, "utf8");
+    const binding = await readCodexAppServerBinding(sessionFile);
+    const sharedClientParams = sharedClientMocks.getSharedCodexAppServerClient.mock.calls[0]?.[0];
+    expect(sharedClientParams?.agentDir).toBe(agentDir);
+    expect(raw).not.toContain('"modelProvider": "openai"');
+    expect(binding?.threadId).toBe("thread-1");
+    expect(binding?.authProfileId).toBe("work");
+    expect(binding?.model).toBe("gpt-5.5");
+    expect(binding?.modelProvider).toBeUndefined();
+  });
+
+  it("escapes model names returned from Codex before chat display", async () => {
+    const sessionFile = path.join(tempDir, "session.jsonl");
+    await writeCodexAppServerBinding(sessionFile, {
+      threadId: "thread-1",
+      cwd: tempDir,
+      model: "gpt-5.4",
+      modelProvider: "openai",
+    });
+    sharedClientMocks.getSharedCodexAppServerClient.mockResolvedValue({
+      request: vi.fn(async () => ({
+        thread: { id: "thread-1", cwd: tempDir },
+        model: "gpt-5.5 <@U123> [trusted](https://evil)",
+        modelProvider: "openai",
+      })),
+    });
+
+    await expect(setCodexConversationModel({ sessionFile, model: "gpt-5.5" })).resolves.toBe(
+      "Codex model set to gpt-5.5 &lt;\uff20U123&gt; \uff3btrusted\uff3d\uff08https://evil\uff09.",
+    );
+  });
+});