@downcity/agent 1.1.400 → 1.1.408

package/src/index.ts

@@ -26,6 +26,11 @@ export type {
   GroupSessionHistoryMeta,
   GroupSessionStore,
 } from "./types/group/GroupSessionStore.js";
+export type {
+  GroupDispatchSessionDataStore,
+  GroupDispatchTurnRecord,
+  GroupDispatchTurnStatus,
+} from "./types/group/GroupDispatchSession.js";
 export { GroupSession, GroupSessions } from "./group/index.js";
 export type {
   GroupMemberRuntime,
@@ -238,6 +243,11 @@ export type {
 } from "./types/sdk/AgentSessionCompact.js";
 export type { PluginContext } from "./types/plugin/PluginContext.js";
 export type { AgentPluginContext } from "./types/plugin/AgentPluginContext.js";
+export type {
+  PluginNotificationInput,
+  PluginNotificationPublisher,
+  PluginNotificationTopicInput,
+} from "./types/plugin/PluginNotification.js";
 export type {
   PluginWebServices,
 } from "./types/plugin/PluginServices.js";

package/src/session/messages/SessionAssistantMessageWriter.ts

@@ -215,7 +215,8 @@ export class SessionAssistantMessageWriter {
   /** 在单写队列中应用标准模型事件。 */
   private async apply_model_event_serialized(event: ModelStreamEvent): Promise<void> {
     if (this.closed) throw new Error("Assistant Message writer is closed");
-    if (event.type === "model_error") throw new Error(event.error.message);
+    // model_error 由 Executor 的恢复策略消费；Writer 保留已经写入的草稿事实。
+    if (event.type === "model_error") return;
     if (event.type === "text_start" || event.type === "reasoning_start") {
       const type = event.type === "text_start" ? "text" : "reasoning";
       const part_id = `${type}:${generate_id()}`;
@@ -283,8 +284,9 @@ export class SessionAssistantMessageWriter {
       const tool = this.require_tool(tool_call_id);
       await this.upsert_tool(tool_call_id, {
         tool_name: tool.tool_name,
-        state: "ready",
+        state: event.input_error ? "failed" : "ready",
         input: event.input,
+        ...(event.input_error ? { error: event.input_error } : {}),
       });
     }
   }
@@ -435,9 +437,11 @@ export class SessionAssistantMessageWriter {
 
 /** 从 Tool 失败输出中提取稳定错误文本。 */
 function read_tool_error(output: unknown): string {
-  if (output && typeof output === "object" && "error" in output) {
-    const error = (output as { error?: unknown }).error;
-    if (typeof error === "string" && error.trim()) return error;
+  if (output && typeof output === "object") {
+    const result = output as { error?: unknown; message?: unknown; output?: unknown };
+    for (const candidate of [result.error, result.message, result.output]) {
+      if (typeof candidate === "string" && candidate.trim()) return candidate;
+    }
   }
   return "Tool execution failed";
 }

package/src/types/group/DispatchStrategy.ts

@@ -3,7 +3,12 @@
 import type { GroupMessage } from "@/types/group/Group.js";
 import type { Agent } from "@/agent/Agent.js";
 import type { AgentModel } from "@/agent/AgentModel.js";
-import type { ModelClient, ModelJsonValue } from "@downcity/type";
+import type {
+  ModelClient,
+  ModelContent,
+  ModelJsonValue,
+  ModelMessage,
+} from "@downcity/type";
 import { generate_model } from "@executor/model/ModelGenerate.js";
 import { z } from "zod";
 
@@ -49,6 +54,8 @@ export interface DispatchStrategy {
     readonly messages: readonly GroupMessage[];
     /** 当前 Group 成员快照。 */
     readonly members: readonly Agent[];
+    /** 当前 Dispatch Session Turn 的取消信号。 */
+    readonly abort_signal: AbortSignal;
   }): Promise<DispatchDecision> | DispatchDecision;
 }
 
@@ -65,6 +72,8 @@ const dispatch_group_input_schema = z.object({
   next: z.enum(["stop", "continue"]),
 });
 
+const max_dispatch_model_steps = 3;
+
 /** 使用 Group.model 理解群聊意图并通过内部 tool call 生成成员投递决定。 */
 export class AiDispatchStrategy implements DispatchStrategy {
   private readonly model?: ModelClient;
@@ -79,29 +88,45 @@ export class AiDispatchStrategy implements DispatchStrategy {
     readonly pending_messages: readonly GroupMessage[];
     readonly messages: readonly GroupMessage[];
     readonly members: readonly Agent[];
+    readonly abort_signal: AbortSignal;
   }): Promise<DispatchDecision> {
     if (!this.model) {
       throw new Error("Group requires a configured model for dispatch");
     }
     try {
-      const result = await generate_model(this.model, {
-        messages: [
-          { role: "system", content: [{ type: "text", text: "你是群聊消息调度器。你只能调用 dispatch_group，不回答用户问题。普通任务默认只选择一个最合适的成员；只有用户明确要求多人分别回答，或确实存在并行的独立工作时，才把多个成员放在同一阶段。外层 steps 阶段按顺序执行，后一个阶段等待前一个阶段完成。只有真实存在的成员才能被选择。" }] },
-          { role: "user", content: [{ type: "text", text: build_dispatch_prompt(input) }] },
-        ],
-        tools: [{
-          name: "dispatch_group",
-          description: "提交当前 Group 的成员投递路径。只调用一次；不要输出普通文本。没有成员需要回复时使用空 steps 和 next=stop。",
-          input_schema: z.toJSONSchema(dispatch_group_input_schema) as Record<string, ModelJsonValue>,
-        }],
-        tool_choice: { type: "tool", tool_name: "dispatch_group" },
-        max_output_tokens: 600,
-        reasoning: { enabled: false },
-      });
-      if (result.tool_calls.length !== 1 || result.tool_calls[0]?.tool_name !== "dispatch_group") {
-        throw new Error("Group dispatch model did not call dispatch_group");
+      const messages: ModelMessage[] = [
+        { role: "system", content: [{ type: "text", text: "你是群聊消息调度器。你只能调用 dispatch_group，不回答用户问题。普通任务默认只选择一个最合适的成员；只有用户明确要求多人分别回答，或确实存在并行的独立工作时，才把多个成员放在同一阶段。外层 steps 阶段按顺序执行，后一个阶段等待前一个阶段完成。只有真实存在的成员才能被选择。" }] },
+        { role: "user", content: [{ type: "text", text: build_dispatch_prompt(input) }] },
+      ];
+      let protocol_error = "Group dispatch model did not call dispatch_group";
+      for (let step_index = 0; step_index < max_dispatch_model_steps; step_index += 1) {
+        const result = await generate_model(this.model, {
+          messages,
+          tools: [{
+            name: "dispatch_group",
+            description: "提交当前 Group 的成员投递路径。只调用一次；不要输出普通文本。没有成员需要回复时使用空 steps 和 next=stop。",
+            input_schema: z.toJSONSchema(dispatch_group_input_schema) as Record<string, ModelJsonValue>,
+          }],
+          tool_choice: { type: "tool", tool_name: "dispatch_group" },
+          max_output_tokens: 600,
+          reasoning: { enabled: false },
+        }, input.abort_signal);
+        const dispatch_call = result.tool_calls.length === 1 && result.tool_calls[0]?.tool_name === "dispatch_group"
+          ? result.tool_calls[0]
+          : undefined;
+        if (dispatch_call) {
+          try {
+            return normalize_dispatch_tool_input(dispatch_call.input, input.members);
+          } catch (error) {
+            protocol_error = error instanceof Error ? error.message : String(error);
+          }
+        } else {
+          protocol_error = "Group dispatch model did not call dispatch_group exactly once";
+        }
+        if (step_index + 1 >= max_dispatch_model_steps) break;
+        append_dispatch_retry_messages(messages, result.text, result.tool_calls, protocol_error);
       }
-      return normalize_dispatch_tool_input(result.tool_calls[0].input, input.members);
+      throw new Error(`${protocol_error} after ${max_dispatch_model_steps} attempts`);
     } catch (error) {
       const detail = error instanceof Error ? error.message : String(error);
       throw new Error(`Group dispatch model failed: ${detail}`, { cause: error });
@@ -109,6 +134,41 @@ export class AiDispatchStrategy implements DispatchStrategy {
   }
 }
 
+/** 把协议错误作为下一模型 step 的显式上下文，允许模型在同一调度 Turn 内纠正。 */
+function append_dispatch_retry_messages(
+  messages: ModelMessage[],
+  text: string,
+  tool_calls: readonly { type: "tool_call"; tool_call_id: string; tool_name: string; input: ModelJsonValue }[],
+  error: string,
+): void {
+  const assistant_content: ModelContent[] = [
+    ...(text.trim() ? [{ type: "text" as const, text }] : []),
+    ...tool_calls,
+  ];
+  if (assistant_content.length > 0) {
+    messages.push({ role: "assistant", content: assistant_content });
+  }
+  if (tool_calls.length > 0) {
+    messages.push({
+      role: "tool",
+      content: tool_calls.map((tool_call) => ({
+        type: "tool_result" as const,
+        tool_call_id: tool_call.tool_call_id,
+        tool_name: tool_call.tool_name,
+        outcome: "failed" as const,
+        content: [{ type: "text" as const, text: error }],
+      })),
+    });
+  }
+  messages.push({
+    role: "user",
+    content: [{
+      type: "text",
+      text: `上一响应不符合调度协议：${error}。请只调用一次 dispatch_group。`,
+    }],
+  });
+}
+
 /** 为 AI 调度器构造稳定、有限长度的群聊上下文。 */
 function build_dispatch_prompt(input: {
   readonly trigger: DispatchTrigger;
@@ -152,7 +212,7 @@ function normalize_dispatch_tool_input(value: unknown, members: readonly Agent[]
       member_ids: unique_member_ids,
       response_mode: unique_member_ids.length > 1 ? "parallel" as const : "single" as const,
       depends_on_node_ids: index === 0 ? [] : [`step-${index - 1}`],
-      instruction: "根据当前 Group 上下文判断是否需要回复，只代表自己发言；不需要时返回空内容。",
+      instruction: "你已被 Group 调度选中，请直接针对当前消息给出回复，并且只代表自己发言。",
     };
   });
   if (nodes.length === 0 && parsed.next === "continue") {

package/src/types/group/GroupDispatchSession.ts

@@ -0,0 +1,80 @@
+/**
+ * Group Dispatch Session 领域类型。
+ *
+ * Dispatch Session 只记录群聊调度 Turn，不复制 GroupMessage 正文；消息正文仍由
+ * GroupSession 的消息日志作为唯一事实源，调度记录通过消息 ID 建立稳定引用。
+ */
+
+import type { Agent } from "@/agent/Agent.js";
+import type { GroupMessage } from "@/types/group/Group.js";
+import type {
+  DispatchDecision,
+  DispatchStrategy,
+  DispatchTrigger,
+} from "@/types/group/DispatchStrategy.js";
+
+/** Dispatch Session 中一次调度 Turn 的持久化状态。 */
+export type GroupDispatchTurnStatus =
+  | "queued"
+  | "running"
+  | "completed"
+  | "failed"
+  | "stopped";
+
+/** Dispatch Session 中一次调度 Turn 的完整持久化快照。 */
+export interface GroupDispatchTurnRecord {
+  /** 当前调度 Turn 的稳定标识。 */
+  readonly dispatch_id: string;
+  /** 本次调度由用户消息还是自动传播触发。 */
+  readonly trigger: DispatchTrigger;
+  /** 当前调度所围绕的 GroupMessage 标识。 */
+  readonly message_id: string;
+  /** 当前调度需要一起判断的新增 GroupMessage 标识。 */
+  readonly pending_message_ids: readonly string[];
+  /** 当前调度 Turn 的生命周期状态。 */
+  readonly status: GroupDispatchTurnStatus;
+  /** 调度成功后已经校验并持久化的成员投递决定。 */
+  readonly decision?: DispatchDecision;
+  /** 调度失败或停止时用于诊断的稳定错误文本。 */
+  readonly error?: string;
+  /** 当前调度 Turn 首次入队的 Unix 毫秒时间戳。 */
+  readonly created_at: number;
+  /** 当前状态最近一次提交的 Unix 毫秒时间戳。 */
+  readonly updated_at: number;
+}
+
+/** Dispatch Session 持久化所需的最小数据能力。 */
+export interface GroupDispatchSessionDataStore {
+  /** 读取每个 dispatch_id 的最新调度 Turn 快照。 */
+  list_turns(): Promise<GroupDispatchTurnRecord[]>;
+  /** 以追加日志方式提交一个调度 Turn 的最新完整快照。 */
+  append_turn(turn: GroupDispatchTurnRecord): Promise<void>;
+}
+
+/** Dispatch Session 成功完成一次调度后的运行结果。 */
+export interface GroupDispatchSessionResult {
+  /** 当前调度 Turn 的稳定标识。 */
+  readonly dispatch_id: string;
+  /** 已经校验并持久化的成员投递决定。 */
+  readonly decision: DispatchDecision;
+}
+
+/** 创建 Group Dispatch Session 的运行依赖。 */
+export interface GroupDispatchSessionOptions {
+  /** 当前 GroupSession 使用的消息调度策略。 */
+  readonly dispatch_strategy: DispatchStrategy;
+}
+
+/** 向 Group Dispatch Session 提交一次调度判断的输入快照。 */
+export interface GroupDispatchSessionInput {
+  /** 本次调度由用户消息还是自动传播触发。 */
+  readonly trigger: DispatchTrigger;
+  /** 当前调度所围绕的 GroupMessage。 */
+  readonly message: GroupMessage;
+  /** 当前调度需要一起判断的新增 GroupMessage。 */
+  readonly pending_messages: readonly GroupMessage[];
+  /** 当前 GroupSession 的完整共享消息快照。 */
+  readonly messages: readonly GroupMessage[];
+  /** 当前 Group 的成员快照。 */
+  readonly members: readonly Agent[];
+}

package/src/types/group/GroupSession.ts

@@ -143,6 +143,8 @@ export interface GroupTurnRuntime {
   readonly root_message_id: string;
   /** 用户消息写入时冻结的上下文消息标识。 */
   readonly context_message_ids: readonly string[];
+  /** 当前 Turn 位于初始用户调度还是自动传播阶段。 */
+  dispatch_stage: "user" | "auto";
   /** 当前 GroupTurn 的异步 user dispatch。 */
   user_dispatch?: Promise<void>;
   /** 当前 GroupTurn 是否等待 GroupSession 的 auto dispatch。 */

package/src/types/group/GroupSessionStore.ts

@@ -1,12 +1,13 @@
 /** GroupSession 持久化协议：只描述 GroupSession 所需的底层数据能力。 */
 
 import type { GroupMessage } from "@/types/group/Group.js";
+import type { GroupDispatchSessionDataStore } from "@/types/group/GroupDispatchSession.js";
 import type { FileSystem } from "@downcity/workspace";
 
 /** GroupSession 的持久化元数据。 */
 export interface GroupSessionHistoryMeta {
   /** metadata schema 版本。 */
-  readonly v: 1;
+  readonly v: 2;
   /** 当前 GroupSession 标识。 */
   readonly session_id: string;
   /** 所属 Group 标识。 */
@@ -37,12 +38,16 @@ export interface GroupSessionTurnCheckpoint {
   readonly root_message_id: string;
   /** 用户消息写入时冻结的上下文消息标识。 */
   readonly context_message_ids: readonly string[];
+  /** 恢复后应重新执行初始用户调度，还是继续等待自动传播收口。 */
+  readonly dispatch_stage: "user" | "auto";
 }
 
 /** 单个 GroupSession 的持久化数据视图。 */
 export interface GroupSessionDataStore {
   /** 当前 GroupSession 标识。 */
   readonly session_id: string;
+  /** 当前 GroupSession 独享的 Dispatch Session 持久化视图。 */
+  readonly dispatch_session: GroupDispatchSessionDataStore;
   /** 初始化当前 GroupSession 的存储布局。 */
   initialize(): Promise<void>;
   /** 读取完整共享消息历史。 */

package/src/types/plugin/PluginNotification.ts

@@ -0,0 +1,38 @@
+/**
+ * Agent Plugin 向宿主发布用户注意事项的通知协议。
+ *
+ * Plugin 只描述通知内容与自身工作区路由，不感知 Desktop、Dock、持久化或已读策略。
+ * 宿主负责绑定 Plugin 身份、聚合通知并决定具体呈现方式。
+ */
+
+import type { JsonObject } from "@/types/common/Json.js";
+
+/** Agent Plugin 发布的一条宿主通知。 */
+export interface PluginNotificationInput {
+  /** Plugin 内稳定的聚合键；同一键的新通知替换旧的未读通知。 */
+  readonly topic_key: string;
+
+  /** 简短的用户可见标题。 */
+  readonly title: string;
+
+  /** 可选的用户可见补充说明。 */
+  readonly body?: string;
+
+  /** 打开通知时使用的当前 Plugin 工作区 JSON 路由。 */
+  readonly route?: JsonObject;
+}
+
+/** Plugin 要清除的一项本地通知主题。 */
+export interface PluginNotificationTopicInput {
+  /** Plugin 内稳定的聚合键。 */
+  readonly topic_key: string;
+}
+
+/** 宿主注入给 Agent Plugin factory 的通知发布能力。 */
+export interface PluginNotificationPublisher {
+  /** 发布一条由当前 Plugin 拥有的通知。 */
+  publish(input: PluginNotificationInput): Promise<void>;
+
+  /** 清除当前 Plugin 命名空间内一个主题的未读通知。 */
+  dismiss(input: PluginNotificationTopicInput): Promise<void>;
+}

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 }]
+      : [];
   });
 }