@downcity/agent 1.1.74 → 1.1.81

package/src/executor/messages/SessionStepEventMapper.ts

@@ -1,14 +1,12 @@
 /**
- * SessionStepEventMapper：把单个 step 结果转成按顺序可持久化的 session 消息。
+ * SessionStepEventMapper：把单个 step 结果转成 assistant parts。
  *
  * 关键点（中文）
- * - 工具结果使用 AI SDK v6 UI tool part 格式，避免历史重放时丢失 tool result。
- * - 只做 best-effort 提取，不依赖 provider 私有结构。
- * - 输出仍然是标准 SessionMessageV1，供 SessionHistoryWriter 直接落盘。
+ * - 运行过程仍然要持久化，但收口到同一条 assistant UIMessage。
+ * - 工具结果使用 AI SDK v6 UI tool part 格式，和官方 UIMessage 语义保持一致。
+ * - 每个 step 前插入 `step-start`，便于在 UI 中保留多 step 边界。
  */
 
-import { generateId } from "@/utils/Id.js";
-import type { JsonObject } from "@/types/common/Json.js";
 import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
 
 type UnknownRecord = Record<string, unknown>;
@@ -64,6 +62,21 @@ function resolveToolResultPayload(value: unknown): unknown {
   return undefined;
 }
 
+function resolveToolResultErrorText(value: unknown): string | undefined {
+  const record = toRecord(value);
+  if (!record) return undefined;
+  if (typeof record.errorText === "string" && record.errorText.trim()) {
+    return record.errorText.trim();
+  }
+  if (typeof record.error === "string" && record.error.trim()) {
+    return record.error.trim();
+  }
+  if (record.error instanceof Error && record.error.message.trim()) {
+    return record.error.message.trim();
+  }
+  return undefined;
+}
+
 function mapToolResultsByCallId(toolResults: unknown[]): Map<string, unknown> {
   const out = new Map<string, unknown>();
   for (const toolResult of toolResults) {
@@ -91,53 +104,16 @@ function toDataPartType(type: string): string {
   return `data-acp-${type.replace(/_/g, "-")}`;
 }
 
-function buildMetadata(params: {
-  sessionId: string;
-  ts: number;
-  extra?: JsonObject;
-}): SessionMessageV1["metadata"] {
-  return {
-    v: 1,
-    ts: params.ts,
-    sessionId: params.sessionId,
-    source: "egress",
-    kind: "normal",
-    ...(params.extra ? { extra: params.extra } : {}),
-  };
-}
-
-function buildAssistantStepMessage(params: {
-  sessionId: string;
-  ts: number;
-  part: Record<string, unknown>;
-  extra: JsonObject;
-}): SessionMessageV1 {
-  return {
-    id: `a:${params.sessionId}:${generateId()}`,
-    role: "assistant",
-    metadata: buildMetadata({
-      sessionId: params.sessionId,
-      ts: params.ts,
-      extra: params.extra,
-    }),
-    parts: [params.part as SessionMessageV1["parts"][number]],
-  };
-}
-
 /**
- * 从 stepResult 提取按顺序落盘的 session assistant 消息。
+ * 从 stepResult 提取按顺序写入同一条 assistant message 的 parts。
  */
-export function buildSessionStepEventMessages(params: {
-  sessionId: string;
+export function buildSessionStepParts(params: {
   stepIndex: number;
   stepResult?: unknown;
   text: string;
   visibility?: "visible" | "internal";
-}): SessionMessageV1[] {
-  const sessionId = String(params.sessionId || "").trim();
-  if (!sessionId) return [];
-
-  const out: SessionMessageV1[] = [];
+}): SessionMessageV1["parts"] {
+  const out: SessionMessageV1["parts"] = [];
   const stepRecord = toRecord(params.stepResult) || {};
   const toolCalls = Array.isArray(stepRecord.toolCalls) ? stepRecord.toolCalls : [];
   const toolResults = Array.isArray(stepRecord.toolResults)
@@ -147,34 +123,29 @@ export function buildSessionStepEventMessages(params: {
   const acpEvents = Array.isArray(stepRecord.acpEvents)
     ? stepRecord.acpEvents
     : [];
-  const baseTs = Date.now();
-  let sequence = 0;
 
   const text = String(params.text || "").trim();
+  const has_structured_output =
+    Boolean(text) || toolCalls.length > 0 || acpEvents.length > 0;
+  if (!has_structured_output) return [];
+
+  out.push({ type: "step-start" });
+
   if (text) {
     const isInternal = params.visibility === "internal";
     out.push(
-      buildAssistantStepMessage({
-        sessionId,
-        ts: baseTs + sequence,
-        part: isInternal
-          ? {
-              type: "reasoning",
-              text,
-              state: "done",
-            }
-          : {
-              type: "text",
-              text,
-            },
-        extra: {
-          internal: isInternal ? "assistant_step_reasoning" : "assistant_step_text",
-          stepIndex: params.stepIndex,
-          persistedBy: "session_store_run",
-        },
-      }),
+      isInternal
+        ? {
+            type: "reasoning",
+            text,
+            state: "done",
+          }
+        : {
+            type: "text",
+            text,
+            state: "done",
+          },
     );
-    sequence += 1;
   }
 
   for (let index = 0; index < toolCalls.length; index += 1) {
@@ -185,25 +156,23 @@ export function buildSessionStepEventMessages(params: {
     const toolResult = toolCallId ? toolResultsByCallId.get(toolCallId) : undefined;
     if (!toolResult) continue;
     const output = resolveToolResultPayload(toolResult);
+    const errorText = resolveToolResultErrorText(toolResult);
     out.push(
-      buildAssistantStepMessage({
-        sessionId,
-        ts: baseTs + sequence,
-        part: {
-          type: `tool-${toolName}`,
-          ...(toolCallId ? { toolCallId } : {}),
-          ...(input !== undefined ? { input } : {}),
-          state: "output-available",
-          output,
-        },
-        extra: {
-          internal: "assistant_step_tool_result",
-          stepIndex: params.stepIndex,
-          toolIndex: index + 1,
-        },
-      }),
+      {
+        type: `tool-${toolName}`,
+        ...(toolCallId ? { toolCallId } : {}),
+        ...(input !== undefined ? { input } : {}),
+        ...(errorText
+          ? {
+              state: "output-error",
+              errorText,
+            }
+          : {
+              state: "output-available",
+              output,
+            }),
+      } as SessionMessageV1["parts"][number],
     );
-    sequence += 1;
   }
 
   for (let index = 0; index < acpEvents.length; index += 1) {
@@ -211,22 +180,11 @@ export function buildSessionStepEventMessages(params: {
     const type = resolveAcpEventType(acpEvent);
     if (!type) continue;
     out.push(
-      buildAssistantStepMessage({
-        sessionId,
-        ts: baseTs + sequence,
-        part: {
-          type: toDataPartType(type),
-          data: resolveAcpEventData(acpEvent),
-        },
-        extra: {
-          internal: "assistant_step_acp_event",
-          stepIndex: params.stepIndex,
-          acpEventType: type,
-          eventIndex: index + 1,
-        },
-      }),
+      {
+        type: toDataPartType(type),
+        data: resolveAcpEventData(acpEvent),
+      } as SessionMessageV1["parts"][number],
     );
-    sequence += 1;
   }
 
   return out;

package/src/executor/messages/UserVisibleText.ts

@@ -17,29 +17,14 @@ import {
  * 生成真正应该落盘到 session 的 assistant message。
  *
  * 关键点（中文）
- * - 没有 step 持久化时，直接保留完整 assistant message。
- * - 一旦 step 已单独落盘，最终 merged assistant 不再重复写入。
+ * - session 正式历史应尽量保留 AI SDK 最终 assistant UIMessage。
+ * - 运行中 step/tool 的中断恢复由 inflight 快照承担，不再通过跳过最终 message 收口。
  */
 export function resolveAssistantMessageForPersistence(
   message: SessionMessageV1 | null | undefined,
 ): SessionMessageV1 | null {
   if (!message || typeof message !== "object") return null;
-  return hasPersistedAssistantSteps(message) ? null : message;
-}
-
-/**
- * 判断 assistant message 是否声明“本轮 step 消息已单独持久化”。
- *
- * 关键点（中文）
- * - 该标记只用于避免在 run 结束时把最终 merged assistant 再重复写入 context。
- * - 不影响 channel 发送；只影响 context messages 的最终 append 策略。
- */
-export function hasPersistedAssistantSteps(
-  message: SessionMessageV1 | null | undefined,
-): boolean {
-  const extra = message?.metadata?.extra;
-  if (!extra || typeof extra !== "object" || Array.isArray(extra)) return false;
-  return extra.assistantStepMessagesPersisted === true;
+  return message;
 }
 
 /**

package/src/executor/services/ExecutorInflightService.ts

@@ -0,0 +1,101 @@
+/**
+ * ExecutorInflightService：运行中 assistant 快照写入服务。
+ *
+ * 关键点（中文）
+ * - 只负责把 step/tool 增量写入当前 inflight assistant 快照。
+ * - 不负责长期 history 组装，不负责主执行循环。
+ * - 保持与 SessionHistoryStore 的交互边界清晰，避免 Executor 自身同时承担编排与写入细节。
+ */
+
+import { generateId } from "@/utils/Id.js";
+import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
+import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+
+interface ExecutorInflightServiceOptions {
+  /**
+   * 当前 session 标识。
+   */
+  session_id: string;
+
+  /**
+   * 当前 session 对应的 history 事实源。
+   */
+  history_store: SessionHistoryStore;
+
+  /**
+   * inflight 更新完成后的异步通知。
+   */
+  run_after_session_updated_async?: () => Promise<void>;
+}
+
+/**
+ * 运行中 assistant 快照写入服务。
+ */
+export class ExecutorInflightService {
+  private readonly session_id: string;
+  private readonly history_store: SessionHistoryStore;
+  private readonly run_after_session_updated_async?: ExecutorInflightServiceOptions["run_after_session_updated_async"];
+
+  constructor(options: ExecutorInflightServiceOptions) {
+    this.session_id = String(options.session_id || "").trim();
+    this.history_store = options.history_store;
+    this.run_after_session_updated_async =
+      options.run_after_session_updated_async;
+
+    if (!this.session_id) {
+      throw new Error("ExecutorInflightService requires a non-empty session_id");
+    }
+  }
+
+  /**
+   * 把 step/tool 过程增量写入当前运行中的 assistant 快照。
+   */
+  async append_assistant_step_parts(
+    parts: SessionMessageV1["parts"],
+  ): Promise<void> {
+    const normalized_parts = Array.isArray(parts)
+      ? parts.filter((part) => part && typeof part === "object")
+      : [];
+    if (normalized_parts.length === 0) return;
+
+    const current_inflight = await this.history_store.readInflight();
+    const next_message: SessionMessageV1 = current_inflight
+      ? {
+          ...current_inflight,
+          metadata: {
+            ...(current_inflight.metadata || {
+              v: 1 as const,
+              ts: Date.now(),
+              sessionId: this.session_id,
+            }),
+            ts: Date.now(),
+            sessionId: this.session_id,
+            source: "egress",
+            kind: "normal",
+          },
+          parts: [
+            ...(Array.isArray(current_inflight.parts)
+              ? current_inflight.parts
+              : []),
+            ...normalized_parts,
+          ],
+        }
+      : {
+          id: `a:${this.session_id}:${generateId()}`,
+          role: "assistant",
+          metadata: {
+            v: 1,
+            ts: Date.now(),
+            sessionId: this.session_id,
+            source: "egress",
+            kind: "normal",
+          },
+          parts: normalized_parts,
+        };
+
+    await this.history_store.writeInflight(next_message);
+    if (this.run_after_session_updated_async) {
+      await this.run_after_session_updated_async();
+    }
+  }
+}

package/src/executor/services/ExecutorRecoveryPolicy.ts

@@ -0,0 +1,213 @@
+/**
+ * ExecutorRecoveryPolicy：执行恢复与重试策略。
+ *
+ * 关键点（中文）
+ * - 统一封装“压缩后重试”和“普通失败兜底”逻辑。
+ * - Executor 只负责准备输入与调用策略，不再直接承载重试状态机。
+ * - 不改变外部行为，只把异常分流规则集中到一个地方。
+ */
+
+import type { LanguageModel } from "ai";
+import type { Logger } from "@/utils/logger/Logger.js";
+import type { SessionCompactionComposer } from "@executor/composer/compaction/SessionCompactionComposer.js";
+import type { SessionContextComposer } from "@executor/composer/context/SessionContextComposer.js";
+import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
+import type {
+  SessionExecuteInput,
+  SessionRunResult,
+} from "@/executor/types/SessionRun.js";
+
+/**
+ * 可压缩错误的最大重试次数。
+ */
+const MAX_COMPACTION_RETRY_ATTEMPTS = 3;
+
+interface ExecutorRecoveryPolicyOptions {
+  /**
+   * 当前 session 对应的 compaction Composer。
+   */
+  compaction_composer: SessionCompactionComposer;
+
+  /**
+   * 当前 session 对应的 context Composer。
+   */
+  context_composer: SessionContextComposer;
+
+  /**
+   * 当前 session 统一日志器。
+   */
+  logger: Logger;
+}
+
+interface ExecutorPrepareRunInput {
+  /**
+   * 当前轮用户 query。
+   */
+  query: string;
+
+  /**
+   * 当前轮模型实例。
+   */
+  model: LanguageModel;
+
+  /**
+   * 当前显式运行上下文。
+   */
+  run_context: SessionRunContext;
+
+  /**
+   * 当前压缩重试次数。
+   */
+  retry_count: number;
+}
+
+interface ExecutorExecutePreparedRunInput {
+  /**
+   * 已装配好的执行输入。
+   */
+  execute_input: SessionExecuteInput;
+
+  /**
+   * 当前轮模型实例。
+   */
+  model: LanguageModel;
+
+  /**
+   * 当前显式运行上下文。
+   */
+  run_context: SessionRunContext;
+}
+
+interface ExecutorRecoveryRunInput {
+  /**
+   * 当前轮用户 query。
+   */
+  query: string;
+
+  /**
+   * 当前轮模型实例。
+   */
+  model: LanguageModel;
+
+  /**
+   * 当前显式运行上下文。
+   */
+  run_context: SessionRunContext;
+
+  /**
+   * 运行前装配执行输入。
+   */
+  prepare_execute_input: (
+    input: ExecutorPrepareRunInput,
+  ) => Promise<SessionExecuteInput>;
+
+  /**
+   * 执行已装配好的运行输入。
+   */
+  execute_prepared_run: (
+    input: ExecutorExecutePreparedRunInput,
+  ) => Promise<SessionRunResult>;
+}
+
+/**
+ * 执行恢复与重试策略服务。
+ */
+export class ExecutorRecoveryPolicy {
+  private readonly compaction_composer: SessionCompactionComposer;
+  private readonly context_composer: SessionContextComposer;
+  private readonly logger: Logger;
+  private retry_count = 0;
+
+  constructor(options: ExecutorRecoveryPolicyOptions) {
+    this.compaction_composer = options.compaction_composer;
+    this.context_composer = options.context_composer;
+    this.logger = options.logger;
+  }
+
+  /**
+   * 重置当前 run 级状态。
+   */
+  reset_run_state(): void {
+    this.retry_count = 0;
+  }
+
+  /**
+   * 执行一次带恢复策略的 session run。
+   */
+  async run_with_retry(
+    input: ExecutorRecoveryRunInput,
+  ): Promise<SessionRunResult> {
+    try {
+      const execute_input = await input.prepare_execute_input({
+        query: input.query,
+        model: input.model,
+        run_context: input.run_context,
+        retry_count: this.retry_count,
+      });
+      return await input.execute_prepared_run({
+        execute_input,
+        model: input.model,
+        run_context: input.run_context,
+      });
+    } catch (error) {
+      if (this.compaction_composer.shouldCompactOnError(error)) {
+        await this.logger.log("info", "[agent] compacting", {
+          retryCount: this.retry_count,
+          error: String(error),
+        });
+
+        if (this.retry_count < MAX_COMPACTION_RETRY_ATTEMPTS) {
+          this.retry_count += 1;
+          return await this.run_with_retry(input);
+        }
+
+        return this.build_failure_result({
+          error_text:
+            "Context length exceeded and retries failed. Please resend your question.",
+          fallback_text:
+            "Context length exceeded and retries failed. Please resend your question.",
+          run_context: input.run_context,
+        });
+      }
+
+      const error_text = String(error);
+      await this.logger.log("error", "Executor execution failed", {
+        error: error_text,
+      });
+      return this.build_failure_result({
+        error_text,
+        fallback_text: `Execution failed: ${error_text}`,
+        run_context: input.run_context,
+      });
+    }
+  }
+
+  private build_failure_result(input: {
+    /**
+     * 对外暴露的错误文本。
+     */
+    error_text: string;
+
+    /**
+     * fallback assistant 消息文本。
+     */
+    fallback_text: string;
+
+    /**
+     * 当前显式运行上下文。
+     */
+    run_context: SessionRunContext;
+  }): SessionRunResult {
+    return {
+      success: false,
+      error: input.error_text,
+      assistantMessage: this.context_composer.buildFallbackAssistantMessage(
+        input.fallback_text,
+        input.run_context,
+      ),
+      deferredPersistedUserMessages: [
+        ...input.run_context.deferredPersistedUserMessages,
+      ],
+    };
+  }
+}

package/src/executor/store/history/SessionHistoryStore.ts

@@ -63,6 +63,21 @@ export interface SessionHistoryStore {
    */
   append(message: SessionMessageV1): Promise<void>;
 
+  /**
+   * 读取当前运行中的 assistant 快照。
+   */
+  readInflight(): Promise<SessionMessageV1 | null>;
+
+  /**
+   * 写入当前运行中的 assistant 快照。
+   */
+  writeInflight(message: SessionMessageV1): Promise<void>;
+
+  /**
+   * 用最终 assistant 收口 inflight 快照。
+   */
+  finalizeInflight(message?: SessionMessageV1 | null): Promise<void>;
+
   /**
    * 读取完整消息历史。
    */