@downcity/agent 1.1.226 → 1.1.232

package/src/session/recorder/SessionRecorder.ts

@@ -11,6 +11,7 @@ import type { JsonObject, JsonValue } from "@/types/common/Json.js";
 import type {
   ListSessionMessagesInput,
   SessionActionMessage,
+  SessionAssistantFilePart,
   SessionAssistantMessage,
   SessionAssistantMessagePart,
   SessionAssistantToolPart,
@@ -24,6 +25,11 @@ import type {
   SessionMutation,
   SessionMessageMutation as SessionMessageSnapshotMutation,
 } from "@/types/session/SessionMutation.js";
+import type {
+  SessionContextSnapshot,
+  SessionMessageStorageStats,
+  SessionSegmentSummary,
+} from "@/types/session/SessionSegment.js";
 
 /** SessionRecorder 构造参数。 */
 export interface SessionRecorderOptions {
@@ -289,38 +295,88 @@ export class SessionRecorder {
     }))) as SessionErrorMessage;
   }
 
-  /** 读取折叠后的 Message snapshot。 */
+  /** 读取 Active 或指定边界之前最近的完整 Segment。 */
   async list_messages(
     input?: ListSessionMessagesInput,
   ): Promise<SessionMessagePage> {
     await this.ensure_initialized();
-    const include_internal = input?.include_internal === true;
-    const through_sequence = Number.isFinite(input?.through_sequence)
-      ? Number(input?.through_sequence)
-      : Number.POSITIVE_INFINITY;
-    const before_sequence = Number.isFinite(input?.before_sequence)
-      ? Number(input?.before_sequence)
-      : Number.POSITIVE_INFINITY;
-    const all = [...this.messages_by_id.values()]
-      .filter(
-        (message) =>
-          (include_internal || message.visibility === "visible") &&
-          message.sequence <= through_sequence &&
-          message.sequence < before_sequence,
-      )
-      .sort((left, right) => left.sequence - right.sequence);
-    const offset = decode_cursor(input?.cursor);
-    const limit = normalize_limit(input?.limit, 100, 500);
-    const items = all.slice(offset, offset + limit).map((item) => structuredClone(item));
-    const next_offset = offset + items.length;
+    const requests_segment = input?.before_sequence !== undefined;
+    const before_sequence = input?.before_sequence;
+    if (
+      requests_segment &&
+      (!Number.isInteger(before_sequence) || Number(before_sequence) <= 0)
+    ) {
+      throw new Error("before_sequence must be a positive integer");
+    }
+    const segment = requests_segment
+      ? await this.store.read_segment_before(Number(before_sequence))
+      : null;
+    const source = requests_segment ? "segment" as const : "active" as const;
+    const messages = requests_segment
+      ? segment?.messages || []
+      : [...this.messages_by_id.values()].sort(compare_message_sequence);
+    const start_sequence = messages[0]?.sequence;
+    const end_sequence = messages.at(-1)?.sequence;
+    const history_boundary = source === "segment"
+      ? segment?.range.start_sequence
+      : await this.store.active_before_sequence(messages);
+    const has_more = history_boundary !== undefined &&
+      await this.store.has_segment_before(history_boundary);
+    const stats = await this.store.stats();
+    const items = messages
+      .filter((message) => input?.include_internal === true || message.visibility === "visible")
+      .map((message) => structuredClone(message));
     return {
       items,
-      total: all.length,
-      ...(next_offset < all.length ? { next_cursor: encode_cursor(next_offset) } : {}),
-      has_more: next_offset < all.length,
+      total: stats.message_count,
+      source,
+      ...(start_sequence !== undefined ? { start_sequence } : {}),
+      ...(end_sequence !== undefined ? { end_sequence } : {}),
+      ...(has_more && history_boundary !== undefined
+        ? { next_before_sequence: history_boundary }
+        : {}),
+      has_more,
+    };
+  }
+
+  /** 读取最新累计 Summary 与全部 Active Message，供模型上下文使用。 */
+  async context_snapshot(): Promise<SessionContextSnapshot> {
+    await this.ensure_initialized();
+    return {
+      summary: await this.store.read_latest_summary(),
+      messages: [...this.messages_by_id.values()]
+        .sort(compare_message_sequence)
+        .map((message) => structuredClone(message)),
     };
   }
 
+  /** 读取全部真实历史，供 Fork 等明确的全量复制操作使用。 */
+  async list_history_messages(): Promise<SessionMessage[]> {
+    await this.ensure_initialized();
+    return await this.store.list_history_messages();
+  }
+
+  /** 读取当前 Session 的存储统计。 */
+  async storage_stats(): Promise<SessionMessageStorageStats> {
+    await this.ensure_initialized();
+    return await this.store.stats();
+  }
+
+  /** 把 Active 前缀和累计 Summary 提交为不可变 Segment。 */
+  async compact_active(input: {
+    /** 移入 Segment 的最后一条真实 Message sequence。 */
+    through_sequence: number;
+    /** 写入 Segment footer 的累计 Summary。 */
+    summary: SessionSegmentSummary;
+  }): Promise<void> {
+    await this.ensure_initialized();
+    const result = await this.store.compact_active(input);
+    this.messages_by_id.clear();
+    for (const message of result.active_messages) {
+      this.messages_by_id.set(message.message_id, structuredClone(message));
+    }
+  }
+
   /** 向当前 Session 导入 fork 来源 Message，并重新分配全部身份和顺序。 */
   async import_messages(messages: SessionMessage[]): Promise<void> {
     const turn_ids = new Map<string, string>();
@@ -551,6 +607,7 @@ export class SessionRecorder {
   private async ensure_initialized(): Promise<void> {
     if (!this.initialized) await this.initialize();
   }
+
 }
 
 /** 单个 Assistant segment 的流式 writer。 */
@@ -558,6 +615,7 @@ export class SessionAssistantMessageWriter {
   readonly message_id: string;
   private readonly recorder: SessionRecorder;
   private readonly pending_text_parts = new Map<string, "text" | "reasoning">();
+  private readonly active_text_part_ids = new Map<string, string>();
   private closed = false;
 
   constructor(recorder: SessionRecorder, message_id: string) {
@@ -573,7 +631,7 @@ export class SessionAssistantMessageWriter {
       case "text-start":
       case "reasoning-start": {
         const type = chunk.type === "text-start" ? "text" : "reasoning";
-        const part_id = `${type}:${chunk.id}`;
+        const part_id = this.resolve_text_part_id(type, chunk.id);
         if (!current.parts.some((part) => part.part_id === part_id)) {
           this.pending_text_parts.set(part_id, type);
         }
@@ -582,7 +640,7 @@ export class SessionAssistantMessageWriter {
       case "text-delta":
       case "reasoning-delta": {
         const type = chunk.type === "text-delta" ? "text" : "reasoning";
-        const part_id = `${type}:${chunk.id}`;
+        const part_id = this.resolve_text_part_id(type, chunk.id);
         await this.ensure_text_part(part_id, type);
         await this.recorder.append_assistant_delta(
           this.message_id,
@@ -594,13 +652,17 @@ export class SessionAssistantMessageWriter {
       }
       case "text-end":
       case "reasoning-end": {
-        const part_id = `${chunk.type === "text-end" ? "text" : "reasoning"}:${chunk.id}`;
+        const type = chunk.type === "text-end" ? "text" : "reasoning";
+        const source_part_id = this.source_text_part_id(type, chunk.id);
+        const part_id = this.active_text_part_ids.get(source_part_id);
+        if (!part_id) return;
         const part = current.parts.find((item) => item.part_id === part_id);
         if (part?.type === "text" || part?.type === "reasoning") {
           await this.upsert_part({ ...part, state: "done" });
         } else {
           this.pending_text_parts.delete(part_id);
         }
+        this.active_text_part_ids.delete(source_part_id);
         return;
       }
       case "tool-input-start":
@@ -666,10 +728,7 @@ export class SessionAssistantMessageWriter {
         return;
       }
       case "file":
-        await this.upsert_part({
-          part_id: `file:${generateId()}`,
-          sequence: this.next_part_sequence(),
-          type: "file",
+        await this.append_file_part({
           media_type: chunk.mediaType,
           url: chunk.url,
         });
@@ -684,6 +743,36 @@ export class SessionAssistantMessageWriter {
     await this.recorder.update_assistant_part(this.message_id, part);
   }
 
+  /**
+   * 把最终结果中的文件补入当前 Assistant，并对流式已写入文件去重。
+   */
+  async append_file_part(
+    input: Pick<SessionAssistantFilePart, "filename" | "media_type" | "url">,
+  ): Promise<void> {
+    const filename = String(input.filename || "").trim();
+    const current = this.current_message();
+    const existing = current.parts.find(
+      (part) =>
+        part.type === "file" &&
+        part.url === input.url &&
+        part.media_type === input.media_type,
+    );
+    if (existing?.type === "file") {
+      if (filename && String(existing.filename || "").trim() !== filename) {
+        await this.upsert_part({ ...existing, filename });
+      }
+      return;
+    }
+    await this.upsert_part({
+      part_id: `file:${generateId()}`,
+      sequence: this.next_part_sequence(),
+      type: "file",
+      media_type: input.media_type,
+      url: input.url,
+      ...(filename ? { filename } : {}),
+    });
+  }
+
   /** 当前实现逐 chunk 等待落盘，因此 flush 在返回时天然完成。 */
   async flush(): Promise<void> {}
 
@@ -724,6 +813,32 @@ export class SessionAssistantMessageWriter {
     );
   }
 
+  /**
+   * 把 AI SDK 当前 stream 内的临时 chunk ID 映射为 Message 内唯一 Part ID。
+   *
+   * AI SDK 会在不同 `streamText()` 调用中重复使用 `txt-0`、`reasoning-0`
+   * 等 ID，因此这些 ID 只能用于关联当前尚未结束的文本片段。
+   */
+  private resolve_text_part_id(
+    type: "text" | "reasoning",
+    chunk_id: string,
+  ): string {
+    const source_part_id = this.source_text_part_id(type, chunk_id);
+    const active_part_id = this.active_text_part_ids.get(source_part_id);
+    if (active_part_id) return active_part_id;
+    const part_id = `${type}:${generateId()}`;
+    this.active_text_part_ids.set(source_part_id, part_id);
+    return part_id;
+  }
+
+  /** 构造当前流片段使用的临时关联键。 */
+  private source_text_part_id(
+    type: "text" | "reasoning",
+    chunk_id: string,
+  ): string {
+    return `${type}:${chunk_id}`;
+  }
+
   /** 在首个有效 Delta 到达时才固定文本 Part 的真实顺序。 */
   private async ensure_text_part(
     part_id: string,
@@ -771,6 +886,7 @@ export class SessionAssistantMessageWriter {
   private async close(status: "completed" | "stopped" | "failed"): Promise<void> {
     if (this.closed) return;
     this.pending_text_parts.clear();
+    this.active_text_part_ids.clear();
     await this.recorder.complete_assistant_message(this.message_id, status);
     this.closed = true;
   }
@@ -875,28 +991,6 @@ function to_json_value(input: unknown): JsonValue {
   }
 }
 
-function normalize_limit(value: number | undefined, fallback: number, maximum: number): number {
-  if (!Number.isFinite(value)) return fallback;
-  return Math.min(maximum, Math.max(1, Math.floor(Number(value))));
-}
-
-function encode_cursor(offset: number): string {
-  return Buffer.from(JSON.stringify({ offset }), "utf8").toString("base64url");
-}
-
-function decode_cursor(cursor: string | undefined): number {
-  const value = String(cursor || "").trim();
-  if (!value) return 0;
-  try {
-    const parsed = JSON.parse(Buffer.from(value, "base64url").toString("utf8")) as { offset?: unknown };
-    return typeof parsed.offset === "number" && parsed.offset >= 0
-      ? Math.floor(parsed.offset)
-      : 0;
-  } catch {
-    throw new Error("Invalid Session Message cursor");
-  }
-}
-
 function resolve_import_id(map: Map<string, string>, source_id: string, prefix: string): string {
   const existing = map.get(source_id);
   if (existing) return existing;
@@ -904,3 +998,8 @@ function resolve_import_id(map: Map<string, string>, source_id: string, prefix:
   map.set(source_id, created);
   return created;
 }
+
+/** 按真实 Message sequence 升序排序。 */
+function compare_message_sequence(left: SessionMessage, right: SessionMessage): number {
+  return left.sequence - right.sequence;
+}

package/src/session/recorder/SessionRecorderCompaction.ts

@@ -1,7 +1,7 @@
 /**
- * SessionRecorder canonical 上下文压缩。
+ * SessionRecorder Active/Segment 上下文压缩。
  *
- * 压缩只追加一条 internal summary Message，不删除、不归档、不重写 Mutation 日志。
+ * Compact 把 Active 前缀写入不可变 Segment，并在 footer 保存累计 Summary。
  */
 
 import { generateText } from "ai";
@@ -15,20 +15,19 @@ import {
 } 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";
+import type { SessionMessage } from "@/types/session/SessionMessage.js";
 
-/** 必要时把较早上下文追加为 canonical internal summary。 */
+/** 必要时把 Active 前缀关闭为带累计 Summary 的 Segment。 */
 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);
+  const snapshot = await input.recorder.context_snapshot();
+  const context_messages = snapshot.messages.filter(
+    (message) => message.type === "user" || message.type === "assistant",
+  );
   if (context_messages.length < 4) {
     return { compacted: false, reason: "small_messages" };
   }
@@ -36,21 +35,24 @@ export async function compact_session_recorder_messages(input: {
     .map((message) => String(message.content || ""))
     .join("\n\n");
   const estimated_tokens = Math.ceil(
-    `${system_text}\n${JSON.stringify(context_messages)}`.length / 3,
+    `${system_text}\n${snapshot.summary?.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 keep_last_messages = Math.max(1, input.compact_input.keepLastMessages);
+  const max_compact_count = context_messages.length - keep_last_messages;
+  if (max_compact_count < 2) {
+    return { compacted: false, reason: "keep_last_messages" };
+  }
+  const compact_count = Math.min(
+    max_compact_count,
+    Math.max(2, 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");
+  const boundary = older.at(-1);
   if (!boundary) return { compacted: false, reason: "nothing_to_compact" };
 
   const action_id = `compacting:${input.recorder.session_id}:${generateId()}`;
@@ -61,19 +63,11 @@ export async function compact_session_recorder_messages(input: {
     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)
-    : "";
+    .join("\n");
+  const previous_summary_text = String(snapshot.summary?.text || "").trim();
   const prompt = previous_summary_text
     ? build_update_session_compaction_prompt({
         previous_summary: previous_summary_text,
@@ -83,7 +77,7 @@ export async function compact_session_recorder_messages(input: {
         conversation_text: conversation_text || "(none)",
       });
 
-  let summary = "";
+  let summary: string;
   try {
     const result = await generateText({
       model: input.compact_input.model,
@@ -91,74 +85,55 @@ export async function compact_session_recorder_messages(input: {
       prompt,
     });
     summary = String(result.text || "").trim();
-  } catch {
-    summary = "Earlier conversation was compacted because the context window was exceeded.";
+  } catch (error) {
+    await publish_action(input.compact_input.onAction, {
+      id: action_id,
+      session_id: input.recorder.session_id,
+      title: "Session message compaction failed",
+      description: error instanceof Error ? error.message : String(error),
+      state: "failed",
+    });
+    return { compacted: false, reason: "summary_failed" };
+  }
+  if (!summary) {
+    await publish_action(input.compact_input.onAction, {
+      id: action_id,
+      session_id: input.recorder.session_id,
+      title: "Session message compaction failed",
+      description: "The compaction model returned an empty Summary.",
+      state: "failed",
+    });
+    return { compacted: false, reason: "summary_failed" };
   }
 
-  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()}`,
-      sequence: 1,
-      type: "text",
+  await input.recorder.compact_active({
+    through_sequence: boundary.sequence,
+    summary: {
+      record_type: "summary",
+      session_id: input.recorder.session_id,
+      summary_id: `summary:${input.recorder.session_id}:${generateId()}`,
+      through_sequence: boundary.sequence,
       text: summary,
-      state: "done",
-    }],
+      created_at: Date.now(),
+    },
   });
   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}.`,
+    description: `Closed Active 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();
+  return JSON.stringify({
+    role: projected.role,
+    parts: projected.parts,
+  });
 }
 
 async function publish_action(
@@ -168,7 +143,7 @@ async function publish_action(
     session_id: string;
     title: string;
     description?: string;
-    state: "running" | "completed";
+    state: "running" | "completed" | "failed";
   },
 ): Promise<void> {
   if (!callback) return;

package/src/session/recorder/SessionRecorderHistoryStore.ts

@@ -2,7 +2,7 @@
  * SessionRecorder 到 Executor SessionHistoryStore 的内部投影适配器。
  *
  * 关键点（中文）
- * - Recorder 的 messages.jsonl 与 assistant_message.json 共同组成持久化事实源。
+ * - Recorder 的 active.jsonl、segments 与 assistant_message.json 共同组成持久化事实源。
  * - Executor 继续读取临时 UIMessage 投影，不直接拥有文件写入权。
  * - 流式草稿写入由 AssistantMessageWriter 负责，Executor 的旧接口只提供投影兼容。
  */
@@ -111,11 +111,8 @@ export class SessionRecorderHistoryStore implements SessionHistoryStore {
 
   /** 从 Recorder 当前快照投影运行中的 Assistant。 */
   async read_inflight(): Promise<SessionRecordV1 | null> {
-    const page = await this.recorder.list_messages({
-      limit: 500,
-      include_internal: true,
-    });
-    const assistant = [...page.items]
+    const snapshot = await this.recorder.context_snapshot();
+    const assistant = [...snapshot.messages]
       .reverse()
       .find(
         (message) =>
@@ -132,15 +129,32 @@ export class SessionRecorderHistoryStore implements SessionHistoryStore {
 
   /** 返回 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 snapshot = await this.recorder.context_snapshot();
+    const records: SessionRecordV1[] = [];
+    if (snapshot.summary) {
+      records.push({
+        id: snapshot.summary.summary_id,
+        role: "assistant",
+        metadata: {
+          v: 1,
+          ts: snapshot.summary.created_at,
+          sessionId: this.sessionId,
+          source: "compact",
+          kind: "summary",
+          extra: {
+            visibility: "internal",
+            summaryThroughSequence: snapshot.summary.through_sequence,
+          },
+        },
+        parts: [{ type: "text", text: snapshot.summary.text }],
+      });
+    }
+    for (const message of snapshot.messages) {
+      if (message.type !== "user" && message.type !== "assistant") continue;
       const projected = to_executor_ui_message(message);
-      return projected ? [projected] : [];
-    });
+      if (projected) records.push(projected);
+    }
+    return records;
   }
 
   /** 返回 Context Message 区间。 */
@@ -158,7 +172,7 @@ export class SessionRecorderHistoryStore implements SessionHistoryStore {
     return {};
   }
 
-  /** 通过 Recorder 追加 internal summary，不重写 Mutation 历史。 */
+  /** 通过 Recorder 把 Active 前缀关闭为带累计 Summary 的 Segment。 */
   async compact(input: SessionHistoryCompactInput): Promise<{
     compacted: boolean;
     reason?: string;
@@ -237,40 +251,6 @@ export class SessionRecorderHistoryStore implements SessionHistoryStore {
   }
 }
 
-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";
 }