@keyou007/agent-bot 0.1.20-alpha.1 → 0.1.21

package/src/codex/CodexRuntime.ts

@@ -1,3 +1,4 @@
+import { statSync } from "node:fs";
 import type { Logger } from "pino";
 import type {
   AgentRuntime,
@@ -9,8 +10,10 @@ import type {
   ModelProviderOption,
   PermissionMode,
   RemoteSessionActivity,
+  RemoteSessionMetrics,
   RemoteSessionPage,
   RemoteSessionSummary,
+  RemoteTurnPage,
   ResumeRuntimeSessionInput,
   RuntimeGoal,
   RuntimeGoalUpdate,
@@ -28,6 +31,8 @@ import { mapCodexNotification } from "./CodexEventMapper.js";
 import { CodexLocalActivityDetector } from "./CodexLocalActivityDetector.js";
 import { detectProjectlessWorkspace } from "./ProjectlessWorkspace.js";
 import { threadWriterLockPath } from "./ThreadWriterProcess.js";
+import { assertProviderSettingsApplied, PROVIDER_SWITCH_BUSY, providerSwitchFailure } from "./ProviderSwitch.js";
+import { fetchProviderModels, type ProviderModelConfig } from "./ProviderModels.js";
 
 const WINDOWS_SCREENSHOT_DEVELOPER_INSTRUCTIONS = [
   "When capturing any screenshot on Windows, use one fresh process and make it Per-Monitor DPI Aware V2 before loading System.Windows.Forms, System.Drawing, or UI Automation, and before calling any screen, window, or bounds API.",
@@ -41,14 +46,13 @@ const WINDOWS_SCREENSHOT_DEVELOPER_INSTRUCTIONS = [
 const SESSION_REQUEST_TIMEOUT_MS = 60_000;
 const CONTROL_REQUEST_TIMEOUT_MS = 10_000;
 const SYNC_REQUEST_TIMEOUT_MS = 5_000;
-const THREAD_TURN_PAGE_SIZE = 100;
 const FORK_SOURCE_TURN_PAGE_SIZE = 20;
 const FORK_SOURCE_REQUEST_TIMEOUT_MS = 15_000;
 const USER_RESUMABLE_THREAD_SOURCE_KINDS = ["cli", "vscode", "exec", "appServer"] as const;
+const BUILT_IN_CODEX_PROVIDER_ID = "openai";
 // A timed-out fork keeps running in App Server and can create an orphan thread.
 // Wait for its response; connection closure still rejects the request.
 const FORK_REQUEST_TIMEOUT_MS = 0;
-type ThreadListSortKey = "recency_at" | "updated_at";
 
 export interface AppServerClient {
   request<T = unknown>(method: string, params?: unknown, timeoutMs?: number): Promise<T>;
@@ -62,8 +66,10 @@ export interface AppServerClient {
 
 export interface AppServerClientProvider {
   getClient(): Promise<AppServerClient>;
+  getAgentFamily?(): "codex" | "traex" | undefined;
   getProcessInfo?(): AgentProcessInfo;
   getCodexHome?(): string;
+  getEnvironmentVariable?(name: string): string | undefined;
   onDisconnect?(listener: (error: Error) => void): () => void;
   release?(): Promise<void>;
   close(): void;
@@ -76,6 +82,11 @@ interface CodexSession extends RuntimeSession {
   generatedImagePaths: string[];
   messagePhases: Map<string, "commentary" | "final_answer">;
   needsResume: boolean;
+  canReplaceEmptyThread: boolean;
+  settingsRecoveryError?: string;
+  rolloutPath?: string;
+  turnCount?: number;
+  knownTurnIds: Set<string>;
 }
 
 interface PendingApproval {
@@ -93,9 +104,9 @@ export class CodexRuntime implements AgentRuntime {
   private unsubscribe?: () => void;
   private readonly unsubscribeDisconnect?: () => void;
   private readonly sessionSyncs = new Map<string, Promise<RuntimeSession>>();
+  private readonly sessionOperations = new Map<string, Promise<unknown>>();
   private readonly localActivityDetector?: CodexLocalActivityDetector;
   private readonly codexHome?: string;
-  private threadListSortKey: ThreadListSortKey = "recency_at";
   private releaseInFlight?: Promise<RuntimeReleaseResult>;
 
   constructor(
@@ -120,6 +131,10 @@ export class CodexRuntime implements AgentRuntime {
   }
 
   async createSession(input: CreateRuntimeSessionInput): Promise<RuntimeSession> {
+    return this.runSessionOperation(input.localSessionId, () => this.createSessionNow(input));
+  }
+
+  private async createSessionNow(input: CreateRuntimeSessionInput): Promise<RuntimeSession> {
     const client = await this.client();
     const response = await client.request<ThreadResponse>("thread/start", {
       cwd: input.cwd,
@@ -144,6 +159,10 @@ export class CodexRuntime implements AgentRuntime {
   }
 
   async resumeSession(input: ResumeRuntimeSessionInput): Promise<RuntimeSession> {
+    return this.runSessionOperation(input.localSessionId, () => this.resumeSessionNow(input));
+  }
+
+  private async resumeSessionNow(input: ResumeRuntimeSessionInput): Promise<RuntimeSession> {
     const client = await this.client();
     const response = await client.request<ThreadResponse>("thread/resume", {
       threadId: input.remoteSessionId,
@@ -161,6 +180,10 @@ export class CodexRuntime implements AgentRuntime {
   }
 
   async forkSession(input: ForkRuntimeSessionInput): Promise<RuntimeSession> {
+    return this.runSessionOperation(input.localSessionId, () => this.forkSessionNow(input));
+  }
+
+  private async forkSessionNow(input: ForkRuntimeSessionInput): Promise<RuntimeSession> {
     const client = await this.client();
     const forkParams = {
       threadId: input.remoteSessionId,
@@ -172,20 +195,10 @@ export class CodexRuntime implements AgentRuntime {
       ...threadLifecycleParams(input.cwd),
       ...permissionParams(input.permissionMode),
     };
-    let response: ThreadResponse;
-    try {
-      response = await client.request<ThreadResponse>("thread/fork", {
-        ...forkParams,
-        excludeTurns: true,
-      }, FORK_REQUEST_TIMEOUT_MS);
-    } catch (error) {
-      if (!isUnsupportedExcludeTurnsError(error)) throw error;
-      this.logger.warn(
-        { error },
-        "App Server does not support thread/fork excludeTurns; retrying without it.",
-      );
-      response = await client.request<ThreadResponse>("thread/fork", forkParams, FORK_REQUEST_TIMEOUT_MS);
-    }
+    const response = await client.request<ThreadResponse>("thread/fork", {
+      ...forkParams,
+      excludeTurns: true,
+    }, FORK_REQUEST_TIMEOUT_MS);
     const requestedTitle = normalizeTaskTitle(input.title);
     if (requestedTitle) {
       await client.request("thread/name/set", {
@@ -201,9 +214,14 @@ export class CodexRuntime implements AgentRuntime {
   }
 
   async startTurn(sessionId: string, prompt: RuntimePrompt): Promise<string> {
+    return this.runSessionOperation(sessionId, () => this.startTurnNow(sessionId, prompt));
+  }
+
+  private async startTurnNow(sessionId: string, prompt: RuntimePrompt): Promise<string> {
     const session = this.requireSession(sessionId);
     const client = await this.client();
     await this.ensureSessionResumed(session, client);
+    session.canReplaceEmptyThread = false;
     const start = () => client.request<{ turn: { id: string } }>("turn/start", {
       threadId: session.remoteSessionId,
       input: codexUserInput(prompt),
@@ -249,28 +267,13 @@ export class CodexRuntime implements AgentRuntime {
     limit?: number;
   } = {}): Promise<RemoteSessionPage> {
     const client = await this.client();
-    let response: ThreadListResponse;
-    try {
-      response = await this.requestThreadList(client, input, this.threadListSortKey);
-    } catch (error) {
-      if (this.threadListSortKey !== "recency_at" || !isUnsupportedRecencySortError(error)) throw error;
-      this.threadListSortKey = "updated_at";
-      this.logger.warn(
-        { error },
-        "App Server does not support thread/list recency_at sorting; retrying with updated_at.",
-      );
-      response = await this.requestThreadList(client, input, this.threadListSortKey);
-    }
+    const response = await this.requestThreadList(client, input);
     const sessions = await Promise.all(response.data.map(async (thread) => {
       const listed = remoteSessionSummary(thread);
       if (listed.status === "active" || listed.lastTurnStatus === "inProgress") return listed;
       try {
-        const detail = await client.request<ThreadReadResponse>(
-          "thread/read",
-          { threadId: thread.id, includeTurns: true },
-          SYNC_REQUEST_TIMEOUT_MS,
-        );
-        return mergeRemoteSessionSummary(listed, remoteSessionSummary(detail.thread));
+        const turns = await this.readLatestThreadTurns(client, thread.id, "summary");
+        return mergeRemoteSessionSummary(listed, remoteSessionSummary({ ...thread, turns }));
       } catch {
         return listed;
       }
@@ -287,15 +290,16 @@ export class CodexRuntime implements AgentRuntime {
   private requestThreadList(
     client: AppServerClient,
     input: { searchTerm?: string; cursor?: string; limit?: number },
-    sortKey: ThreadListSortKey,
   ): Promise<ThreadListResponse> {
     return client.request<ThreadListResponse>(
       "thread/list",
       {
         cursor: input.cursor,
         limit: input.limit ?? 20,
-        sortKey,
+        sortKey: this.provider.getAgentFamily?.() === "traex" ? "updated_at" : "recency_at",
         sortDirection: "desc",
+        // Omitting this filter only lists the App Server's current Provider.
+        modelProviders: [],
         sourceKinds: USER_RESUMABLE_THREAD_SOURCE_KINDS,
         archived: false,
         searchTerm: input.searchTerm,
@@ -304,10 +308,79 @@ export class CodexRuntime implements AgentRuntime {
     );
   }
 
-  async readRemoteSession(remoteSessionId: string): Promise<RemoteSessionSummary> {
+  async readRemoteSession(
+    remoteSessionId: string,
+    view: "metadata" | "latest" | "latest-full" = "latest",
+  ): Promise<RemoteSessionSummary> {
+    const client = await this.client();
+    const response = await client.request<ThreadReadResponse>(
+      "thread/read", { threadId: remoteSessionId, includeTurns: false }, SYNC_REQUEST_TIMEOUT_MS,
+    );
+    const turns = view === "metadata" ? []
+      : await this.readLatestThreadTurns(client, remoteSessionId, view === "latest-full" ? "full" : "summary");
+    return this.decorateRemoteSession(remoteSessionId, remoteSessionSummary({ ...response.thread, turns }));
+  }
+
+  async readRemoteSessionMetrics(remoteSessionId: string): Promise<RemoteSessionMetrics> {
     const client = await this.client();
-    const response = await this.readThreadWithTurns(client, remoteSessionId);
-    return this.decorateRemoteSession(remoteSessionId, remoteSessionSummary(response.thread));
+    const metadata = await client.request<ThreadReadResponse>(
+      "thread/read", { threadId: remoteSessionId, includeTurns: false }, SYNC_REQUEST_TIMEOUT_MS,
+    );
+    const { turnCount, turnIds } = await this.countRemoteTurns(client, remoteSessionId);
+    const rolloutPath = stringValue(metadata.thread.path)?.trim() || undefined;
+    const loaded = [...this.sessions.values()].filter((session) => session.remoteSessionId === remoteSessionId);
+    for (const session of loaded) {
+      session.rolloutPath = rolloutPath ?? session.rolloutPath;
+      const knownTurnIds = new Set(turnIds);
+      if (session.activeTurnId && !knownTurnIds.has(session.activeTurnId)) knownTurnIds.add(session.activeTurnId);
+      session.knownTurnIds = knownTurnIds;
+      session.turnCount = knownTurnIds.size;
+    }
+    const effectivePath = rolloutPath ?? loaded[0]?.rolloutPath;
+    return {
+      turnCount: loaded[0]?.turnCount ?? turnCount,
+      storageBytes: rolloutStorageBytes(effectivePath),
+    };
+  }
+
+  private async countRemoteTurns(
+    client: AppServerClient,
+    remoteSessionId: string,
+  ): Promise<{ turnCount: number; turnIds: Set<string> }> {
+    const turnIds = new Set<string>();
+    const seenCursors = new Set<string>();
+    let cursor: string | undefined;
+    do {
+      const page = await this.readTurnPage(client, remoteSessionId, {
+        cursor,
+        limit: 100,
+        itemsView: "summary",
+      }, CONTROL_REQUEST_TIMEOUT_MS);
+      for (const turn of page.data) turnIds.add(turn.id);
+      const nextCursor = page.nextCursor ?? undefined;
+      if (!nextCursor) break;
+      if (nextCursor === cursor || seenCursors.has(nextCursor)) {
+        throw new Error("App Server repeated a Turn history cursor while counting task Turns.");
+      }
+      seenCursors.add(nextCursor);
+      cursor = nextCursor;
+    } while (cursor);
+    return { turnCount: turnIds.size, turnIds };
+  }
+
+  async listRemoteTurnSummaries(
+    remoteSessionId: string,
+    input: { cursor?: string; limit: number },
+  ): Promise<RemoteTurnPage> {
+    const response = await this.readTurnPage(await this.client(), remoteSessionId, {
+      cursor: input.cursor,
+      limit: Math.max(1, Math.min(100, Math.trunc(input.limit))),
+      itemsView: "summary",
+    });
+    return {
+      turns: remoteSessionSummary({ id: remoteSessionId, turns: response.data }).completedTurns ?? [],
+      nextCursor: response.nextCursor ?? undefined,
+    };
   }
 
   async readRemoteForkSource(remoteSessionId: string): Promise<RemoteSessionSummary> {
@@ -317,17 +390,7 @@ export class CodexRuntime implements AgentRuntime {
       { threadId: remoteSessionId, includeTurns: false },
       FORK_SOURCE_REQUEST_TIMEOUT_MS,
     );
-    let turns: CodexTurnSnapshot[];
-    try {
-      turns = await this.listRecentThreadTurnsThroughCompleted(client, remoteSessionId);
-    } catch (error) {
-      if (!isUnsupportedThreadTurnsListError(error)) throw error;
-      this.logger.warn(
-        { error, remoteSessionId },
-        "App Server does not support lightweight Fork source reads; falling back to complete thread history.",
-      );
-      return this.readRemoteSession(remoteSessionId);
-    }
+    const turns = await this.listRecentThreadTurnsThroughCompleted(client, remoteSessionId);
     return this.decorateRemoteSession(remoteSessionId, remoteSessionSummary({
       ...metadata.thread,
       turns,
@@ -355,17 +418,9 @@ export class CodexRuntime implements AgentRuntime {
     const seenCursors = new Set<string>();
     let cursor: string | undefined;
     do {
-      const response = await client.request<ThreadTurnsListResponse>(
-        "thread/turns/list",
-        {
-          threadId: remoteSessionId,
-          ...(cursor ? { cursor } : {}),
-          limit: FORK_SOURCE_TURN_PAGE_SIZE,
-          sortDirection: "desc",
-          itemsView: "summary",
-        },
-        FORK_SOURCE_REQUEST_TIMEOUT_MS,
-      );
+      const response = await this.readTurnPage(client, remoteSessionId, {
+        cursor, limit: FORK_SOURCE_TURN_PAGE_SIZE, itemsView: "summary",
+      }, FORK_SOURCE_REQUEST_TIMEOUT_MS);
       turns.push(...response.data);
       const completedIndex = turns.findIndex((turn) => turn.status === "completed");
       if (completedIndex >= 0) {
@@ -387,69 +442,34 @@ export class CodexRuntime implements AgentRuntime {
     return turns.reverse();
   }
 
-  private async readThreadWithTurns(
+  private async readLatestThreadTurns(
     client: AppServerClient,
     remoteSessionId: string,
-  ): Promise<ThreadReadResponse> {
-    try {
-      return await client.request<ThreadReadResponse>(
-        "thread/read",
-        { threadId: remoteSessionId, includeTurns: true },
-        SYNC_REQUEST_TIMEOUT_MS,
-      );
-    } catch (error) {
-      const paginated = isPaginatedThreadReadError(error);
-      if (!paginated && !isUnmaterializedThreadReadError(error)) throw error;
-
-      const metadata = await client.request<ThreadReadResponse>(
-        "thread/read",
-        { threadId: remoteSessionId, includeTurns: false },
-        SYNC_REQUEST_TIMEOUT_MS,
-      );
-      if (!paginated) return { thread: { ...metadata.thread, turns: [] } };
-
-      return {
-        thread: {
-          ...metadata.thread,
-          turns: await this.listThreadTurns(client, remoteSessionId),
-        },
-      };
-    }
+    itemsView: "summary" | "full",
+  ): Promise<CodexTurnSnapshot[]> {
+    const response = await this.readTurnPage(client, remoteSessionId, { limit: 1, itemsView });
+    return response.data;
   }
 
-  private async listThreadTurns(
+  private async readTurnPage(
     client: AppServerClient,
     remoteSessionId: string,
-  ): Promise<CodexTurnSnapshot[]> {
-    const turns: CodexTurnSnapshot[] = [];
-    const seenCursors = new Set<string>();
-    let cursor: string | undefined;
-    do {
-      const response = await client.request<ThreadTurnsListResponse>(
-        "thread/turns/list",
-        {
-          threadId: remoteSessionId,
-          ...(cursor ? { cursor } : {}),
-          limit: THREAD_TURN_PAGE_SIZE,
-          sortDirection: "asc",
-          itemsView: "full",
-        },
-        SYNC_REQUEST_TIMEOUT_MS,
-      );
-      turns.push(...response.data);
-      const nextCursor = response.nextCursor ?? undefined;
-      if (!nextCursor) break;
-      if (seenCursors.has(nextCursor)) {
-        this.logger.warn(
-          { remoteSessionId, cursor: nextCursor },
-          "App Server repeated a thread Turn pagination cursor; stopping pagination.",
-        );
-        break;
+    input: { cursor?: string; limit: number; itemsView: "summary" | "full" },
+    timeoutMs = SYNC_REQUEST_TIMEOUT_MS,
+  ): Promise<ThreadTurnsListResponse> {
+    try {
+      return await client.request<ThreadTurnsListResponse>("thread/turns/list", {
+        threadId: remoteSessionId,
+        ...(input.cursor ? { cursor: input.cursor } : {}),
+        limit: input.limit, sortDirection: "desc", itemsView: input.itemsView,
+      }, timeoutMs);
+    } catch (error) {
+      if (error instanceof AppServerRequestError && error.method === "thread/turns/list"
+        && /not materialized yet; thread\/turns\/list is unavailable before first user message/i.test(error.serverMessage)) {
+        return { data: [], nextCursor: null };
       }
-      seenCursors.add(nextCursor);
-      cursor = nextCursor;
-    } while (cursor);
-    return turns;
+      throw error;
+    }
   }
 
   async inspectRemoteSessionActivity(remoteSessionId: string): Promise<RemoteSessionActivity> {
@@ -477,7 +497,7 @@ export class CodexRuntime implements AgentRuntime {
   async synchronizeSession(sessionId: string): Promise<RuntimeSession> {
     const existing = this.sessionSyncs.get(sessionId);
     if (existing) return existing;
-    const synchronization = this.synchronizeSessionNow(sessionId);
+    const synchronization = this.runSessionOperation(sessionId, () => this.synchronizeSessionNow(sessionId));
     this.sessionSyncs.set(sessionId, synchronization);
     try {
       return await synchronization;
@@ -513,8 +533,10 @@ export class CodexRuntime implements AgentRuntime {
   }
 
   async closeSession(sessionId: string): Promise<void> {
-    const session = this.requireSession(sessionId);
-    await this.archiveRemoteSession(session.remoteSessionId);
+    await this.runSessionOperation(sessionId, async () => {
+      const session = this.requireSession(sessionId);
+      await this.archiveRemoteSession(session.remoteSessionId);
+    });
   }
 
   async archiveRemoteSession(remoteSessionId: string): Promise<void> {
@@ -529,6 +551,10 @@ export class CodexRuntime implements AgentRuntime {
   }
 
   async setTitle(sessionId: string, title: string): Promise<void> {
+    return this.runSessionOperation(sessionId, () => this.setTitleNow(sessionId, title));
+  }
+
+  private async setTitleNow(sessionId: string, title: string): Promise<void> {
     const session = this.requireSession(sessionId);
     const normalizedTitle = normalizeTaskTitle(title);
     if (!normalizedTitle) throw new Error("任务标题不能为空。");
@@ -541,6 +567,10 @@ export class CodexRuntime implements AgentRuntime {
   }
 
   async getGoal(sessionId: string): Promise<RuntimeGoal | undefined> {
+    return this.runSessionOperation(sessionId, () => this.getGoalNow(sessionId));
+  }
+
+  private async getGoalNow(sessionId: string): Promise<RuntimeGoal | undefined> {
     const session = this.requireSession(sessionId);
     const client = await this.client();
     await this.ensureSessionResumed(session, client);
@@ -553,9 +583,14 @@ export class CodexRuntime implements AgentRuntime {
   }
 
   async setGoal(sessionId: string, update: RuntimeGoalUpdate): Promise<RuntimeGoal> {
+    return this.runSessionOperation(sessionId, () => this.setGoalNow(sessionId, update));
+  }
+
+  private async setGoalNow(sessionId: string, update: RuntimeGoalUpdate): Promise<RuntimeGoal> {
     const session = this.requireSession(sessionId);
     const client = await this.client();
     await this.ensureSessionResumed(session, client);
+    session.canReplaceEmptyThread = false;
     const response = await client.request<{ goal: RuntimeGoal }>(
       "thread/goal/set",
       { threadId: session.remoteSessionId, ...update },
@@ -565,6 +600,10 @@ export class CodexRuntime implements AgentRuntime {
   }
 
   async clearGoal(sessionId: string): Promise<boolean> {
+    return this.runSessionOperation(sessionId, () => this.clearGoalNow(sessionId));
+  }
+
+  private async clearGoalNow(sessionId: string): Promise<boolean> {
     const session = this.requireSession(sessionId);
     const client = await this.client();
     await this.ensureSessionResumed(session, client);
@@ -577,39 +616,132 @@ export class CodexRuntime implements AgentRuntime {
   }
 
   async setModel(sessionId: string, model: string): Promise<void> {
-    this.requireSession(sessionId).model = model;
+    await this.runSessionOperation(sessionId, async () => { this.requireSession(sessionId).model = model; });
   }
 
   async setReasoningEffort(sessionId: string, effort: string): Promise<void> {
-    this.requireSession(sessionId).reasoningEffort = effort;
+    await this.runSessionOperation(sessionId, async () => { this.requireSession(sessionId).reasoningEffort = effort; });
   }
 
   async setPermissionMode(sessionId: string, mode: PermissionMode): Promise<void> {
-    this.requireSession(sessionId).permissionMode = mode;
+    await this.runSessionOperation(sessionId, async () => { this.requireSession(sessionId).permissionMode = mode; });
   }
 
   async setExecutionSettings(
     sessionId: string,
     settings: RuntimeExecutionSettings,
+    persist?: (session: RuntimeSession) => Promise<void>,
+  ): Promise<RuntimeSession> {
+    return this.runSessionOperation(sessionId, () => this.setExecutionSettingsNow(sessionId, settings, persist));
+  }
+
+  private async setExecutionSettingsNow(
+    sessionId: string,
+    settings: RuntimeExecutionSettings,
+    persist?: (session: RuntimeSession) => Promise<void>,
   ): Promise<RuntimeSession> {
     const session = this.requireSession(sessionId);
-    const response = await (await this.client()).request<ThreadResponse>("thread/resume", {
-      threadId: session.remoteSessionId,
-      excludeTurns: true,
-      cwd: session.cwd,
-      modelProvider: settings.modelProvider,
-      model: settings.model,
-      ...threadLifecycleParams(session.cwd),
-      ...permissionParams(settings.permissionMode),
-    }, SESSION_REQUEST_TIMEOUT_MS);
-    session.modelProvider = response.modelProvider ?? settings.modelProvider;
-    session.model = response.model ?? settings.model;
-    session.reasoningEffort = settings.reasoningEffort;
-    session.permissionMode = settings.permissionMode;
-    session.needsResume = false;
+    if (session.activeTurnId) throw new Error(PROVIDER_SWITCH_BUSY);
+    const client = await this.client();
+    const metadata = await client.request<ThreadReadResponse>("thread/read", {
+      threadId: session.remoteSessionId, includeTurns: false,
+    }, SYNC_REQUEST_TIMEOUT_MS);
+    const localActive = await this.localActivityDetector?.activeThreads([session.remoteSessionId]);
+    if (metadata.thread.status?.type === "active" || localActive?.has(session.remoteSessionId) || session.activeTurnId) {
+      throw new Error(PROVIDER_SWITCH_BUSY);
+    }
+    let empty = false;
+    if (session.canReplaceEmptyThread && !metadata.thread.forkedFromId && !metadata.thread.preview?.trim()) {
+      try {
+        const turns = await this.readLatestThreadTurns(client, session.remoteSessionId, "summary");
+        empty = turns.length === 0;
+        if (!empty) session.canReplaceEmptyThread = false;
+      } catch (error) {
+        if (!(error instanceof AppServerRequestError) || error.method !== "thread/turns/list"
+          || !/missing source rollout|no rollout found/iu.test(error.serverMessage)) throw error;
+        empty = true;
+      }
+    }
+    const previous = { ...session };
+    let replacementId: string | undefined;
+    let detached = false;
+    try {
+      const params = {
+        cwd: session.cwd, modelProvider: settings.modelProvider, model: settings.model,
+        ...threadLifecycleParams(session.cwd), ...permissionParams(settings.permissionMode),
+      };
+      if (!empty) {
+        await this.detachThreadForSettings(client, session);
+        detached = true;
+      }
+      const response = empty
+        ? await client.request<ThreadResponse>("thread/start", {
+            ...params, threadSource: "user", allowProviderModelFallback: false,
+          }, SESSION_REQUEST_TIMEOUT_MS)
+        : await client.request<ThreadResponse>("thread/resume", {
+            ...params, threadId: session.remoteSessionId, excludeTurns: true,
+          }, SESSION_REQUEST_TIMEOUT_MS);
+      if (empty) replacementId = response.thread.id;
+      assertProviderSettingsApplied(response, settings);
+      if (!empty && response.thread.id !== session.remoteSessionId) throw new Error("App Server 返回了不同的任务 ID，未保存设置。");
+      if (empty && session.title) await client.request("thread/name/set", {
+        threadId: response.thread.id, name: session.title,
+      }, SESSION_REQUEST_TIMEOUT_MS);
+      const candidate = { ...session, ...settings, remoteSessionId: response.thread.id,
+        needsResume: false, settingsRecoveryError: undefined };
+      await persist?.(candidate);
+      Object.assign(session, candidate);
+    } catch (error) {
+      if (replacementId) await this.discardUnusedThread(client, replacementId);
+      let recovery = "原任务设置未更改。";
+      if (detached) {
+        try {
+          await this.detachThreadForSettings(client, previous);
+          const restored = await client.request<ThreadResponse>("thread/resume", {
+            threadId: previous.remoteSessionId, excludeTurns: true, cwd: previous.cwd,
+            modelProvider: previous.modelProvider, model: previous.model,
+            ...threadLifecycleParams(previous.cwd), ...permissionParams(previous.permissionMode),
+          }, SESSION_REQUEST_TIMEOUT_MS);
+          if (previous.modelProvider && previous.model) assertProviderSettingsApplied(restored, {
+            modelProvider: previous.modelProvider, model: previous.model,
+          });
+          if (restored.thread.id !== previous.remoteSessionId) throw new Error("恢复时返回了不同的任务 ID。");
+          session.needsResume = false;
+          session.settingsRecoveryError = undefined;
+        } catch (restoreError) {
+          this.logger.warn({ error: restoreError, sessionId }, "Failed to restore Provider after a rejected settings change.");
+          recovery = "原设置仍保留，但远端恢复失败；请重新切换 Provider，确认成功后再发送消息。";
+          session.settingsRecoveryError = recovery;
+          session.needsResume = true;
+        }
+      }
+      throw new Error(`Provider 切换失败：${providerSwitchFailure(error)} ${recovery}`, { cause: error });
+    }
+    if (replacementId) await this.discardUnusedThread(client, previous.remoteSessionId);
     return session;
   }
 
+  private async detachThreadForSettings(client: AppServerClient, session: CodexSession): Promise<void> {
+    const current = await client.request<ThreadReadResponse>("thread/read", {
+      threadId: session.remoteSessionId, includeTurns: false,
+    }, SYNC_REQUEST_TIMEOUT_MS);
+    if (session.activeTurnId || current.thread.status?.type === "active") throw new Error(PROVIDER_SWITCH_BUSY);
+    const result = await client.request<{ status: string }>("thread/unsubscribe", {
+      threadId: session.remoteSessionId,
+    }, CONTROL_REQUEST_TIMEOUT_MS);
+    if (result.status !== "unsubscribed" && result.status !== "notLoaded") {
+      throw new Error("当前任务仍由其他客户端加载，无法安全切换 Provider。请先在原客户端释放任务。");
+    }
+  }
+
+  private async discardUnusedThread(client: AppServerClient, threadId: string): Promise<void> {
+    try {
+      await client.request("thread/unsubscribe", { threadId }, CONTROL_REQUEST_TIMEOUT_MS);
+    } catch (error) {
+      this.logger.warn({ error, threadId }, "Failed to release an unused empty Thread after changing Provider.");
+    }
+  }
+
   async respondToApproval(
     sessionId: string,
     requestId: string,
@@ -622,7 +754,43 @@ export class CodexRuntime implements AgentRuntime {
     this.emit({ type: "approval_resolved", sessionId, turnId: pending.turnId, requestId, decision });
   }
 
-  async listModels(): Promise<ModelOption[]> {
+  async listModels(modelProvider?: string, fallbackModel?: string): Promise<ModelOption[]> {
+    const requestedProvider = modelProvider?.trim();
+    if (!requestedProvider
+      || (requestedProvider === BUILT_IN_CODEX_PROVIDER_ID && this.provider.getAgentFamily?.() !== "traex")) {
+      return this.listCatalogModels();
+    }
+    const config = await this.readConfig();
+    const configuredProviders = isRecord(config.model_providers) ? config.model_providers : {};
+    const providerConfig = configuredProviders[requestedProvider];
+    let catalog: ModelOption[] = [];
+    try {
+      catalog = await this.listCatalogModels();
+    } catch (error) {
+      this.logger.warn({ error, modelProvider: requestedProvider },
+        "Failed to read the App Server model catalog while discovering Provider models.");
+    }
+    const configuredDefaultModel = stringValue(config.model_provider)?.trim() === requestedProvider
+      ? stringValue(config.model)?.trim()
+      : undefined;
+    try {
+      return await fetchProviderModels({
+        providerId: requestedProvider,
+        config: (isRecord(providerConfig) ? providerConfig : {}) as ProviderModelConfig,
+        catalog,
+        configuredDefaultModel,
+        environmentValue: (name) => this.provider.getEnvironmentVariable?.(name) ?? process.env[name],
+      });
+    } catch (error) {
+      const fallback = fallbackProviderModel(catalog, fallbackModel, configuredDefaultModel);
+      if (!fallback) throw error;
+      this.logger.warn({ error, modelProvider: requestedProvider, fallbackModel: fallback.id },
+        "Provider model discovery failed; using the current or configured model as a fallback.");
+      return [fallback];
+    }
+  }
+
+  private async listCatalogModels(): Promise<ModelOption[]> {
     const response = await (await this.client()).request<{
       data: Array<{
         id: string;
@@ -648,12 +816,7 @@ export class CodexRuntime implements AgentRuntime {
   }
 
   async listModelProviders(): Promise<ModelProviderOption[]> {
-    const response = await (await this.client()).request<{ config?: Record<string, unknown> }>(
-      "config/read",
-      {},
-      CONTROL_REQUEST_TIMEOUT_MS,
-    );
-    const config = response.config ?? {};
+    const config = await this.readConfig();
     const defaultProvider = stringValue(config.model_provider)?.trim();
     const configuredProviders = isRecord(config.model_providers) ? config.model_providers : {};
     const providers = new Map<string, ModelProviderOption>();
@@ -666,6 +829,13 @@ export class CodexRuntime implements AgentRuntime {
         ...(id === defaultProvider ? { isDefault: true } : {}),
       });
     }
+    if (this.provider.getAgentFamily?.() === "codex" && !providers.has(BUILT_IN_CODEX_PROVIDER_ID)) {
+      providers.set(BUILT_IN_CODEX_PROVIDER_ID, {
+        id: BUILT_IN_CODEX_PROVIDER_ID,
+        displayName: "OpenAI",
+        ...(!defaultProvider ? { isDefault: true } : {}),
+      });
+    }
     if (defaultProvider && !providers.has(defaultProvider)) {
       providers.set(defaultProvider, { id: defaultProvider, isDefault: true });
     }
@@ -674,6 +844,15 @@ export class CodexRuntime implements AgentRuntime {
     );
   }
 
+  private async readConfig(): Promise<Record<string, unknown>> {
+    const response = await (await this.client()).request<{ config?: Record<string, unknown> }>(
+      "config/read",
+      {},
+      CONTROL_REQUEST_TIMEOUT_MS,
+    );
+    return response.config ?? {};
+  }
+
   onEvent(listener: (event: RuntimeEvent) => void): () => void {
     this.listeners.add(listener);
     return () => this.listeners.delete(listener);
@@ -682,7 +861,7 @@ export class CodexRuntime implements AgentRuntime {
   async release(options: { force?: boolean } = {}): Promise<RuntimeReleaseResult> {
     if (this.releaseInFlight) return this.releaseInFlight;
     const activeSessionIds = [...this.sessions.values()]
-      .filter((session) => Boolean(session.activeTurnId))
+      .filter((session) => Boolean(session.activeTurnId) || this.sessionOperations.has(session.localSessionId))
       .map((session) => session.localSessionId);
     if (activeSessionIds.length > 0 && options.force !== true) {
       return { status: "busy", activeSessionIds };
@@ -807,6 +986,18 @@ export class CodexRuntime implements AgentRuntime {
         turnId: mapped.turnId,
         lastTokens: mapped.lastTokens,
         cumulativeTokens: mapped.cumulativeTokens,
+        contextTokens: mapped.contextTokens,
+      });
+    } else if (mapped.kind === "context_compaction") {
+      this.emit({
+        type: "context_compaction",
+        sessionId,
+        turnId: mapped.turnId,
+        phase: mapped.phase,
+        compactionId: mapped.compactionId,
+        timestampMs: mapped.timestampMs,
+        turnCount: session.turnCount,
+        storageBytes: rolloutStorageBytes(session.rolloutPath),
       });
     } else if (mapped.kind === "agent_message_phase") {
       session.messagePhases.set(mapped.itemId, mapped.phase);
@@ -922,12 +1113,13 @@ export class CodexRuntime implements AgentRuntime {
     if (input.reasoningEffort) return input.reasoningEffort;
     if (response.reasoningEffort) return response.reasoningEffort;
     const model = input.model ?? response.model;
-    const models = await this.listModels();
+    const models = await this.listModels(input.modelProvider ?? response.modelProvider, model);
     return models.find((item) => item.id === model)?.defaultReasoningEffort
       ?? models.find((item) => item.isDefault)?.defaultReasoningEffort;
   }
 
   private async ensureSessionResumed(session: CodexSession, client: AppServerClient): Promise<void> {
+    if (session.settingsRecoveryError) throw new Error(session.settingsRecoveryError);
     if (!session.needsResume) return;
     await this.resumeAppServerSession(session, client);
     session.needsResume = false;
@@ -947,13 +1139,16 @@ export class CodexRuntime implements AgentRuntime {
 
   private async synchronizeSessionNow(sessionId: string): Promise<RuntimeSession> {
     const session = this.requireSession(sessionId);
-    const response = await (await this.client()).request<ThreadReadResponse>(
+    const client = await this.client();
+    const response = await client.request<ThreadReadResponse>(
       "thread/read",
-      { threadId: session.remoteSessionId, includeTurns: true },
+      { threadId: session.remoteSessionId, includeTurns: false },
       SYNC_REQUEST_TIMEOUT_MS,
     );
-    this.reconcileThreadSnapshot(session, response.thread);
-    return session;
+    const turns = await this.readLatestThreadTurns(client, session.remoteSessionId, "full");
+    const thread = { ...response.thread, turns };
+    this.reconcileThreadSnapshot(session, thread);
+    return { ...session, remoteSummary: await this.decorateRemoteSession(session.remoteSessionId, remoteSessionSummary(thread)) };
   }
 
   private reconcileThreadSnapshot(session: CodexSession, thread: ThreadReadResponse["thread"]): void {
@@ -1003,6 +1198,11 @@ export class CodexRuntime implements AgentRuntime {
   }
 
   private adoptTurn(session: CodexSession, turnId: string, startedAt: number): void {
+    session.canReplaceEmptyThread = false;
+    if (!session.knownTurnIds.has(turnId)) {
+      session.knownTurnIds.add(turnId);
+      if (session.turnCount !== undefined) session.turnCount += 1;
+    }
     session.activeTurnId = turnId;
     session.activeTurnStartedAt = startedAt;
     session.finalText = "";
@@ -1094,6 +1294,10 @@ export class CodexRuntime implements AgentRuntime {
       generatedImagePaths: [],
       messagePhases: new Map(),
       needsResume: false,
+      canReplaceEmptyThread: !("remoteSessionId" in input),
+      rolloutPath: stringValue(response.thread.path)?.trim() || undefined,
+      turnCount: "remoteSessionId" in input ? undefined : 0,
+      knownTurnIds: new Set(),
     };
   }
 
@@ -1103,6 +1307,17 @@ export class CodexRuntime implements AgentRuntime {
     return session;
   }
 
+  private async runSessionOperation<T>(sessionId: string, operation: () => Promise<T>): Promise<T> {
+    const previous = this.sessionOperations.get(sessionId);
+    const current = (previous ?? Promise.resolve()).catch(() => undefined).then(operation);
+    this.sessionOperations.set(sessionId, current);
+    try {
+      return await current;
+    } finally {
+      if (this.sessionOperations.get(sessionId) === current) this.sessionOperations.delete(sessionId);
+    }
+  }
+
   private requireActiveTurn(sessionId: string, turnId: string): CodexSession {
     const session = this.requireSession(sessionId);
     if (session.activeTurnId !== turnId) throw new Error(`App Server turn is no longer active: ${turnId}`);
@@ -1141,7 +1356,7 @@ export class CodexRuntime implements AgentRuntime {
 }
 
 interface ThreadResponse {
-  thread: { id: string; name?: string | null; preview?: string };
+  thread: { id: string; name?: string | null; preview?: string; path?: string | null };
   modelProvider?: string;
   model?: string;
   reasoningEffort?: string | null;
@@ -1172,6 +1387,8 @@ interface CodexThreadSnapshot {
   updatedAt?: number;
   recencyAt?: number | null;
   status?: { type?: string };
+  forkedFromId?: string | null;
+  path?: string | null;
   turns?: CodexTurnSnapshot[];
 }
 
@@ -1240,6 +1457,34 @@ function stringValue(value: unknown): string | undefined {
   return typeof value === "string" ? value : undefined;
 }
 
+function rolloutStorageBytes(filePath: string | undefined): number | undefined {
+  if (!filePath) return undefined;
+  try {
+    const stats = statSync(filePath);
+    return stats.isFile() ? stats.size : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function fallbackProviderModel(
+  catalog: ModelOption[],
+  requestedModel?: string,
+  configuredDefaultModel?: string,
+): ModelOption | undefined {
+  const id = requestedModel?.trim()
+    || configuredDefaultModel?.trim()
+    || catalog.find((model) => model.isDefault)?.id
+    || catalog[0]?.id;
+  if (!id) return undefined;
+  const catalogModel = catalog.find((model) => model.id === id);
+  return {
+    ...(catalogModel ?? { id, supportedReasoningEfforts: [] }),
+    id,
+    isDefault: true,
+  };
+}
+
 function turnStartedAt(turn: CodexTurnSnapshot): number {
   return typeof turn.startedAt === "number" ? turn.startedAt * 1_000 : Date.now();
 }
@@ -1265,64 +1510,12 @@ function uniqueStrings(values: string[]): string[] {
   return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
 }
 
-function isUnsupportedExcludeTurnsError(error: unknown): boolean {
-  if (!(error instanceof AppServerRequestError) || error.method !== "thread/fork") return false;
-  const data = typeof error.data === "string"
-    ? error.data
-    : error.data === undefined
-      ? ""
-      : JSON.stringify(error.data);
-  const details = `${error.serverMessage} ${data}`;
-  if (!details.toLowerCase().replaceAll(/[^a-z]/g, "").includes("excludeturns")) return false;
-  return error.code === -32602
-    || /unknown|unrecognized|unexpected|unsupported|not supported|experimental/i.test(details);
-}
-
 function isInvalidWorkingDirectoryError(error: unknown): boolean {
   return error instanceof AppServerRequestError
     && error.method === "turn/start"
     && /invalid cwd/i.test(`${error.serverMessage} ${error.data === undefined ? "" : JSON.stringify(error.data)}`);
 }
 
-function isUnsupportedRecencySortError(error: unknown): boolean {
-  if (!(error instanceof AppServerRequestError) || error.method !== "thread/list") return false;
-  const data = typeof error.data === "string"
-    ? error.data
-    : error.data === undefined
-      ? ""
-      : JSON.stringify(error.data);
-  const details = `${error.serverMessage} ${data}`;
-  return /recency_at/i.test(details)
-    && /unknown|unrecognized|unexpected|unsupported|not supported|invalid/i.test(details);
-}
-
-function isPaginatedThreadReadError(error: unknown): boolean {
-  const details = appServerErrorDetails(error);
-  return /paginated threads?[^\n]*do(?:es)? not support[^\n]*thread\/read[^\n]*includeTurns\s*=\s*true/i.test(details);
-}
-
-function isUnsupportedThreadTurnsListError(error: unknown): boolean {
-  if (!(error instanceof AppServerRequestError) || error.method !== "thread/turns/list") return false;
-  return error.code === -32601
-    || /method not found|unknown method|unsupported|not supported/i.test(appServerErrorDetails(error));
-}
-
-function isUnmaterializedThreadReadError(error: unknown): boolean {
-  const details = appServerErrorDetails(error);
-  return /thread[^\n]*(?:not materialized|not loaded)[^\n]*includeTurns[^\n]*(?:unavailable|before first user message)/i
-    .test(details);
-}
-
-function appServerErrorDetails(error: unknown): string {
-  if (!(error instanceof AppServerRequestError)) return error instanceof Error ? error.message : String(error);
-  const data = typeof error.data === "string"
-    ? error.data
-    : error.data === undefined
-      ? ""
-      : JSON.stringify(error.data);
-  return `${error.message} ${error.serverMessage} ${data}`;
-}
-
 function remoteSessionSummary(thread: CodexThreadSnapshot): RemoteSessionSummary {
   const lastTurn = thread.turns?.at(-1);
   const lastCompletedTurn = [...(thread.turns ?? [])]