@downcity/agent 1.1.408 → 1.1.437

package/bin/session/SessionLoop.js

@@ -6,11 +6,16 @@
  * - 不把调度逻辑塞进 Executor；Executor 继续只负责单次执行。
  * - Queue 由 Session 持有；这里不解释配置种类，只执行出队 Command。
  */
+import { createHash } from "node:crypto";
 import { nanoid } from "nanoid";
 import { is_agent_session_prompt_input_empty } from "../types/sdk/AgentSessionPrompt.js";
-import { create_session_turn_context } from "./runtime/SessionTurnContext.js";
-import { SessionAssistantOutputAdapter } from "./execution/SessionAssistantOutputAdapter.js";
-import { SessionCommand } from "./SessionCommand.js";
+import { create_session_turn_context } from "../session/runtime/SessionTurnContext.js";
+import { normalize_session_user_parts, } from "../session/SessionMessages.js";
+import { SessionAssistantOutputAdapter } from "../session/execution/SessionAssistantOutputAdapter.js";
+import { extract_session_message_text } from "../session/messages/SessionMessageText.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";
 const TURN_STOPPED_MESSAGE = "Turn stopped";
 const QUEUED_PROMPT_CANCELLED_MESSAGE = "Prompt cancelled because session was stopped";
 /**
@@ -18,9 +23,10 @@ const QUEUED_PROMPT_CANCELLED_MESSAGE = "Prompt cancelled because session was st
  */
 export class SessionLoop {
     session_id;
+    session_origin;
     workspace_path;
     executor;
-    compact_history_handler;
+    maintain_context;
     state;
     messages;
     events;
@@ -31,12 +37,14 @@ export class SessionLoop {
     pending_prompt_count = 0;
     processing_promise = null;
     active_turn = null;
-    checkpoint_merged_messages = null;
+    /** 尚未完成 canonical 接收的幂等 Prompt，防止进程内并发重复入队。 */
+    pending_request_handles = new Map();
     constructor(options) {
         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;
@@ -59,20 +67,55 @@ 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 加入队列。 */
+    async prompt_with_identity(input, request_identity) {
+        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。 */
+    async enqueue_prompt(input, request_identity, persisted_message) {
         const deferred_handle = create_deferred();
         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) {
+        this.queue.enqueue_command(command);
+        this.ensure_processing();
+    }
     /**
      * 判断是否存在等待并入下一 Session step 的 prompt。
      */
@@ -101,7 +144,7 @@ export class SessionLoop {
      * - Session 会用它阻止内部 direct execution 与 actor 模式并发混用。
      */
     is_active() {
-        return this.processing_promise !== null || this.has_pending_prompt();
+        return this.processing_promise !== null || this.has_pending_command();
     }
     /**
      * 停止当前 turn，并取消尚未被吸收的排队 prompt。
@@ -125,14 +168,21 @@ export class SessionLoop {
             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();
             }
         });
     }
     async process_loop() {
-        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);
@@ -145,18 +195,28 @@ export class SessionLoop {
                 status: "running",
                 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 级维护命令。 */
+    async execute_maintenance_command(command) {
+        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 继续执行。
             }
         }
     }
@@ -166,45 +226,38 @@ export class SessionLoop {
     /**
      * 在下一 Session step 检查点按入队顺序提交配置并持久化 steer。
      */
-    async drain_queued_inputs(active_turn) {
+    async drain_queued_inputs() {
         const drained = this.queue.drain();
         if (drained.length <= 0)
-            return [];
-        const merged = [];
-        this.checkpoint_merged_messages = merged;
-        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;
-                }
+            return;
+        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 完成信息。 */
     async execute_command(command) {
-        const completion = await command.execute();
+        await command.execute();
+        const completion = command.completion;
         if (!completion)
             return;
         await this.persist_command_completion(completion);
     }
     /** 持久化 Command 完成信息；观测失败不能反向改变已经提交的领域状态。 */
     async persist_command_completion(completion) {
-        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 }
@@ -227,63 +280,32 @@ export class SessionLoop {
             }
         }
     }
-    /** 在当前 Turn 上执行一次显式历史压缩。 */
-    async compact_history(compact_id) {
-        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 合并。 */
-    async execute_prompt_command(input, deferred_handle) {
+    async execute_prompt_command(input, deferred_handle, message_id, persisted_message) {
         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");
+            const message = await this.persist_prompt_message(input, active_turn.turn_id);
+            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;
         }
         active_turn.prompt_started = true;
         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，而不是永久等待。
@@ -298,78 +320,12 @@ export class SessionLoop {
             return this.active_turn;
         throw new Error("Session Command requires an active Turn");
     }
-    /** 用 Executor 结果结束当前 Active Turn。 */
-    async finish_active_turn(active_turn, result) {
-        const stopped = active_turn.turn_context?.lifecycle.abort_signal.aborted === true;
-        const final_result = {
-            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。 */
     async fail_active_turn(active_turn, error) {
-        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 = {
-            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 创建可观测取消结果。 */
     resolve_cancelled_prompt(deferred_handle) {
@@ -412,17 +368,32 @@ 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;
-        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({
             status: turn_context.lifecycle.abort_signal.aborted
@@ -432,23 +403,8 @@ export class SessionLoop {
                     : "failed",
             ...(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,
@@ -465,61 +421,89 @@ 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)
+            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();
-                return merged;
             },
-            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,
+                }));
+            },
         });
     }
     /** 持久化本轮 User 输入，并同步刷新标题与 metadata。 */
-    async persist_prompt_message(prompt, turn_id, input_type) {
+    async persist_prompt_message(prompt, turn_id, message_id) {
         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。 */
+    async resolve_idempotent_prompt(identity) {
+        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。 */
     async persist_action_event(event, options) {
         await this.messages.persist_action(event, options);
-        await this.state.touch_metadata();
     }
-    /** 由 Turn 生命周期所有者尽力释放其唯一 Context。 */
-    async dispose_turn_context(active_turn) {
-        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 收口领域函数投影稳定依赖。 */
+    turn_completion_options() {
+        return {
+            session_id: this.session_id,
+            messages: this.messages,
+            events: this.events,
+            logger: this.logger,
+            stopped_message: TURN_STOPPED_MESSAGE,
+        };
     }
 }
 function create_deferred() {
@@ -538,7 +522,6 @@ function create_active_session_turn_state(turn_id) {
         result: null,
         deferred_finished: create_deferred(),
         turn_context: null,
-        history_reload_requested: false,
         prompt_started: false,
     };
 }
@@ -551,4 +534,42 @@ function create_turn_handle(active_turn) {
         finished: active_turn.deferred_finished.promise,
     };
 }
+/** 把调用方业务键映射为不暴露原值的 Session 内稳定身份。 */
+function resolve_prompt_request_identity(session_id, request_id_input) {
+    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, message) {
+    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) {
+    return {
+        id: result.turn_id,
+        result,
+        finished: Promise.resolve(result),
+    };
+}
 //# sourceMappingURL=SessionLoop.js.map