@downcity/agent 1.1.217 → 1.1.222

package/src/session/recorder/SessionRecorderCompaction.ts

@@ -0,0 +1,187 @@
+/**
+ * SessionRecorder canonical 上下文压缩。
+ *
+ * 压缩只追加一条 internal summary Message，不删除、不归档、不重写 Mutation 日志。
+ */
+
+import { generateText } from "ai";
+import { generateId } from "@/utils/Id.js";
+import type { SessionHistoryCompactInput } from "@/executor/store/history/SessionHistoryStore.js";
+import type { SessionActionRecordV1 } from "@/executor/types/SessionRecords.js";
+import {
+  build_initial_session_compaction_prompt,
+  build_update_session_compaction_prompt,
+  SESSION_COMPACTION_SYSTEM_PROMPT,
+} from "@executor/composer/compaction/jsonl/JsonlSessionCompactionPrompts.js";
+import { SessionRecorder } from "@/session/recorder/SessionRecorder.js";
+import { to_executor_ui_message } from "@/session/recorder/SessionMessageCodec.js";
+import type { SessionAssistantMessage, SessionMessage } from "@/types/session/SessionMessage.js";
+
+/** 必要时把较早上下文追加为 canonical internal summary。 */
+export async function compact_session_recorder_messages(input: {
+  /** 当前 Session Recorder。 */
+  recorder: SessionRecorder;
+  /** 压缩策略和模型。 */
+  compact_input: SessionHistoryCompactInput;
+}): Promise<{ compacted: boolean; reason?: string }> {
+  const page = await input.recorder.list_messages({
+    limit: 500,
+    include_internal: true,
+  });
+  const context_messages = project_current_context(page.items);
+  if (context_messages.length < 4) {
+    return { compacted: false, reason: "small_messages" };
+  }
+  const system_text = input.compact_input.system
+    .map((message) => String(message.content || ""))
+    .join("\n\n");
+  const estimated_tokens = Math.ceil(
+    `${system_text}\n${JSON.stringify(context_messages)}`.length / 3,
+  );
+  if (estimated_tokens <= input.compact_input.maxInputTokensApprox) {
+    return { compacted: false, reason: "under_budget" };
+  }
+
+  const ratio = Math.max(0.1, Math.min(0.9, input.compact_input.compactRatio));
+  const compact_count = Math.max(
+    2,
+    Math.min(context_messages.length - 1, Math.floor(context_messages.length * ratio)),
+  );
+  const older = context_messages.slice(0, compact_count);
+  const boundary = [...older]
+    .reverse()
+    .find((message) => message.type !== "assistant" || message.kind !== "summary");
+  if (!boundary) return { compacted: false, reason: "nothing_to_compact" };
+
+  const action_id = `compacting:${input.recorder.session_id}:${generateId()}`;
+  await publish_action(input.compact_input.onAction, {
+    id: action_id,
+    session_id: input.recorder.session_id,
+    title: "Compacting session messages",
+    state: "running",
+  });
+
+  const previous_summary = older.find(
+    (message): message is SessionAssistantMessage =>
+      message.type === "assistant" && message.kind === "summary",
+  );
+  const conversation_text = older
+    .filter((message) => message !== previous_summary)
+    .map((message) => message_to_compaction_text(message))
+    .filter(Boolean)
+    .join("\n")
+    .slice(-24_000);
+  const previous_summary_text = previous_summary
+    ? assistant_text(previous_summary)
+    : "";
+  const prompt = previous_summary_text
+    ? build_update_session_compaction_prompt({
+        previous_summary: previous_summary_text,
+        new_conversation_text: conversation_text || "(none)",
+      })
+    : build_initial_session_compaction_prompt({
+        conversation_text: conversation_text || "(none)",
+      });
+
+  let summary = "";
+  try {
+    const result = await generateText({
+      model: input.compact_input.model,
+      system: [{ role: "system", content: SESSION_COMPACTION_SYSTEM_PROMPT }],
+      prompt,
+    });
+    summary = String(result.text || "").trim();
+  } catch {
+    summary = "Earlier conversation was compacted because the context window was exceeded.";
+  }
+
+  await input.recorder.append_completed_assistant_message({
+    turn_id: `compact:${input.recorder.session_id}:${generateId()}`,
+    kind: "summary",
+    visibility: "internal",
+    summary_through_message_id: boundary.message_id,
+    parts: [{
+      part_id: `summary-text:${generateId()}`,
+      type: "text",
+      text: summary,
+      state: "done",
+    }],
+  });
+  await publish_action(input.compact_input.onAction, {
+    id: action_id,
+    session_id: input.recorder.session_id,
+    title: "Session messages compacted",
+    description: `Compacted through Message ${boundary.message_id}.`,
+    state: "completed",
+  });
+  return { compacted: true };
+}
+
+function project_current_context(messages: SessionMessage[]): SessionMessage[] {
+  const latest_summary = [...messages].reverse().find(
+    (message): message is SessionAssistantMessage =>
+      message.type === "assistant" &&
+      message.kind === "summary" &&
+      message.visibility === "internal",
+  );
+  if (!latest_summary?.summary_through_message_id) {
+    return messages.filter(
+      (message) => message.type === "user" || message.type === "assistant",
+    );
+  }
+  const boundary_index = messages.findIndex(
+    (message) => message.message_id === latest_summary.summary_through_message_id,
+  );
+  return [
+    latest_summary,
+    ...messages.slice(boundary_index + 1).filter(
+      (message) =>
+        message !== latest_summary &&
+        (message.type === "user" ||
+          message.type === "assistant" && message.kind !== "summary"),
+    ),
+  ];
+}
+
+function message_to_compaction_text(message: SessionMessage): string {
+  const projected = to_executor_ui_message(message);
+  if (!projected) return "";
+  const text = projected.parts
+    .flatMap((part) => part.type === "text" ? [String(part.text || "")] : [])
+    .join("\n")
+    .trim();
+  return text ? `${message.type}: ${text}` : "";
+}
+
+function assistant_text(message: SessionAssistantMessage): string {
+  return message.parts
+    .flatMap((part) => part.type === "text" ? [part.text] : [])
+    .join("\n")
+    .trim();
+}
+
+async function publish_action(
+  callback: SessionHistoryCompactInput["onAction"],
+  input: {
+    id: string;
+    session_id: string;
+    title: string;
+    description?: string;
+    state: "running" | "completed";
+  },
+): Promise<void> {
+  if (!callback) return;
+  const action: SessionActionRecordV1 = {
+    type: "action",
+    id: input.id,
+    title: input.title,
+    ...(input.description ? { description: input.description } : {}),
+    state: input.state,
+    metadata: {
+      v: 1,
+      ts: Date.now(),
+      sessionId: input.session_id,
+    },
+  };
+  await callback(action);
+}

package/src/session/recorder/SessionRecorderHistoryStore.ts

@@ -0,0 +1,276 @@
+/**
+ * SessionRecorder 到 Executor SessionHistoryStore 的内部投影适配器。
+ *
+ * 关键点（中文）
+ * - Recorder messages.jsonl 是唯一持久化事实源。
+ * - Executor 继续读取临时 UIMessage 投影，不直接拥有文件写入权。
+ * - inflight 写入已经由 AssistantMessageWriter 取代，因此对应接口只提供投影兼容。
+ */
+
+import { nanoid } from "nanoid";
+import type {
+  SessionActionRecordV1,
+  SessionMetadataV1,
+  SessionRecordV1,
+} from "@/executor/types/SessionRecords.js";
+import { is_session_action_record } from "@/executor/types/SessionRecords.js";
+import type {
+  SessionHistoryCompactInput,
+  SessionHistoryStore,
+} from "@/executor/store/history/SessionHistoryStore.js";
+import { SessionRecorder } from "@/session/recorder/SessionRecorder.js";
+import {
+  from_ui_assistant_parts,
+  from_ui_user_parts,
+  to_executor_ui_message,
+} from "@/session/recorder/SessionMessageCodec.js";
+import { compact_session_recorder_messages } from "@/session/recorder/SessionRecorderCompaction.js";
+
+/** Recorder History Store 构造参数。 */
+export interface SessionRecorderHistoryStoreOptions {
+  /** 当前 Session 标识。 */
+  session_id: string;
+  /** 当前 Session Recorder。 */
+  recorder: SessionRecorder;
+}
+
+/** 只把 canonical SessionMessage 投影给 Executor 的 Store。 */
+export class SessionRecorderHistoryStore implements SessionHistoryStore {
+  readonly sessionId: string;
+
+  private readonly recorder: SessionRecorder;
+
+  constructor(options: SessionRecorderHistoryStoreOptions) {
+    this.sessionId = String(options.session_id || "").trim();
+    this.recorder = options.recorder;
+    if (!this.sessionId) {
+      throw new Error("SessionRecorderHistoryStore requires session_id");
+    }
+  }
+
+  /** 把外部 user/assistant/action 写入请求收口到 Recorder。 */
+  async write_record(message: SessionRecordV1): Promise<void> {
+    if (is_session_action_record(message)) {
+      const action = message as SessionActionRecordV1;
+      const existing = this.recorder.get_message(action.id);
+      if (existing?.type === "action") {
+        if (action.state !== "running") {
+          await this.recorder.update_action_message(
+            action.id,
+            action.state,
+            {
+              title: action.title,
+              description: action.description,
+            },
+          );
+        }
+        return;
+      }
+      const writer = await this.recorder.open_action_message({
+        message_id: action.id,
+        turn_id: action.metadata.turnId,
+        action_type: infer_action_type(action.id),
+        title: action.title,
+        description: action.description,
+      });
+      if (action.state === "completed") await writer.complete();
+      if (action.state === "failed") await writer.fail(action.description || action.title);
+      return;
+    }
+
+    if (message.role === "user") {
+      const metadata = message.metadata || {
+        v: 1 as const,
+        ts: Date.now(),
+        sessionId: this.sessionId,
+      };
+      await this.recorder.append_user_message({
+        turn_id: String(metadata.turnId || `external:${nanoid(10)}`),
+        input_type:
+          metadata.extra?.inputType === "steer" ? "steer" : "prompt",
+        parts: from_ui_user_parts(message.parts),
+      });
+      return;
+    }
+
+    const metadata = message.metadata || {
+      v: 1 as const,
+      ts: Date.now(),
+      sessionId: this.sessionId,
+    };
+    await this.recorder.append_completed_assistant_message({
+      turn_id: metadata.turnId,
+      parts: from_ui_assistant_parts(message.parts),
+      visibility:
+        metadata.extra?.visibility === "internal"
+          ? "internal"
+          : "visible",
+      kind: metadata.kind === "summary" ? "summary" : "normal",
+    });
+  }
+
+  /** Recorder 已经逐 delta 保存 assistant，不再维护第二份 inflight。 */
+  async read_inflight(): Promise<SessionRecordV1 | null> {
+    const page = await this.recorder.list_messages({
+      limit: 500,
+      include_internal: true,
+    });
+    const assistant = [...page.items]
+      .reverse()
+      .find(
+        (message) =>
+          message.type === "assistant" && message.status === "streaming",
+      );
+    return assistant ? to_executor_ui_message(assistant) : null;
+  }
+
+  /** 旧 inflight 写入口已废弃；流式内容由 Recorder writer 负责。 */
+  async write_inflight(_message: SessionRecordV1): Promise<void> {}
+
+  /** 旧 inflight 收口入口已废弃；Assistant writer 负责 complete。 */
+  async finalize_inflight(_message?: SessionRecordV1 | null): Promise<void> {}
+
+  /** 返回 Context Composer 使用的 UIMessage 投影。 */
+  async list_records(): Promise<SessionRecordV1[]> {
+    const page = await this.recorder.list_messages({
+      limit: 500,
+      include_internal: true,
+    });
+    const messages = project_context_messages(page.items);
+    return messages.flatMap((message) => {
+      const projected = to_executor_ui_message(message);
+      return projected ? [projected] : [];
+    });
+  }
+
+  /** 返回 Context Message 区间。 */
+  async slice_records(start: number, end: number): Promise<SessionRecordV1[]> {
+    return (await this.list_records()).slice(start, end);
+  }
+
+  /** 返回 Context Message 数量。 */
+  async record_count(): Promise<number> {
+    return (await this.list_records()).length;
+  }
+
+  /** Recorder metadata 由 SessionStateService 管理。 */
+  async meta(): Promise<Record<string, unknown>> {
+    return {};
+  }
+
+  /** 通过 Recorder 追加 internal summary，不重写 Mutation 历史。 */
+  async compact(input: SessionHistoryCompactInput): Promise<{
+    compacted: boolean;
+    reason?: string;
+  }> {
+    return await compact_session_recorder_messages({
+      recorder: this.recorder,
+      compact_input: input,
+    });
+  }
+
+  /** 构造临时 user UIMessage。 */
+  userText(input: {
+    text: string;
+    metadata: Omit<SessionMetadataV1, "v" | "ts"> &
+      Partial<Pick<SessionMetadataV1, "ts">>;
+    id?: string;
+  }): SessionRecordV1 {
+    const { ts, ...metadata } = input.metadata;
+    return {
+      id: input.id || `u:${this.sessionId}:${nanoid(10)}`,
+      role: "user",
+      metadata: {
+        v: 1,
+        ts: typeof ts === "number" ? ts : Date.now(),
+        ...metadata,
+        source: "ingress",
+        kind: "normal",
+      },
+      parts: [{ type: "text", text: String(input.text || "") }],
+    };
+  }
+
+  /** 构造临时 assistant UIMessage。 */
+  assistantText(input: {
+    text: string;
+    metadata: Omit<SessionMetadataV1, "v" | "ts"> &
+      Partial<Pick<SessionMetadataV1, "ts">>;
+    id?: string;
+    kind?: "normal" | "summary";
+    source?: "egress" | "compact";
+  }): SessionRecordV1 {
+    const { ts, ...metadata } = input.metadata;
+    return {
+      id: input.id || `a:${this.sessionId}:${nanoid(10)}`,
+      role: "assistant",
+      metadata: {
+        v: 1,
+        ts: typeof ts === "number" ? ts : Date.now(),
+        ...metadata,
+        source: input.source || "egress",
+        kind: input.kind || "normal",
+      },
+      parts: [{ type: "text", text: String(input.text || "") }],
+    };
+  }
+
+  /** 返回 action 原结构，真正持久化仍经过 write_record。 */
+  action(input: {
+    action: SessionActionRecordV1;
+    metadata: Pick<SessionMetadataV1, "sessionId"> &
+      Partial<Pick<SessionMetadataV1, "ts">>;
+    id?: string;
+  }): SessionActionRecordV1 {
+    return {
+      ...input.action,
+      id: input.id || input.action.id,
+      metadata: {
+        ...input.action.metadata,
+        sessionId: input.metadata.sessionId,
+        ts:
+          typeof input.metadata.ts === "number"
+            ? input.metadata.ts
+            : input.action.metadata.ts,
+      },
+    };
+  }
+}
+
+function project_context_messages(messages: import("@/types/session/SessionMessage.js").SessionMessage[]) {
+  const latest_summary = [...messages]
+    .reverse()
+    .find(
+      (message) =>
+        message.type === "assistant" &&
+        message.kind === "summary" &&
+        message.visibility === "internal",
+    );
+  if (
+    !latest_summary ||
+    latest_summary.type !== "assistant" ||
+    !latest_summary.summary_through_message_id
+  ) {
+    return messages.filter(
+      (message) => message.type === "user" || message.type === "assistant",
+    );
+  }
+  const boundary_index = messages.findIndex(
+    (message) => message.message_id === latest_summary.summary_through_message_id,
+  );
+  return [
+    latest_summary,
+    ...messages
+      .slice(boundary_index + 1)
+      .filter(
+        (message) =>
+          message !== latest_summary &&
+          message.type === "user" ||
+          (message.type === "assistant" && message.kind !== "summary"),
+      ),
+  ];
+}
+
+function infer_action_type(message_id: string): string {
+  return String(message_id || "").split(":")[0] || "action";
+}

package/src/session/runtime/SessionMessageEventHub.ts

@@ -0,0 +1,35 @@
+/**
+ * SessionMessage mutation 事件总线。
+ *
+ * EventHub 只广播 Recorder 已成功提交的 mutation，不创建或转换事件。
+ */
+
+import type {
+  SessionMessageMutation,
+  SessionMessageMutationSubscriber,
+  SessionMessageMutationUnsubscribe,
+} from "@/types/session/SessionMessageMutation.js";
+
+/** SessionMessage mutation 的进程内广播器。 */
+export class SessionMessageEventHub {
+  private readonly subscribers = new Set<SessionMessageMutationSubscriber>();
+
+  /** 订阅未来成功提交的 mutation。 */
+  subscribe(subscriber: SessionMessageMutationSubscriber): SessionMessageMutationUnsubscribe {
+    this.subscribers.add(subscriber);
+    return () => {
+      this.subscribers.delete(subscriber);
+    };
+  }
+
+  /** 广播一条已持久化 mutation。 */
+  publish(mutation: SessionMessageMutation): void {
+    for (const subscriber of this.subscribers) {
+      try {
+        subscriber(mutation);
+      } catch {
+        // 单个订阅者失败不能影响提交结果和其他订阅者。
+      }
+    }
+  }
+}

package/src/session/runtime/SessionPromptRuntime.ts

@@ -96,21 +96,16 @@ export interface SessionPromptRuntimeOptions {
    */
   createAndPersistUserMessage: (
     input: AgentSessionPromptInput,
+    turn_id: string,
+    input_type: "prompt" | "steer",
   ) => Promise<SessionUserMessageV1>;
 
-  /**
-   * 在 steer message 成功持久化后发送对应 action。
-   */
-  emit_steer_action: (input: {
-    /**
-     * steer message 所属的当前 turn 标识。
-     */
+  /** 持久化一条用户可见的 turn 错误 Message。 */
+  appendErrorMessage: (input: {
+    /** 错误所属 turn。 */
     turn_id: string;
-
-    /**
-     * 已成功持久化的 steer message。
-     */
-    message: SessionUserMessageV1;
+    /** 用户可见错误文本。 */
+    message: string;
   }) => Promise<void>;
 
   /**
@@ -141,7 +136,7 @@ export class SessionPromptRuntime {
   private readonly sessionId: string;
   private readonly publish: SessionPromptRuntimeOptions["publish"];
   private readonly createAndPersistUserMessage: SessionPromptRuntimeOptions["createAndPersistUserMessage"];
-  private readonly emit_steer_action: SessionPromptRuntimeOptions["emit_steer_action"];
+  private readonly appendErrorMessage: SessionPromptRuntimeOptions["appendErrorMessage"];
   private readonly executeTurn: SessionPromptRuntimeOptions["executeTurn"];
   private readonly stopTurn: SessionPromptRuntimeOptions["stopTurn"];
   private readonly queue: QueuedPrompt[] = [];
@@ -152,7 +147,7 @@ export class SessionPromptRuntime {
     this.sessionId = String(options.sessionId || "").trim();
     this.publish = options.publish;
     this.createAndPersistUserMessage = options.createAndPersistUserMessage;
-    this.emit_steer_action = options.emit_steer_action;
+    this.appendErrorMessage = options.appendErrorMessage;
     this.executeTurn = options.executeTurn;
     this.stopTurn = options.stopTurn;
     if (!this.sessionId) {
@@ -237,7 +232,7 @@ export class SessionPromptRuntime {
       current.deferredHandle.resolve(createTurnHandle(activeTurn));
 
       try {
-        await this.createAndPersistUserMessage(current.input);
+        await this.createAndPersistUserMessage(current.input, turnId, "prompt");
         const result = await this.executeTurn({
           turnId,
           promptInput: current.input,
@@ -283,6 +278,14 @@ export class SessionPromptRuntime {
         };
         activeTurn.result = finalResult;
         if (message !== TURN_STOPPED_MESSAGE) {
+          try {
+            await this.appendErrorMessage({
+              turn_id: turnId,
+              message,
+            });
+          } catch {
+            // Error Message 写入失败不能阻止 turn handle 收口。
+          }
           this.publish({
             type: "error",
             message,
@@ -348,17 +351,13 @@ export class SessionPromptRuntime {
     for (let index = 0; index < drained.length; index += 1) {
       const item = drained[index];
       try {
-        const message = await this.createAndPersistUserMessage(item.input);
+        const message = await this.createAndPersistUserMessage(
+          item.input,
+          activeTurn.turnId,
+          "steer",
+        );
         item.deferredHandle.resolve(createTurnHandle(activeTurn));
         merged.push(message);
-        try {
-          await this.emit_steer_action({
-            turn_id: activeTurn.turnId,
-            message,
-          });
-        } catch {
-          // action 发送失败不应阻断已经持久化的 steer message。
-        }
       } catch {
         // 关键点（中文）：若某条消息持久化失败，把未处理部分重新放回队列头部，避免静默丢失。
         const remaining = drained.slice(index);