@downcity/agent 1.1.10 → 1.1.12

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

@@ -0,0 +1,133 @@
+/**
+ * Session 模型消息运行态。
+ *
+ * 关键点（中文）
+ * - LocalSessionCore 同时维护 session 语义消息与模型消息。
+ * - 新增 user 消息可优先做增量转换，失败时再回退为全量重算。
+ * - assistant UI 消息只需要进入 session 语义基线；模型侧使用 SDK 返回的 response messages。
+ */
+
+import type { ModelMessage, Tool } from "ai";
+import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
+import {
+  pickMergedUserMessages,
+  toModelMessages,
+} from "@session/messages/SessionMessageCodec.js";
+
+/**
+ * LocalSessionCore 单轮执行期间的消息基线。
+ */
+export class SessionModelMessageState {
+  /**
+   * 当前运行时 session 语义消息。
+   */
+  private sessionMessages: SessionMessageV1[];
+
+  /**
+   * 当前模型侧消息基线。
+   */
+  private currentModelMessages: ModelMessage[];
+
+  /**
+   * 当前轮可用工具集合。
+   */
+  private readonly tools: Record<string, Tool>;
+
+  private constructor(params: {
+    /**
+     * 当前运行时 session 语义消息。
+     */
+    sessionMessages: SessionMessageV1[];
+    /**
+     * 当前模型侧消息基线。
+     */
+    modelMessages: ModelMessage[];
+    /**
+     * 当前轮可用工具集合。
+     */
+    tools: Record<string, Tool>;
+  }) {
+    this.sessionMessages = params.sessionMessages;
+    this.currentModelMessages = params.modelMessages;
+    this.tools = params.tools;
+  }
+
+  /**
+   * 基于初始 session 消息创建运行态。
+   */
+  static async create(params: {
+    /**
+     * 初始 session 语义消息。
+     */
+    messages: SessionMessageV1[];
+    /**
+     * 当前轮可用工具集合。
+     */
+    tools: Record<string, Tool>;
+  }): Promise<SessionModelMessageState> {
+    const sessionMessages = Array.isArray(params.messages)
+      ? [...params.messages]
+      : [];
+    return new SessionModelMessageState({
+      sessionMessages,
+      modelMessages: await toModelMessages(sessionMessages, params.tools),
+      tools: params.tools,
+    });
+  }
+
+  /**
+   * 读取当前模型消息。
+   */
+  get modelMessages(): ModelMessage[] {
+    return this.currentModelMessages;
+  }
+
+  /**
+   * 把 step 间新增的 user 消息并入两份基线。
+   */
+  async appendMergedUserMessages(
+    messages: SessionMessageV1[],
+  ): Promise<ModelMessage[]> {
+    const mergedMessages = pickMergedUserMessages(messages);
+    if (mergedMessages.length === 0) return [];
+    return await this.appendSessionMessagesAsModelMessages(mergedMessages);
+  }
+
+  /**
+   * 追加内部生成的 user nudge 消息。
+   */
+  async appendUserTextMessage(message: SessionMessageV1): Promise<void> {
+    await this.appendSessionMessagesAsModelMessages([message]);
+  }
+
+  /**
+   * 追加 assistant UI 消息到 session 语义基线。
+   */
+  appendRuntimeSessionMessage(message: SessionMessageV1): void {
+    this.sessionMessages = [...this.sessionMessages, message];
+  }
+
+  /**
+   * 追加 SDK 返回的模型 response messages。
+   */
+  appendModelMessages(messages: ModelMessage[]): void {
+    if (!Array.isArray(messages) || messages.length === 0) return;
+    this.currentModelMessages = [...this.currentModelMessages, ...messages];
+  }
+
+  private async appendSessionMessagesAsModelMessages(
+    messages: SessionMessageV1[],
+  ): Promise<ModelMessage[]> {
+    this.sessionMessages = [...this.sessionMessages, ...messages];
+    const modelMessages = await toModelMessages(messages, this.tools);
+    if (modelMessages.length > 0) {
+      this.currentModelMessages = [...this.currentModelMessages, ...modelMessages];
+      return modelMessages;
+    }
+    this.currentModelMessages = await toModelMessages(
+      this.sessionMessages,
+      this.tools,
+    );
+    return [];
+  }
+}

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

@@ -13,7 +13,7 @@ import {
   isToolUIPart,
 } from "ai";
 import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
-import type { JsonObject } from "@/utils/types/Json.js";
+import type { JsonObject } from "@/types/common/Json.js";
 
 /**
  * 单次 tool-loop 允许的最大 step 数。

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

@@ -0,0 +1,350 @@
+/**
+ * Session tool-loop runner。
+ *
+ * 关键点（中文）
+ * - 这里只负责已准备好的 `SessionExecuteInput` 如何进入 `streamText` 循环。
+ * - LocalSessionCore 保留入口、重试与输入准备职责，本模块负责 step 循环、续写、恢复和最终日志。
+ * - 运行过程中同时维护 UI assistant 消息、模型消息基线和 step 统计。
+ */
+
+import { streamText, type LanguageModel } from "ai";
+import type { Logger } from "@/utils/logger/Logger.js";
+import type {
+  SessionExecuteInput,
+  SessionRunResult,
+} from "@/session/types/SessionRun.js";
+import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
+import { SessionHistoryComposer } from "@session/composer/history/SessionHistoryComposer.js";
+import { SessionExecutionComposer } from "@session/composer/execution/SessionExecutionComposer.js";
+import {
+  buildOpenAIResponsesProviderOptions,
+} 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 {
+  resolveEffectiveExecutionError,
+  summarizeStreamError,
+} from "@session/executors/local/SessionExecutionError.js";
+import { collectFinalAssistantMessageFromUiStream } from "@session/executors/local/SessionUiStreamCollector.js";
+import { SessionModelMessageState } from "@session/executors/local/SessionModelMessageState.js";
+
+/**
+ * SessionToolLoopRunner 构造参数。
+ */
+export type SessionToolLoopRunnerOptions = {
+  /** 当前模型实例。 */
+  model: LanguageModel;
+  /** 统一日志器。 */
+  logger: Logger;
+  /** 当前会话历史存储。 */
+  historyComposer: SessionHistoryComposer;
+  /** 当前轮运行编排 Composer。 */
+  executionComposer: SessionExecutionComposer;
+  /** 判断错误是否应交给上层 compaction retry。 */
+  shouldCompactOnError: (error: unknown) => boolean;
+};
+
+/**
+ * 已准备输入的模型/tool-loop 执行器。
+ */
+export class SessionToolLoopRunner {
+  private readonly model: LanguageModel;
+  private readonly logger: Logger;
+  private readonly historyComposer: SessionHistoryComposer;
+  private readonly executionComposer: SessionExecutionComposer;
+  private readonly shouldCompactOnError: (error: unknown) => boolean;
+
+  constructor(options: SessionToolLoopRunnerOptions) {
+    this.model = options.model;
+    this.logger = options.logger;
+    this.historyComposer = options.historyComposer;
+    this.executionComposer = options.executionComposer;
+    this.shouldCompactOnError = options.shouldCompactOnError;
+  }
+
+  /**
+   * 执行一次已装配完成的运行材料。
+   */
+  async execute(input: SessionExecuteInput): Promise<SessionRunResult> {
+    const startTime = Date.now();
+    const sessionId = String(this.historyComposer.sessionId || "").trim();
+    const system = Array.isArray(input.system) ? input.system : [];
+    const tools = input.tools;
+    let lastObservedStreamError: unknown = undefined;
+
+    try {
+      const messageState = await SessionModelMessageState.create({
+        messages: input.messages,
+        tools,
+      });
+
+      const appendMergedUserMessages = (messages: SessionMessageV1[]) =>
+        messageState.appendMergedUserMessages(messages);
+
+      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);
+      };
+
+      const prepareStep = this.executionComposer.createPrepareStepHandler({
+        system,
+        appendMergedUserMessages,
+      });
+
+      let finalAssistantUiMessage: SessionMessageV1 | null = null;
+      let textOnlyContinuationCount = 0;
+      let incompleteResponseRecoveryCount = 0;
+
+      while (stepCount < MAX_TOOL_LOOP_STEPS) {
+        const result = streamText({
+          model: this.model,
+          system,
+          onStepFinish,
+          prepareStep,
+          messages: messageState.modelMessages,
+          tools,
+          providerOptions: buildOpenAIResponsesProviderOptions(),
+          onError: async ({ error }) => {
+            lastObservedStreamError = error;
+            await this.logger.log("error", "[agent] stream.error", {
+              sessionId,
+              ...summarizeStreamError(error),
+            });
+          },
+        });
+
+        const stepAssistantUiMessage = await collectFinalAssistantMessageFromUiStream({
+          result,
+          sessionId,
+          logger: this.logger,
+          buildFallbackAssistantMessage: (text) =>
+            this.executionComposer.buildFallbackAssistantMessage(text),
+        });
+
+        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,
+              },
+            },
+          });
+          await messageState.appendUserTextMessage(recoveryMessage);
+          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
+          : [];
+        messageState.appendModelMessages(responseMessages);
+
+        finalAssistantUiMessage = mergeAssistantUiMessages(
+          finalAssistantUiMessage,
+          stepAssistantUiMessage,
+        );
+
+        // 关键点（中文）：把本 step 的 assistant UI 消息并入运行时上下文，保证后续全量重算不丢历史。
+        messageState.appendRuntimeSessionMessage(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,
+              },
+            },
+          });
+          await messageState.appendUserTextMessage(continuationMessage);
+          continue;
+        }
+
+        // 关键点（中文）：stop 前做 tail merge，覆盖最后一个 step 后才入队的新 user 消息。
+        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,
+        });
+      }
+
+      const finalMessage =
+        finalAssistantUiMessage ||
+        this.executionComposer.buildFallbackAssistantMessage("Execution completed");
+
+      await this.logger.log("info", "[agent] final.message", {
+        sessionId,
+        ...summarizeUiMessageForDebug(finalMessage),
+      });
+      await logAssistantMessageNow(this.logger, finalMessage);
+
+      const duration = Date.now() - startTime;
+      await this.logger.log("info", "[agent] finish", {
+        sessionId,
+        duration,
+        stepCount,
+        totalToolCallCount,
+        totalToolResultCount,
+      });
+
+      return {
+        success: true,
+        assistantMessage: finalMessage,
+      };
+    } catch (error) {
+      if (this.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}`,
+        ),
+      };
+    }
+  }
+}

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

@@ -0,0 +1,96 @@
+/**
+ * Session UI stream 最终消息收敛器。
+ *
+ * 关键点（中文）
+ * - 必须完整消费 AI SDK UI stream，才能稳定触发 `onFinish`。
+ * - 优先使用结构化 `responseMessage`；缺失时才回退到纯文本。
+ * - UI chunk 回调是展示层副作用，失败不应阻断 session 执行。
+ */
+
+import type { streamText } from "ai";
+import type { Logger } from "@/utils/logger/Logger.js";
+import type { JsonObject } from "@/types/common/Json.js";
+import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
+import { getSessionRunScope } from "@session/SessionRunScope.js";
+import {
+  summarizeUiMessageForDebug,
+  toInlinePreview,
+} from "@session/executors/local/SessionSignals.js";
+
+/**
+ * 收敛 UI stream 中的最终 assistant 消息。
+ */
+export async function collectFinalAssistantMessageFromUiStream(params: {
+  /**
+   * 当前 `streamText` 执行结果。
+   */
+  result: ReturnType<typeof streamText>;
+  /**
+   * 当前 sessionId，用于日志关联。
+   */
+  sessionId: string;
+  /**
+   * 当前日志器。
+   */
+  logger: Logger;
+  /**
+   * 构造 fallback assistant 消息的工厂函数。
+   */
+  buildFallbackAssistantMessage: (text: string) => SessionMessageV1;
+}): Promise<SessionMessageV1> {
+  let streamedAssistantMessage: SessionMessageV1 | null = null;
+  let uiFinishSummary: JsonObject | null = null;
+
+  const uiStream = params.result.toUIMessageStream<SessionMessageV1>({
+    // 关键点（中文）：SDK stream 需要 reasoning 旁路事件时可直接消费；最终落盘仍由 responseMessage 收敛。
+    sendReasoning: true,
+    sendSources: false,
+    onFinish: (event) => {
+      streamedAssistantMessage = event.responseMessage ?? null;
+      uiFinishSummary = {
+        isContinuation: event.isContinuation,
+        isAborted: event.isAborted,
+        finishReason:
+          typeof event.finishReason === "string" ? event.finishReason : null,
+        ...summarizeUiMessageForDebug(event.responseMessage),
+      };
+    },
+  });
+
+  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 params.logger.log("info", "[agent] ui.finish", {
+    sessionId: params.sessionId,
+    ...(uiFinishSummary || {
+      responseMessageMissing: true,
+    }),
+  });
+
+  if (streamedAssistantMessage) return streamedAssistantMessage;
+
+  let assistantText = "";
+  try {
+    assistantText = String((await params.result.text) ?? "").trim();
+  } catch {
+    assistantText = "";
+  }
+
+  await params.logger.log("warn", "[agent] final.message.fallback", {
+    sessionId: params.sessionId,
+    assistantTextLength: assistantText.length,
+    assistantTextPreview: toInlinePreview(assistantText),
+  });
+
+  return params.buildFallbackAssistantMessage(
+    assistantText || "Execution completed",
+  );
+}

package/src/session/messages/SessionStepEventMapper.ts

@@ -8,7 +8,7 @@
  */
 
 import { generateId } from "@/utils/Id.js";
-import type { JsonObject } from "@/utils/types/Json.js";
+import type { JsonObject } from "@/types/common/Json.js";
 import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
 
 type UnknownRecord = Record<string, unknown>;

package/src/session/tools/shell/ShellToolBridge.ts

@@ -7,11 +7,11 @@
  */
 
 import { generateId } from "@/utils/Id.js";
-import type { JsonObject, JsonValue } from "@/utils/types/Json.js";
+import type { JsonObject, JsonValue } from "@/types/common/Json.js";
 import type {
   InvokeServicePort,
   InvokeServiceResult,
-} from "@/agent/AgentContextTypes.js";
+} from "@/runtime/AgentContextTypes.js";
 import type { ShellActionResponse } from "@/service/builtins/shell/types/ShellService.js";
 import {
   enqueueDeferredPersistedUserMessage,

package/src/session/tools/shell/ShellToolDefinition.ts

@@ -17,7 +17,7 @@ import type {
   ShellWaitInput,
   ShellWriteInput,
 } from "@/service/builtins/shell/types/Shell.js";
-import type { JsonObject } from "@/utils/types/Json.js";
+import type { JsonObject } from "@/types/common/Json.js";
 import { validateChatSendCommand } from "./ShellToolFormatting.js";
 import {
   bridgeCommandResponse,

package/src/session/tools/shell/ShellToolFormatting.ts

@@ -6,7 +6,7 @@
  * - 这里仅保留当前仍被 tool 与测试复用的最小能力：命令安全校验与 env 注入。
  */
 
-import { stripInvocationAuthEnv } from "@/host/http/auth/AuthEnv.js";
+import { stripInvocationAuthEnv } from "@/server/http/auth/AuthEnv.js";
 import { getSessionRunScope } from "@session/SessionRunScope.js";
 
 function setEnvString(

package/src/session/types/SessionHistoryMeta.ts

@@ -27,6 +27,8 @@ export type SessionHistoryMetaV1 = {
   agentId?: string;
   /** 当前 session 首次创建时间戳（ms）。 */
   createdAt?: number;
+  /** 当前 session 初始化时解析到的系统时区。 */
+  timezone?: string;
   /** 最近一次更新元信息的时间戳（ms）。 */
   updatedAt: number;
   /** 固定注入到 Session 上下文的 skill id 列表。 */

package/src/session/types/SessionMessages.ts

@@ -8,7 +8,7 @@
  */
 
 import type { UIMessage } from "ai";
-import type { JsonObject } from "@/utils/types/Json.js";
+import type { JsonObject } from "@/types/common/Json.js";
 
 /**
  * Session 消息：以 UIMessage[] 作为唯一事实源。

package/src/{host → transport}/rpc/Client.ts

@@ -12,7 +12,7 @@ import type {
   DaemonJsonApiCallParams,
   DaemonJsonApiCallResult,
 } from "@/host/daemon/Api.js";
-import type { LocalRpcRequest, LocalRpcResponse } from "@/host/rpc/types/LocalRpc.js";
+import type { LocalRpcRequest, LocalRpcResponse } from "@/types/rpc/LocalRpc.js";
 import { getLocalRpcEndpoint } from "./Paths.js";
 
 const LOCAL_RPC_TIMEOUT_MS = 5_000;