@keyou007/agent-bot 0.1.24-alpha.5 → 0.1.24-alpha.6

package/src/codex/CodexRuntime.ts

@@ -4,6 +4,7 @@ import type {
   AgentRuntime,
   AgentProcessInfo,
   ApprovalDecision,
+  ApprovalRequest,
   CreateRuntimeSessionInput,
   ConversationTurn,
   ForkRuntimeSessionInput,
@@ -35,7 +36,7 @@ import { formatCodexError, 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 { assertProviderSettingsApplied, PROVIDER_SWITCH_BUSY, PROVIDER_SWITCH_EMPTY, ProviderSwitchError, providerSwitchFailure } from "./ProviderSwitch.js";
 import { fetchProviderModels, type ProviderModelConfig } from "./ProviderModels.js";
 
 const WINDOWS_SCREENSHOT_DEVELOPER_INSTRUCTIONS = [
@@ -84,6 +85,7 @@ interface CodexSession extends RuntimeSession {
   activeTurnStartedAt?: number;
   terminalTurnIds: Set<string>;
   modeChangeRequestIds: Set<string>;
+  planContinuationTurnId?: string;
   finalText: string;
   generatedImagePaths: string[];
   messagePhases: Map<string, "commentary" | "final_answer">;
@@ -91,7 +93,6 @@ interface CodexSession extends RuntimeSession {
   unphasedFinalMessageId?: string;
   needsResume: boolean;
   workspaceSandboxPolicy?: WorkspaceSandboxPolicy;
-  canReplaceEmptyThread: boolean;
   settingsRecoveryError?: string;
   rolloutPath?: string;
   turnCount?: number;
@@ -110,6 +111,10 @@ interface PendingModeChange {
   requestId: string;
   targetMode: "plan" | "default";
   responding: boolean;
+  decision?: ApprovalDecision;
+  automatic?: boolean;
+  continued?: boolean;
+  terminalEvent?: Extract<RuntimeEvent, { type: "turn_completed" }>;
 }
 
 export class CodexRuntime implements AgentRuntime {
@@ -184,6 +189,20 @@ export class CodexRuntime implements AgentRuntime {
     return this.runSessionOperation(input.localSessionId, () => this.resumeSessionNow(input));
   }
 
+  async prepareSessionForSettings(input: ResumeRuntimeSessionInput): Promise<RuntimeSession> {
+    return this.runSessionOperation(input.localSessionId, async () => {
+      const existing = this.sessions.get(input.localSessionId);
+      if (existing) return existing;
+      const session = this.makeSession(input, {
+        thread: { id: input.remoteSessionId, name: input.title },
+        modelProvider: input.modelProvider, model: input.model,
+      }, input.reasoningEffort);
+      session.needsResume = true;
+      this.sessions.set(input.localSessionId, session);
+      return session;
+    });
+  }
+
   private async resumeSessionNow(input: ResumeRuntimeSessionInput): Promise<RuntimeSession> {
     const client = await this.client();
     const response = await client.request<ThreadResponse>("thread/resume", {
@@ -195,8 +214,16 @@ export class CodexRuntime implements AgentRuntime {
       ...threadLifecycleParams(input.cwd),
       ...permissionParams(input.permissionMode),
     }, SESSION_REQUEST_TIMEOUT_MS);
+    if (response.thread.id !== input.remoteSessionId) throw new Error("App Server 返回了不同的任务 ID，未恢复会话。");
     const reasoningEffort = await this.resolveReasoningEffort(input, response);
     const session = this.makeSession(input, response, reasoningEffort);
+    try {
+      assertProviderSettingsApplied(response, { modelProvider: input.modelProvider });
+    } catch (error) {
+      // Keep the attachment available for an explicit settings repair, but never send to the wrong Provider.
+      session.settingsRecoveryError = providerSwitchFailure(error);
+      session.needsResume = true;
+    }
     this.sessions.set(input.localSessionId, session);
     return session;
   }
@@ -243,13 +270,18 @@ export class CodexRuntime implements AgentRuntime {
     const session = this.requireSession(sessionId);
     const client = await this.client();
     await this.ensureSessionResumed(session, client);
-    session.canReplaceEmptyThread = false;
     const start = async () => client.request<{ turn: { id: string } }>("turn/start", {
       threadId: session.remoteSessionId,
       input: codexUserInput(prompt),
       cwd: session.cwd,
       model: session.model,
       effort: session.reasoningEffort,
+      ...(typeof prompt !== "string" && prompt.collaborationMode ? {
+        collaborationMode: {
+          mode: prompt.collaborationMode,
+          settings: { model: session.model, reasoning_effort: session.reasoningEffort ?? null, developer_instructions: null },
+        },
+      } : {}),
       summary: "auto",
       approvalPolicy: session.permissionMode === "auto" ? "never" : "on-request",
       sandboxPolicy: await this.turnSandboxPolicy(session, client),
@@ -591,9 +623,10 @@ export class CodexRuntime implements AgentRuntime {
       .find((session) => session.remoteSessionId === remoteSessionId);
     const detectedTurnId = activeThreads?.get(remoteSessionId);
     // A turn started in this process is evidence; a restored activeTurnId alone is not.
+    const observedTurnId = runtimeSession?.activeTurnStartedAt !== undefined ? runtimeSession.activeTurnId : undefined;
     const active = status === "active" || Boolean(activeThreads?.has(remoteSessionId))
-      || Boolean(runtimeSession?.activeTurnId && runtimeSession.activeTurnStartedAt !== undefined);
-    const activeTurnId = detectedTurnId ?? runtimeSession?.activeTurnId;
+      || Boolean(observedTurnId);
+    const activeTurnId = detectedTurnId ?? observedTurnId;
     return {
       active,
       ...(active && activeTurnId ? { activeTurnId } : {}),
@@ -627,6 +660,12 @@ export class CodexRuntime implements AgentRuntime {
   }
 
   async interruptRemoteTurn(remoteSessionId: string, turnId: string, sessionId?: string): Promise<void> {
+    for (const session of this.sessions.values()) {
+      if (session.remoteSessionId === remoteSessionId) session.planContinuationTurnId = undefined;
+    }
+    for (const pending of this.modeChanges.values()) {
+      if (pending.turnId === turnId) pending.decision = "cancel";
+    }
     await (await this.client()).request(
       "turn/interrupt",
       { threadId: remoteSessionId, turnId },
@@ -645,17 +684,51 @@ export class CodexRuntime implements AgentRuntime {
     });
   }
 
-  async archiveRemoteSession(remoteSessionId: string): Promise<void> {
-    await (await this.client()).request(
-      "thread/archive",
-      { threadId: remoteSessionId },
-      CONTROL_REQUEST_TIMEOUT_MS,
-    );
+  async archiveRemoteSession(remoteSessionId: string, options: { allowUnmaterialized?: boolean } = {}): Promise<void> {
+    const client = await this.client();
+    try {
+      await client.request("thread/archive", { threadId: remoteSessionId }, CONTROL_REQUEST_TIMEOUT_MS);
+    } catch (error) {
+      if (!options.allowUnmaterialized || !(error instanceof AppServerRequestError)
+        || error.method !== "thread/archive" || error.code !== -32600
+        || error.serverMessage !== `no rollout found for thread id ${remoteSessionId}`
+        || !await this.isUnmaterializedThread(client, remoteSessionId)) throw error;
+      // Codex has nothing to move to its archive before the first user message.
+      const result = await client.request<{ status: string }>(
+        "thread/unsubscribe", { threadId: remoteSessionId }, CONTROL_REQUEST_TIMEOUT_MS,
+      );
+      if (!["unsubscribed", "notLoaded", "notSubscribed"].includes(result.status)) {
+        throw new Error(`Cannot release empty App Server task: ${result.status}`);
+      }
+      this.logger.info({ remoteSessionId }, "Released an empty App Server task without a materialized rollout.");
+    }
     for (const [localSessionId, session] of this.sessions) {
       if (session.remoteSessionId === remoteSessionId) this.sessions.delete(localSessionId);
     }
   }
 
+  private async isUnmaterializedThread(client: AppServerClient, remoteSessionId: string): Promise<boolean> {
+    const { thread } = await client.request<ThreadReadResponse>(
+      "thread/read", { threadId: remoteSessionId, includeTurns: false }, CONTROL_REQUEST_TIMEOUT_MS,
+    );
+    if (thread.id !== remoteSessionId || thread.preview !== "" || thread.forkedFromId !== null
+      || !["idle", "notLoaded"].includes(thread.status?.type ?? "") || !thread.path
+      || (thread.turns?.length ?? 0) > 0) return false;
+    for (const session of this.sessions.values()) {
+      if (session.remoteSessionId === remoteSessionId && (session.activeTurnId
+        || session.knownTurnIds.size > 0 || (session.turnCount ?? 0) > 0)) return false;
+    }
+    const active = await this.localActivityDetector?.activeThreads([remoteSessionId]);
+    if (active?.has(remoteSessionId)) return false;
+    try {
+      statSync(thread.path);
+      return false;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return true;
+      throw error;
+    }
+  }
+
   async setTitle(sessionId: string, title: string): Promise<void> {
     return this.runSessionOperation(sessionId, () => this.setTitleNow(sessionId, title));
   }
@@ -696,7 +769,6 @@ export class CodexRuntime implements AgentRuntime {
     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 },
@@ -738,7 +810,16 @@ export class CodexRuntime implements AgentRuntime {
     settings: RuntimeExecutionSettings,
     persist?: (session: RuntimeSession) => Promise<void>,
   ): Promise<RuntimeSession> {
-    return this.runSessionOperation(sessionId, () => this.setExecutionSettingsNow(sessionId, settings, persist));
+    return this.runSessionOperation(sessionId, async () => {
+      try {
+        return await this.setExecutionSettingsNow(sessionId, settings, persist);
+      } catch (error) {
+        if (error instanceof ProviderSwitchError) throw error;
+        // Errors outside the mutation block are preflight failures; no settings were changed.
+        const session = this.sessions.get(sessionId);
+        throw new ProviderSwitchError(providerSwitchFailure(error), Boolean(session && !session.needsResume && !session.settingsRecoveryError), { cause: error });
+      }
+    });
   }
 
   private async setExecutionSettingsNow(
@@ -756,82 +837,54 @@ export class CodexRuntime implements AgentRuntime {
     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()) {
+    if (session.turnCount === 0 && !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;
+        if (turns.length === 0) throw new Error(PROVIDER_SWITCH_EMPTY);
       } 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;
+        throw new Error(PROVIDER_SWITCH_EMPTY, { cause: error });
       }
     }
     const previous = { ...session };
-    let replacementId: string | undefined;
+    const restoreProvider = previous.modelProvider?.trim()
+      || (metadata.thread.id === previous.remoteSessionId ? metadata.thread.modelProvider?.trim() : 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;
-      }
-      let response: ThreadResponse;
-      if (empty) {
-        response = await client.request<ThreadResponse>("thread/start", {
-          ...params, threadSource: "user", allowProviderModelFallback: false,
-        }, SESSION_REQUEST_TIMEOUT_MS);
-        replacementId = response.thread.id;
-      } else {
-        response = await client.request<ThreadResponse>("thread/resume", {
-          ...params, threadId: session.remoteSessionId, excludeTurns: true,
-        }, SESSION_REQUEST_TIMEOUT_MS);
-        if (!providerSettingsMatch(response, settings)) {
-          this.logger.warn(
-            {
-              sessionId,
-              threadId: session.remoteSessionId,
-              requestedProvider: settings.modelProvider,
-              actualProvider: response.modelProvider,
-              requestedModel: settings.model,
-              actualModel: response.model,
-            },
-            "App Server did not apply Provider settings while resuming; forking the latest completed Turn.",
-          );
-          await this.detachThreadForSettings(client, session);
-          response = await this.forkThreadForSettings(client, session, settings);
-          replacementId = response.thread.id;
-        }
-      }
+      await this.detachThreadForSettings(client, session, () => { detached = true; });
+      const response = await client.request<ThreadResponse>("thread/resume", {
+        ...params, threadId: session.remoteSessionId, excludeTurns: true,
+      }, SESSION_REQUEST_TIMEOUT_MS);
       assertProviderSettingsApplied(response, settings);
-      if (!empty && !replacementId && response.thread.id !== session.remoteSessionId) {
+      if (response.thread.id !== session.remoteSessionId) {
         throw new Error("App Server 返回了不同的任务 ID，未保存设置。");
       }
-      if (session.title && (empty || replacementId)) 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,
+      const candidate = { ...session, ...settings,
         workspaceSandboxPolicy: workspaceSandboxFromResponse(response.sandbox),
         needsResume: false, settingsRecoveryError: undefined };
       await persist?.(candidate);
-      Object.assign(session, candidate);
+      Object.assign(session, settings);
+      session.workspaceSandboxPolicy = candidate.workspaceSandboxPolicy;
+      session.needsResume = this.attachedClient !== client;
+      session.settingsRecoveryError = undefined;
     } catch (error) {
-      if (replacementId) await this.discardUnusedThread(client, replacementId);
       let recovery = "原任务设置未更改。";
       if (detached) {
         try {
+          if (!restoreProvider) throw new Error("无法确认切换前的 Provider，不能验证原设置已恢复。");
           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,
+            modelProvider: restoreProvider, 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,
+          assertProviderSettingsApplied(restored, {
+            modelProvider: restoreProvider, model: previous.model,
           });
           if (restored.thread.id !== previous.remoteSessionId) throw new Error("恢复时返回了不同的任务 ID。");
           session.needsResume = false;
@@ -844,60 +897,42 @@ export class CodexRuntime implements AgentRuntime {
           session.needsResume = true;
         }
       }
-      throw new Error(`Provider 切换失败：${providerSwitchFailure(error)} ${recovery}`, { cause: error });
+      throw new ProviderSwitchError(
+        `Provider 切换失败：${providerSwitchFailure(error)} ${recovery}`,
+        !session.needsResume && !session.settingsRecoveryError, { cause: error },
+      );
     }
-    if (replacementId) await this.discardUnusedThread(client, previous.remoteSessionId);
     return session;
   }
 
-  private async detachThreadForSettings(client: AppServerClient, session: CodexSession): Promise<void> {
+  private async detachThreadForSettings(client: AppServerClient, session: CodexSession, onDetach?: () => void): 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);
+    // A timeout does not cancel the remote unsubscribe, so recovery is required once it is sent.
+    onDetach?.();
     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。请先在原客户端释放任务。");
+    if (!["unsubscribed", "notLoaded", "notSubscribed"].includes(result.status)) {
+      throw new Error(`App Server 返回了未知的取消订阅状态：${result.status}`);
     }
   }
 
-  private async forkThreadForSettings(
-    client: AppServerClient,
-    session: CodexSession,
-    settings: RuntimeExecutionSettings,
-  ): Promise<ThreadResponse> {
-    const turns = await this.listRecentThreadTurnsThroughCompleted(client, session.remoteSessionId);
-    const lastTurnId = turns.find((turn) => turn.status === "completed")?.id;
-    if (!lastTurnId) {
-      throw new Error("无法为 Provider 切换找到已完成的 Turn。请先完成一轮任务后重试。");
-    }
-    return client.request<ThreadResponse>("thread/fork", {
-      threadId: session.remoteSessionId,
-      lastTurnId,
-      cwd: session.cwd,
-      model: settings.model,
-      modelProvider: settings.modelProvider,
-      threadSource: "user",
-      excludeTurns: true,
-      ...threadLifecycleParams(session.cwd),
-      ...permissionParams(settings.permissionMode),
-    }, FORK_REQUEST_TIMEOUT_MS);
-  }
-
-  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,
+    decision: ApprovalDecision,
+  ): Promise<void> {
+    return this.resolveApproval(sessionId, requestId, decision);
   }
 
-  async respondToApproval(
+  private async resolveApproval(
     sessionId: string,
     requestId: string,
     decision: ApprovalDecision,
+    automatic = false,
   ): Promise<void> {
     const modeChange = this.modeChanges.get(requestId);
     if (modeChange) {
@@ -910,6 +945,8 @@ export class CodexRuntime implements AgentRuntime {
       }
       if (modeChange.responding) throw new Error("Approval response is already in progress.");
       modeChange.responding = true;
+      modeChange.decision = decision;
+      modeChange.automatic = automatic;
       try {
         const client = await this.client();
         if (this.modeChanges.get(requestId) !== modeChange) throw new Error("Approval request is no longer pending.");
@@ -919,11 +956,14 @@ export class CodexRuntime implements AgentRuntime {
           decision: decision === "accept" ? "approved" : decision === "decline" ? "rejected" : "cancelled",
         }, CONTROL_REQUEST_TIMEOUT_MS);
         if (this.modeChanges.get(requestId) === modeChange) {
+          this.confirmPlanContinuation(modeChange, decision);
           this.modeChanges.delete(requestId);
-          this.emit({ type: "approval_resolved", sessionId, turnId: modeChange.turnId, requestId, decision });
+          this.emit({ type: "approval_resolved", sessionId, turnId: modeChange.turnId, requestId, decision,
+            ...(automatic ? { automatic: true } : {}) });
         }
       } finally {
         modeChange.responding = false;
+        if (modeChange.terminalEvent) this.emit(modeChange.terminalEvent);
       }
       return;
     }
@@ -1174,34 +1214,45 @@ export class CodexRuntime implements AgentRuntime {
       const requestId = `mode:${mapped.threadId}:${mapped.requestId}`;
       if (session.modeChangeRequestIds.has(requestId)) return;
       session.modeChangeRequestIds.add(requestId);
-      this.modeChanges.set(requestId, {
+      const pending: PendingModeChange = {
         sessionId, turnId: mapped.turnId, requestId: mapped.requestId,
         targetMode: mapped.targetMode, responding: false,
-      });
-      this.emit({
-        type: "approval_requested", sessionId, turnId: mapped.turnId,
-        request: {
-          id: requestId,
-          kind: "mode_change",
-          title: mapped.targetMode === "default" ? "确认方案并开始执行" : "确认进入规划模式",
-          reason: [mapped.reason, ...(mapped.allowedPrompts ?? []).map((entry) => `- ${entry.tool}: ${entry.prompt}`)]
-            .filter(Boolean).join("\n"),
-          options: [
-            { id: "accept", label: mapped.targetMode === "default" ? "Approve Plan" : "Enter Plan Mode" },
-            { id: "decline", label: "Reject" },
-            { id: "cancel", label: "Cancel Request" },
-          ],
-        },
-      });
+      };
+      this.modeChanges.set(requestId, pending);
+      const automatic = session.permissionMode === "auto" && this.provider.getAgentFamily?.() === "traex";
+      const request: ApprovalRequest = {
+        id: requestId,
+        kind: "mode_change",
+        ...(automatic ? { automatic: true } : {}),
+        title: mapped.targetMode === "default" ? "确认方案并开始执行" : "确认进入规划模式",
+        reason: [mapped.reason, ...(mapped.allowedPrompts ?? []).map((entry) => `- ${entry.tool}: ${entry.prompt}`)]
+          .filter(Boolean).join("\n"),
+        options: [
+          { id: "accept", label: mapped.targetMode === "default" ? "Approve Plan" : "Enter Plan Mode" },
+          { id: "decline", label: "Reject" },
+          { id: "cancel", label: "Cancel Request" },
+        ],
+      };
+      this.emit({ type: "approval_requested", sessionId, turnId: mapped.turnId, request });
+      if (automatic) {
+        void this.resolveApproval(sessionId, requestId, "accept", true).catch((error: unknown) => {
+          this.logger.warn({ error, sessionId, requestId }, "Failed to automatically approve the TraeX mode change.");
+          if (this.modeChanges.get(requestId) !== pending || session.activeTurnId !== mapped.turnId) return;
+          this.emit({ type: "approval_requested", sessionId, turnId: mapped.turnId,
+            request: { ...request, automatic: false, reason: ["自动同意失败，请手动确认。", request.reason].filter(Boolean).join("\n\n") } });
+        });
+      }
     } else if (mapped.kind === "mode_change_resolved") {
       const requestId = `mode:${mapped.threadId}:${mapped.requestId}`;
       const pending = this.modeChanges.get(requestId);
       if (!pending || pending.sessionId !== sessionId || pending.turnId !== mapped.turnId
         || pending.targetMode !== mapped.targetMode) return;
+      this.confirmPlanContinuation(pending, mapped.decision === "approved" ? "accept" : "decline");
       this.modeChanges.delete(requestId);
       this.emit({
         type: "approval_resolved", sessionId, turnId: mapped.turnId, requestId,
         decision: mapped.decision === "approved" ? "accept" : mapped.decision === "rejected" ? "decline" : "cancel",
+        ...(pending.automatic && mapped.decision === "approved" ? { automatic: true } : {}),
       });
     } else if (mapped.kind === "token_usage") {
       this.emit({
@@ -1232,6 +1283,7 @@ export class CodexRuntime implements AgentRuntime {
       if (mapped.phase === "final_answer") this.promoteUnphasedMessage(session, mapped.turnId, mapped.itemId);
       else if (session.unphasedFinalMessageId === mapped.itemId) session.unphasedFinalMessageId = undefined;
     } else if (mapped.kind === "agent_delta") {
+      this.clearPlanContinuation(session, mapped.turnId);
       const phase = session.messagePhases.get(mapped.itemId);
       if (phase !== "final_answer") {
         // Providers may omit phase. Keep their text in sequence until a tool or completion disambiguates it.
@@ -1283,6 +1335,8 @@ export class CodexRuntime implements AgentRuntime {
     } else if (mapped.kind === "plan") {
       this.emit({ type: "plan_updated", sessionId, turnId: mapped.turnId, steps: mapped.steps });
     } else if (mapped.kind === "tool") {
+      // A backend that resumes tool execution itself needs no client handoff.
+      if (mapped.phase === "started") this.clearPlanContinuation(session, mapped.turnId);
       if (mapped.phase === "started") session.unphasedFinalMessageId = undefined;
       if (
         mapped.phase === "updated"
@@ -1409,6 +1463,8 @@ export class CodexRuntime implements AgentRuntime {
       ...threadLifecycleParams(session.cwd),
       ...permissionParams(session.permissionMode),
     }, SESSION_REQUEST_TIMEOUT_MS);
+    if (response.thread.id !== session.remoteSessionId) throw new Error("App Server 返回了不同的任务 ID，未恢复会话。");
+    assertProviderSettingsApplied(response, { modelProvider: session.modelProvider });
     session.workspaceSandboxPolicy = workspaceSandboxFromResponse(response.sandbox);
   }
 
@@ -1487,13 +1543,13 @@ 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.planContinuationTurnId = undefined;
     session.modeChangeRequestIds.clear();
     session.unphasedMessages.clear();
     session.unphasedFinalMessageId = undefined;
@@ -1596,7 +1652,6 @@ export class CodexRuntime implements AgentRuntime {
       unphasedMessages: new Map(),
       needsResume: false,
       workspaceSandboxPolicy: workspaceSandboxFromResponse(response.sandbox),
-      canReplaceEmptyThread: !("remoteSessionId" in input),
       rolloutPath: stringValue(response.thread.path)?.trim() || undefined,
       turnCount: "remoteSessionId" in input ? undefined : 0,
       knownTurnIds: new Set(),
@@ -1626,10 +1681,38 @@ export class CodexRuntime implements AgentRuntime {
     return session;
   }
 
+  private clearPlanContinuation(session: CodexSession, turnId: string): void {
+    session.planContinuationTurnId = undefined;
+    for (const pending of this.modeChanges.values()) {
+      if (pending.sessionId === session.localSessionId && pending.turnId === turnId && pending.responding) {
+        pending.continued = true;
+      }
+    }
+  }
+
+  private confirmPlanContinuation(pending: PendingModeChange, decision: ApprovalDecision): void {
+    const session = this.sessions.get(pending.sessionId);
+    // Do not start work approved in a different client.
+    if (session && pending.responding && !pending.continued && pending.decision === "accept" && decision === "accept"
+      && pending.targetMode === "default") session.planContinuationTurnId = pending.turnId;
+  }
+
   private emit(event: RuntimeEvent): void {
     if (event.type === "turn_completed" || event.type === "turn_cancelled" || event.type === "turn_failed") {
       for (const [requestId, pending] of this.modeChanges) {
-        if (pending.sessionId === event.sessionId && pending.turnId === event.turnId) this.modeChanges.delete(requestId);
+        if (pending.sessionId !== event.sessionId || pending.turnId !== event.turnId) continue;
+        if (event.type === "turn_completed" && pending.responding && pending.decision === "accept"
+          && pending.targetMode === "default") {
+          // The terminal notification may beat the approval RPC response.
+          pending.terminalEvent = event;
+          return;
+        }
+        this.modeChanges.delete(requestId);
+      }
+      const session = this.sessions.get(event.sessionId);
+      if (session?.planContinuationTurnId === event.turnId) {
+        session.planContinuationTurnId = undefined;
+        if (event.type === "turn_completed") event = { ...event, approvedPlan: true };
       }
     }
     for (const listener of this.listeners) listener(event);
@@ -1642,6 +1725,7 @@ export class CodexRuntime implements AgentRuntime {
     this.modeChanges.clear();
     for (const session of this.sessions.values()) {
       session.needsResume = true;
+      session.planContinuationTurnId = undefined;
       const turnId = session.activeTurnId;
       if (!turnId) continue;
       session.activeTurnId = undefined;
@@ -2037,13 +2121,6 @@ function remoteThreadStatus(value: string | undefined): RemoteSessionSummary["st
   return "not_loaded";
 }
 
-function providerSettingsMatch(
-  response: Pick<ThreadResponse, "modelProvider" | "model">,
-  settings: RuntimeExecutionSettings,
-): boolean {
-  return response.modelProvider === settings.modelProvider && response.model === settings.model;
-}
-
 function codexSourceLabel(source: unknown): string {
   if (typeof source === "string") return source;
   if (isRecord(source)) {

package/src/codex/ProviderSwitch.ts

@@ -1,24 +1,23 @@
-import { AppServerRequestError } from "./AppServerConnection.js";
 import type { RuntimeExecutionSettings } from "../runtime/types.js";
 
 export const PROVIDER_SWITCH_BUSY = "当前任务正在执行，暂时不能切换 Provider。请等待任务完成，或停止任务后重试。";
+export const PROVIDER_SWITCH_EMPTY = "App Server 尚未保存此空会话，无法在保留任务 ID 的前提下切换 Provider。未改变会话或设置，也不会自动创建替代任务。";
 
-export function isMissingRolloutError(error: unknown): boolean {
-  if (error instanceof AppServerRequestError && error.method !== "thread/resume") return false;
-  const message = error instanceof AppServerRequestError ? error.serverMessage
-    : error instanceof Error ? error.message : String(error);
-  if (/paginated history lineage|missing source rollout/iu.test(message)) return false;
-  return /no rollout found|rollout[^\n]*(?:not found|missing)/iu.test(message);
+export class ProviderSwitchError extends Error {
+  constructor(message: string, readonly previousSettingsRestored: boolean, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "ProviderSwitchError";
+  }
 }
 
 export function assertProviderSettingsApplied(
   actual: { modelProvider?: string; model?: string },
-  requested: Pick<RuntimeExecutionSettings, "modelProvider" | "model">,
+  requested: Partial<Pick<RuntimeExecutionSettings, "modelProvider" | "model">>,
 ): void {
-  if (actual.modelProvider !== requested.modelProvider) {
-    throw new Error(`Provider 未生效：请求 ${requested.modelProvider}，实际返回 ${actual.modelProvider ?? "未知"}。`);
+  if (requested.modelProvider !== undefined && actual.modelProvider !== requested.modelProvider) {
+    throw new Error(`Provider 未生效：请求 ${requested.modelProvider}，实际返回 ${actual.modelProvider ?? "未知"}。App Server 未应用设置；可在任务空闲后安全重启再重试，不会自动 Fork 或更改历史。`);
   }
-  if (actual.model !== requested.model) {
+  if (requested.model !== undefined && actual.model !== requested.model) {
     throw new Error(`模型未生效：请求 ${requested.model}，实际返回 ${actual.model ?? "未知"}。请确认目标 Provider 支持该模型。`);
   }
 }
@@ -29,7 +28,7 @@ export function providerSwitchFailure(error: unknown): string {
   if (/model[^\n]*(?:unsupported|not supported|not found|unavailable|does not exist)|unknown model/iu.test(message)) {
     return `目标 Provider 不支持当前模型，请选择兼容的模型后重试。${message}`;
   }
-  if (/unauthorized|forbidden|auth(?:entication|orization)|api.?key|provider[^\n]*(?:not found|unknown|not configured)/iu.test(message)) {
+  if (/unauthorized|forbidden|auth(?:enticat(?:e|ion)|orization)|api.?key|provider[^\n]*(?:not found|unknown|not configured)/iu.test(message)) {
     return `请检查目标 Provider 的配置和认证信息。${message}`;
   }
   return message;

package/src/config/AgentExecutionDefaultsStore.ts

@@ -33,7 +33,9 @@ export function writeAgentExecutionDefaults(
   for (const key of DEFAULT_KEYS) {
     const value = defaults[key];
     if (value !== undefined) target.set(key, value);
+    else target.delete(key);
   }
+  if (target.items.length === 0) agent.delete("defaults");
 
   const updated = document.toString();
   if (updated === original) return false;

package/src/config/loadConfig.ts

@@ -30,6 +30,10 @@ updates:
   # Daily stable update check, private 60-second cancellation window, then safe update.
   enabled: true
 
+terminal:
+  enabled: true
+  # Shares fileViewer host, port and publicBaseUrl; keeps independent owner authorization.
+
 fileViewer:
   enabled: true
   # Use 0.0.0.0 to accept LAN connections and automatically prefer