@downcity/agent 1.1.338 → 1.1.400

package/src/workspace/store/LocalGroupSessionDataStore.ts

@@ -0,0 +1,232 @@
+/** LocalGroupSessionDataStore：GroupSession 的 metadata 与消息 JSONL 存储。 */
+
+import path from "node:path";
+import type { FileSystem } from "@downcity/workspace";
+import type { GroupMessage } from "@/types/group/Group.js";
+import type {
+  GroupSessionDataStore,
+  GroupSessionHistoryMeta,
+  GroupSessionTurnCheckpoint,
+} from "@/types/group/GroupSessionStore.js";
+
+/** 单个 GroupSession 的本地文件存储。 */
+export class LocalGroupSessionDataStore implements GroupSessionDataStore {
+  readonly session_id: string;
+  private readonly files: FileSystem;
+  private readonly group_id: string;
+  private readonly session_root_path: string;
+  private readonly metadata_file_path: string;
+  private readonly messages_file_path: string;
+  private readonly transaction_lock_path: string;
+
+  constructor(options: {
+    /** 当前 Group StorageScope 文件能力。 */
+    files: FileSystem;
+    /** 当前 Group StorageScope 根路径。 */
+    storage_root_path: string;
+    /** 当前 GroupSession 标识。 */
+    session_id: string;
+    /** 所属 Group 标识。 */
+    group_id: string;
+  }) {
+    this.files = options.files;
+    this.group_id = options.group_id;
+    this.session_id = String(options.session_id || "").trim();
+    if (!this.session_id) throw new Error("GroupSession store requires a non-empty session_id");
+    this.session_root_path = path.join(
+      path.resolve(options.storage_root_path),
+      "sessions",
+      encodeURIComponent(this.session_id),
+    );
+    this.metadata_file_path = path.join(this.session_root_path, "meta.json");
+    this.messages_file_path = path.join(this.session_root_path, "messages.jsonl");
+    this.transaction_lock_path = path.join(this.session_root_path, ".lock");
+  }
+
+  /** 初始化当前 GroupSession 目录与 metadata。 */
+  async initialize(): Promise<void> {
+    await this.files.ensure_directory(this.session_root_path);
+    await this.files.with_file_lock(this.transaction_lock_path, async () => {
+      if (!(await this.files.path_exists(this.metadata_file_path))) {
+        await this.write_metadata_unlocked(this.create_initial_metadata());
+      }
+      await this.repair_metadata_unlocked();
+    });
+  }
+
+  /** 读取完整共享消息历史。 */
+  async list_messages(): Promise<GroupMessage[]> {
+    return await this.read_messages();
+  }
+
+  /** 追加一条消息并更新 metadata。 */
+  async append_message(message: GroupMessage): Promise<void> {
+    if (message.group_id !== this.group_id) {
+      throw new Error(`GroupSession message belongs to another Group: ${this.session_id}`);
+    }
+    await this.initialize();
+    await this.files.with_file_lock(this.transaction_lock_path, async () => {
+      await this.files.append_file(this.messages_file_path, `${JSON.stringify(message)}\n`);
+      const metadata = await this.read_metadata_unlocked();
+      await this.write_metadata_unlocked({
+        ...metadata,
+        updated_at: message.created_at,
+        message_count: metadata.message_count + 1,
+        preview_text: message.text,
+      });
+    });
+  }
+
+  /** 读取当前 metadata。 */
+  async read_metadata(): Promise<GroupSessionHistoryMeta> {
+    if (!(await this.files.path_exists(this.metadata_file_path))) {
+      return this.create_initial_metadata();
+    }
+    return await this.read_metadata_unlocked();
+  }
+
+  /** 在调用方已经持有事务锁时读取 metadata。 */
+  private async read_metadata_unlocked(): Promise<GroupSessionHistoryMeta> {
+    if (!(await this.files.path_exists(this.metadata_file_path))) {
+      return this.create_initial_metadata();
+    }
+    const raw = JSON.parse(
+      (await this.files.read_file(this.metadata_file_path)).toString("utf8"),
+    ) as Partial<GroupSessionHistoryMeta>;
+    if (raw.session_id !== this.session_id) {
+      throw new Error(`Invalid GroupSession ownership metadata: ${this.session_id}`);
+    }
+    if (raw.group_id && raw.group_id !== this.group_id) {
+      throw new Error(`GroupSession "${this.session_id}" belongs to another Group`);
+    }
+    return {
+      v: 1,
+      session_id: this.session_id,
+      group_id: String(raw.group_id || this.group_id),
+      ...(typeof raw.workspace_id === "string" && raw.workspace_id.trim() ? { workspace_id: raw.workspace_id.trim() } : {}),
+      created_at: typeof raw.created_at === "number" ? raw.created_at : Date.now(),
+      updated_at: typeof raw.updated_at === "number" ? raw.updated_at : 0,
+      message_count: typeof raw.message_count === "number" ? raw.message_count : 0,
+      ...(typeof raw.preview_text === "string" && raw.preview_text ? { preview_text: raw.preview_text } : {}),
+      ...(raw.member_session_ids && typeof raw.member_session_ids === "object"
+        ? { member_session_ids: normalize_member_session_ids(raw.member_session_ids) }
+        : {}),
+      ...(Array.isArray(raw.pending_turns)
+        ? { pending_turns: normalize_pending_turns(raw.pending_turns) }
+        : {}),
+      ...(Array.isArray(raw.auto_frontier_message_ids)
+        ? { auto_frontier_message_ids: normalize_message_ids(raw.auto_frontier_message_ids) }
+        : {}),
+    };
+  }
+
+  /** 原子写入当前 metadata。 */
+  async write_metadata(metadata: GroupSessionHistoryMeta): Promise<void> {
+    await this.files.with_file_lock(this.transaction_lock_path, async () => {
+      await this.write_metadata_unlocked(metadata);
+    });
+  }
+
+  /** 在调用方已经持有事务锁时写入 metadata。 */
+  private async write_metadata_unlocked(metadata: GroupSessionHistoryMeta): Promise<void> {
+    if (metadata.session_id !== this.session_id || metadata.group_id !== this.group_id) {
+      throw new Error(`Invalid GroupSession metadata ownership: ${this.session_id}`);
+    }
+    await this.files.ensure_directory(this.session_root_path);
+    await this.files.write_file_atomically(
+      this.metadata_file_path,
+      `${JSON.stringify(metadata, null, 2)}\n`,
+    );
+  }
+
+  /** 在文件锁内合并 metadata，避免消息追加和成员映射互相覆盖。 */
+  async update_metadata(patch: Partial<GroupSessionHistoryMeta>): Promise<GroupSessionHistoryMeta> {
+    await this.initialize();
+    return await this.files.with_file_lock(this.transaction_lock_path, async () => {
+      const next_metadata = {
+        ...(await this.read_metadata_unlocked()),
+        ...patch,
+        session_id: this.session_id,
+        group_id: this.group_id,
+        v: 1 as const,
+      };
+      await this.write_metadata_unlocked(next_metadata);
+      return next_metadata;
+    });
+  }
+
+  /** 校验消息日志并由真实消息重建可恢复的摘要字段。 */
+  private async repair_metadata_unlocked(): Promise<void> {
+    const messages = await this.read_messages(true);
+    const metadata = await this.read_metadata_unlocked();
+    const first_message = messages[0];
+    const last_message = messages[messages.length - 1];
+    await this.write_metadata_unlocked({
+      ...metadata,
+      created_at: first_message?.created_at || metadata.created_at,
+      updated_at: last_message?.created_at || metadata.updated_at,
+      message_count: messages.length,
+      ...(last_message?.text ? { preview_text: last_message.text } : {}),
+    });
+  }
+
+  /** 读取 JSONL；仅允许自动修复文件尾部不完整的一行。 */
+  private async read_messages(repair_tail = false): Promise<GroupMessage[]> {
+    if (!(await this.files.path_exists(this.messages_file_path))) return [];
+    const content = (await this.files.read_file(this.messages_file_path)).toString("utf8");
+    const lines = content.split("\n");
+    const messages: GroupMessage[] = [];
+    for (let line_index = 0; line_index < lines.length; line_index += 1) {
+      const line = lines[line_index];
+      if (!line.trim()) continue;
+      let message: GroupMessage;
+      try {
+        message = JSON.parse(line) as GroupMessage;
+      } catch (error) {
+        const is_tail = lines.slice(line_index + 1).every((item) => !item.trim());
+        if (!repair_tail || !is_tail) throw error;
+        const repaired_content = messages.map((item) => JSON.stringify(item)).join("\n");
+        await this.files.write_file_atomically(this.messages_file_path, repaired_content ? `${repaired_content}\n` : "");
+        break;
+      }
+      if (message.group_id !== this.group_id) {
+        throw new Error(`GroupSession message belongs to another Group: ${this.session_id}`);
+      }
+      messages.push(message);
+    }
+    return messages;
+  }
+
+  private create_initial_metadata(): GroupSessionHistoryMeta {
+    const created_at = Date.now();
+    return {
+      v: 1,
+      session_id: this.session_id,
+      group_id: this.group_id,
+      created_at,
+      updated_at: created_at,
+      message_count: 0,
+    };
+  }
+}
+
+function normalize_member_session_ids(input: object): Record<string, string> {
+  return Object.fromEntries(Object.entries(input).filter(([agent_id, session_id]) => Boolean(agent_id.trim()) && typeof session_id === "string" && session_id.trim()));
+}
+
+function normalize_pending_turns(input: unknown[]): GroupSessionTurnCheckpoint[] {
+  return input.flatMap((item) => {
+    if (!item || typeof item !== "object") return [];
+    const candidate = item as Partial<GroupSessionTurnCheckpoint>;
+    const turn_id = typeof candidate.turn_id === "string" ? candidate.turn_id.trim() : "";
+    const root_message_id = typeof candidate.root_message_id === "string" ? candidate.root_message_id.trim() : "";
+    const context_message_ids = Array.isArray(candidate.context_message_ids)
+      ? normalize_message_ids(candidate.context_message_ids)
+      : [];
+    return turn_id && root_message_id ? [{ turn_id, root_message_id, context_message_ids }] : [];
+  });
+}
+
+function normalize_message_ids(input: unknown[]): string[] {
+  return [...new Set(input.filter((item): item is string => typeof item === "string").map((item) => item.trim()).filter(Boolean))];
+}

package/src/workspace/store/LocalGroupSessionStore.ts

@@ -0,0 +1,90 @@
+/** LocalGroupSessionStore：基于 City StorageScope 的 GroupSession 集合存储。 */
+
+import path from "node:path";
+import type { FileSystem } from "@downcity/workspace";
+import type {
+  GroupSessionDataStore,
+  GroupSessionHistoryMeta,
+  GroupSessionStore,
+  GroupSessionStoreOptions,
+} from "@/types/group/GroupSessionStore.js";
+import { LocalGroupSessionDataStore } from "@/workspace/store/LocalGroupSessionDataStore.js";
+
+/** GroupSession 的底层文件 Store。 */
+export class LocalGroupSessionStore implements GroupSessionStore {
+  private readonly files: FileSystem;
+  private readonly storage_root_path: string;
+  private readonly group_id: string;
+  private readonly sessions_by_id = new Map<string, LocalGroupSessionDataStore>();
+
+  constructor(options: GroupSessionStoreOptions) {
+    this.files = options.files;
+    this.storage_root_path = options.storage_root_path;
+    this.group_id = options.group_id;
+  }
+
+  /** 返回指定 GroupSession 的持久化视图。 */
+  session(session_id: string): GroupSessionDataStore {
+    const resolved_session_id = String(session_id || "").trim();
+    if (!resolved_session_id) throw new Error("GroupSessionStore.session requires a non-empty session_id");
+    const cached = this.sessions_by_id.get(resolved_session_id);
+    if (cached) return cached;
+    const created = new LocalGroupSessionDataStore({
+      files: this.files,
+      storage_root_path: this.storage_root_path,
+      session_id: resolved_session_id,
+      group_id: this.group_id,
+    });
+    this.sessions_by_id.set(resolved_session_id, created);
+    return created;
+  }
+
+  /** 判断指定 GroupSession 是否存在。 */
+  async has_session(session_id: string): Promise<boolean> {
+    return await this.files.path_exists(this.session_path(session_id));
+  }
+
+  /** 列出当前 Group 的全部 Session metadata。 */
+  async list_session_metadata(): Promise<GroupSessionHistoryMeta[]> {
+    const sessions_path = path.join(path.resolve(this.storage_root_path), "sessions");
+    if (!(await this.files.path_exists(sessions_path))) return [];
+    const entries = await this.files.read_directory(sessions_path);
+    const metadata: GroupSessionHistoryMeta[] = [];
+    for (const entry of entries.filter((item) => item.is_directory)) {
+      const session_id = decode_session_id(entry.name);
+      metadata.push(await this.session(session_id).read_metadata());
+    }
+    return metadata.sort((left, right) => right.updated_at - left.updated_at);
+  }
+
+  /** 删除指定 GroupSession 的全部数据。 */
+  async remove_session(session_id: string): Promise<boolean> {
+    const resolved_session_id = String(session_id || "").trim();
+    const session_path = this.session_path(resolved_session_id);
+    const existed = await this.files.path_exists(session_path);
+    if (existed) await this.files.remove_path(session_path);
+    this.sessions_by_id.delete(resolved_session_id);
+    return existed;
+  }
+
+  /** 释放当前 Store 的运行时缓存。 */
+  async dispose(): Promise<void> {
+    this.sessions_by_id.clear();
+  }
+
+  private session_path(session_id: string): string {
+    return path.join(
+      path.resolve(this.storage_root_path),
+      "sessions",
+      encodeURIComponent(String(session_id || "").trim()),
+    );
+  }
+}
+
+function decode_session_id(input: string): string {
+  try {
+    return decodeURIComponent(input);
+  } catch {
+    return input;
+  }
+}

package/src/workspace/store/LocalSessionAttachmentStore.ts

@@ -1,12 +1,12 @@
 /**
  * Workspace 内 Session 附件的本地实现。
  *
- * Data URL 在这里解码为文件；Message 层只接收相对 Workspace 根目录的文件引用。
+ * Data URL 在这里解码为文件；Message 层保存 Agent 私有目录中的绝对路径。
  */
 
 import path from "node:path";
 import { generate_id } from "@/utils/Id.js";
-import type { FileSystem } from "@/types/workspace/FileSystem.js";
+import type { FileSystem } from "@downcity/workspace";
 import type { SessionAttachmentStore } from "@/types/store/SessionAttachmentStore.js";
 
 const DATA_URL_PATTERN = /^data:([^;,]+)?((?:;[^;,]+)*),(.*)$/s;
@@ -50,7 +50,7 @@ export class LocalSessionAttachmentStore implements SessionAttachmentStore {
     const absolute_path = path.join(this.attachments_dir_path, attachment_name);
     await this.files.ensure_directory(this.attachments_dir_path);
     await this.files.write_file_atomically(absolute_path, parsed.bytes);
-    return path.relative(this.files.root_path, absolute_path);
+    return absolute_path;
   }
 }
 

package/src/workspace/store/LocalSessionDataStore.ts

@@ -0,0 +1,169 @@
+/**
+ * LocalSessionDataStore：Agent 内单个 Session 的 JSONL 持久化视图。
+ *
+ * 职责说明（中文）
+ * - 集中创建 Message Store，并封装 Metadata 与 Instruction 的物理路径。
+ * - Session 领域只持有本对象，不再自行拼接任何存储路径。
+ */
+
+import { JsonlSessionMessageStore } from "@/workspace/store/JsonlSessionMessageStore.js";
+import {
+  get_workspace_session_instruction_path,
+  get_workspace_session_meta_path,
+  get_workspace_session_assistant_message_path,
+  get_workspace_session_active_messages_path,
+  get_workspace_session_attachments_path,
+} from "@/workspace/store/LocalStorePaths.js";
+import { normalize_session_metadata } from "@/session/storage/Metadata.js";
+import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
+import type { SessionDataStore } from "@/types/store/SessionDataStore.js";
+import type { FileSystem } from "@downcity/workspace";
+import type { LocalSessionDataStoreOptions } from "@/types/store/LocalStore.js";
+import { LocalSessionAttachmentStore } from "@/workspace/store/LocalSessionAttachmentStore.js";
+
+/** 本地 Session Store。 */
+export class LocalSessionDataStore implements SessionDataStore {
+  /** 当前 Session 的稳定标识。 */
+  readonly session_id: string;
+
+  /** 当前 Session 的 JSONL Message Store。 */
+  readonly messages: JsonlSessionMessageStore;
+
+  /** 当前 Session 的附件持久化能力。 */
+  readonly attachments: LocalSessionAttachmentStore;
+
+  /** 当前 Agent 内部数据文件能力。 */
+  private readonly files: FileSystem;
+
+  /** 当前 Agent 的稳定标识。 */
+  private readonly agent_id: string;
+
+  /** 当前 Workspace 的稳定标识。 */
+  private readonly workspace_id?: string;
+
+  /** 当前 Agent 内部数据根路径。 */
+  private readonly storage_root_path: string;
+
+  constructor(options: LocalSessionDataStoreOptions) {
+    this.files = options.files;
+    this.agent_id = options.agent_id;
+    this.workspace_id = options.workspace_id;
+    this.storage_root_path = options.storage_root_path;
+    this.session_id = options.session_id;
+    this.messages = new JsonlSessionMessageStore({
+      files: this.files,
+      session_id: this.session_id,
+      file_path: get_workspace_session_active_messages_path(
+        this.storage_root_path,
+        this.session_id,
+      ),
+      assistant_message_file_path: get_workspace_session_assistant_message_path(
+        this.storage_root_path,
+        this.session_id,
+      ),
+    });
+    this.attachments = new LocalSessionAttachmentStore({
+      files: this.files,
+      attachments_dir_path: get_workspace_session_attachments_path(
+        this.storage_root_path,
+        this.session_id,
+      ),
+    });
+  }
+
+  /** 读取规范化 Session Metadata。 */
+  async read_metadata(): Promise<SessionHistoryMetaV1> {
+    try {
+      const raw = JSON.parse(
+        (await this.files.read_file(this.metadata_path())).toString("utf8"),
+      ) as Partial<SessionHistoryMetaV1>;
+      const metadata = normalize_session_metadata(
+        raw,
+        this.session_id,
+        this.agent_id,
+        this.workspace_id,
+      );
+      if (raw.agent_id !== this.agent_id) {
+        throw new Error(
+          `Session "${this.session_id}" belongs to another Agent`,
+        );
+      }
+      return metadata;
+    } catch {
+      if (await this.files.path_exists(this.metadata_path())) {
+        throw new Error(
+          `Invalid Session ownership metadata: ${this.session_id}`,
+        );
+      }
+      return normalize_session_metadata(
+        {},
+        this.session_id,
+        this.agent_id,
+        this.workspace_id,
+      );
+    }
+  }
+
+  /** 写入完整 Session Metadata。 */
+  async write_metadata(metadata: SessionHistoryMetaV1): Promise<void> {
+    const normalized = normalize_session_metadata(
+      metadata,
+      this.session_id,
+      this.agent_id,
+      this.workspace_id,
+    );
+    const metadata_path = this.metadata_path();
+    await this.files.with_file_lock(`${metadata_path}.lock`, async () => {
+      if (await this.files.path_exists(metadata_path)) {
+        const existing = JSON.parse(
+          (await this.files.read_file(metadata_path)).toString("utf8"),
+        ) as Partial<SessionHistoryMetaV1>;
+        if (existing.session_id !== this.session_id || existing.agent_id !== this.agent_id) {
+          throw new Error(
+            `Session "${this.session_id}" belongs to another Agent`,
+          );
+        }
+      }
+      await this.files.write_file_atomically(
+        metadata_path,
+        `${JSON.stringify(normalized, null, 2)}\n`,
+      );
+    });
+  }
+
+  /** 判断显式 system 快照是否存在。 */
+  async has_instruction(): Promise<boolean> {
+    return await this.files.path_exists(this.instruction_path());
+  }
+
+  /** 读取显式 system 快照。 */
+  async read_instruction(): Promise<string | null> {
+    if (!(await this.has_instruction())) return null;
+    return (await this.files.read_file(this.instruction_path())).toString("utf8");
+  }
+
+  /** 写入显式 system 快照。 */
+  async write_instruction(instruction: string): Promise<void> {
+    const instruction_path = get_workspace_session_instruction_path(
+      this.storage_root_path,
+      this.session_id,
+    );
+    await this.files.write_file_atomically(instruction_path, instruction);
+  }
+
+  /** 返回当前 Session instruction.md 的 Workspace 路径。 */
+  private instruction_path(): string {
+    return get_workspace_session_instruction_path(
+      this.storage_root_path,
+      this.session_id,
+    );
+  }
+
+  /** 返回当前 Session meta.json 的 Workspace 路径。 */
+  private metadata_path(): string {
+    return get_workspace_session_meta_path(
+      this.storage_root_path,
+      this.session_id,
+    );
+  }
+}