@downcity/agent 1.1.408 → 1.1.437

package/src/session/SessionLoop.ts

@@ -7,9 +7,10 @@
  * - Queue 由 Session 持有；这里不解释配置种类，只执行出队 Command。
  */
 
+import { createHash } from "node:crypto";
 import { nanoid } from "nanoid";
-import type { SessionUserMessage } from "@/types/session/SessionMessage.js";
-import type { SessionActionEvent } from "@/types/session/SessionAction.js";
+import type { SessionAgentMessage, SessionUserMessage } from "@downcity/type";
+import type { SessionActionEvent } from "@downcity/type";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type {
@@ -18,7 +19,6 @@ import type {
 } from "@/types/sdk/AgentSessionTurn.js";
 import { is_agent_session_prompt_input_empty } from "@/types/sdk/AgentSessionPrompt.js";
 import type {
-  SessionCompactHistory,
   SessionExecutor,
   SessionTurnExecutionResult,
 } from "@/types/session/SessionExecution.js";
@@ -26,21 +26,37 @@ import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js"
 import { create_session_turn_context } from "@/session/runtime/SessionTurnContext.js";
 import { SessionEventHub } from "@/session/runtime/SessionEventHub.js";
 import { SessionState } from "@/session/SessionState.js";
-import { SessionMessages } from "@/session/SessionMessages.js";
-import type { ShellApprovalGateway } from "@downcity/workspace";
+import {
+  normalize_session_user_parts,
+  SessionMessages,
+} from "@/session/SessionMessages.js";
+import type { ShellApprovalGateway } from "@downcity/type";
 import type {
   SessionInteractionLifecycle,
   SessionInteractionPort,
-} from "@/types/session/SessionInteraction.js";
+} from "@downcity/type";
 import { SessionAssistantOutputAdapter } from "@/session/execution/SessionAssistantOutputAdapter.js";
 import { SessionQueue } from "@/session/SessionQueue.js";
-import { SessionCommand } from "@/session/SessionCommand.js";
+import { extract_session_message_text } from "@/session/messages/SessionMessageText.js";
 import type {
   ActiveSessionTurnState,
   SessionDeferred,
   SessionLoopOptions,
 } from "@/types/session/SessionLoop.js";
-import type { SessionCommandCompletion } from "@/types/session/SessionCommand.js";
+import type {
+  SessionCommand,
+  SessionCommandCompletion,
+} from "@/types/session/SessionCommand.js";
+import { create_session_model_request_warning } from "@/session/runtime/SessionModelRequestWarning.js";
+import {
+  complete_session_turn,
+  fail_session_turn,
+} from "@/session/runtime/SessionTurnCompletion.js";
+import {
+  append_session_turn_file_diff,
+  publish_session_turn_file_diff,
+} from "@/session/runtime/SessionTurnFileDiff.js";
+import type { SessionTurnCompletionOptions } from "@/types/session/SessionTurnCompletion.js";
 
 const TURN_STOPPED_MESSAGE = "Turn stopped";
 const QUEUED_PROMPT_CANCELLED_MESSAGE =
@@ -51,9 +67,10 @@ const QUEUED_PROMPT_CANCELLED_MESSAGE =
  */
 export class SessionLoop {
   private readonly session_id: string;
+  private readonly session_origin: SessionLoopOptions["session_origin"];
   private readonly workspace_path: string;
   private readonly executor: SessionExecutor;
-  private readonly compact_history_handler: SessionCompactHistory;
+  private readonly maintain_context: SessionLoopOptions["maintain_context"];
   private readonly state: SessionState;
   private readonly messages: SessionMessages;
   private readonly events: SessionEventHub;
@@ -65,13 +82,15 @@ export class SessionLoop {
   private pending_prompt_count = 0;
   private processing_promise: Promise<void> | null = null;
   private active_turn: ActiveSessionTurnState | null = null;
-  private checkpoint_merged_messages: SessionUserMessage[] | null = null;
+  /** 尚未完成 canonical 接收的幂等 Prompt，防止进程内并发重复入队。 */
+  private readonly pending_request_handles = new Map<string, Promise<AgentSessionTurnHandle>>();
 
   constructor(options: SessionLoopOptions) {
     this.session_id = String(options.session_id || "").trim();
+    this.session_origin = options.session_origin;
     this.workspace_path = String(options.workspace_path || "").trim();
     this.executor = options.executor;
-    this.compact_history_handler = options.compact_history;
+    this.maintain_context = options.maintain_context;
     this.state = options.state;
     this.messages = options.messages;
     this.events = options.events;
@@ -95,21 +114,67 @@ export class SessionLoop {
       throw new Error("session.prompt requires a non-empty query");
     }
     await this.state.ensure_runnable();
+    const request_identity = resolve_prompt_request_identity(this.session_id, input.request_id);
+    if (!request_identity) return await this.enqueue_prompt(input);
+    const pending_handle = this.pending_request_handles.get(request_identity.turn_id);
+    if (pending_handle) return await pending_handle;
+    const operation = this.prompt_with_identity(input, request_identity);
+    this.pending_request_handles.set(request_identity.turn_id, operation);
+    try {
+      return await operation;
+    } finally {
+      if (this.pending_request_handles.get(request_identity.turn_id) === operation) {
+        this.pending_request_handles.delete(request_identity.turn_id);
+      }
+    }
+  }
+
+  /** 解析已有幂等结果，或把同一个稳定 Prompt 加入队列。 */
+  private async prompt_with_identity(
+    input: AgentSessionPromptInput,
+    request_identity: PromptRequestIdentity,
+  ): Promise<AgentSessionTurnHandle> {
+    const existing_handle = await this.resolve_idempotent_prompt(request_identity);
+    if (existing_handle) return existing_handle;
+    const persisted_message = this.messages.get_message(request_identity.message_id);
+    return await this.enqueue_prompt(input, request_identity, persisted_message?.role === "user"
+      ? persisted_message
+      : undefined);
+  }
+
+  /** 把一个已校验的 Prompt 加入 Session FIFO。 */
+  private async enqueue_prompt(
+    input: AgentSessionPromptInput,
+    request_identity?: PromptRequestIdentity,
+    persisted_message?: SessionUserMessage,
+  ): Promise<AgentSessionTurnHandle> {
     const deferred_handle = create_deferred<AgentSessionTurnHandle>();
     this.pending_prompt_count += 1;
-    this.queue.enqueue_command(new SessionCommand({
+    this.enqueue_command({
+      kind: "prompt",
+      ...(request_identity ? { turn_id: request_identity.turn_id } : {}),
       execute: async () => {
-        await this.execute_prompt_command(input, deferred_handle);
+        await this.execute_prompt_command(
+          input,
+          deferred_handle,
+          request_identity?.message_id,
+          persisted_message,
+        );
       },
       cancel: () => {
         this.pending_prompt_count = Math.max(0, this.pending_prompt_count - 1);
         this.resolve_cancelled_prompt(deferred_handle);
       },
-    }));
-    this.ensure_processing();
+    });
     return await deferred_handle.promise;
   }
 
+  /** 追加 Command，并确保空闲 Session 也会主动消费维护操作。 */
+  enqueue_command(command: SessionCommand): void {
+    this.queue.enqueue_command(command);
+    this.ensure_processing();
+  }
+
   /**
    * 判断是否存在等待并入下一 Session step 的 prompt。
    */
@@ -142,7 +207,7 @@ export class SessionLoop {
    * - Session 会用它阻止内部 direct execution 与 actor 模式并发混用。
    */
   is_active(): boolean {
-    return this.processing_promise !== null || this.has_pending_prompt();
+    return this.processing_promise !== null || this.has_pending_command();
   }
 
   /**
@@ -174,15 +239,22 @@ export class SessionLoop {
     if (this.processing_promise) return;
     this.processing_promise = this.process_loop().finally(() => {
       this.processing_promise = null;
-      if (this.has_pending_prompt()) {
+      if (this.has_pending_command()) {
         this.ensure_processing();
       }
     });
   }
 
   private async process_loop(): Promise<void> {
-    while (this.has_pending_prompt()) {
-      const turn_id = `turn:${this.session_id}:${Date.now()}:${nanoid(6)}`;
+    while (this.has_pending_command()) {
+      const command = this.queue.take_next();
+      if (!command) return;
+      if (command.kind === "maintenance") {
+        await this.execute_maintenance_command(command);
+        continue;
+      }
+
+      const turn_id = command.turn_id || `turn:${this.session_id}:${Date.now()}:${nanoid(6)}`;
       const active_turn = create_active_session_turn_state(turn_id);
       this.active_turn = active_turn;
       active_turn.turn_context = this.create_turn_context(active_turn);
@@ -196,20 +268,26 @@ export class SessionLoop {
         created_at: Date.now(),
       });
 
-      while (this.active_turn === active_turn) {
-        const command = this.queue.take_next();
-        if (!command) {
-          await this.fail_active_turn(
-            active_turn,
-            new Error("Session Queue lost its pending Prompt Command"),
-          );
-          break;
-        }
-        try {
-          await this.execute_command(command);
-        } catch (error) {
-          await this.fail_active_turn(active_turn, error);
-        }
+      try {
+        await this.execute_command(command);
+      } catch (error) {
+        await this.fail_active_turn(active_turn, error);
+      }
+    }
+  }
+
+  /** 在没有 Active Turn 时执行 Session 级维护命令。 */
+  private async execute_maintenance_command(command: SessionCommand): Promise<void> {
+    try {
+      await this.execute_command(command);
+    } catch (error) {
+      try {
+        await this.logger.log("warn", "[agent] session maintenance command failed", {
+          session_id: this.session_id,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      } catch {
+        // Maintenance Command 已经失败，日志失败不能阻止后续 Command 继续执行。
       }
     }
   }
@@ -221,35 +299,26 @@ export class SessionLoop {
   /**
    * 在下一 Session step 检查点按入队顺序提交配置并持久化 steer。
    */
-  private async drain_queued_inputs(
-    active_turn: ActiveSessionTurnState,
-  ): Promise<SessionUserMessage[]> {
+  private async drain_queued_inputs(): Promise<void> {
     const drained = this.queue.drain();
-    if (drained.length <= 0) return [];
-    const merged: SessionUserMessage[] = [];
-    this.checkpoint_merged_messages = merged;
+    if (drained.length <= 0) return;
 
-    try {
-      for (let index = 0; index < drained.length; index += 1) {
-        const command = drained[index];
-        try {
-          await this.execute_command(command);
-        } catch {
-          // Prompt 持久化失败时恢复尚未处理的对象；Action 自己负责失败观测。
-          this.queue.restore_front(drained.slice(index));
-          break;
-        }
+    for (let index = 0; index < drained.length; index += 1) {
+      const command = drained[index];
+      try {
+        await this.execute_command(command);
+      } catch {
+        // Prompt 持久化失败时恢复尚未处理的对象；Action 自己负责失败观测。
+        this.queue.restore_front(drained.slice(index));
+        break;
       }
-    } finally {
-      this.checkpoint_merged_messages = null;
     }
-
-    return merged;
   }
 
   /** 执行 Command，并尽力持久化其声明的 canonical 完成信息。 */
   private async execute_command(command: SessionCommand): Promise<void> {
-    const completion = await command.execute();
+    await command.execute();
+    const completion = command.completion;
     if (!completion) return;
     await this.persist_command_completion(completion);
   }
@@ -258,12 +327,12 @@ export class SessionLoop {
   private async persist_command_completion(
     completion: SessionCommandCompletion,
   ): Promise<void> {
-    const turn_id = this.require_active_turn().turn_id;
+    const turn_id = this.current_turn_id();
     try {
       await this.persist_action_event({
         action_id: completion.id,
         action_type: "command",
-        turn_id,
+        ...(turn_id ? { turn_id } : {}),
         title: completion.title,
         ...(completion.description
           ? { description: completion.description }
@@ -285,58 +354,22 @@ export class SessionLoop {
     }
   }
 
-  /** 在当前 Turn 上执行一次显式历史压缩。 */
-  async compact_history(
-    compact_id: string,
-  ): ReturnType<SessionCompactHistory> {
-    const turn_id = this.require_active_turn().turn_id;
-    const result = await this.compact_history_handler({ turn_id });
-    if (
-      result.compacted &&
-      this.active_turn?.turn_context
-    ) {
-      this.require_active_turn().history_reload_requested = true;
-    }
-    if (result.reason === "nothing_to_compact") {
-      try {
-        await this.persist_action_event({
-          action_id: compact_id,
-          action_type: "history-compaction",
-          turn_id,
-          title: "Session messages already compact",
-          description: "The Session has no active messages to compact.",
-          status: "completed",
-        });
-      } catch (error) {
-        try {
-          await this.logger.log("warn", "[agent] compact result persistence failed", {
-            session_id: this.session_id,
-            compact_id,
-            error: error instanceof Error ? error.message : String(error),
-          });
-        } catch {
-          // 领域结果已经确定，Action 与日志失败都不能把成功压缩改写为失败。
-        }
-      }
-    }
-    return result;
-  }
-
   /** 执行一个出队 Prompt；首条 Prompt 启动 Turn，后续 Prompt 作为 steer 合并。 */
   private async execute_prompt_command(
     input: AgentSessionPromptInput,
     deferred_handle: SessionDeferred<AgentSessionTurnHandle>,
+    message_id?: string,
+    persisted_message?: SessionUserMessage,
   ): Promise<void> {
     const active_turn = this.require_active_turn();
     if (active_turn.prompt_started) {
       const message = await this.persist_prompt_message(
         input,
         active_turn.turn_id,
-        "steer",
       );
+      active_turn.turn_context?.input.observe_user_message(message);
       this.pending_prompt_count = Math.max(0, this.pending_prompt_count - 1);
       deferred_handle.resolve(create_turn_handle(active_turn));
-      this.checkpoint_merged_messages?.push(message);
       return;
     }
 
@@ -344,15 +377,25 @@ export class SessionLoop {
     this.pending_prompt_count = Math.max(0, this.pending_prompt_count - 1);
     let handle_resolved = false;
     try {
-      await this.persist_prompt_message(input, active_turn.turn_id, "prompt");
+      const message = persisted_message || await this.persist_prompt_message(
+          input,
+          active_turn.turn_id,
+          message_id,
+        );
+      active_turn.turn_context?.input.observe_user_message(message);
       // 只有 canonical user message 已经写入 Session 后，调用方才认为输入被接收。
       deferred_handle.resolve(create_turn_handle(active_turn));
       handle_resolved = true;
       const result = await this.execute_prompt_turn({
         active_turn,
-        prompt_input: input,
       });
-      await this.finish_active_turn(active_turn, result);
+      const final_result = await complete_session_turn(
+        this.turn_completion_options(),
+        active_turn,
+        result,
+      );
+      if (this.active_turn === active_turn) this.active_turn = null;
+      active_turn.deferred_finished.resolve(final_result);
     } catch (error) {
       // 持久化失败时仍兑现句柄，让调用方可以观察到失败的 Turn，而不是永久等待。
       if (!handle_resolved) deferred_handle.resolve(create_turn_handle(active_turn));
@@ -366,81 +409,18 @@ export class SessionLoop {
     throw new Error("Session Command requires an active Turn");
   }
 
-  /** 用 Executor 结果结束当前 Active Turn。 */
-  private async finish_active_turn(
-    active_turn: ActiveSessionTurnState,
-    result: SessionTurnExecutionResult,
-  ): Promise<void> {
-    const stopped = active_turn.turn_context?.lifecycle.abort_signal.aborted === true;
-    const final_result: AgentSessionTurnResult = {
-      turn_id: active_turn.turn_id,
-      text: result.text,
-      success: stopped ? false : result.success,
-      ...(stopped
-        ? { error: TURN_STOPPED_MESSAGE }
-        : result.error ? { error: result.error } : {}),
-    };
-    active_turn.result = final_result;
-    this.events.publish({
-      mutation_id: nanoid(),
-      variant: "turn",
-      type: "finish",
-      session_id: this.session_id,
-      turn_id: active_turn.turn_id,
-      status: stopped ? "stopped" : final_result.success ? "completed" : "failed",
-      created_at: Date.now(),
-      text: final_result.text,
-      ...(final_result.error ? { error: final_result.error } : {}),
-    });
-    await this.dispose_turn_context(active_turn);
-    active_turn.deferred_finished.resolve(final_result);
-    if (this.active_turn === active_turn) this.active_turn = null;
-  }
-
-  /** 以失败结果结束当前 Active Turn，并尽力持久化 Error Message。 */
+  /** 以失败结果结束当前 Active Turn，并尽力持久化包含 Error Part 的 Agent Message。 */
   private async fail_active_turn(
     active_turn: ActiveSessionTurnState,
     error: unknown,
   ): Promise<void> {
-    if (active_turn.result) return;
-    const stopped = active_turn.turn_context?.lifecycle.abort_signal.aborted === true;
-    const message = stopped
-      ? TURN_STOPPED_MESSAGE
-      : error instanceof Error ? error.message : String(error);
-    const final_result: AgentSessionTurnResult = {
-      turn_id: active_turn.turn_id,
-      text: "",
-      success: false,
-      error: message,
-    };
-    active_turn.result = final_result;
-    if (message !== TURN_STOPPED_MESSAGE) {
-      try {
-        await this.messages.append_error_message({
-          scope: "turn",
-          turn_id: active_turn.turn_id,
-          code: "turn_execution_failed",
-          message,
-          recoverable: true,
-        });
-      } catch {
-        // Error Message 写入失败不能阻止 Turn Handle 收口。
-      }
-    }
-    this.events.publish({
-      mutation_id: nanoid(),
-      variant: "turn",
-      type: "finish",
-      session_id: this.session_id,
-      turn_id: active_turn.turn_id,
-      status: stopped ? "stopped" : "failed",
-      created_at: Date.now(),
-      text: "",
-      error: message,
-    });
-    await this.dispose_turn_context(active_turn);
-    active_turn.deferred_finished.resolve(final_result);
+    const final_result = await fail_session_turn(
+      this.turn_completion_options(),
+      active_turn,
+      error,
+    );
     if (this.active_turn === active_turn) this.active_turn = null;
+    active_turn.deferred_finished.resolve(final_result);
   }
 
   /** 为一条尚未执行的 Prompt 创建可观测取消结果。 */
@@ -483,7 +463,6 @@ export class SessionLoop {
   /** 执行一个 Turn 内的模型与 Tool Step Loop。 */
   private async execute_prompt_turn(input: {
     active_turn: ActiveSessionTurnState;
-    prompt_input: AgentSessionPromptInput;
   }): Promise<{
     text: string;
     success: boolean;
@@ -494,17 +473,33 @@ export class SessionLoop {
     if (!turn_context || !assistant_output) {
       throw new Error("Active Session Turn requires an initialized context");
     }
-    const query = input.prompt_input.query;
-    const executor_query = typeof query === "string"
-      ? query
-      : query
-          .flatMap((part) => part.type === "text" ? [part.text] : [])
-          .join("\n")
-          .trim();
     let result: SessionTurnExecutionResult;
-    result = await this.executor.execute({
-      query: executor_query,
+    try {
+      result = await this.executor.execute({ turn_context });
+    } catch (error) {
+      result = {
+        text: "",
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+
+    if (!result.success && !turn_context.lifecycle.abort_signal.aborted && result.error) {
+      await assistant_output.append_error({
+        scope: "turn",
+        code: "turn_execution_failed",
+        message: result.error,
+        recoverable: true,
+      });
+    }
+
+    await append_session_turn_file_diff({
+      session_id: this.session_id,
+      turn_id: input.active_turn.turn_id,
+      workspace_path: this.workspace_path,
       turn_context,
+      assistant_output,
+      logger: this.logger,
     });
 
     await assistant_output.finish({
@@ -516,24 +511,8 @@ export class SessionLoop {
       ...(result.error ? { error: result.error } : {}),
     });
 
-    if (!result.success && !turn_context.lifecycle.abort_signal.aborted && result.error) {
-      await this.messages.append_error_message({
-        scope: "turn",
-        turn_id: input.active_turn.turn_id,
-        code: "turn_execution_failed",
-        message: result.error,
-        recoverable: true,
-      });
-    }
-    await this.state.touch_metadata();
-    const deferred_count = await this.messages.append_deferred_user_messages(
-      result.deferred_persisted_user_messages,
-    );
-    if (deferred_count > 0) await this.state.touch_metadata();
     if (result.compact_required) {
-      await this.compact_history_handler({
-        turn_id: input.active_turn.turn_id,
-      });
+      await this.maintain_context();
     }
     return {
       text: result.text,
@@ -553,24 +532,46 @@ export class SessionLoop {
     return create_session_turn_context({
       turn_id: active_turn.turn_id,
       session_id: this.session_id,
+      session_origin: this.session_origin,
       project_root: this.workspace_path,
-      merge_step_input: async () => {
-        const merged = await this.drain_queued_inputs(active_turn);
-        if (merged.length > 0) await assistant_output.close_current_message();
-        return merged;
+      commit_step_input: async () => {
+        const had_pending_prompt = this.has_pending_prompt();
+        await this.drain_queued_inputs();
+        if (had_pending_prompt) await assistant_output.close_current_message();
       },
-      has_pending_step_input: () => this.has_pending_prompt(),
-      consume_history_reload: () => {
-        const requested = active_turn.history_reload_requested;
-        active_turn.history_reload_requested = false;
-        return requested;
+      append_internal_user_message: async (parts) => {
+        const message = await this.messages.append_user_message({
+          turn_id: active_turn.turn_id,
+          visibility: "internal",
+          parts: normalize_session_user_parts([...parts]),
+        });
+        active_turn.turn_context?.input.observe_user_message(message);
+        return message;
       },
+      has_pending_step_input: () => this.has_pending_prompt(),
       assistant_output,
       shell_approval_gateway: this.shell_approval_gateway,
       interactions: this.interactions,
+      on_effects_changed: (effects) => {
+        publish_session_turn_file_diff({
+          session_id: this.session_id,
+          turn_id: active_turn.turn_id,
+          workspace_path: this.workspace_path,
+          effects,
+          publish: (mutation) => this.events.publish(mutation),
+          logger: this.logger,
+        });
+      },
       publish_action: async (event) => {
         await this.persist_action_event(event);
       },
+      report_model_request_failure: (notice) => {
+        this.events.publish(create_session_model_request_warning({
+          session_id: this.session_id,
+          turn_id: active_turn.turn_id,
+          notice,
+        }));
+      },
     });
   }
 
@@ -578,45 +579,52 @@ export class SessionLoop {
   private async persist_prompt_message(
     prompt: AgentSessionPromptInput,
     turn_id: string,
-    input_type: "prompt" | "steer",
+    message_id?: string,
   ): Promise<SessionUserMessage> {
     const message = await this.messages.append_prompt_message({
       project_root: this.workspace_path,
       prompt,
       turn_id,
-      input_type,
+      ...(message_id ? { message_id } : {}),
     });
-    this.state.touch_metadata_in_background();
     this.state.schedule_title_generation();
     return message;
   }
 
+  /** 解析已经持久化或仍在执行的幂等 Prompt。 */
+  private async resolve_idempotent_prompt(
+    identity: PromptRequestIdentity,
+  ): Promise<AgentSessionTurnHandle | null> {
+    const existing_message = this.messages.get_message(identity.message_id);
+    if (!existing_message) return null;
+    if (existing_message.role !== "user" || existing_message.turn_id !== identity.turn_id) {
+      throw new Error("Session prompt request identity conflicts with canonical history");
+    }
+    if (this.active_turn?.turn_id === identity.turn_id) {
+      return create_turn_handle(this.active_turn);
+    }
+    const agent_message = await this.messages.read_latest_agent_message(identity.turn_id);
+    if (!agent_message || agent_message.state === "streaming") return null;
+    return create_completed_turn_handle(to_persisted_turn_result(identity.turn_id, agent_message));
+  }
+
   /** 持久化 Executor Action，并同步刷新 Session metadata。 */
   private async persist_action_event(
     event: SessionActionEvent,
     options?: { publish_mutation?: boolean },
   ): Promise<void> {
     await this.messages.persist_action(event, options);
-    await this.state.touch_metadata();
   }
 
-  /** 由 Turn 生命周期所有者尽力释放其唯一 Context。 */
-  private async dispose_turn_context(
-    active_turn: ActiveSessionTurnState,
-  ): Promise<void> {
-    try {
-      await active_turn.turn_context?.lifecycle.dispose();
-    } catch (error) {
-      try {
-        await this.logger.log("warn", "[agent] turn context disposal failed", {
-          session_id: this.session_id,
-          turn_id: active_turn.turn_id,
-          error: error instanceof Error ? error.message : String(error),
-        });
-      } catch {
-        // Context 已进入释放流程，日志失败不能阻止 Turn Handle 收口。
-      }
-    }
+  /** 为 Turn 收口领域函数投影稳定依赖。 */
+  private turn_completion_options(): SessionTurnCompletionOptions {
+    return {
+      session_id: this.session_id,
+      messages: this.messages,
+      events: this.events,
+      logger: this.logger,
+      stopped_message: TURN_STOPPED_MESSAGE,
+    };
   }
 }
 
@@ -639,7 +647,6 @@ function create_active_session_turn_state(
     result: null,
     deferred_finished: create_deferred<AgentSessionTurnResult>(),
     turn_context: null,
-    history_reload_requested: false,
     prompt_started: false,
   };
 }
@@ -655,3 +662,59 @@ function create_turn_handle(
     finished: active_turn.deferred_finished.promise,
   };
 }
+
+/** 幂等 Prompt 在 canonical history 中使用的稳定身份。 */
+interface PromptRequestIdentity {
+  /** 稳定 User Message ID。 */
+  message_id: string;
+  /** 稳定 Turn ID。 */
+  turn_id: string;
+}
+
+/** 把调用方业务键映射为不暴露原值的 Session 内稳定身份。 */
+function resolve_prompt_request_identity(
+  session_id: string,
+  request_id_input: string | undefined,
+): PromptRequestIdentity | null {
+  const request_id = String(request_id_input || "").trim();
+  if (!request_id) return null;
+  if (request_id.length > 512) {
+    throw new Error("session.prompt request_id must not exceed 512 characters");
+  }
+  const digest = createHash("sha256")
+    .update(session_id)
+    .update("\u0000")
+    .update(request_id)
+    .digest("hex");
+  return {
+    message_id: `user-request:${digest}`,
+    turn_id: `turn-request:${digest}`,
+  };
+}
+
+/** 从已完成的 canonical Agent Message 恢复 Turn 结果。 */
+function to_persisted_turn_result(
+  turn_id: string,
+  message: SessionAgentMessage,
+): AgentSessionTurnResult {
+  const error_part = [...message.parts].reverse().find((part) => part.type === "error");
+  const error = error_part?.type === "error" ? error_part.message : undefined;
+  const success = !error;
+  return {
+    turn_id,
+    text: extract_session_message_text(message),
+    success,
+    ...(!success ? { error } : {}),
+  };
+}
+
+/** 为已经持久化完成的 Turn 创建立即兑现的句柄。 */
+function create_completed_turn_handle(
+  result: AgentSessionTurnResult,
+): AgentSessionTurnHandle {
+  return {
+    id: result.turn_id,
+    result,
+    finished: Promise.resolve(result),
+  };
+}