@downcity/agent 1.1.408 → 1.1.437

package/src/group/GroupDispatchRuntime.ts

@@ -0,0 +1,233 @@
+/**
+ * GroupSession 私有调度运行器。
+ *
+ * 本模块只封装调度请求的串行执行、模型取消和 Turn 状态提交。共享消息、成员关系、
+ * 恢复检查点与整体生命周期仍由 GroupSession 统一拥有。
+ */
+
+import { nanoid } from "nanoid";
+import type {
+  GroupDispatchInput,
+  GroupDispatchResult,
+  GroupDispatchRuntimeOptions,
+  GroupDispatchTurnRecord,
+} from "@/types/group/GroupDispatch.js";
+import type {
+  DispatchDecision,
+  DispatchMemberProfile,
+} from "@/types/group/DispatchStrategy.js";
+import type { GroupSessionDataStore } from "@/types/group/GroupSessionStore.js";
+
+/** 主动停止 Group 调度时使用的内部错误。 */
+export class GroupDispatchStoppedError extends Error {
+  constructor() {
+    super("Group dispatch stopped");
+    this.name = "GroupDispatchStoppedError";
+  }
+}
+
+/** GroupSession 私有的调度运行机制，不构成独立 Session。 */
+export class GroupDispatchRuntime {
+  private readonly dispatch_strategy: GroupDispatchRuntimeOptions["dispatch_strategy"];
+  private store?: GroupSessionDataStore;
+  private queue_tail: Promise<void> = Promise.resolve();
+  private active_abort_controller?: AbortController;
+  private stopping = false;
+  private disposed = false;
+
+  constructor(options: GroupDispatchRuntimeOptions) {
+    this.dispatch_strategy = options.dispatch_strategy;
+  }
+
+  /** 绑定 GroupSession Store，并把进程中断留下的运行态明确收口为 stopped。 */
+  async initialize(store: GroupSessionDataStore): Promise<this> {
+    if (this.store && this.store !== store) {
+      throw new Error("GroupDispatchRuntime is already initialized with another Store");
+    }
+    if (this.store === store) return this;
+    this.store = store;
+    const interrupted_turns = (await store.list_dispatch_turns()).filter((turn) => (
+      turn.status === "queued" || turn.status === "running"
+    ));
+    for (const turn of interrupted_turns) {
+      await store.append_dispatch_turn({
+        ...turn,
+        status: "stopped",
+        error: "Group dispatch interrupted before recovery",
+        updated_at: Date.now(),
+      });
+    }
+    return this;
+  }
+
+  /** 按提交顺序执行一次调度，并在返回前持久化最终决定。 */
+  decide(input: GroupDispatchInput): Promise<GroupDispatchResult> {
+    this.assert_available();
+    const store = this.require_store();
+    const created_at = Date.now();
+    const queued_turn: GroupDispatchTurnRecord = {
+      dispatch_id: `group-dispatch-${nanoid(12)}`,
+      trigger: input.trigger,
+      message_id: input.current_message.id,
+      pending_message_ids: input.pending_messages.map((message) => message.id),
+      status: "queued",
+      created_at,
+      updated_at: created_at,
+    };
+    const persist_queued = store.append_dispatch_turn(queued_turn);
+    const operation = this.queue_tail.then(async () => {
+      await persist_queued;
+      return await this.execute_turn(input, queued_turn);
+    });
+    this.queue_tail = operation.then(() => undefined, () => undefined);
+    return operation;
+  }
+
+  /** 中断当前模型调用，并让尚未开始的调度 Turn 按队列顺序收口。 */
+  async stop(): Promise<void> {
+    if (this.disposed || this.stopping) return;
+    this.stopping = true;
+    this.active_abort_controller?.abort(new GroupDispatchStoppedError());
+    await this.queue_tail;
+    this.active_abort_controller = undefined;
+    this.stopping = false;
+  }
+
+  /** 永久释放当前调度运行器。 */
+  async dispose(): Promise<void> {
+    if (this.disposed) return;
+    await this.stop();
+    this.disposed = true;
+    this.store = undefined;
+  }
+
+  /** 执行队首调度 Turn，确保成功、失败和停止都形成持久化终态。 */
+  private async execute_turn(
+    input: GroupDispatchInput,
+    queued_turn: GroupDispatchTurnRecord,
+  ): Promise<GroupDispatchResult> {
+    const store = this.require_store();
+    if (this.stopping || this.disposed) {
+      await this.persist_terminal_turn(queued_turn, "stopped", "Group dispatch stopped");
+      throw new GroupDispatchStoppedError();
+    }
+    const abort_controller = new AbortController();
+    this.active_abort_controller = abort_controller;
+    await store.append_dispatch_turn({
+      ...queued_turn,
+      status: "running",
+      updated_at: Date.now(),
+    });
+    try {
+      const strategy_decision = await this.dispatch_strategy.decide_dispatch({
+        ...input,
+        abort_signal: abort_controller.signal,
+      });
+      if (this.stopping || this.disposed || abort_controller.signal.aborted) {
+        throw new GroupDispatchStoppedError();
+      }
+      const decision = normalize_dispatch_decision(strategy_decision, input.members);
+      await store.append_dispatch_turn({
+        ...queued_turn,
+        status: "completed",
+        decision,
+        updated_at: Date.now(),
+      });
+      return { dispatch_id: queued_turn.dispatch_id, decision };
+    } catch (error) {
+      if (
+        error instanceof GroupDispatchStoppedError ||
+        this.stopping ||
+        this.disposed ||
+        abort_controller.signal.aborted
+      ) {
+        await this.persist_terminal_turn(queued_turn, "stopped", "Group dispatch stopped");
+        throw new GroupDispatchStoppedError();
+      }
+      const detail = error instanceof Error ? error.message : String(error);
+      await this.persist_terminal_turn(queued_turn, "failed", detail);
+      throw error;
+    } finally {
+      if (this.active_abort_controller === abort_controller) {
+        this.active_abort_controller = undefined;
+      }
+    }
+  }
+
+  /** 提交没有 decision 的失败或停止终态。 */
+  private async persist_terminal_turn(
+    turn: GroupDispatchTurnRecord,
+    status: "failed" | "stopped",
+    error: string,
+  ): Promise<void> {
+    await this.require_store().append_dispatch_turn({
+      ...turn,
+      status,
+      error,
+      updated_at: Date.now(),
+    });
+  }
+
+  private require_store(): GroupSessionDataStore {
+    if (!this.store) throw new Error("GroupDispatchRuntime is not initialized");
+    return this.store;
+  }
+
+  private assert_available(): void {
+    if (this.disposed) throw new Error("GroupDispatchRuntime is disposed");
+    if (this.stopping) throw new Error("GroupDispatchRuntime is stopping");
+  }
+}
+
+/** 在持久化和执行之前统一校验自定义策略与 AI 策略的调度结果。 */
+function normalize_dispatch_decision(
+  decision: DispatchDecision,
+  members: readonly DispatchMemberProfile[],
+): DispatchDecision {
+  if (typeof decision?.reason !== "string") throw new Error("Group dispatch requires a reason");
+  const reason = decision.reason.trim();
+  if (!reason) throw new Error("Group dispatch requires a non-empty reason");
+  if (!Array.isArray(decision.stages)) throw new Error("Group dispatch requires stages");
+  if (typeof decision.terminal !== "boolean") throw new Error("Group dispatch requires terminal");
+  if (decision.stages.length === 0 && !decision.terminal) {
+    throw new Error("Group dispatch cannot continue without any stage");
+  }
+  const valid_member_ids = new Set(members.map((member) => member.agent_id));
+  const stage_ids = new Set<string>();
+  const stages = decision.stages.map((stage) => {
+    if (typeof stage?.stage_id !== "string") {
+      throw new Error("Group dispatch requires a stage_id");
+    }
+    const stage_id = stage.stage_id.trim();
+    if (!stage_id) throw new Error("Group dispatch requires a non-empty stage_id");
+    if (stage_ids.has(stage_id)) throw new Error(`Group dispatch contains duplicate stage "${stage_id}"`);
+    stage_ids.add(stage_id);
+    if (!Array.isArray(stage.assignments) || stage.assignments.length === 0) {
+      throw new Error(`Group dispatch stage "${stage_id}" requires assignments`);
+    }
+    const selected_member_ids = new Set<string>();
+    const assignments = stage.assignments.map((assignment) => {
+      if (typeof assignment?.member_id !== "string") {
+        throw new Error(`Group dispatch stage "${stage_id}" requires assignment member_id`);
+      }
+      const member_id = assignment.member_id.trim();
+      if (!valid_member_ids.has(member_id)) {
+        throw new Error(`Group dispatch selected unknown member: ${member_id}`);
+      }
+      if (selected_member_ids.has(member_id)) {
+        throw new Error(`Group dispatch selected member more than once in stage "${stage_id}"`);
+      }
+      selected_member_ids.add(member_id);
+      if (typeof assignment.instruction !== "string") {
+        throw new Error(`Group dispatch assignment for "${member_id}" requires an instruction`);
+      }
+      const instruction = assignment.instruction.trim();
+      if (!instruction) {
+        throw new Error(`Group dispatch assignment for "${member_id}" requires an instruction`);
+      }
+      return { member_id, instruction };
+    });
+    return { stage_id, assignments };
+  });
+  return { reason, stages, terminal: decision.terminal };
+}

package/src/group/GroupSession.ts

@@ -13,15 +13,23 @@ import type {
   GroupTurnRuntime,
   GroupSessionContract,
 } from "@/types/group/GroupSession.js";
-import type { DispatchDecision, DispatchNode, DispatchStrategy } from "@/types/group/DispatchStrategy.js";
-import type { WorkspaceBase } from "@downcity/workspace";
+import type {
+  DispatchAssignment,
+  DispatchDecision,
+  DispatchStage,
+  DispatchStrategy,
+} from "@/types/group/DispatchStrategy.js";
+import type { ModelClient, WorkspaceRuntime } from "@downcity/type";
 import type { GroupSessionDataStore } from "@/types/group/GroupSessionStore.js";
-import type { RespondSessionInteractionInput } from "@/types/session/SessionInteraction.js";
+import type { RespondSessionInteractionInput } from "@downcity/type";
 import {
-  GroupDispatchSession,
+  GroupDispatchRuntime,
   GroupDispatchStoppedError,
-} from "@/group/GroupDispatchSession.js";
-import type { GroupDispatchSessionResult } from "@/types/group/GroupDispatchSession.js";
+} from "@/group/GroupDispatchRuntime.js";
+import type { GroupDispatchResult } from "@/types/group/GroupDispatch.js";
+import { normalize_session_title } from "@/session/storage/Metadata.js";
+import { generate_session_title } from "@/session/SessionTitle.js";
+import { SessionTitleTask } from "@/session/runtime/SessionTitleTask.js";
 
 const max_auto_dispatch_count = 32;
 
@@ -35,12 +43,14 @@ export interface GroupSessionOptions {
   readonly group_name: string;
   /** Group 协作说明。 */
   readonly instruction?: string;
+  /** GroupSession 用于生成标题的 Group 模型。 */
+  readonly model?: ModelClient;
   /** Group 成员。 */
   readonly members: readonly Agent[];
   /** Group 消息调度策略。 */
   readonly dispatch_strategy: DispatchStrategy;
   /** Group 为成员执行提供的共享 Workspace。 */
-  readonly workspace?: WorkspaceBase;
+  readonly workspace?: WorkspaceRuntime;
 }
 
 /** Group 的一个独立群聊上下文。 */
@@ -51,9 +61,11 @@ export class GroupSession implements GroupSessionContract {
 
   private readonly group_name: string;
   private readonly instruction?: string;
+  private readonly model?: ModelClient;
   private readonly members: readonly Agent[];
-  private readonly dispatch_session: GroupDispatchSession;
-  private readonly workspace?: WorkspaceBase;
+  private readonly dispatch_runtime: GroupDispatchRuntime;
+  private readonly title_task: SessionTitleTask;
+  private readonly workspace?: WorkspaceRuntime;
   private readonly messages_by_id: GroupMessage[] = [];
   private readonly subscribers = new Set<GroupEventSubscriber>();
   private readonly member_sessions = new Map<string, AgentSession>();
@@ -73,6 +85,7 @@ export class GroupSession implements GroupSessionContract {
   private auto_dispatch_requested = false;
   private stop_requested = false;
   private disposed = false;
+  private metadata_mutation_chain: Promise<void> = Promise.resolve();
 
   constructor(options: GroupSessionOptions) {
     this.id = String(options.id || "").trim();
@@ -81,10 +94,12 @@ export class GroupSession implements GroupSessionContract {
     if (!this.group_id) throw new Error("GroupSession requires a non-empty group_id");
     this.group_name = options.group_name;
     this.instruction = options.instruction;
+    this.model = options.model;
     this.members = options.members;
-    this.dispatch_session = new GroupDispatchSession({
+    this.dispatch_runtime = new GroupDispatchRuntime({
       dispatch_strategy: options.dispatch_strategy,
     });
+    this.title_task = new SessionTitleTask({ session_id: this.id });
     this.workspace = options.workspace;
     this.workspace_id = options.workspace?.id;
   }
@@ -97,7 +112,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);
+    await this.dispatch_runtime.initialize(store);
     const metadata = await store.read_metadata();
     if (metadata.group_id !== this.group_id) {
       throw new Error(`GroupSession "${this.id}" belongs to another Group`);
@@ -141,14 +156,10 @@ export class GroupSession implements GroupSessionContract {
       const member = this.get_member(agent_id);
       if (!member) continue;
       try {
-        const session = await member.sessions.get(session_id, {
+        const session = await member.sessions.get(session_id, "group", {
           ...(this.workspace ? { workspace: this.workspace } : {}),
-          origin: {
-            type: "group",
-            group_id: this.group_id,
-            group_session_id: this.id,
-          },
         });
+        this.assert_member_session_origin(session);
         this.member_sessions.set(agent_id, session);
         this.member_session_ids.set(agent_id, session.id);
         this.subscribe_member_session(agent_id, session);
@@ -191,9 +202,29 @@ export class GroupSession implements GroupSessionContract {
     await this.persist_dispatch_checkpoint();
     this.publish_status(turn_id, "dispatching", { message_id: message.id });
     this.start_user_dispatch(message, group_turn);
+    this.schedule_title_generation();
     return { turn_id, success: true, message_count: this.messages_by_id.length };
   }
 
+  /** 修改当前 GroupSession 的 canonical 用户可见标题。 */
+  async rename(input: string): Promise<string> {
+    this.assert_available();
+    const title = normalize_session_title(input);
+    if (!title) throw new Error("group_session.rename requires a non-empty title");
+    if (!this.store) throw new Error(`GroupSession "${this.id}" is not initialized`);
+    this.title_task.dispose();
+    const updated_at = Date.now();
+    const changed = await this.run_metadata_mutation(async () => {
+      if (!this.store) return false;
+      const metadata = await this.store.read_metadata();
+      if (normalize_session_title(metadata.title) === title) return false;
+      await this.store.update_metadata({ title, updated_at });
+      return true;
+    });
+    if (changed) this.publish_event({ type: "title", title });
+    return title;
+  }
+
   /** 读取共享消息快照。 */
   async messages(): Promise<readonly GroupMessage[]> {
     return this.messages_by_id.map((message) => ({ ...message }));
@@ -227,7 +258,7 @@ export class GroupSession implements GroupSessionContract {
     this.stop_requested = true;
     this.publish_status(undefined, "stopped");
     await Promise.allSettled([
-      this.dispatch_session.stop(),
+      this.dispatch_runtime.stop(),
       ...[...this.member_sessions.values()].map((session) => session.stop()),
     ]);
     await Promise.allSettled([...this.pending_deliveries]);
@@ -244,7 +275,8 @@ export class GroupSession implements GroupSessionContract {
   async dispose(): Promise<void> {
     if (this.disposed) return;
     await this.stop();
-    await this.dispatch_session.dispose();
+    await this.dispatch_runtime.dispose();
+    this.title_task.dispose();
     this.disposed = true;
     this.subscribers.clear();
     for (const unsubscribe of this.member_session_unsubscribes.values()) unsubscribe();
@@ -445,17 +477,27 @@ export class GroupSession implements GroupSessionContract {
     trigger: "user" | "auto",
     message: GroupMessage,
     pending_messages: readonly GroupMessage[],
-  ): Promise<GroupDispatchSessionResult> {
-    return await this.dispatch_session.decide({
+  ): Promise<GroupDispatchResult> {
+    const pending_message_ids = new Set(pending_messages.map((item) => item.id));
+    return await this.dispatch_runtime.decide({
+      group: {
+        group_id: this.group_id,
+        name: this.group_name,
+        ...(this.instruction ? { instruction: this.instruction } : {}),
+      },
       trigger,
-      message,
+      current_message: message,
       pending_messages,
-      messages: await this.messages(),
-      members: this.members,
+      history: this.messages_by_id.filter((item) => !pending_message_ids.has(item.id)),
+      members: this.members.map((member) => ({
+        agent_id: member.id,
+        name: member.name,
+        description: member.description,
+      })),
     });
   }
 
-  /** 执行当前响应图；节点依赖只影响投递顺序，不创建额外的调度循环。 */
+  /** 顺序执行有限阶段计划；任一阶段没有有效输出时不再执行后续阶段。 */
   private async run_dispatch_plan(
     decision: DispatchDecision,
     source_message: GroupMessage,
@@ -463,71 +505,45 @@ export class GroupSession implements GroupSessionContract {
     turn_id?: string,
     dispatch_id?: string,
   ): Promise<readonly GroupMessage[]> {
-    const node_promises = new Map<string, Promise<void>>();
-    const nodes_by_id = new Map(decision.nodes.map((node) => [node.node_id, node]));
-    const node_outputs = new Map<string, GroupMessage[]>();
-    const resolving_node_ids = new Set<string>();
-    const run_node = (node: DispatchNode): Promise<void> => {
-      const cached = node_promises.get(node.node_id);
-      if (cached) return cached;
-      if (resolving_node_ids.has(node.node_id)) {
-        return Promise.reject(new Error(`Dispatch graph contains a cycle at node "${node.node_id}"`));
-      }
-      resolving_node_ids.add(node.node_id);
-      const promise = (async () => {
-        try {
-          await Promise.all(node.depends_on_node_ids.map((node_id) => {
-            const dependency = nodes_by_id.get(node_id);
-            if (!dependency) return Promise.reject(new Error(`Dispatch node "${node.node_id}" depends on missing node "${node_id}"`));
-            return run_node(dependency);
-          }));
-          const dependency_messages = node.depends_on_node_ids.flatMap((node_id) => node_outputs.get(node_id) || []);
-          // 依赖表示真实的前置回复；任一前置节点没有有效输出时，下游不应
-          // 退化为重新消费 source_message，否则会形成虚假的串行链路。
-          const dependencies_ready = node.depends_on_node_ids.every((node_id) => (
-            (node_outputs.get(node_id) || []).length > 0
-          ));
-          if (!dependencies_ready) {
-            node_outputs.set(node.node_id, []);
-            return;
-          }
-          const current_message = dependency_messages.at(-1) || source_message;
-          const context_messages = [...base_messages, ...dependency_messages];
-          const outputs = await this.execute_dispatch_node(node, current_message, context_messages, turn_id, dispatch_id);
-          node_outputs.set(node.node_id, outputs);
-        } finally {
-          resolving_node_ids.delete(node.node_id);
-        }
-      })();
-      node_promises.set(node.node_id, promise);
-      return promise;
-    };
-    const promises = decision.nodes.map(run_node);
-    await Promise.all(promises);
-    const depended_node_ids = new Set(
-      decision.nodes.flatMap((node) => node.depends_on_node_ids),
-    );
-    // 只把叶子节点作为下一次 auto dispatch 的 frontier；中间节点的回复
-    // 已经被下游节点消费，不能再次被当作新的群聊发言重复投递。
-    return decision.nodes
-      .filter((node) => !depended_node_ids.has(node.node_id))
-      .flatMap((node) => node_outputs.get(node.node_id) || []);
+    const completed_outputs: GroupMessage[] = [];
+    let stage_outputs: readonly GroupMessage[] = [];
+    for (const [stage_index, stage] of decision.stages.entries()) {
+      const current_message = stage_index === 0
+        ? source_message
+        : stage_outputs.at(-1) || source_message;
+      stage_outputs = await this.execute_dispatch_stage(
+        stage,
+        current_message,
+        [...base_messages, ...completed_outputs],
+        turn_id,
+        dispatch_id,
+      );
+      if (stage_outputs.length === 0) return [];
+      completed_outputs.push(...stage_outputs);
+    }
+    // 只有最后阶段是下一轮语义判断的 frontier；此前阶段已经被后续成员消费。
+    return stage_outputs;
   }
 
-  private async execute_dispatch_node(
-    node: DispatchNode,
+  /** 并行执行一个阶段内的成员专属任务。 */
+  private async execute_dispatch_stage(
+    stage: DispatchStage,
     message: GroupMessage,
     context_messages: readonly GroupMessage[],
     turn_id?: string,
     dispatch_id?: string,
   ): Promise<GroupMessage[]> {
-    const selected_ids = node.response_mode === "single" ? node.member_ids.slice(0, 1) : node.member_ids;
-    const targets = [...new Set(selected_ids)]
-      .map((agent_id) => this.get_member(agent_id))
-      .filter((agent): agent is Agent => Boolean(agent));
-    const prepared_results = await Promise.all(targets.map(async (agent) => {
+    const targets = stage.assignments.map((assignment) => {
+      const agent = this.get_member(assignment.member_id);
+      if (!agent) throw new Error(`Dispatch selected unknown member "${assignment.member_id}"`);
+      return { agent, assignment };
+    });
+    const prepared_results = await Promise.all(targets.map(async ({ agent, assignment }) => {
       try {
-        return { agent, turn: await this.prepare_member_delivery(agent, message, context_messages, node.instruction) } as const;
+        return {
+          agent,
+          turn: await this.prepare_member_delivery(agent, message, context_messages, assignment),
+        } as const;
       } catch (error) {
         await this.append_member_failure(agent, message, error);
         return null;
@@ -540,7 +556,9 @@ export class GroupSession implements GroupSessionContract {
         dispatched_member_ids: prepared_deliveries.map(({ agent }) => agent.id),
       });
     }
-    const execution_results = Promise.all(prepared_deliveries.map(({ agent, turn }) => this.execute_member_delivery(agent, message, turn, turn_id, dispatch_id, node.node_id)));
+    const execution_results = Promise.all(prepared_deliveries.map(({ agent, turn }) => (
+      this.execute_member_delivery(agent, message, turn, turn_id, dispatch_id, stage.stage_id)
+    )));
     const execution = execution_results.then(() => undefined);
     this.active_member_deliveries.add(execution);
     try {
@@ -556,14 +574,14 @@ export class GroupSession implements GroupSessionContract {
     agent: Agent,
     message: GroupMessage,
     context_messages: readonly GroupMessage[],
-    dispatch_instruction: string,
+    assignment: DispatchAssignment,
   ): Promise<Awaited<ReturnType<AgentSession["prompt"]>>> {
     if (this.stop_requested || this.disposed) {
       throw new Error(`GroupSession "${this.id}" is stopping`);
     }
     const session = await this.ensure_member_session(agent);
     return await session.prompt({
-      query: this.build_member_context(agent, message, context_messages, dispatch_instruction),
+      query: this.build_member_context(agent, message, context_messages, assignment.instruction),
     });
   }
 
@@ -574,7 +592,7 @@ export class GroupSession implements GroupSessionContract {
     turn: Awaited<ReturnType<AgentSession["prompt"]>>,
     turn_id?: string,
     dispatch_id?: string,
-    dispatch_node_id?: string,
+    dispatch_stage_id?: string,
   ): Promise<GroupMessage | null> {
     this.set_member_running(agent.id, 1, turn_id);
     let running = true;
@@ -599,7 +617,7 @@ export class GroupSession implements GroupSessionContract {
         reply_to: message.id,
         ...(turn_id ? { turn_id } : {}),
         ...(dispatch_id ? { dispatch_id } : {}),
-        ...(dispatch_node_id ? { dispatch_node_id } : {}),
+        ...(dispatch_stage_id ? { dispatch_stage_id } : {}),
       });
       return reply;
     } catch (error) {
@@ -676,6 +694,19 @@ export class GroupSession implements GroupSessionContract {
     return session;
   }
 
+  /** 校验恢复的成员 Session 确实属于当前 GroupSession。 */
+  private assert_member_session_origin(session: AgentSession): void {
+    if (
+      session.origin.type !== "group"
+      || session.origin.group_id !== this.group_id
+      || session.origin.group_session_id !== this.id
+    ) {
+      throw new Error(
+        `Agent Session "${session.id}" does not belong to GroupSession "${this.id}"`,
+      );
+    }
+  }
+
   private subscribe_member_session(agent_id: string, session: AgentSession): void {
     this.member_session_unsubscribes.get(agent_id)?.();
     this.member_session_unsubscribes.set(agent_id, session.subscribe((mutation) => {
@@ -700,14 +731,21 @@ export class GroupSession implements GroupSessionContract {
       .map((item) => `${item.sender_type === "user" ? "User" : item.sender_id}: ${item.text}`)
       .join("\n");
     return [
+      `Group: ${this.group_name}`,
       this.instruction ? `Group objective: ${this.instruction}` : "",
-      `你是 Group ${this.group_name} 的成员 ${agent.id}。`,
-      "Group conversation:",
-      history,
-      `Current message from ${message.sender_type === "agent" ? message.sender_id : "user"}: ${message.text}`,
+      `Your identity: ${agent.name} (${agent.id})`,
+      `Your description: ${agent.description || "（未提供）"}`,
+      "Conversation:",
+      history || "（无）",
+      "Current message:",
+      `${message.sender_type === "agent" ? message.sender_id : "user"}: ${message.text}`,
+      "Assignment:",
       dispatch_instruction,
-      `你只能代表成员 ${agent.id} 自己发言。不得代替、指挥、裁定、总结或转述其他成员；不得假装自己是其他成员；不得创建队长、裁判或协调者。`,
-      "你已被 Group 调度选中，必须直接回复当前消息。",
+      "Response constraints:",
+      `- 只代表成员 ${agent.id} 自己发言。`,
+      "- 直接完成 Assignment，不判断或改写其他成员的任务。",
+      "- 不代替、指挥、裁定、总结或转述其他成员。",
+      "- 不创建队长、裁判、领导者或协调者角色。",
     ].filter(Boolean).join("\n");
   }
 
@@ -739,6 +777,43 @@ export class GroupSession implements GroupSessionContract {
     return message;
   }
 
+  /** 基于首条用户消息异步生成标题，不阻塞 Group 调度主链路。 */
+  private schedule_title_generation(): void {
+    this.title_task.schedule(async (signal) => {
+      if (!this.store || !this.model) return;
+      const before_metadata = await this.store.read_metadata();
+      if (normalize_session_title(before_metadata.title)) return;
+      const first_user_message = this.messages_by_id.find((message) => message.sender_type === "user");
+      if (!first_user_message) return;
+      const title = await generate_session_title({
+        model: this.model,
+        session_id: this.id,
+        first_user_text: first_user_message.text,
+        signal,
+      });
+      if (!title || signal.aborted || !this.store) return;
+      const changed = await this.run_metadata_mutation(async () => {
+        if (!this.store || signal.aborted) return false;
+        const latest_metadata = await this.store.read_metadata();
+        const source_exists = this.messages_by_id.some((message) => message.id === first_user_message.id);
+        if (normalize_session_title(latest_metadata.title) || !source_exists || signal.aborted) return false;
+        await this.store.update_metadata({ title });
+        return true;
+      });
+      if (changed && !signal.aborted) this.publish_event({ type: "title", title });
+    });
+  }
+
+  /** 串行提交 GroupSession metadata，避免后台标题覆盖手动重命名。 */
+  private async run_metadata_mutation<T>(mutation: () => Promise<T>): Promise<T> {
+    const task = this.metadata_mutation_chain.then(mutation, mutation);
+    this.metadata_mutation_chain = task.then(
+      () => undefined,
+      () => undefined,
+    );
+    return await task;
+  }
+
   /** 持久化当前调度检查点；只记录可由消息事实安全恢复的状态。 */
   private async persist_dispatch_checkpoint(): Promise<void> {
     if (!this.store) return;