@downcity/agent 1.1.401 → 1.1.408

package/src/workspace/store/LocalGroupDispatchSessionDataStore.ts

@@ -0,0 +1,118 @@
+/**
+ * LocalGroupDispatchSessionDataStore：Group Dispatch Session 的追加式 Turn 日志。
+ *
+ * 每次状态迁移都追加完整快照；读取时按 dispatch_id 选择最后一条记录，因此中断前
+ * 已提交的状态不会被覆盖，文件尾部的非完整写入也可以安全修复。
+ */
+
+import path from "node:path";
+import type { FileSystem } from "@downcity/workspace";
+import type {
+  GroupDispatchSessionDataStore,
+  GroupDispatchTurnRecord,
+  GroupDispatchTurnStatus,
+} from "@/types/group/GroupDispatchSession.js";
+
+const dispatch_turn_statuses = new Set<GroupDispatchTurnStatus>([
+  "queued",
+  "running",
+  "completed",
+  "failed",
+  "stopped",
+]);
+
+/** 基于 GroupSession 私有目录的 Dispatch Session Store。 */
+export class LocalGroupDispatchSessionDataStore implements GroupDispatchSessionDataStore {
+  private readonly files: FileSystem;
+  private readonly dispatch_root_path: string;
+  private readonly turns_file_path: string;
+  private readonly transaction_lock_path: string;
+
+  constructor(options: {
+    /** 当前 Group StorageScope 文件能力。 */
+    readonly files: FileSystem;
+    /** 当前 GroupSession 的私有存储根目录。 */
+    readonly session_root_path: string;
+  }) {
+    this.files = options.files;
+    this.dispatch_root_path = path.join(options.session_root_path, "dispatch");
+    this.turns_file_path = path.join(this.dispatch_root_path, "turns.jsonl");
+    this.transaction_lock_path = path.join(this.dispatch_root_path, ".lock");
+  }
+
+  /** 读取每个调度 Turn 最后一次成功提交的状态。 */
+  async list_turns(): Promise<GroupDispatchTurnRecord[]> {
+    if (!(await this.files.path_exists(this.turns_file_path))) return [];
+    await this.files.ensure_directory(this.dispatch_root_path);
+    return await this.files.with_file_lock(this.transaction_lock_path, async () => {
+      const records = await this.read_records(true);
+      const turns_by_id = new Map<string, GroupDispatchTurnRecord>();
+      for (const record of records) {
+        turns_by_id.delete(record.dispatch_id);
+        turns_by_id.set(record.dispatch_id, record);
+      }
+      return [...turns_by_id.values()];
+    });
+  }
+
+  /** 追加一个完整状态快照，状态提交与其它调度 Turn 串行。 */
+  async append_turn(turn: GroupDispatchTurnRecord): Promise<void> {
+    assert_dispatch_turn(turn);
+    await this.files.ensure_directory(this.dispatch_root_path);
+    await this.files.with_file_lock(this.transaction_lock_path, async () => {
+      await this.files.append_file(this.turns_file_path, `${JSON.stringify(turn)}\n`);
+    });
+  }
+
+  /** 读取状态日志；只允许修复进程中断产生的最后一条残缺记录。 */
+  private async read_records(repair_tail: boolean): Promise<GroupDispatchTurnRecord[]> {
+    const content = (await this.files.read_file(this.turns_file_path)).toString("utf8");
+    const lines = content.split("\n");
+    const records: GroupDispatchTurnRecord[] = [];
+    for (let line_index = 0; line_index < lines.length; line_index += 1) {
+      const line = lines[line_index];
+      if (!line.trim()) continue;
+      try {
+        const record = JSON.parse(line) as GroupDispatchTurnRecord;
+        assert_dispatch_turn(record);
+        records.push(record);
+      } catch (error) {
+        const is_tail = lines.slice(line_index + 1).every((item) => !item.trim());
+        if (!repair_tail || !is_tail) throw error;
+        const repaired = records.map((record) => JSON.stringify(record)).join("\n");
+        await this.files.write_file_atomically(
+          this.turns_file_path,
+          repaired ? `${repaired}\n` : "",
+        );
+        break;
+      }
+    }
+    return records;
+  }
+}
+
+/** 防止损坏的持久化记录进入 Dispatch Session 恢复流程。 */
+function assert_dispatch_turn(value: GroupDispatchTurnRecord): void {
+  if (!value || typeof value !== "object") throw new Error("Invalid Group dispatch turn record");
+  if (typeof value.dispatch_id !== "string" || !value.dispatch_id.trim()) {
+    throw new Error("Invalid Group dispatch turn id");
+  }
+  if (value.trigger !== "user" && value.trigger !== "auto") {
+    throw new Error(`Invalid Group dispatch trigger: ${String(value.trigger)}`);
+  }
+  if (typeof value.message_id !== "string" || !value.message_id.trim()) {
+    throw new Error(`Invalid Group dispatch message id: ${value.dispatch_id}`);
+  }
+  if (!Array.isArray(value.pending_message_ids) || value.pending_message_ids.some((item) => typeof item !== "string" || !item.trim())) {
+    throw new Error(`Invalid Group dispatch pending messages: ${value.dispatch_id}`);
+  }
+  if (!dispatch_turn_statuses.has(value.status)) {
+    throw new Error(`Invalid Group dispatch status: ${String(value.status)}`);
+  }
+  if (!Number.isFinite(value.created_at) || !Number.isFinite(value.updated_at)) {
+    throw new Error(`Invalid Group dispatch timestamps: ${value.dispatch_id}`);
+  }
+  if (value.status === "completed" && !value.decision) {
+    throw new Error(`Completed Group dispatch is missing its decision: ${value.dispatch_id}`);
+  }
+}

package/src/workspace/store/LocalGroupSessionDataStore.ts

@@ -3,6 +3,8 @@
 import path from "node:path";
 import type { FileSystem } from "@downcity/workspace";
 import type { GroupMessage } from "@/types/group/Group.js";
+import type { GroupDispatchSessionDataStore } from "@/types/group/GroupDispatchSession.js";
+import { LocalGroupDispatchSessionDataStore } from "@/workspace/store/LocalGroupDispatchSessionDataStore.js";
 import type {
   GroupSessionDataStore,
   GroupSessionHistoryMeta,
@@ -12,6 +14,7 @@ import type {
 /** 单个 GroupSession 的本地文件存储。 */
 export class LocalGroupSessionDataStore implements GroupSessionDataStore {
   readonly session_id: string;
+  readonly dispatch_session: GroupDispatchSessionDataStore;
   private readonly files: FileSystem;
   private readonly group_id: string;
   private readonly session_root_path: string;
@@ -38,6 +41,10 @@ export class LocalGroupSessionDataStore implements GroupSessionDataStore {
       "sessions",
       encodeURIComponent(this.session_id),
     );
+    this.dispatch_session = new LocalGroupDispatchSessionDataStore({
+      files: this.files,
+      session_root_path: this.session_root_path,
+    });
     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");
@@ -82,7 +89,10 @@ export class LocalGroupSessionDataStore implements GroupSessionDataStore {
     if (!(await this.files.path_exists(this.metadata_file_path))) {
       return this.create_initial_metadata();
     }
-    return await this.read_metadata_unlocked();
+    return await this.files.with_file_lock(
+      this.transaction_lock_path,
+      async () => await this.read_metadata_unlocked(),
+    );
   }
 
   /** 在调用方已经持有事务锁时读取 metadata。 */
@@ -92,15 +102,21 @@ export class LocalGroupSessionDataStore implements GroupSessionDataStore {
     }
     const raw = JSON.parse(
       (await this.files.read_file(this.metadata_file_path)).toString("utf8"),
-    ) as Partial<GroupSessionHistoryMeta>;
+    ) as Omit<Partial<GroupSessionHistoryMeta>, "v" | "pending_turns"> & {
+      readonly v?: unknown;
+      readonly pending_turns?: unknown[];
+    };
+    if (raw.v !== 1 && raw.v !== 2) {
+      throw new Error(`Unsupported GroupSession metadata version: ${String(raw.v)}`);
+    }
     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,
+    const metadata: GroupSessionHistoryMeta = {
+      v: 2,
       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() } : {}),
@@ -112,12 +128,14 @@ export class LocalGroupSessionDataStore implements GroupSessionDataStore {
         ? { member_session_ids: normalize_member_session_ids(raw.member_session_ids) }
         : {}),
       ...(Array.isArray(raw.pending_turns)
-        ? { pending_turns: normalize_pending_turns(raw.pending_turns) }
+        ? { pending_turns: normalize_pending_turns(raw.pending_turns, raw.v === 1 ? "auto" : undefined) }
         : {}),
       ...(Array.isArray(raw.auto_frontier_message_ids)
         ? { auto_frontier_message_ids: normalize_message_ids(raw.auto_frontier_message_ids) }
         : {}),
     };
+    if (raw.v === 1) await this.write_metadata_unlocked(metadata);
+    return metadata;
   }
 
   /** 原子写入当前 metadata。 */
@@ -148,7 +166,7 @@ export class LocalGroupSessionDataStore implements GroupSessionDataStore {
         ...patch,
         session_id: this.session_id,
         group_id: this.group_id,
-        v: 1 as const,
+        v: 2 as const,
       };
       await this.write_metadata_unlocked(next_metadata);
       return next_metadata;
@@ -200,7 +218,7 @@ export class LocalGroupSessionDataStore implements GroupSessionDataStore {
   private create_initial_metadata(): GroupSessionHistoryMeta {
     const created_at = Date.now();
     return {
-      v: 1,
+      v: 2,
       session_id: this.session_id,
       group_id: this.group_id,
       created_at,
@@ -214,7 +232,10 @@ 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[] {
+function normalize_pending_turns(
+  input: unknown[],
+  default_dispatch_stage?: GroupSessionTurnCheckpoint["dispatch_stage"],
+): GroupSessionTurnCheckpoint[] {
   return input.flatMap((item) => {
     if (!item || typeof item !== "object") return [];
     const candidate = item as Partial<GroupSessionTurnCheckpoint>;
@@ -223,7 +244,12 @@ function normalize_pending_turns(input: unknown[]): GroupSessionTurnCheckpoint[]
     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 }] : [];
+    const dispatch_stage = candidate.dispatch_stage === "user" || candidate.dispatch_stage === "auto"
+      ? candidate.dispatch_stage
+      : default_dispatch_stage;
+    return turn_id && root_message_id && dispatch_stage
+      ? [{ turn_id, root_message_id, context_message_ids, dispatch_stage }]
+      : [];
   });
 }