@downcity/agent 1.1.8 → 1.1.11

package/src/session/executors/local/LocalSessionCore.ts

@@ -14,93 +14,24 @@
  * 5) `collectFinalAssistantMessage`：收敛最终 assistant 消息。
  */
 
-import {
-  streamText,
-  type LanguageModel,
-  type ModelMessage,
-} from "ai";
-import type { Logger } from "@shared/utils/logger/Logger.js";
+import type { LanguageModel } from "ai";
+import type { Logger } from "@/utils/logger/Logger.js";
 import { SessionCompactionComposer } from "@session/composer/compaction/SessionCompactionComposer.js";
 import { SessionExecutionComposer } from "@session/composer/execution/SessionExecutionComposer.js";
 import { SessionHistoryComposer } from "@session/composer/history/SessionHistoryComposer.js";
 import { SessionSystemComposer } from "@session/composer/system/SessionSystemComposer.js";
-import {
-  buildOpenAIResponsesProviderOptions,
-  pickMergedUserMessages,
-  toModelMessages,
-} from "@session/messages/SessionMessageCodec.js";
-import { logAssistantMessageNow } from "@session/messages/SessionMessageLog.js";
-import {
-  MAX_INCOMPLETE_RESPONSE_RECOVERIES,
-  MAX_TEXT_ONLY_CONTINUATIONS,
-  MAX_TOOL_LOOP_STEPS,
-  buildIncompleteResponseRecoveryNudge,
-  buildTextOnlyContinuationNudge,
-  detectIncompleteResponse,
-  detectTextOnlyContinuationReason,
-  mergeAssistantUiMessages,
-  summarizeStepForDebug,
-  summarizeUiMessageForDebug,
-  toInlinePreview,
-} from "@session/executors/local/SessionSignals.js";
-import {
-  evaluateSessionLoopDecision,
-  shouldContinueForTailMergedUserMessages,
-} from "@session/executors/local/SessionLoopDecision.js";
-import { getSessionRunScope } from "@session/SessionRunScope.js";
 import type {
   SessionExecuteInput,
   SessionRunResult,
   SessionRunInput,
-} from "@/types/session/SessionRun.js";
-import type { SessionMessageV1 } from "@/types/session/SessionMessages.js";
-import type { JsonObject } from "@/shared/types/Json.js";
+} from "@/session/types/SessionRun.js";
+import { SessionToolLoopRunner } from "@session/executors/local/SessionToolLoopRunner.js";
 
 /**
  * 可压缩错误的最大重试次数。
  */
 const MAX_COMPACTION_RETRY_ATTEMPTS = 3;
 
-/**
- * 归一化 stream 错误日志字段。
- *
- * 关键点（中文）
- * - AI SDK 的 `No output generated` 常常只是最终兜底错误。
- * - 真正的 provider 错误会先经过 `onError`，这里保留 name/cause 便于定位。
- */
-function summarizeStreamError(error: unknown): JsonObject {
-  const record =
-    error && typeof error === "object" && !Array.isArray(error)
-      ? (error as Record<string, unknown>)
-      : {};
-  const cause = record.cause;
-  return {
-    error: String(error),
-    name: typeof record.name === "string" ? record.name : null,
-    message: typeof record.message === "string" ? record.message : null,
-    cause: cause === undefined ? null : String(cause),
-  };
-}
-
-/**
- * 提取实际应返回给上层的错误文本。
- *
- * 关键点（中文）
- * - `AI_NoOutputGeneratedError` 往往只是 AI SDK 的兜底包装。
- * - 如果同一轮里已经捕获到底层 `stream.error`，应优先把底层 provider 错误透传出去。
- */
-function resolveEffectiveExecutionError(params: {
-  error: unknown;
-  streamError?: unknown;
-}): string {
-  const outerError = String(params.error ?? "").trim();
-  const innerError = String(params.streamError ?? "").trim();
-  if (/AI_NoOutputGeneratedError|No output generated/i.test(outerError) && innerError) {
-    return innerError;
-  }
-  return outerError || innerError || "Unknown execution error";
-}
-
 /**
  * LocalSessionCore 构造参数。
  */
@@ -342,434 +273,15 @@ export class LocalSessionCore {
   private async executePreparedRun(
     input: SessionExecuteInput,
   ): Promise<SessionRunResult> {
-    // 记录开始时间，用于 finish 日志。
-    const startTime = Date.now();
-    const sessionId = String(this.historyComposer.sessionId || "").trim();
-
-    // 防御性兜底：确保 system 至少是数组。
-    const system = Array.isArray(input.system) ? input.system : [];
-
-    // 工具集合直接透传。
-    const tools = input.tools;
-    let lastObservedStreamError: unknown = undefined;
-
-    try {
-      // 核心步骤 1（中文）：把 session messages 转成模型输入消息。
-      let runtimeSessionMessages = Array.isArray(input.messages)
-        ? [...input.messages]
-        : [];
-
-      // 根据当前基线消息生成模型消息。
-      let baseModelMessages = await toModelMessages(runtimeSessionMessages, tools);
-
-      // 核心步骤 2（中文）：定义“step 间新增 user 消息并入器”。
-      const appendMergedUserMessages = async (
-        messages: SessionMessageV1[],
-      ): Promise<ModelMessage[]> => {
-        // 子步骤 A（中文）：过滤出有效 user 文本消息。
-        const mergedMessages = pickMergedUserMessages(messages);
-
-        // 如果没有可并入消息，直接返回空增量。
-        if (mergedMessages.length === 0) return [];
-
-        // 子步骤 B（中文）：更新 context 基线，保证后续全量重算时可见这些新增消息。
-        runtimeSessionMessages = [...runtimeSessionMessages, ...mergedMessages];
-
-        // 先尝试只转换新增消息，减少重复计算。
-        const mergedModelMessages = await toModelMessages(
-          mergedMessages,
-          tools,
-        );
-
-        // 如果增量转换成功，直接追加并返回增量。
-        if (mergedModelMessages.length > 0) {
-          baseModelMessages = [...baseModelMessages, ...mergedModelMessages];
-          return mergedModelMessages;
-        }
-
-        // 子步骤 C（中文）：增量不可用时回退为全量重算，保证一致性。
-        baseModelMessages = await toModelMessages(runtimeSessionMessages, tools);
-
-        // 返回空，表示本次 prepareStep 不注入增量片段。
-        return [];
-      };
-
-      // 从 execution Composer 获取 step 完成回调（用于中间输出处理）。
-      const executionComposerOnStepFinish =
-        this.executionComposer.createOnStepFinishHandler();
-      let stepCount = 0;
-      let totalToolCallCount = 0;
-      let totalToolResultCount = 0;
-      const onStepFinish = async (stepResult: unknown): Promise<void> => {
-        stepCount += 1;
-        const summary = summarizeStepForDebug(stepResult);
-        totalToolCallCount +=
-          typeof summary.toolCallCount === "number" ? summary.toolCallCount : 0;
-        totalToolResultCount +=
-          typeof summary.toolResultCount === "number"
-            ? summary.toolResultCount
-            : 0;
-        await this.logger.log("info", "[agent] step.finish", {
-          sessionId,
-          stepIndex: stepCount,
-          ...summary,
-        });
-        await executionComposerOnStepFinish(stepResult);
-      };
-
-      // 从 execution Composer 获取 step 准备回调（用于 step 间消息并入）。
-      const prepareStep = this.executionComposer.createPrepareStepHandler({
-        system,
-        appendMergedUserMessages,
-      });
-
-      // 核心步骤 3（中文）：改为显式外层循环，由 runtime 自己决定是否继续下一步。
-      let finalAssistantUiMessage: SessionMessageV1 | null = null;
-      let textOnlyContinuationCount = 0;
-      let incompleteResponseRecoveryCount = 0;
-
-      while (stepCount < MAX_TOOL_LOOP_STEPS) {
-        const result = streamText({
-          // 指定模型。
-          model: this.model,
-          // 指定 system。
-          system,
-          // 注入 step 完成钩子。
-          onStepFinish,
-          // 注入 step 准备钩子。
-          prepareStep,
-          // 注入消息基线。
-          messages: baseModelMessages,
-          // 注入工具集。
-          tools,
-          // 注入 provider 选项。
-          providerOptions: buildOpenAIResponsesProviderOptions(),
-          // 记录底层 stream 错误，避免只看到最终的 NoOutputGenerated 兜底错误。
-          onError: async ({ error }) => {
-            lastObservedStreamError = error;
-            await this.logger.log("error", "[agent] stream.error", {
-              sessionId,
-              ...summarizeStreamError(error),
-            });
-          },
-        });
-
-        // 单步收敛 UI assistant 消息，并累计为本轮最终消息。
-        const stepAssistantUiMessage = await this.collectFinalAssistantMessage({
-          result,
-        });
-
-        const executedSteps = await result.steps;
-        const lastStep = executedSteps[executedSteps.length - 1];
-        if (!lastStep) break;
-
-        const incompleteResponse = detectIncompleteResponse({
-          stepResult: lastStep,
-          assistantMessage: stepAssistantUiMessage,
-        });
-        const textOnlyContinuationReason =
-          detectTextOnlyContinuationReason(lastStep);
-        const loopDecision = evaluateSessionLoopDecision({
-          hasIncompleteResponse: incompleteResponse !== null,
-          incompleteRecoveryCount: incompleteResponseRecoveryCount,
-          maxIncompleteRecoveries: MAX_INCOMPLETE_RESPONSE_RECOVERIES,
-          textOnlyContinuationReason,
-          textOnlyContinuationCount,
-          maxTextOnlyContinuations: MAX_TEXT_ONLY_CONTINUATIONS,
-          hasTools: Object.keys(tools).length > 0,
-          toolCallCount: lastStep.toolCalls.length,
-        });
-
-        await this.logger.log("info", "[agent] loop.decision", {
-          sessionId,
-          stepIndex: stepCount,
-          continueForToolCalls: loopDecision.continueForToolCalls,
-          continueForTextOnly: loopDecision.continueForTextOnly,
-          continueForIncompleteRecovery:
-            loopDecision.continueForIncompleteRecovery,
-          decisionKind: loopDecision.kind,
-          textOnlyContinuationReason,
-          textOnlyContinuationCount,
-          incompleteResponseReason: incompleteResponse?.reason ?? null,
-          incompleteResponseRecoveryCount,
-          toolCallCount: lastStep.toolCalls.length,
-          toolResultCount: lastStep.toolResults.length,
-          finishReason: lastStep.finishReason,
-          textPreview: toInlinePreview(lastStep.text),
-        });
-
-        if (loopDecision.continueForIncompleteRecovery && incompleteResponse) {
-          incompleteResponseRecoveryCount += 1;
-          await this.logger.log("warn", "[agent] incomplete_response.recover", {
-            sessionId,
-            stepIndex: stepCount,
-            recoveryCount: incompleteResponseRecoveryCount,
-            reason: incompleteResponse.reason,
-            ...incompleteResponse.details,
-          });
-          const recoveryMessage = this.historyComposer.userText({
-            text: buildIncompleteResponseRecoveryNudge(
-              incompleteResponseRecoveryCount,
-            ),
-            metadata: {
-              sessionId,
-              extra: {
-                internal: "agent_incomplete_response_recover",
-                reason: incompleteResponse.reason,
-                stepIndex: stepCount,
-              },
-            },
-          });
-          runtimeSessionMessages = [...runtimeSessionMessages, recoveryMessage];
-          const recoveryModelMessages = await toModelMessages(
-            [recoveryMessage],
-            tools,
-          );
-          if (recoveryModelMessages.length > 0) {
-            baseModelMessages = [...baseModelMessages, ...recoveryModelMessages];
-          } else {
-            baseModelMessages = await toModelMessages(
-              runtimeSessionMessages,
-              tools,
-            );
-          }
-          continue;
-        }
-
-        if (incompleteResponse) {
-          await this.logger.log("error", "[agent] incomplete_response", {
-            sessionId,
-            stepIndex: stepCount,
-            reason: incompleteResponse.reason,
-            recoveryCount: incompleteResponseRecoveryCount,
-            ...incompleteResponse.details,
-          });
-          throw new Error(
-            `Agent received incomplete response (${incompleteResponse.reason})`,
-          );
-        }
-
-        const responseMessages = Array.isArray(lastStep.response?.messages)
-          ? lastStep.response.messages
-          : [];
-        if (responseMessages.length > 0) {
-          baseModelMessages = [...baseModelMessages, ...responseMessages];
-        }
-
-        finalAssistantUiMessage = mergeAssistantUiMessages(
-          finalAssistantUiMessage,
-          stepAssistantUiMessage,
-        );
-
-        // 关键点（中文）：把本 step 的 assistant UI 消息并入运行时上下文，保证后续全量重算不丢历史。
-        runtimeSessionMessages = [...runtimeSessionMessages, stepAssistantUiMessage];
-
-        if (loopDecision.continueForToolCalls) {
-          textOnlyContinuationCount = 0;
-          incompleteResponseRecoveryCount = 0;
-          continue;
-        }
-
-        if (loopDecision.continueForTextOnly) {
-          textOnlyContinuationCount += 1;
-          incompleteResponseRecoveryCount = 0;
-          const continuationMessage = this.historyComposer.userText({
-            text: buildTextOnlyContinuationNudge(textOnlyContinuationCount),
-            metadata: {
-              sessionId,
-              extra: {
-                internal: "agent_loop_auto_continue",
-                reason: textOnlyContinuationReason,
-                stepIndex: stepCount,
-              },
-            },
-          });
-          runtimeSessionMessages = [...runtimeSessionMessages, continuationMessage];
-          const continuationModelMessages = await toModelMessages(
-            [continuationMessage],
-            tools,
-          );
-          if (continuationModelMessages.length > 0) {
-            baseModelMessages = [
-              ...baseModelMessages,
-              ...continuationModelMessages,
-            ];
-          } else {
-            baseModelMessages = await toModelMessages(
-              runtimeSessionMessages,
-              tools,
-            );
-          }
-          continue;
-        }
-
-        // 关键点（中文）：
-        // - 正常 stop 前，再执行一次 tail merge 检查。
-        // - 这样可覆盖“最后一个 step 结束后，新的 user 消息才入队”的窗口。
-        // - 若这时真的并入了新消息，则继续当前 run，而不是等整个 run 结束后再开下一轮。
-        const tailPrepared = await prepareStep({ messages: [] });
-        const tailMergedMessageCount = Array.isArray(tailPrepared.messages)
-          ? tailPrepared.messages.length
-          : 0;
-        if (
-          shouldContinueForTailMergedUserMessages({
-            mergedUserMessageCount: tailMergedMessageCount,
-          })
-        ) {
-          textOnlyContinuationCount = 0;
-          incompleteResponseRecoveryCount = 0;
-          await this.logger.log("info", "[agent] loop.tail_merge_continue", {
-            sessionId,
-            stepIndex: stepCount,
-            mergedUserMessageCount: tailMergedMessageCount,
-          });
-          continue;
-        }
-
-        break;
-      }
-
-      if (stepCount >= MAX_TOOL_LOOP_STEPS) {
-        await this.logger.log("warn", "[agent] loop.max_steps_reached", {
-          sessionId,
-          stepCount,
-          totalToolCallCount,
-          totalToolResultCount,
-        });
-      }
-
-      // 核心步骤 4（中文）：收敛最终 assistant 消息。
-      const finalMessage =
-        finalAssistantUiMessage ||
-        this.executionComposer.buildFallbackAssistantMessage("Execution completed");
-
-      await this.logger.log("info", "[agent] final.message", {
-        sessionId,
-        ...summarizeUiMessageForDebug(finalMessage),
-      });
-
-      // 输出 assistant 文本日志。
-      await logAssistantMessageNow(this.logger, finalMessage);
-
-      // 计算耗时。
-      const duration = Date.now() - startTime;
-
-      // 写入 finish 日志。
-      await this.logger.log("info", "[agent] finish", {
-        sessionId,
-        duration,
-        stepCount,
-        totalToolCallCount,
-        totalToolResultCount,
-      });
-
-      // 返回成功结果。
-      return {
-        success: true,
-        assistantMessage: finalMessage,
-      };
-    } catch (error) {
-      // 可压缩错误上抛，让上层 runWithRetry 统一处理重试。
-      if (this.compactionComposer.shouldCompactOnError(error)) {
-        throw error;
-      }
-
-      // 非“可压缩错误”转为失败结果。
-      const errorMsg = resolveEffectiveExecutionError({
-        error,
-        streamError: lastObservedStreamError,
-      });
-
-      // 记录错误日志。
-      await this.logger.log("error", "LocalSessionCore execution failed", {
-        error: errorMsg,
-      });
-
-      // 返回失败消息。
-      return {
-        success: false,
-        error: errorMsg,
-        assistantMessage: this.executionComposer.buildFallbackAssistantMessage(
-          `Execution failed: ${errorMsg}`,
-        ),
-      };
-    }
-  }
-
-  /**
-   * 消费 UI stream 并解析最终 assistant 消息。
-   *
-   * 关键点（中文）
-   * - 优先取 UI stream 的结构化 responseMessage。
-   * - 取不到时回退到 `result.text` 生成文本消息。
-   */
-  private async collectFinalAssistantMessage(params: {
-    result: ReturnType<typeof streamText>;
-  }): Promise<SessionMessageV1> {
-    // 用于接收 onFinish 传出的结构化 assistant 消息。
-    let streamedAssistantMessage: SessionMessageV1 | null = null;
-    let uiFinishSummary: JsonObject | null = null;
-
-    // 创建 UI message stream。
-    const uiStream = params.result.toUIMessageStream<SessionMessageV1>({
-      // 关键点（中文）：SDK stream 需要 reasoning 旁路事件时可直接消费；最终落盘仍由 responseMessage 收敛。
-      sendReasoning: true,
-      // 不发送来源片段。
-      sendSources: false,
-      // 在 finish 时收敛最终 responseMessage。
-      onFinish: (event) => {
-        streamedAssistantMessage = event.responseMessage ?? null;
-        uiFinishSummary = {
-          isContinuation: event.isContinuation,
-          isAborted: event.isAborted,
-          finishReason:
-            typeof event.finishReason === "string" ? event.finishReason : null,
-          ...summarizeUiMessageForDebug(event.responseMessage),
-        };
-      },
-    });
-
-    // 必须完整消费 stream，确保 onFinish 被触发。
-    const onUiMessageChunkCallback =
-      getSessionRunScope()?.onUiMessageChunkCallback;
-    for await (const chunk of uiStream) {
-      if (typeof onUiMessageChunkCallback !== "function") continue;
-      try {
-        await onUiMessageChunkCallback(chunk);
-      } catch {
-        // ignore UI stream callback failures
-      }
-    }
-
-    await this.logger.log("info", "[agent] ui.finish", {
-      sessionId: String(this.historyComposer.sessionId || "").trim(),
-      ...(uiFinishSummary || {
-        responseMessageMissing: true,
-      }),
-    });
-
-    // 如果拿到结构化消息，直接返回。
-    if (streamedAssistantMessage) return streamedAssistantMessage;
-
-    // 回退路径：尝试读取纯文本结果。
-    let assistantText = "";
-    try {
-      assistantText = String((await params.result.text) ?? "").trim();
-    } catch {
-      // 读取文本失败时保持空串。
-      assistantText = "";
-    }
-
-    await this.logger.log("warn", "[agent] final.message.fallback", {
-      sessionId: String(this.historyComposer.sessionId || "").trim(),
-      assistantTextLength: assistantText.length,
-      assistantTextPreview: toInlinePreview(assistantText),
+    const runner = new SessionToolLoopRunner({
+      model: this.model,
+      logger: this.logger,
+      historyComposer: this.historyComposer,
+      executionComposer: this.executionComposer,
+      shouldCompactOnError: (error) =>
+        this.compactionComposer.shouldCompactOnError(error),
     });
-
-    // 用回退文本构造标准 assistant 消息并返回。
-    return this.executionComposer.buildFallbackAssistantMessage(
-      assistantText || "Execution completed",
-    );
+    return await runner.execute(input);
   }
 
   /**

package/src/session/executors/local/LocalSessionExecutor.ts

@@ -7,14 +7,14 @@
  */
 
 import type { LanguageModel, Tool } from "ai";
-import type { Logger } from "@shared/utils/logger/Logger.js";
+import type { Logger } from "@/utils/logger/Logger.js";
 import { LocalSessionCore } from "@session/executors/local/LocalSessionCore.js";
 import { SessionCompactionComposer } from "@session/composer/compaction/SessionCompactionComposer.js";
 import { SessionExecutionComposer } from "@session/composer/execution/SessionExecutionComposer.js";
 import { SessionHistoryComposer } from "@session/composer/history/SessionHistoryComposer.js";
 import { SessionSystemComposer } from "@session/composer/system/SessionSystemComposer.js";
 import { LocalSessionExecutionComposer } from "@session/composer/execution/LocalSessionExecutionComposer.js";
-import type { SessionRunResult, SessionRunInput } from "@/types/session/SessionRun.js";
+import type { SessionRunResult, SessionRunInput } from "@/session/types/SessionRun.js";
 
 type LocalSessionExecutorOptions = {
   /**

package/src/session/executors/local/SessionExecutionError.ts

@@ -0,0 +1,47 @@
+/**
+ * Session 执行错误归一化工具。
+ *
+ * 关键点（中文）
+ * - AI SDK 的最终错误有时只是兜底包装，底层 provider 错误会先从 stream `onError` 暴露。
+ * - LocalSessionCore 只需要消费这里输出的日志字段与最终错误文本。
+ */
+
+import type { JsonObject } from "@/types/common/Json.js";
+
+/**
+ * 归一化 stream 错误日志字段。
+ */
+export function summarizeStreamError(error: unknown): JsonObject {
+  const record =
+    error && typeof error === "object" && !Array.isArray(error)
+      ? (error as Record<string, unknown>)
+      : {};
+  const cause = record.cause;
+  return {
+    error: String(error),
+    name: typeof record.name === "string" ? record.name : null,
+    message: typeof record.message === "string" ? record.message : null,
+    cause: cause === undefined ? null : String(cause),
+  };
+}
+
+/**
+ * 提取实际应返回给上层的错误文本。
+ */
+export function resolveEffectiveExecutionError(params: {
+  /**
+   * 外层捕获到的执行错误。
+   */
+  error: unknown;
+  /**
+   * stream `onError` 捕获到的底层错误。
+   */
+  streamError?: unknown;
+}): string {
+  const outerError = String(params.error ?? "").trim();
+  const innerError = String(params.streamError ?? "").trim();
+  if (/AI_NoOutputGeneratedError|No output generated/i.test(outerError) && innerError) {
+    return innerError;
+  }
+  return outerError || innerError || "Unknown execution error";
+}

package/src/session/executors/local/SessionLoopDecision.ts

@@ -10,7 +10,7 @@ import type {
   SessionLoopDecision,
   SessionLoopDecisionInput,
   SessionTailMergeContinuationInput,
-} from "@/types/session/SessionLoop.js";
+} from "@/session/types/SessionLoop.js";
 
 /**
  * 评估当前 step 完成后，LocalSessionCore 是否应继续下一轮。