@downcity/agent 1.1.401 → 1.1.408

package/src/group/GroupSession.ts

@@ -17,6 +17,11 @@ import type { DispatchDecision, DispatchNode, DispatchStrategy } from "@/types/g
 import type { WorkspaceBase } from "@downcity/workspace";
 import type { GroupSessionDataStore } from "@/types/group/GroupSessionStore.js";
 import type { RespondSessionInteractionInput } from "@/types/session/SessionInteraction.js";
+import {
+  GroupDispatchSession,
+  GroupDispatchStoppedError,
+} from "@/group/GroupDispatchSession.js";
+import type { GroupDispatchSessionResult } from "@/types/group/GroupDispatchSession.js";
 
 const max_auto_dispatch_count = 32;
 
@@ -47,7 +52,7 @@ export class GroupSession implements GroupSessionContract {
   private readonly group_name: string;
   private readonly instruction?: string;
   private readonly members: readonly Agent[];
-  private readonly dispatch_strategy: DispatchStrategy;
+  private readonly dispatch_session: GroupDispatchSession;
   private readonly workspace?: WorkspaceBase;
   private readonly messages_by_id: GroupMessage[] = [];
   private readonly subscribers = new Set<GroupEventSubscriber>();
@@ -77,7 +82,9 @@ export class GroupSession implements GroupSessionContract {
     this.group_name = options.group_name;
     this.instruction = options.instruction;
     this.members = options.members;
-    this.dispatch_strategy = options.dispatch_strategy;
+    this.dispatch_session = new GroupDispatchSession({
+      dispatch_strategy: options.dispatch_strategy,
+    });
     this.workspace = options.workspace;
     this.workspace_id = options.workspace?.id;
   }
@@ -90,6 +97,7 @@ export class GroupSession implements GroupSessionContract {
     if (this.store === store) return this;
     this.store = store;
     await store.initialize();
+    await this.dispatch_session.initialize(store.dispatch_session);
     const metadata = await store.read_metadata();
     if (metadata.group_id !== this.group_id) {
       throw new Error(`GroupSession "${this.id}" belongs to another Group`);
@@ -112,7 +120,8 @@ export class GroupSession implements GroupSessionContract {
         turn_id: checkpoint.turn_id,
         root_message_id: checkpoint.root_message_id,
         context_message_ids: checkpoint.context_message_ids,
-        auto_pending: true,
+        dispatch_stage: checkpoint.dispatch_stage,
+        auto_pending: checkpoint.dispatch_stage === "auto",
         stopped: false,
         recovered: true,
       });
@@ -151,7 +160,12 @@ export class GroupSession implements GroupSessionContract {
     if (Object.keys(valid_member_session_ids).length !== Object.keys(member_session_ids).length) {
       await store.update_metadata({ member_session_ids: valid_member_session_ids });
     }
-    if (this.group_turns_by_id.size > 0 || this.auto_frontier_messages.length > 0) {
+    for (const group_turn of this.group_turns_by_id.values()) {
+      if (group_turn.dispatch_stage !== "user") continue;
+      const message = this.messages_by_id.find((item) => item.id === group_turn.root_message_id);
+      if (message) this.start_user_dispatch(message, group_turn);
+    }
+    if ([...this.group_turns_by_id.values()].some((turn) => turn.auto_pending) || this.auto_frontier_messages.length > 0) {
       this.request_auto_dispatch();
     }
     return this;
@@ -169,19 +183,14 @@ export class GroupSession implements GroupSessionContract {
       turn_id,
       root_message_id: message.id,
       context_message_ids: [...context_message_ids, message.id],
+      dispatch_stage: "user",
       auto_pending: false,
       stopped: false,
     };
     this.group_turns_by_id.set(turn_id, group_turn);
     await this.persist_dispatch_checkpoint();
     this.publish_status(turn_id, "dispatching", { message_id: message.id });
-    const dispatch = this.run_user_dispatch(message, turn_id);
-    group_turn.user_dispatch = dispatch;
-    this.pending_deliveries.add(dispatch);
-    void dispatch.finally(() => {
-      this.pending_deliveries.delete(dispatch);
-      if (group_turn.auto_pending) this.request_auto_dispatch();
-    });
+    this.start_user_dispatch(message, group_turn);
     return { turn_id, success: true, message_count: this.messages_by_id.length };
   }
 
@@ -217,7 +226,10 @@ export class GroupSession implements GroupSessionContract {
     if (this.disposed) return;
     this.stop_requested = true;
     this.publish_status(undefined, "stopped");
-    await Promise.allSettled([...this.member_sessions.values()].map((session) => session.stop()));
+    await Promise.allSettled([
+      this.dispatch_session.stop(),
+      ...[...this.member_sessions.values()].map((session) => session.stop()),
+    ]);
     await Promise.allSettled([...this.pending_deliveries]);
     if (this.auto_dispatch_promise) await this.auto_dispatch_promise;
     this.auto_dispatch_requested = false;
@@ -232,6 +244,7 @@ export class GroupSession implements GroupSessionContract {
   async dispose(): Promise<void> {
     if (this.disposed) return;
     await this.stop();
+    await this.dispatch_session.dispose();
     this.disposed = true;
     this.subscribers.clear();
     for (const unsubscribe of this.member_session_unsubscribes.values()) unsubscribe();
@@ -250,28 +263,53 @@ export class GroupSession implements GroupSessionContract {
     const group_turn = this.group_turns_by_id.get(turn_id);
     if (!group_turn) return;
     try {
-      const decision = await this.decide_dispatch("user", message, [message]);
+      const dispatch = await this.decide_dispatch("user", message, [message]);
       const context_messages = group_turn.context_message_ids
         .map((message_id) => this.messages_by_id.find((item) => item.id === message_id))
         .filter((item): item is GroupMessage => Boolean(item));
-      await this.run_dispatch_plan(decision, message, context_messages, turn_id);
+      await this.run_dispatch_plan(
+        dispatch.decision,
+        message,
+        context_messages,
+        turn_id,
+        dispatch.dispatch_id,
+      );
       if (this.stop_requested || this.disposed) {
         group_turn.stopped = true;
         this.group_turns_by_id.delete(turn_id);
         await this.persist_dispatch_checkpoint();
         return;
       }
-      group_turn.auto_pending = true;
+      if (dispatch.decision.terminal) {
+        this.group_turns_by_id.delete(turn_id);
+      } else {
+        group_turn.dispatch_stage = "auto";
+        group_turn.auto_pending = true;
+      }
       await this.persist_dispatch_checkpoint();
+      if (dispatch.decision.terminal) this.publish_status(turn_id, "idle");
     } catch (error) {
       group_turn.stopped = this.stop_requested;
-      await this.append_dispatch_failure(message, error);
+      if (!(error instanceof GroupDispatchStoppedError)) {
+        await this.append_dispatch_failure(message, error);
+      }
       this.group_turns_by_id.delete(turn_id);
       await this.persist_dispatch_checkpoint();
       this.publish_status(turn_id, this.stop_requested ? "stopped" : "failed");
     }
   }
 
+  /** 登记一次用户调度运行；新建和恢复必须经过同一个生命周期入口。 */
+  private start_user_dispatch(message: GroupMessage, group_turn: GroupTurnRuntime): void {
+    const dispatch = this.run_user_dispatch(message, group_turn.turn_id);
+    group_turn.user_dispatch = dispatch;
+    this.pending_deliveries.add(dispatch);
+    void dispatch.finally(() => {
+      this.pending_deliveries.delete(dispatch);
+      if (group_turn.auto_pending) this.request_auto_dispatch();
+    });
+  }
+
   /** GroupSession 唯一的自动调度循环，统一消费已完成成员产生的新消息。 */
   private request_auto_dispatch(): void {
     if (this.stop_requested || this.disposed) return;
@@ -299,8 +337,8 @@ export class GroupSession implements GroupSessionContract {
         const message = frontier_messages[frontier_messages.length - 1];
         this.publish_status(undefined, "dispatching", { message_id: message.id });
         try {
-          const decision = await this.decide_dispatch("auto", message, frontier_messages);
-          const dispatch_key = JSON.stringify(decision);
+          const dispatch = await this.decide_dispatch("auto", message, frontier_messages);
+          const dispatch_key = JSON.stringify(dispatch.decision);
           if (this.auto_dispatch_path_keys.has(dispatch_key)) {
             await this.append_message({ sender_type: "system", sender_id: "system", text: "Group auto dispatch detected a repeated path.", reply_to: message.id });
             frontier_messages = [];
@@ -311,8 +349,14 @@ export class GroupSession implements GroupSessionContract {
             continue;
           }
           this.auto_dispatch_path_keys.add(dispatch_key);
-          frontier_messages = await this.run_dispatch_plan(decision, message, this.messages_by_id, undefined, `group-dispatch-${nanoid(12)}`);
-          if (decision.terminal || frontier_messages.length === 0) {
+          frontier_messages = await this.run_dispatch_plan(
+            dispatch.decision,
+            message,
+            this.messages_by_id,
+            undefined,
+            dispatch.dispatch_id,
+          );
+          if (dispatch.decision.terminal || frontier_messages.length === 0) {
             frontier_messages = [];
             this.auto_frontier_messages = [];
             this.auto_dispatch_path_keys.clear();
@@ -324,6 +368,7 @@ export class GroupSession implements GroupSessionContract {
             this.auto_dispatch_requested = true;
           }
         } catch (error) {
+          if (error instanceof GroupDispatchStoppedError) return;
           await this.append_dispatch_failure(message, error);
           this.publish_status(undefined, "failed");
           frontier_messages = [];
@@ -361,16 +406,21 @@ export class GroupSession implements GroupSessionContract {
       batch_turns.forEach((group_turn) => { group_turn.auto_pending = false; });
       for (const message of candidate_messages) this.consumed_auto_message_ids.add(message.id);
       await this.persist_dispatch_checkpoint();
-      const dispatch_id = `group-dispatch-${nanoid(12)}`;
       dispatch_count = 0;
       const message = candidate_messages[candidate_messages.length - 1];
       this.publish_status(undefined, "dispatching", { message_id: message.id });
       try {
-        const decision = await this.decide_dispatch("auto", message, pending_messages);
+        const dispatch = await this.decide_dispatch("auto", message, pending_messages);
         const context_messages = this.messages_by_id.filter((item) => item.turn_id && batch_turn_ids.has(item.turn_id));
-        const outputs = await this.run_dispatch_plan(decision, message, context_messages, undefined, dispatch_id);
+        const outputs = await this.run_dispatch_plan(
+          dispatch.decision,
+          message,
+          context_messages,
+          undefined,
+          dispatch.dispatch_id,
+        );
         for (const turn_id of batch_turn_ids) this.group_turns_by_id.delete(turn_id);
-        if (decision.terminal || outputs.length === 0) {
+        if (dispatch.decision.terminal || outputs.length === 0) {
           this.auto_frontier_messages = [];
           await this.persist_dispatch_checkpoint();
           this.publish_status(undefined, "idle");
@@ -381,6 +431,7 @@ export class GroupSession implements GroupSessionContract {
           this.auto_dispatch_requested = true;
         }
       } catch (error) {
+        if (error instanceof GroupDispatchStoppedError) return;
         await this.append_dispatch_failure(message, error);
         this.publish_status(undefined, "failed");
         for (const turn_id of batch_turn_ids) this.group_turns_by_id.delete(turn_id);
@@ -394,8 +445,8 @@ export class GroupSession implements GroupSessionContract {
     trigger: "user" | "auto",
     message: GroupMessage,
     pending_messages: readonly GroupMessage[],
-  ): Promise<DispatchDecision> {
-    return await this.dispatch_strategy.decide_dispatch({
+  ): Promise<GroupDispatchSessionResult> {
+    return await this.dispatch_session.decide({
       trigger,
       message,
       pending_messages,
@@ -537,7 +588,10 @@ export class GroupSession implements GroupSessionContract {
         await this.append_member_failure(agent, message, result.error || "未知错误");
         return null;
       }
-      if (!result.text?.trim()) return null;
+      if (!result.text?.trim()) {
+        await this.append_member_failure(agent, message, "未生成有效回复");
+        return null;
+      }
       const reply = await this.append_message({
         sender_type: "agent",
         sender_id: agent.id,
@@ -653,7 +707,7 @@ export class GroupSession implements GroupSessionContract {
       `Current message from ${message.sender_type === "agent" ? message.sender_id : "user"}: ${message.text}`,
       dispatch_instruction,
       `你只能代表成员 ${agent.id} 自己发言。不得代替、指挥、裁定、总结或转述其他成员；不得假装自己是其他成员；不得创建队长、裁判或协调者。`,
-      "如果不需要你发言，返回空内容。",
+      "你已被 Group 调度选中，必须直接回复当前消息。",
     ].filter(Boolean).join("\n");
   }
 
@@ -695,6 +749,7 @@ export class GroupSession implements GroupSessionContract {
           turn_id: group_turn.turn_id,
           root_message_id: group_turn.root_message_id,
           context_message_ids: [...group_turn.context_message_ids],
+          dispatch_stage: group_turn.dispatch_stage,
         })),
       auto_frontier_message_ids: this.auto_frontier_messages.map((message) => message.id),
     });

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>;
+}