@downcity/agent 1.1.287 → 1.1.310

package/src/executor/core-engine/CoreEngineRunner.ts

@@ -13,30 +13,32 @@ import {
   type LanguageModel,
   type StepResult,
   type Tool,
+  type UIMessage,
 } from "ai";
-import { logAssistantMessageNow } from "@executor/messages/SessionMessageLog.js";
+import { log_assistant_message_now } from "@executor/messages/SessionMessageLog.js";
+import { pick_last_successful_chat_send_text } from "@executor/messages/UserVisibleText.js";
 import {
   MAX_INCOMPLETE_RESPONSE_RECOVERIES,
   MAX_TEXT_ONLY_CONTINUATIONS,
   MAX_TOOL_LOOP_STEPS,
-  buildIncompleteResponseRecoveryNudge,
-  buildTextOnlyContinuationNudge,
-  detectIncompleteResponse,
-  detectTextOnlyContinuationReason,
-  mergeAssistantUiMessages,
-  summarizeStepForDebug,
-  summarizeUiMessageForDebug,
-  toInlinePreview,
+  build_incomplete_response_recovery_nudge,
+  build_text_only_continuation_nudge,
+  detect_incomplete_response,
+  detect_text_only_continuation_reason,
+  merge_assistant_ui_messages,
+  summarize_step_for_debug,
+  summarize_ui_message_for_debug,
+  to_inline_preview,
 } from "@executor/core-engine/CoreEngineSignals.js";
 import {
-  evaluateCoreEngineLoopDecision,
-  shouldContinueForTailMergedUserMessages,
+  evaluate_core_engine_loop_decision,
+  should_continue_for_tail_merged_user_messages,
 } from "@executor/core-engine/CoreEngineLoopDecision.js";
 import {
-  resolveEffectiveCoreEngineError,
-  summarizeStreamError,
+  resolve_effective_core_engine_error,
+  summarize_stream_error,
 } from "@executor/core-engine/CoreEngineError.js";
-import { collectFinalAssistantMessageFromUiStream } from "@executor/core-engine/CoreEngineUiStreamCollector.js";
+import { collect_final_assistant_message_from_ui_stream } from "@executor/core-engine/CoreEngineUiStreamCollector.js";
 import { CoreEngineMessageState } from "@executor/core-engine/CoreEngineMessageState.js";
 import {
   deep_compact_model_messages,
@@ -45,11 +47,11 @@ import {
 } from "@executor/core-engine/CoreEngineContextCompaction.js";
 import type { Logger } from "@/utils/logger/Logger.js";
 import type { JsonObject } from "@/types/common/Json.js";
-import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
+import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js";
 import type {
-  SessionExecuteInput,
-  SessionRunResult,
-} from "@/executor/types/SessionRun.js";
+  SessionStepExecutionInput,
+  SessionTurnExecutionResult,
+} from "@/types/session/SessionExecution.js";
 import type {
   SessionRecordV1,
   SessionMessageRecordV1,
@@ -75,28 +77,29 @@ function build_file_part_key(part: FileUIPart): string {
 /**
  * 把 tool/plugin 运行期产生的 file parts 并入最终 assistant UIMessage。
  */
-function mergePendingAssistantFileParts(
+function merge_assistant_parts(
   message: SessionMessageRecordV1,
-  parts: FileUIPart[],
+  parts: UIMessage["parts"],
 ): SessionMessageRecordV1 {
   if (!Array.isArray(parts) || parts.length === 0) return message;
   const current_parts = Array.isArray(message.parts) ? message.parts : [];
   const seen = new Set<string>();
   for (const part of current_parts) {
-    const candidate = part as FileUIPart;
+    const candidate = part as UIMessage["parts"][number];
     if (candidate?.type !== "file") continue;
-    seen.add(build_file_part_key(candidate));
+    seen.add(build_file_part_key(candidate as FileUIPart));
   }
-  const next_file_parts = parts.filter((part) => {
-    const key = build_file_part_key(part);
+  const next_parts = parts.filter((part) => {
+    if (part.type !== "file") return true;
+    const key = build_file_part_key(part as FileUIPart);
     if (seen.has(key)) return false;
     seen.add(key);
     return true;
   });
-  if (next_file_parts.length === 0) return message;
+  if (next_parts.length === 0) return message;
   return {
     ...message,
-    parts: [...current_parts, ...next_file_parts],
+    parts: [...current_parts, ...next_parts],
   };
 }
 
@@ -115,11 +118,11 @@ interface CoreEngineRunnerOptions {
   should_compact_on_error: (error: unknown) => boolean;
 }
 
-interface CoreEngineRunInput {
+interface CoreEngineTurnInput {
   /**
    * 已装配好的执行输入。
    */
-  execute_input: SessionExecuteInput;
+  execute_input: SessionStepExecutionInput;
 
   /**
    * 当前轮模型实例。
@@ -129,7 +132,7 @@ interface CoreEngineRunInput {
   /**
    * 当前显式运行上下文。
    */
-  run_context: SessionRunContext;
+  turn_context: SessionTurnContext;
 
   /**
    * 在统一输入队列提交后解析当前 Session step 的 effective 配置。
@@ -138,9 +141,9 @@ interface CoreEngineRunInput {
     /** 当前 Session step 使用的模型。 */
     model: LanguageModel;
     /** 当前 Session step 使用的 system messages。 */
-    system: SessionExecuteInput["system"];
+    system: SessionStepExecutionInput["system"];
     /** 当前 Session step 使用的工具集合。 */
-    tools: SessionExecuteInput["tools"];
+    tools: SessionStepExecutionInput["tools"];
     /** 当前 Session step 模型支持的总上下文窗口长度。 */
     context_window?: number;
   }>;
@@ -172,7 +175,7 @@ export class CoreEngineRunner {
   /**
    * 执行一次已装配完成的模型/tool-loop 运行。
    */
-  async run(input: CoreEngineRunInput): Promise<SessionRunResult> {
+  async execute(input: CoreEngineTurnInput): Promise<SessionTurnExecutionResult> {
     const start_time = Date.now();
     const session_id = this.session_id;
     let system = Array.isArray(input.execute_input.system)
@@ -187,7 +190,7 @@ export class CoreEngineRunner {
       const message_state = await CoreEngineMessageState.create({
         messages: input.execute_input.messages,
         tools,
-        projectRoot: input.run_context.projectRoot,
+        project_root: input.turn_context.session.project_root,
       });
       let persisted_compaction_summary_id = resolve_compaction_summary_id(
         input.execute_input.messages,
@@ -201,7 +204,7 @@ export class CoreEngineRunner {
       let total_tool_result_count = 0;
       const on_step_finish = async (step_result: unknown): Promise<void> => {
         step_count += 1;
-        const summary = summarizeStepForDebug(step_result);
+        const summary = summarize_step_for_debug(step_result);
         total_tool_call_count +=
           typeof summary.toolCallCount === "number" ? summary.toolCallCount : 0;
         total_tool_result_count +=
@@ -209,21 +212,10 @@ export class CoreEngineRunner {
             ? summary.toolResultCount
             : 0;
         await this.logger.log("info", "[agent] step.finish", {
-          sessionId: session_id,
-          stepIndex: step_count,
+          session_id: session_id,
+          step_index: step_count,
           ...summary,
         });
-        if (input.run_context.onAssistantStepCallback) {
-          try {
-            await input.run_context.onAssistantStepCallback({
-              text: String((step_result as { text?: unknown })?.text || "").trim(),
-              stepIndex: step_count,
-              stepResult: step_result,
-            });
-          } catch {
-            // Assistant step 观察回调失败不能改变模型执行结果。
-          }
-        }
       };
 
       let text_only_continuation_count = 0;
@@ -240,24 +232,13 @@ export class CoreEngineRunner {
       while (step_count < MAX_TOOL_LOOP_STEPS) {
         // 关键点（中文）：steer 与 command 在同一个 Session step 检查点执行。
         // 当前流与 tool callback 保持原执行视图，下一 step 再统一读取 effective 配置。
-        const injected_messages = [...input.run_context.injectedUserMessages];
-        input.run_context.injectedUserMessages = [];
-        let queued_messages: SessionRecordV1[] = [];
-        if (input.run_context.onStepCallback) {
-          try {
-            queued_messages = await input.run_context.onStepCallback();
-          } catch {
-            queued_messages = [];
-          }
-        }
-        await append_merged_user_messages([
-          ...injected_messages,
-          ...queued_messages,
-        ]);
+        await append_merged_user_messages(
+          await input.turn_context.input.checkpoint(),
+        );
         const step_inputs = await input.resolve_step_inputs();
         system = Array.isArray(step_inputs.system) ? step_inputs.system : [];
         tools = step_inputs.tools;
-        if (input.run_context.consume_history_reload?.()) {
+        if (input.turn_context.input.consume_history_reload()) {
           const canonical_records = await input.reload_history();
           await message_state.replace_session_messages(canonical_records, tools);
           persisted_compaction_summary_id = resolve_compaction_summary_id(
@@ -269,7 +250,7 @@ export class CoreEngineRunner {
                 this.validated_compaction_summary_id,
           );
           await this.logger.log("info", "[agent] context.history_reloaded", {
-            sessionId: session_id,
+            session_id: session_id,
             recordCount: canonical_records.length,
             compactionSummaryId: persisted_compaction_summary_id || undefined,
           });
@@ -287,7 +268,7 @@ export class CoreEngineRunner {
           compact_validation_pending = true;
           compact_required = true;
           await this.logger.log("info", "[agent] context.compacted", {
-            sessionId: session_id,
+            session_id: session_id,
             reason: "usage_threshold",
             compactDepth: compact_depth,
             previousMessageCount: previous_message_count,
@@ -301,8 +282,8 @@ export class CoreEngineRunner {
         let canonical_step_started = false;
         let canonical_step_finished = false;
         try {
-          if (input.run_context.on_ui_message_step_start) {
-            await input.run_context.on_ui_message_step_start();
+          if (input.turn_context.output.assistant) {
+            await input.turn_context.output.assistant.begin_step();
             canonical_step_started = true;
           }
           const result = streamText({
@@ -311,35 +292,50 @@ export class CoreEngineRunner {
             onStepFinish: on_step_finish,
             messages: message_state.modelMessages,
             tools,
-            abortSignal: input.run_context.abortSignal,
+            abortSignal: input.turn_context.lifecycle.abort_signal,
             onError: async ({ error }) => {
               last_observed_stream_error = error;
               await this.logger.log("error", "[agent] stream.error", {
-                sessionId: session_id,
-                ...summarizeStreamError(error),
+                session_id: session_id,
+                ...summarize_stream_error(error),
               });
             },
           });
 
           step_assistant_ui_message =
-            await collectFinalAssistantMessageFromUiStream({
+            await collect_final_assistant_message_from_ui_stream({
               result,
-              sessionId: session_id,
+              session_id: session_id,
               logger: this.logger,
               buildFallbackAssistantMessage: (text) =>
                 build_fallback_assistant_message(session_id, text),
-              onUiMessageChunkCallback: input.run_context.onUiMessageChunkCallback,
-              abortSignal: input.run_context.abortSignal,
+              on_ui_message_chunk_callback: input.turn_context.output.assistant
+                ? async (chunk) => {
+                    await input.turn_context.output.assistant?.write_chunk(chunk);
+                  }
+                : undefined,
+              abort_signal: input.turn_context.lifecycle.abort_signal,
             });
 
-          if (input.run_context.on_ui_message_step_finish) {
-            await input.run_context.on_ui_message_step_finish(
+          if (input.turn_context.output.assistant) {
+            await input.turn_context.output.assistant.finish_step(
               step_assistant_ui_message,
             );
           }
+          const action_assistant_parts =
+            input.turn_context.output.take_assistant_parts();
+          if (action_assistant_parts.length > 0) {
+            await input.turn_context.output.assistant?.append_parts(
+              action_assistant_parts,
+            );
+            step_assistant_ui_message = merge_assistant_parts(
+              step_assistant_ui_message,
+              action_assistant_parts,
+            );
+          }
           canonical_step_finished = true;
 
-          final_assistant_ui_message = mergeAssistantUiMessages(
+          final_assistant_ui_message = merge_assistant_ui_messages(
             final_assistant_ui_message,
             step_assistant_ui_message,
           );
@@ -352,9 +348,9 @@ export class CoreEngineRunner {
           if (
             canonical_step_started &&
             !canonical_step_finished &&
-            input.run_context.on_ui_message_step_abort
+            input.turn_context.output.assistant
           ) {
-            await input.run_context.on_ui_message_step_abort();
+            await input.turn_context.output.assistant.abort_step();
           }
           const compact_error = this.should_compact_on_error(error)
             ? error
@@ -377,13 +373,13 @@ export class CoreEngineRunner {
             compact_validation_pending = true;
             compact_required = true;
             await this.logger.log("warn", "[agent] context.compacted", {
-              sessionId: session_id,
+              session_id: session_id,
               reason: "provider_context_error",
               retryCount: context_error_compaction_retries,
               compactDepth: compact_depth,
               previousMessageCount: previous_message_count,
               nextMessageCount: message_state.modelMessages.length,
-              ...summarizeStreamError(compact_error),
+              ...summarize_stream_error(compact_error),
             });
             continue;
           }
@@ -411,8 +407,8 @@ export class CoreEngineRunner {
           }
           if (compact_pending) compact_required = true;
           await this.logger.log("info", "[agent] context.usage", {
-            sessionId: session_id,
-            stepIndex: step_count,
+            session_id: session_id,
+            step_index: step_count,
             usageRatio: usage_ratio,
             contextWindow: step_inputs.context_window,
             validatingCompaction: validating_compaction,
@@ -420,13 +416,13 @@ export class CoreEngineRunner {
           });
         }
 
-        const incomplete_response = detectIncompleteResponse({
-          stepResult: last_step,
-          assistantMessage: step_assistant_ui_message,
+        const incomplete_response = detect_incomplete_response({
+          step_result: last_step,
+          assistant_message: step_assistant_ui_message,
         });
         const text_only_continuation_reason =
-          detectTextOnlyContinuationReason(last_step);
-        const loop_decision = evaluateCoreEngineLoopDecision({
+          detect_text_only_continuation_reason(last_step);
+        const loop_decision = evaluate_core_engine_loop_decision({
           hasIncompleteResponse: incomplete_response !== null,
           incompleteRecoveryCount: incomplete_response_recovery_count,
           maxIncompleteRecoveries: MAX_INCOMPLETE_RESPONSE_RECOVERIES,
@@ -438,8 +434,8 @@ export class CoreEngineRunner {
         });
 
         await this.logger.log("info", "[agent] loop.decision", {
-          sessionId: session_id,
-          stepIndex: step_count,
+          session_id: session_id,
+          step_index: step_count,
           continueForToolCalls: loop_decision.continueForToolCalls,
           continueForTextOnly: loop_decision.continueForTextOnly,
           continueForIncompleteRecovery:
@@ -452,7 +448,7 @@ export class CoreEngineRunner {
           toolCallCount: last_step.toolCalls.length,
           toolResultCount: last_step.toolResults.length,
           finishReason: last_step.finishReason,
-          textPreview: toInlinePreview(last_step.text),
+          textPreview: to_inline_preview(last_step.text),
         });
 
         if (
@@ -461,21 +457,21 @@ export class CoreEngineRunner {
         ) {
           incomplete_response_recovery_count += 1;
           await this.logger.log("warn", "[agent] incomplete_response.recover", {
-            sessionId: session_id,
-            stepIndex: step_count,
+            session_id: session_id,
+            step_index: step_count,
             recoveryCount: incomplete_response_recovery_count,
             reason: incomplete_response.reason,
             ...incomplete_response.details,
           });
           const recovery_message = build_internal_user_message({
             session_id,
-            text: buildIncompleteResponseRecoveryNudge(
+            text: build_incomplete_response_recovery_nudge(
               incomplete_response_recovery_count,
             ),
             extra: {
               internal: "agent_incomplete_response_recover",
               reason: incomplete_response.reason,
-              stepIndex: step_count,
+              step_index: step_count,
             },
           });
           await message_state.appendUserTextMessage(recovery_message);
@@ -484,8 +480,8 @@ export class CoreEngineRunner {
 
         if (incomplete_response) {
           await this.logger.log("error", "[agent] incomplete_response", {
-            sessionId: session_id,
-            stepIndex: step_count,
+            session_id: session_id,
+            step_index: step_count,
             reason: incomplete_response.reason,
             recoveryCount: incomplete_response_recovery_count,
             ...incomplete_response.details,
@@ -511,11 +507,11 @@ export class CoreEngineRunner {
           incomplete_response_recovery_count = 0;
           const continuation_message = build_internal_user_message({
             session_id,
-            text: buildTextOnlyContinuationNudge(text_only_continuation_count),
+            text: build_text_only_continuation_nudge(text_only_continuation_count),
             extra: {
               internal: "agent_loop_auto_continue",
               reason: text_only_continuation_reason,
-              stepIndex: step_count,
+              step_index: step_count,
             },
           });
           await message_state.appendUserTextMessage(continuation_message);
@@ -523,19 +519,19 @@ export class CoreEngineRunner {
         }
 
         // 关键点（中文）：stop 前做 tail merge，覆盖最后一个 step 后才入队的新 user 消息。
-        const tail_merged_message_count = input.run_context.hasPendingStepInput?.()
+        const tail_merged_message_count = input.turn_context.input.has_pending()
           ? 1
           : 0;
         if (
-          shouldContinueForTailMergedUserMessages({
+          should_continue_for_tail_merged_user_messages({
             mergedUserMessageCount: tail_merged_message_count,
           })
         ) {
           text_only_continuation_count = 0;
           incomplete_response_recovery_count = 0;
           await this.logger.log("info", "[agent] loop.tail_merge_continue", {
-            sessionId: session_id,
-            stepIndex: step_count,
+            session_id: session_id,
+            step_index: step_count,
             mergedUserMessageCount: tail_merged_message_count,
           });
           continue;
@@ -546,28 +542,25 @@ export class CoreEngineRunner {
 
       if (step_count >= MAX_TOOL_LOOP_STEPS) {
         await this.logger.log("warn", "[agent] loop.max_steps_reached", {
-          sessionId: session_id,
+          session_id: session_id,
           stepCount: step_count,
           totalToolCallCount: total_tool_call_count,
           totalToolResultCount: total_tool_result_count,
         });
       }
 
-      const final_message = mergePendingAssistantFileParts(
-        final_assistant_ui_message ||
-          build_fallback_assistant_message(session_id, "Execution completed"),
-        input.run_context.pendingAssistantFileParts,
-      );
+      const final_message = final_assistant_ui_message ||
+        build_fallback_assistant_message(session_id, "Execution completed");
 
       await this.logger.log("info", "[agent] final.message", {
-        sessionId: session_id,
-        ...summarizeUiMessageForDebug(final_message),
+        session_id: session_id,
+        ...summarize_ui_message_for_debug(final_message),
       });
-      await logAssistantMessageNow(this.logger, final_message);
+      await log_assistant_message_now(this.logger, final_message);
 
       const duration = Date.now() - start_time;
       await this.logger.log("info", "[agent] finish", {
-        sessionId: session_id,
+        session_id: session_id,
         duration,
         stepCount: step_count,
         totalToolCallCount: total_tool_call_count,
@@ -576,33 +569,28 @@ export class CoreEngineRunner {
 
       return {
         success: true,
-        assistantMessage: final_message,
-        assistant_file_parts: [...input.run_context.pendingAssistantFileParts],
+        text: pick_last_successful_chat_send_text(final_message),
         ...(compact_required ? { compact_required: true } : {}),
-        deferredPersistedUserMessages: [
-          ...input.run_context.deferredPersistedUserMessages,
+        deferred_persisted_user_messages: [
+          ...input.turn_context.input.deferred_user_messages(),
         ],
       };
     } catch (error) {
-      if (input.run_context.abortSignal?.aborted) {
+      if (input.turn_context.lifecycle.abort_signal.aborted) {
         const error_text = TURN_STOPPED_MESSAGE;
         await this.logger.log("info", "[agent] stopped", {
-          sessionId: session_id,
+          session_id: session_id,
         });
-        const stopped_message = final_assistant_ui_message
-          ? mergePendingAssistantFileParts(
-              final_assistant_ui_message,
-              input.run_context.pendingAssistantFileParts,
-            )
-          : null;
+        const stopped_message = final_assistant_ui_message;
         return {
           success: false,
+          text: stopped_message
+            ? pick_last_successful_chat_send_text(stopped_message)
+            : "",
           error: error_text,
-          ...(stopped_message ? { assistantMessage: stopped_message } : {}),
-          assistant_file_parts: [...input.run_context.pendingAssistantFileParts],
           ...(compact_required ? { compact_required: true } : {}),
-          deferredPersistedUserMessages: [
-            ...input.run_context.deferredPersistedUserMessages,
+          deferred_persisted_user_messages: [
+            ...input.turn_context.input.deferred_user_messages(),
           ],
         };
       }
@@ -611,7 +599,7 @@ export class CoreEngineRunner {
         throw error;
       }
 
-      const error_text = resolveEffectiveCoreEngineError({
+      const error_text = resolve_effective_core_engine_error({
         error,
         streamError: last_observed_stream_error,
       });
@@ -622,11 +610,13 @@ export class CoreEngineRunner {
 
       return {
         success: false,
+        text: final_assistant_ui_message
+          ? pick_last_successful_chat_send_text(final_assistant_ui_message)
+          : "",
         error: error_text,
-        assistant_file_parts: [...input.run_context.pendingAssistantFileParts],
         ...(compact_required ? { compact_required: true } : {}),
-        deferredPersistedUserMessages: [
-          ...input.run_context.deferredPersistedUserMessages,
+        deferred_persisted_user_messages: [
+          ...input.turn_context.input.deferred_user_messages(),
         ],
       };
     }
@@ -645,7 +635,7 @@ function build_internal_user_message(input: {
     metadata: {
       v: 1,
       ts: Date.now(),
-      sessionId: input.session_id,
+      session_id: input.session_id,
       source: "ingress",
       kind: "normal",
       extra: input.extra,
@@ -665,7 +655,7 @@ function build_fallback_assistant_message(
     metadata: {
       v: 1,
       ts: Date.now(),
-      sessionId: session_id,
+      session_id: session_id,
       source: "egress",
       kind: "normal",
     },