@downcity/agent 1.1.166 → 1.1.170

package/scripts/session-history-archive.test.mjs

@@ -0,0 +1,188 @@
+/**
+ * @file 验证 session.history 的 compact archive 分层读取语义。
+ *
+ * 关键点（中文）
+ * - compact summary 是模型上下文消息，但不应作为用户可见 history item 返回。
+ * - 调用方通过 previous_archive_id 再传入 archive_id，读取上一层被覆盖历史。
+ * - history 分页字段使用 snake_case，保持 SDK 对外数据命名一致。
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs/promises";
+
+import { Agent } from "../bin/index.js";
+
+function user_message(session_id, index) {
+  return {
+    id: `u:${index}`,
+    role: "user",
+    metadata: {
+      v: 1,
+      ts: index,
+      sessionId: session_id,
+      source: "ingress",
+    },
+    parts: [{ type: "text", text: `user ${index}` }],
+  };
+}
+
+function assistant_message(session_id, index) {
+  return {
+    id: `a:${index}`,
+    role: "assistant",
+    metadata: {
+      v: 1,
+      ts: index,
+      sessionId: session_id,
+      source: "egress",
+    },
+    parts: [{ type: "text", text: `assistant ${index}` }],
+  };
+}
+
+function compact_summary(session_id, archive_id, text) {
+  return {
+    id: `summary:${archive_id}`,
+    role: "assistant",
+    metadata: {
+      v: 1,
+      ts: 1000,
+      sessionId: session_id,
+      source: "compact",
+      kind: "summary",
+      archiveId: archive_id,
+      sourceRange: {
+        fromId: "start",
+        toId: "end",
+        count: 2,
+      },
+    },
+    parts: [{ type: "text", text }],
+  };
+}
+
+async function write_jsonl(file_path, messages) {
+  await fs.mkdir(path.dirname(file_path), { recursive: true });
+  await fs.writeFile(
+    file_path,
+    messages.map((message) => JSON.stringify(message)).join("\n") + "\n",
+    "utf8",
+  );
+}
+
+async function write_archive(file_path, session_id, messages) {
+  await fs.mkdir(path.dirname(file_path), { recursive: true });
+  await fs.writeFile(
+    file_path,
+    JSON.stringify(
+      {
+        v: 1,
+        sessionId: session_id,
+        archivedAt: Date.now(),
+        messages,
+      },
+      null,
+      2,
+    ),
+    "utf8",
+  );
+}
+
+test("session.history hides compact summary and reads archive layers by archive_id", async () => {
+  const agent_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-agent-history-archive-"),
+  );
+  const agent = new Agent({
+    id: "history_archive_agent",
+    path: agent_path,
+  });
+  const session = await agent.session_collection().create_session({
+    sessionId: "history_archive_session",
+  });
+
+  const messages_dir = path.join(
+    agent_path,
+    ".downcity",
+    "agents",
+    encodeURIComponent("history_archive_agent"),
+    "sessions",
+    encodeURIComponent(session.id),
+    "messages",
+  );
+  const messages_path = path.join(messages_dir, "messages.jsonl");
+  const archive_dir = path.join(messages_dir, "archive");
+
+  try {
+    await write_jsonl(messages_path, [
+      compact_summary(session.id, "compact-B", "summary B"),
+      user_message(session.id, 31),
+      assistant_message(session.id, 32),
+    ]);
+    await write_archive(path.join(archive_dir, "compact-B.json"), session.id, [
+      compact_summary(session.id, "compact-A", "summary A"),
+      user_message(session.id, 16),
+      assistant_message(session.id, 17),
+    ]);
+    await write_archive(path.join(archive_dir, "compact-A.json"), session.id, [
+      user_message(session.id, 1),
+      assistant_message(session.id, 2),
+    ]);
+
+    const current_page = await session.history({
+      limit: 1,
+    });
+    assert.equal(current_page.total, 2);
+    assert.equal(current_page.has_more, true);
+    assert.equal(current_page.next_cursor, "1");
+    assert.equal(current_page.archive_id, undefined);
+    assert.equal(current_page.previous_archive_id, "compact-B");
+    assert.deepEqual(
+      current_page.items.map((message) => message.id),
+      ["u:31"],
+    );
+
+    const next_current_page = await session.history({
+      cursor: current_page.next_cursor,
+    });
+    assert.equal(next_current_page.has_more, false);
+    assert.deepEqual(
+      next_current_page.items.map((message) => message.id),
+      ["a:32"],
+    );
+
+    const previous_page = await session.history({
+      archive_id: current_page.previous_archive_id,
+    });
+    assert.equal(previous_page.archive_id, "compact-B");
+    assert.equal(previous_page.previous_archive_id, "compact-A");
+    assert.equal(previous_page.total, 2);
+    assert.deepEqual(
+      previous_page.items.map((message) => message.id),
+      ["u:16", "a:17"],
+    );
+
+    const oldest_page = await session.history({
+      archive_id: previous_page.previous_archive_id,
+    });
+    assert.equal(oldest_page.archive_id, "compact-A");
+    assert.equal(oldest_page.previous_archive_id, undefined);
+    assert.deepEqual(
+      oldest_page.items.map((message) => message.id),
+      ["u:1", "a:2"],
+    );
+
+    const timeline_page = await session.history({
+      view: "timeline",
+      archive_id: "compact-B",
+    });
+    assert.deepEqual(
+      timeline_page.items.map((event) => event.text),
+      ["user 16", "assistant 17"],
+    );
+  } finally {
+    await agent.dispose();
+  }
+});

package/src/agent/remote/transports/HttpRemoteAgentTransport.ts

@@ -191,6 +191,7 @@ export class HttpRemoteAgentTransport implements RemoteAgentTransport {
     const query = new URLSearchParams();
     if (input?.limit !== undefined) query.set("limit", String(input.limit));
     if (input?.cursor) query.set("cursor", input.cursor);
+    if (input?.archive_id) query.set("archive_id", input.archive_id);
     if (input?.order) query.set("order", input.order);
     if (input?.view) query.set("view", input.view);
     const payload = await read_http_json<{

package/src/executor/composer/compaction/jsonl/JsonlSessionCompactionExecutor.ts

@@ -39,6 +39,7 @@ type SessionCompactDeps = {
   loadAll: () => Promise<SessionMessageV1[]>;
   createSummaryMessage: (params: {
     text: string;
+    archiveId?: string;
     sourceRange?: SessionMetadataV1["sourceRange"];
   }) => SessionMessageV1;
   getArchiveDirPath: () => string;
@@ -141,13 +142,13 @@ export async function compactSessionMessagesIfNeeded(
 
   const fromId = String(older[0]?.id || "");
   const toId = String(older[older.length - 1]?.id || "");
+  const archiveId = `compact-${Date.now()}-${generateId()}`;
   const summaryMsg = deps.createSummaryMessage({
     text: summary,
+    archiveId,
     sourceRange: fromId && toId ? { fromId, toId, count: older.length } : undefined,
   });
 
-  const archiveId = `compact-${Date.now()}-${generateId()}`;
-
   // phase 2：写入（短锁，且避免覆盖新追加）
   // - 以“当前最新 session messages”为准重算 currentOlder / currentKept，避免覆盖并发新消息。
   await deps.withWriteLock(async () => {

package/src/executor/messages/SessionAttachmentMapper.ts

@@ -16,6 +16,7 @@ import {
   isTextUIPart,
   type FileUIPart,
 } from "ai";
+import type { SessionUserMessagePart } from "@/types/sdk/AgentSessionPrompt.js";
 import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
 import { parseChatMessageMarkup } from "@/executor/messages/ChatMessageMarkup.js";
 
@@ -102,6 +103,66 @@ async function hydrateFileUrlPart(
   }
 }
 
+async function hydrateFileUrlPartStrict(
+  part: FileUIPart,
+  project_root?: string,
+): Promise<FileUIPart> {
+  const url = String(part.url || "").trim();
+  const file_path = resolveHydratableFilePath(project_root, url);
+  if (!file_path) return part;
+
+  try {
+    const buffer = await fs.readFile(file_path);
+    const media_type =
+      String(part.mediaType || "").trim() ||
+      guessAttachmentMediaTypeFromPath(file_path) ||
+      "application/octet-stream";
+    return {
+      ...part,
+      mediaType: media_type,
+      url: buildDataUrl(media_type, buffer),
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`读取本地附件失败：${file_path}。${message}`);
+  }
+}
+
+/**
+ * 在用户 prompt 入库前，将本地图片 file part 转成 data URL。
+ *
+ * 关键点（中文）
+ * - 只处理调用侧直接传入的图片 file part。
+ * - 已经是 data URL 或远程 URL 的附件保持原样。
+ * - 本地文件读取失败时直接报错，避免模型请求拿到不可访问的本地路径。
+ */
+export async function hydrateUserPromptFileParts(
+  parts: SessionUserMessagePart[],
+  project_root?: string,
+): Promise<SessionUserMessagePart[]> {
+  if (!Array.isArray(parts) || parts.length === 0) return [];
+
+  const out: SessionUserMessagePart[] = [];
+  for (const part of parts) {
+    if (!isFileUIPart(part as FileUIPart)) {
+      out.push(part);
+      continue;
+    }
+
+    const file_part = part as FileUIPart;
+    const media_type = String(file_part.mediaType || "").trim();
+    if (!media_type.startsWith("image/")) {
+      out.push(part);
+      continue;
+    }
+
+    const next_part = await hydrateFileUrlPartStrict(file_part, project_root);
+    out.push(next_part as SessionUserMessagePart);
+  }
+
+  return out;
+}
+
 /**
  * 将历史中的资源 file part 临时转换为模型可消费的 data URL。
  *

package/src/executor/store/history/jsonl/JsonlSessionHistoryStore.ts

@@ -445,7 +445,7 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
         sessionId: this.sessionId,
         withWriteLock: (fn) => this.withWriteLock(fn),
         loadAll: () => this.list(),
-        createSummaryMessage: ({ text, sourceRange }) => ({
+        createSummaryMessage: ({ text, archiveId, sourceRange }) => ({
           id: `a:${this.sessionId}:${generateId()}`,
           role: "assistant",
           metadata: {
@@ -454,6 +454,7 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
             sessionId: this.sessionId,
             source: "compact",
             kind: "summary",
+            ...(archiveId ? { archiveId } : {}),
             ...(sourceRange ? { sourceRange } : {}),
           },
           parts: [{ type: "text", text: String(text ?? "") }],

package/src/executor/types/SessionMessages.ts

@@ -64,6 +64,8 @@ export type SessionMetadataV1 = {
   kind?: SessionMessageKind;
   /** 当前消息来自入站、出站还是 compact。 */
   source?: SessionMessageSource;
+  /** compact 摘要对应的 archive 文件 ID，用于用户历史按层读取更早消息。 */
+  archiveId?: string;
   /** compact 摘要所覆盖的原始消息范围。 */
   sourceRange?: SessionMessageSourceRangeV1;
   /**

package/src/session/browse/Browse.ts

@@ -83,6 +83,13 @@ type SessionBrowseBaseInput = {
   executing?: boolean;
 };
 
+type SessionArchiveFileV1 = {
+  v?: unknown;
+  sessionId?: unknown;
+  archivedAt?: unknown;
+  messages?: unknown;
+};
+
 function decodeMaybe(input: string): string {
   try {
     return decodeURIComponent(input);
@@ -122,6 +129,11 @@ function encodeCursor(offset: number): string | undefined {
   return String(Math.floor(offset));
 }
 
+function normalizeArchiveId(input: unknown): string | undefined {
+  const value = String(input || "").trim();
+  return value || undefined;
+}
+
 function stringifyForDisplay(input: unknown, maxChars = 2400): string {
   if (input === undefined) return "";
   if (input === null) return "null";
@@ -359,6 +371,53 @@ export async function loadSessionMessagesFromPath(
   return messages;
 }
 
+/**
+ * 读取 compact archive 文件中的消息。
+ *
+ * 关键点（中文）
+ * - archive 是 compact 时被覆盖的“上一层历史”，不是当前运行态事实源。
+ * - 这里不读取 inflight，因为 archive 层永远是已完成的历史快照。
+ */
+export async function loadSessionArchiveMessagesFromPath(
+  filePath: string,
+): Promise<SessionMessageV1[]> {
+  try {
+    const raw = (await fs.readJson(filePath)) as SessionArchiveFileV1 | null;
+    const items = Array.isArray(raw?.messages) ? raw.messages : [];
+    return items.filter((item): item is SessionMessageV1 => {
+      if (!item || typeof item !== "object") return false;
+      const candidate = item as Partial<SessionMessageV1>;
+      return (
+        (candidate.role === "user" || candidate.role === "assistant") &&
+        Array.isArray(candidate.parts)
+      );
+    });
+  } catch {
+    return [];
+  }
+}
+
+function isCompactSummaryMessage(message: SessionMessageV1): boolean {
+  const metadata = (message.metadata || null) as SessionMetadataV1 | null;
+  return metadata?.source === "compact" || metadata?.kind === "summary";
+}
+
+function resolvePreviousArchiveId(messages: SessionMessageV1[]): string | undefined {
+  for (const message of messages) {
+    if (!isCompactSummaryMessage(message)) continue;
+    const metadata = (message.metadata || null) as SessionMetadataV1 | null;
+    const archiveId = normalizeArchiveId(metadata?.archiveId);
+    if (archiveId) return archiveId;
+  }
+  return undefined;
+}
+
+function filterUserVisibleHistoryMessages(
+  messages: SessionMessageV1[],
+): SessionMessageV1[] {
+  return messages.filter((message) => !isCompactSummaryMessage(message));
+}
+
 /**
  * 基于 metadata + messages 构建 SDK session 详情。
  */
@@ -409,9 +468,12 @@ export function buildSessionHistoryPage(params: {
   const order = params.input?.order || "asc";
   const limit = normalizeLimit(params.input?.limit, 50, 500);
   const cursor = normalizeCursor(params.input?.cursor);
+  const archive_id = normalizeArchiveId(params.input?.archive_id);
+  const previous_archive_id = resolvePreviousArchiveId(params.messages);
+  const visibleMessages = filterUserVisibleHistoryMessages(params.messages);
 
   if (view === "timeline") {
-    const allEvents = params.messages.flatMap((message) => toSessionTimelineEvents(message));
+    const allEvents = visibleMessages.flatMap((message) => toSessionTimelineEvents(message));
     const orderedEvents = order === "desc" ? [...allEvents].reverse() : allEvents;
     const pageItems = orderedEvents.slice(cursor, cursor + limit);
     const nextOffset = cursor + pageItems.length;
@@ -421,14 +483,16 @@ export function buildSessionHistoryPage(params: {
       items: pageItems,
       total: orderedEvents.length,
       ...(nextOffset < orderedEvents.length
-        ? { nextCursor: encodeCursor(nextOffset) }
+        ? { next_cursor: encodeCursor(nextOffset) }
         : {}),
-      hasMore: nextOffset < orderedEvents.length,
+      has_more: nextOffset < orderedEvents.length,
+      ...(archive_id ? { archive_id } : {}),
+      ...(previous_archive_id ? { previous_archive_id } : {}),
     };
   }
 
   const orderedMessages =
-    order === "desc" ? [...params.messages].reverse() : [...params.messages];
+    order === "desc" ? [...visibleMessages].reverse() : [...visibleMessages];
   const pageItems = orderedMessages.slice(cursor, cursor + limit);
   const nextOffset = cursor + pageItems.length;
   return {
@@ -437,9 +501,11 @@ export function buildSessionHistoryPage(params: {
     items: pageItems,
     total: orderedMessages.length,
     ...(nextOffset < orderedMessages.length
-      ? { nextCursor: encodeCursor(nextOffset) }
+      ? { next_cursor: encodeCursor(nextOffset) }
       : {}),
-    hasMore: nextOffset < orderedMessages.length,
+    has_more: nextOffset < orderedMessages.length,
+    ...(archive_id ? { archive_id } : {}),
+    ...(previous_archive_id ? { previous_archive_id } : {}),
   };
 }
 

package/src/session/index.ts

@@ -16,6 +16,7 @@ export {
   getSdkAgentArchivedSessionMetaPath,
   getSdkAgentArchivedSessionsDirPath,
   getSdkAgentSessionArchiveDirPath,
+  getSdkAgentSessionArchiveFilePath,
   getSdkAgentSessionDirPath,
   getSdkAgentSessionInflightPath,
   getSdkAgentSessionMessagesDirPath,
@@ -49,6 +50,7 @@ export {
   buildSessionInfo,
   listArchivedAgentSessionSummaryPage,
   listAgentSessionSummaryPage,
+  loadSessionArchiveMessagesFromPath,
   loadSessionMessagesFromPath,
   resolveSessionMessagePreview,
   toSessionTimelineEvents,

package/src/session/services/SessionStateService.ts

@@ -20,6 +20,7 @@ import {
 } from "@/session/index.js";
 import { ensureSessionTitle } from "@/session/SessionTitle.js";
 import { persistSdkAssistantResult } from "@/session/storage/Persistence.js";
+import { hydrateUserPromptFileParts } from "@executor/messages/SessionAttachmentMapper.js";
 import type { Executor } from "@executor/Executor.js";
 import type { JsonlSessionHistoryStore } from "@/executor/store/history/jsonl/JsonlSessionHistoryStore.js";
 import type {
@@ -324,8 +325,11 @@ export class SessionStateService {
       return message;
     }
 
-    // query 是 parts 数组，直接用其构造 user 消息
-    const parts = Array.isArray(query) ? query : [];
+    // query 是 parts 数组，先把本地图片附件转换为模型可消费的 data URL。
+    const parts = await hydrateUserPromptFileParts(
+      Array.isArray(query) ? query : [],
+      this.project_root,
+    );
     const message: SessionUserMessageV1 = {
       id: `u:${this.session_id}:${generateId()}`,
       role: "user",

package/src/session/services/SessionViewService.ts

@@ -11,7 +11,9 @@ import { nanoid } from "nanoid";
 import {
   buildSessionHistoryPage,
   buildSessionInfo,
+  getSdkAgentSessionArchiveFilePath,
   ensureSessionTitle,
+  loadSessionArchiveMessagesFromPath,
   readSessionMetadata,
 } from "@/session/index.js";
 import { buildSessionSystemBlocks } from "@/session/SessionSystemBuilder.js";
@@ -179,7 +181,8 @@ export class SessionViewService<TSession extends Pick<AgentSession, "set">> {
   async history(
     input?: AgentSessionHistoryInput,
   ): Promise<AgentSessionHistoryPage> {
-    const [metadata, messages] = await Promise.all([
+    const archive_id = String(input?.archive_id || "").trim();
+    const [metadata, current_messages] = await Promise.all([
       readSessionMetadata({
         projectRoot: this.project_root,
         agentId: this.agent_id,
@@ -187,13 +190,23 @@ export class SessionViewService<TSession extends Pick<AgentSession, "set">> {
       }),
       this.history_store.list(),
     ]);
+    const page_messages = archive_id
+      ? await loadSessionArchiveMessagesFromPath(
+          getSdkAgentSessionArchiveFilePath(
+            this.project_root,
+            this.agent_id,
+            this.session_id,
+            archive_id,
+          ),
+        )
+      : current_messages;
     const session = await this.build_info({
       metadata,
-      messages,
+      messages: current_messages,
     });
     return buildSessionHistoryPage({
       session,
-      messages,
+      messages: page_messages,
       input,
     });
   }

package/src/session/storage/Paths.ts

@@ -185,6 +185,25 @@ export function getSdkAgentSessionArchiveDirPath(
   );
 }
 
+/**
+ * 单个 session 的 compact archive JSON 文件路径。
+ *
+ * 关键点（中文）
+ * - `archiveId` 来自 compact summary metadata，不由调用方拼接扩展名。
+ * - 这里统一 encode，避免 archiveId 中的特殊字符影响文件路径。
+ */
+export function getSdkAgentSessionArchiveFilePath(
+  projectRoot: string,
+  agentId: string,
+  sessionId: string,
+  archiveId: string,
+): string {
+  return path.join(
+    getSdkAgentSessionArchiveDirPath(projectRoot, agentId, sessionId),
+    `${encodeURIComponent(String(archiveId || "").trim())}.json`,
+  );
+}
+
 /**
  * 单个 session 的 inflight assistant 路径。
  *

package/src/types/agent/SessionTypes.ts

@@ -272,6 +272,14 @@ export interface AgentSessionHistoryInput {
   limit?: number;
   /** 分页游标。 */
   cursor?: string;
+  /**
+   * 要读取的 compact archive 层 ID。
+   *
+   * 说明（中文）
+   * - 省略时读取当前 `messages.jsonl`。
+   * - 传入时读取 `messages/archive/<archive_id>.json` 中保存的上一层历史。
+   */
+  archive_id?: string;
   /**
    * 返回顺序。
    *
@@ -315,9 +323,25 @@ export interface AgentSessionHistoryPage {
    */
   total: number;
   /** 下一页游标。 */
-  nextCursor?: string;
+  next_cursor?: string;
   /** 是否仍有更多数据。 */
-  hasMore: boolean;
+  has_more: boolean;
+  /**
+   * 当前读取的 compact archive 层 ID。
+   *
+   * 说明（中文）
+   * - 省略表示当前页来自主历史 `messages.jsonl`。
+   * - 有值表示当前页来自指定 compact archive。
+   */
+  archive_id?: string;
+  /**
+   * 当前层更早一次 compact 对应的 archive ID。
+   *
+   * 关键点（中文）
+   * - compact summary 不会出现在 `items` 中。
+   * - 若当前层包含 compact summary，则这里暴露其 archive ID，供调用方继续 `session.history({ archive_id })`。
+   */
+  previous_archive_id?: string;
 }
 
 /**