@downcity/agent 1.1.438 → 1.1.445

package/src/session/messages/SessionAgentMessageState.ts

@@ -6,52 +6,64 @@
  */
 
 import { generate_id } from "@/utils/Id.js";
-import { SessionMessageInteractionWriter } from "@/session/messages/SessionMessageInteractionWriter.js";
+import { create_session_part_mutation } from "@/session/messages/SessionMutationFactory.js";
+import { resolve_session_message_state } from "@/session/messages/SessionMessageState.js";
+import {
+  is_same_agent_part,
+  next_agent_part_sequence,
+  resolve_changed_agent_parts,
+} from "@/session/messages/SessionAgentParts.js";
 import type {
   SessionAgentErrorPart,
-  SessionAgentInteractionPart,
+  SessionAgentInteraction,
   SessionAgentMessage,
   SessionAgentMessagePart,
   SessionAgentToolPart,
   SessionMessage,
-  SessionMutation,
 } from "@downcity/type";
 import type {
   SessionInteractionCloseInput,
   SessionInteractionRequest,
   SessionInteractionResponse,
 } from "@downcity/type";
-import type { SessionStreamingToolLocation } from "@/types/session/SessionTool.js";
+import type { SessionOpenMessageToolLocation } from "@/types/session/SessionTool.js";
 import type { SessionAgentMessageStateOptions } from "@/types/session/SessionAgentMessageState.js";
 
+/** 一次 Interaction 的定位结果：所属 Message、Tool 与自身。 */
+interface SessionInteractionLocation {
+  /** 所属 Agent Message 标识。 */
+  message_id: string;
+  /** 承载该 Interaction 的 canonical Tool Part。 */
+  tool: SessionAgentToolPart;
+  /** Interaction 自身。 */
+  interaction: SessionAgentInteraction;
+}
+
 /** 管理 Agent Message 运行投影、语义检查点与 Interaction 原子状态。 */
 export class SessionAgentMessageState {
   private readonly session_id: string;
   private readonly options: SessionAgentMessageStateOptions;
   /** 同一 Agent Message 的检查点严格串行，不同 Message 可以独立提交。 */
   private readonly write_chains = new Map<string, Promise<void>>();
-  private readonly interaction_writer: SessionMessageInteractionWriter;
 
   constructor(options: SessionAgentMessageStateOptions) {
     this.session_id = options.session_id;
     this.options = options;
-    this.interaction_writer = new SessionMessageInteractionWriter({
-      list_messages: options.list_messages,
-      find_streaming_tool: (tool_call_id) => this.find_streaming_tool(tool_call_id),
-      enqueue_assistant_write: (message_id, operation) =>
-        this.enqueue_write(message_id, operation),
-      commit_assistant_snapshot: (current, parts) =>
-        this.persist_snapshot(current.message_id, parts),
-    });
   }
 
-  /** 只在内存中创建或替换一个 Part，并立即发布实时完整 Part。 */
+  /**
+   * 只在内存中创建或替换一个 Part，并立即发布实时完整 Part。
+   *
+   * 内容未变化时不发布：Tool 的 ready 状态会被模型事件与输入校验先后置为同一值，
+   * 无条件下发会产生同 revision、同内容的重复 Mutation。
+   */
   project_part(message_id: string, part: SessionAgentMessagePart): void {
-    const current = this.require_streaming_agent(message_id);
+    const current = this.require_writable_agent(message_id);
     const existing = current.parts.find((item) => item.part_id === part.part_id);
     if (existing && existing.sequence !== part.sequence) {
       throw new Error(`Agent Part sequence changed: ${part.part_id}`);
     }
+    if (existing && is_same_agent_part(existing, part)) return;
     const projected: SessionAgentMessage = {
       ...current,
       updated_at: Date.now(),
@@ -60,18 +72,18 @@ export class SessionAgentMessageState {
         : [...current.parts, structuredClone(part)]
       ).sort((left, right) => left.sequence - right.sequence),
     };
-    this.options.project_mutation({
-      mutation_id: generate_id(),
-      variant: "part",
-      type: part.type,
-      message_id,
-      revision: current.revision,
-      session_id: this.session_id,
-      ...(current.turn_id ? { turn_id: current.turn_id } : {}),
-      created_at: projected.updated_at,
-      part_id: part.part_id,
-      part: structuredClone(part),
-    } as SessionMutation, projected);
+    this.options.cache.project(
+      create_session_part_mutation({
+        mutation_id: generate_id(),
+        session_id: this.session_id,
+        message_id,
+        ...(current.turn_id ? { turn_id: current.turn_id } : {}),
+        revision: current.revision,
+        created_at: projected.updated_at,
+        part: structuredClone(part),
+      }),
+      projected,
+    );
   }
 
   /** 只在内存中追加文本、推理或 Tool 输入增量，并立即发布 delta。 */
@@ -83,7 +95,7 @@ export class SessionAgentMessageState {
     tool_call_id?: string,
   ): void {
     if (!delta) return;
-    const current = this.require_streaming_agent(message_id);
+    const current = this.require_writable_agent(message_id);
     let matched = false;
     const projected: SessionAgentMessage = {
       ...current,
@@ -109,25 +121,30 @@ export class SessionAgentMessageState {
       }),
     };
     if (!matched) throw new Error(`Delta target Part does not exist: ${part_id}`);
-    this.options.project_mutation({
+    const base = {
       mutation_id: generate_id(),
-      variant: "delta",
-      type,
+      variant: "delta" as const,
       message_id,
+      ...(current.turn_id ? { turn_id: current.turn_id } : {}),
       revision: current.revision,
       session_id: this.session_id,
-      ...(current.turn_id ? { turn_id: current.turn_id } : {}),
       created_at: projected.updated_at,
       part_id,
-      ...(tool_call_id ? { tool_call_id } : {}),
       delta,
-    } as SessionMutation, projected);
+    };
+    const tool_input_id = type === "tool_input" ? String(tool_call_id || "").trim() : "";
+    this.options.cache.project(
+      type === "tool_input"
+        ? { ...base, type, tool_call_id: tool_input_id }
+        : { ...base, type },
+      projected,
+    );
   }
 
   /** 将当前内存投影作为一个稳定语义检查点原子提交。 */
   async checkpoint(message_id: string): Promise<void> {
     await this.enqueue_write(message_id, async () => {
-      const current = this.require_streaming_agent(message_id);
+      const current = this.require_writable_agent(message_id);
       await this.persist_snapshot(message_id, current.parts);
     });
   }
@@ -138,7 +155,7 @@ export class SessionAgentMessageState {
     parts: SessionAgentMessagePart[],
   ): Promise<void> {
     await this.enqueue_write(message_id, async () => {
-      const current = this.require_streaming_agent(message_id);
+      const current = this.require_writable_agent(message_id);
       if (
         parts.length !== current.parts.length ||
         parts.some((part, index) =>
@@ -152,14 +169,20 @@ export class SessionAgentMessageState {
     });
   }
 
-  /** 原子追加一组非流式 Agent Parts。 */
+  /**
+   * 原子追加或替换一组非流式 Agent Parts。
+   *
+   * 同 part_id 已存在时原地替换并保留原 sequence；不存在时追加到 Message 末尾。
+   * options.publish_mutation 为 false 时只更新 canonical 快照而不发布 Mutation。
+   */
   async commit_parts(
     message_id: string,
     parts: readonly SessionAgentMessagePart[],
+    options?: { publish_mutation?: boolean },
   ): Promise<void> {
     if (parts.length === 0) return;
     await this.enqueue_write(message_id, async () => {
-      const current = this.require_streaming_agent(message_id);
+      const current = this.require_writable_agent(message_id);
       const replacements = new Map(parts.map((part) => [part.part_id, structuredClone(part)]));
       const existing_ids = new Set(current.parts.map((part) => part.part_id));
       const merged = current.parts.map((part) => replacements.get(part.part_id) ?? part);
@@ -169,6 +192,7 @@ export class SessionAgentMessageState {
       await this.persist_snapshot(
         message_id,
         merged.sort((left, right) => left.sequence - right.sequence),
+        { publish_mutation: options?.publish_mutation !== false },
       );
     });
   }
@@ -180,7 +204,7 @@ export class SessionAgentMessageState {
       if (!persisted || persisted.role !== "agent") {
         throw new Error(`Persisted Agent Message not found: ${message_id}`);
       }
-      this.options.accept_message(persisted);
+      this.options.cache.accept(persisted);
     });
   }
 
@@ -190,17 +214,11 @@ export class SessionAgentMessageState {
     outcome: "completed" | "stopped" | "failed",
     error?: string,
   ): Promise<void> {
+    // 先释放持有，收口提交才能把 Message 收敛为终态。
+    this.options.cache.release_held(message_id);
     await this.enqueue_write(message_id, async () => {
-      const current = this.require_streaming_agent(message_id);
+      const current = this.require_writable_agent(message_id);
       const completed_at = Date.now();
-      const interrupted_tool_ids = new Set(
-        current.parts.flatMap((part) =>
-          part.type === "interaction" && part.status === "pending" &&
-            part.request.source.tool_call_id
-            ? [part.request.source.tool_call_id]
-            : [],
-        ),
-      );
       const parts: SessionAgentMessagePart[] = current.parts.map((part) => {
         if (part.type === "text" || part.type === "reasoning") {
           return { ...part, state: "done" as const };
@@ -214,25 +232,36 @@ export class SessionAgentMessageState {
               : { description: error || "Action did not complete before Agent Message closed" }),
           };
         }
-        if (part.type === "interaction" && part.status === "pending") {
-          return {
-            ...part,
-            status: "cancelled" as const,
-            cancel_reason: "runtime_interrupted" as const,
-            resolved_at: completed_at,
-          };
+        if (part.type !== "tool") return part;
+        // Interaction 属于 Tool，收口时随所属 Tool 一起终止。
+        const existing_interactions = part.interactions ?? [];
+        const had_pending_interaction = existing_interactions.some(
+          (interaction) => interaction.status === "pending",
+        );
+        const interactions = had_pending_interaction
+          ? existing_interactions.map((interaction) =>
+              interaction.status === "pending"
+                ? {
+                    ...interaction,
+                    status: "cancelled" as const,
+                    cancel_reason: "runtime_interrupted" as const,
+                    resolved_at: completed_at,
+                  }
+                : interaction,
+            )
+          : part.interactions;
+        if (part.state === "completed" || part.state === "failed") {
+          return had_pending_interaction ? { ...part, interactions } : part;
         }
-        if (part.type === "tool" && part.state !== "completed" && part.state !== "failed") {
-          return {
-            ...part,
-            state: "failed" as const,
-            error: outcome === "stopped" && part.state === "waiting-user" &&
-                interrupted_tool_ids.has(part.tool_call_id)
-              ? "Interaction cancelled"
-              : error || "Tool did not complete before Agent Message closed",
-          };
-        }
-        return part;
+        return {
+          ...part,
+          state: "failed" as const,
+          interactions,
+          error: outcome === "stopped" && part.state === "waiting-user" &&
+              had_pending_interaction
+            ? "Interaction cancelled"
+            : error || "Tool did not complete before Agent Message closed",
+        };
       });
       if (outcome === "stopped" && !parts.some((part) =>
         part.type === "error" && part.code === "turn_stopped"
@@ -241,14 +270,14 @@ export class SessionAgentMessageState {
       } else if (outcome === "failed" && error && !parts.some((part) => part.type === "error")) {
         parts.push(create_terminal_error_part(parts, "turn_execution_failed", error));
       }
-      await this.persist_snapshot(message_id, parts, "done");
+      await this.persist_snapshot(message_id, parts, { held_by_writer: false });
     });
   }
 
-  /** 读取当前流式 Agent Message 中的指定 Tool Part。 */
-  find_streaming_tool(tool_call_id: string): SessionStreamingToolLocation | undefined {
-    for (const message of this.options.list_messages()) {
-      if (message.role !== "agent" || message.state !== "streaming") continue;
+  /** 读取当前可写 Agent Message 中的指定 Tool Part。 */
+  find_tool_in_open_message(tool_call_id: string): SessionOpenMessageToolLocation | undefined {
+    for (const message of this.options.cache.all()) {
+      if (message.role !== "agent") continue;
       const part = message.parts.find(
         (item): item is SessionAgentToolPart =>
           item.type === "tool" && item.tool_call_id === tool_call_id,
@@ -258,59 +287,166 @@ export class SessionAgentMessageState {
     return undefined;
   }
 
-  /** 返回当前 Session 全部待响应 Interaction。 */
-  list_pending_interactions(): SessionAgentInteractionPart[] {
-    return this.interaction_writer.list_pending();
+  /** 返回当前 Session 中全部等待用户响应的 Interaction。 */
+  list_pending_interactions(): SessionAgentInteraction[] {
+    return [...this.options.cache.all()].flatMap((message) =>
+      message.role === "agent"
+        ? message.parts.flatMap((part) =>
+            part.type === "tool"
+              ? (part.interactions ?? []).flatMap((interaction) =>
+                  interaction.status === "pending"
+                    ? [structuredClone(interaction)]
+                    : [],
+                )
+              : [],
+          )
+        : [],
+    );
   }
 
-  /** 持久化 Interaction 请求及关联 Tool 状态。 */
+  /**
+   * 原子创建 Interaction，并把所属 Tool 转为 waiting-user。
+   *
+   * Interaction 是 Tool Part 的从属数据：Tool 在等待响应时阻塞，因此两者的转换
+   * 必须在同一次快照提交内完成，否则会出现“Interaction pending 但 Tool 未等待”的中间态。
+   */
   async request_interaction(
     request: SessionInteractionRequest,
-  ): Promise<SessionAgentInteractionPart> {
-    return await this.interaction_writer.request(request);
+  ): Promise<SessionAgentInteraction> {
+    const tool_call_id = request.source.tool_call_id;
+    await this.run_interaction_write(tool_call_id, async (current, owner) => {
+      if (
+        (owner.interactions ?? []).some(
+          (item) => item.interaction_id === request.interaction_id,
+        )
+      ) {
+        throw new Error(
+          `Session Interaction already exists: ${request.interaction_id}`,
+        );
+      }
+      if (owner.state !== "ready" && owner.state !== "waiting-user") {
+        throw new Error(
+          `Tool Interaction requires ready input: ${tool_call_id} (${owner.state})`,
+        );
+      }
+      const interaction: SessionAgentInteraction = {
+        interaction_id: request.interaction_id,
+        interaction_type: request.type,
+        status: "pending",
+        request: structuredClone(request),
+      };
+      await this.persist_snapshot(
+        current.message_id,
+        replace_tool_part(current.parts, {
+          ...owner,
+          state: "waiting-user",
+          interactions: [...(owner.interactions ?? []), interaction],
+        }),
+      );
+    });
+    return this.require_pending_interaction(request.interaction_id).interaction;
   }
 
-  /** 持久化 Interaction 响应及关联 Tool 状态。 */
+  /** 原子保存用户响应，并按 Interaction 结果恢复或终止所属 Tool。 */
   async resolve_interaction(
     interaction_id: string,
     response: SessionInteractionResponse,
-  ): Promise<SessionAgentInteractionPart> {
-    return await this.interaction_writer.resolve(interaction_id, response);
+  ): Promise<SessionAgentInteraction> {
+    const location = this.require_pending_interaction(interaction_id);
+    if (location.interaction.interaction_type !== response.type) {
+      throw new Error(`Session Interaction response type mismatch: ${interaction_id}`);
+    }
+    await this.enqueue_write(location.message_id, async () => {
+      const current = this.require_writable_agent(location.message_id);
+      const owner = require_tool_part_in(current, location.tool.part_id);
+      if (owner.state !== "waiting-user") {
+        throw new Error(
+          `Tool is not waiting for Interaction: ${owner.tool_call_id} (${owner.state})`,
+        );
+      }
+      const denied = response.outcome === "denied";
+      await this.persist_snapshot(
+        current.message_id,
+        replace_tool_part(current.parts, {
+          ...owner,
+          state: denied ? "failed" : "running",
+          ...(denied ? { error: "Interaction denied" } : {}),
+          interactions: update_tool_interaction(owner, interaction_id, (item) => ({
+            ...item,
+            status: denied ? "denied" : "resolved",
+            response: structuredClone(response),
+            resolved_at: Date.now(),
+          })),
+        }),
+      );
+    });
+    return this.require_interaction(interaction_id).interaction;
   }
 
-  /** 持久化 Interaction 关闭及关联 Tool 状态。 */
+  /** 原子结束未响应 Interaction，并把所属 Tool 标记为失败。 */
   async close_interaction(
     interaction_id: string,
     input: SessionInteractionCloseInput,
-  ): Promise<SessionAgentInteractionPart> {
-    return await this.interaction_writer.close(interaction_id, input);
+  ): Promise<SessionAgentInteraction> {
+    const location = this.require_pending_interaction(interaction_id);
+    await this.enqueue_write(location.message_id, async () => {
+      const current = this.require_writable_agent(location.message_id);
+      const owner = require_tool_part_in(current, location.tool.part_id);
+      await this.persist_snapshot(
+        current.message_id,
+        replace_tool_part(current.parts, {
+          ...owner,
+          ...(owner.state === "waiting-user"
+            ? { state: "failed" as const, error: "Interaction cancelled" }
+            : {}),
+          interactions: update_tool_interaction(owner, interaction_id, (item) => ({
+            ...item,
+            status: "cancelled",
+            resolved_at: Date.now(),
+            cancel_reason: input.reason,
+          })),
+        }),
+      );
+    });
+    return this.require_interaction(interaction_id).interaction;
   }
 
   /** 原子保存完整 Message 快照；变更比较以数据库事实而非运行投影为准。 */
   private async persist_snapshot(
     message_id: string,
     parts: SessionAgentMessagePart[],
-    state: SessionAgentMessage["state"] = "streaming",
+    options?: {
+      /** 本次提交后是否仍由 writer 持有；收口时传 false。省略时读取当前持有关系。 */
+      held_by_writer?: boolean;
+      /** 是否向订阅方发布 Message Mutation。 */
+      publish_mutation?: boolean;
+    },
   ): Promise<void> {
     const persisted = await this.options.store.read_message(message_id);
-    if (!persisted || persisted.role !== "agent" || persisted.state !== "streaming") {
-      throw new Error(`Persisted streaming Agent Message not found: ${message_id}`);
+    if (!persisted || persisted.role !== "agent") {
+      throw new Error(`Agent Message not found: ${message_id}`);
     }
     const committed_at = Date.now();
+    const next_parts = structuredClone(parts).sort(
+      (left, right) => left.sequence - right.sequence,
+    );
     const message: SessionAgentMessage = {
       ...persisted,
-      state,
+      state: resolve_session_message_state(
+        next_parts,
+        options?.held_by_writer ?? this.options.cache.is_held(message_id),
+      ),
       revision: persisted.revision + 1,
       updated_at: committed_at,
-      parts: structuredClone(parts).sort((left, right) => left.sequence - right.sequence),
+      parts: next_parts,
     };
-    const changed_parts = resolve_changed_parts(persisted.parts, message.parts);
+    const changed_parts = resolve_changed_agent_parts(persisted.parts, message.parts);
     await this.options.store.update_message({
       message,
       expected_revision: persisted.revision,
       changed_parts,
     });
-    this.options.accept_message(message);
+    this.options.cache.accept(message, options?.publish_mutation !== false);
   }
 
   /** 串行执行同一 Message 的语义检查点。 */
@@ -329,21 +465,111 @@ export class SessionAgentMessageState {
     }
   }
 
-  /** 读取当前运行投影中的可写 Agent Message。 */
-  private require_streaming_agent(message_id: string): SessionAgentMessage {
-    const message = [...this.options.list_messages()].find(
+  /**
+   * 在所属 Tool 的串行写链内执行一次 Interaction 变更。
+   *
+   * Interaction 与 Tool 必须整体提交：先定位 Tool，再在同一串行段内读取最新快照并替换它，
+   * 避免两个并发响应基于过期快照各自提交。
+   */
+  private async run_interaction_write(
+    tool_call_id: string,
+    operation: (
+      current: SessionAgentMessage,
+      owner: SessionAgentToolPart,
+    ) => Promise<void>,
+  ): Promise<void> {
+    const located = this.find_tool_in_open_message(tool_call_id);
+    if (!located) throw new Error(`Open Tool Part not found: ${tool_call_id}`);
+    await this.enqueue_write(located.message_id, async () => {
+      const current = this.require_writable_agent(located.message_id);
+      const owner = require_tool_part_in(current, located.part.part_id);
+      await operation(current, owner);
+    });
+  }
+
+  /** 查找指定 Interaction 及其所属 Tool 与 Message。 */
+  private find_interaction(
+    interaction_id: string,
+  ): SessionInteractionLocation | undefined {
+    for (const message of this.options.cache.all()) {
+      if (message.role !== "agent") continue;
+      for (const part of message.parts) {
+        if (part.type !== "tool") continue;
+        const interaction = (part.interactions ?? []).find(
+          (item) => item.interaction_id === interaction_id,
+        );
+        if (interaction) {
+          return { message_id: message.message_id, tool: part, interaction };
+        }
+      }
+    }
+    return undefined;
+  }
+
+  /** 读取指定 Interaction，否则抛出稳定领域错误。 */
+  private require_interaction(interaction_id: string): SessionInteractionLocation {
+    const interaction = this.find_interaction(interaction_id);
+    if (interaction) return interaction;
+    throw new Error(`Session Interaction not found: ${interaction_id}`);
+  }
+
+  /** 读取指定 pending Interaction，否则拒绝重复响应终态 Interaction。 */
+  private require_pending_interaction(
+    interaction_id: string,
+  ): SessionInteractionLocation {
+    const interaction = this.require_interaction(interaction_id);
+    if (interaction.interaction.status !== "pending") {
+      throw new Error(
+        `Session Interaction is already ${interaction.interaction.status}: ${interaction_id}`,
+      );
+    }
+    return interaction;
+  }
+
+  /** 读取当前运行投影中的可写 Agent Message；只有 writer 持有的消息可写。 */
+  private require_writable_agent(message_id: string): SessionAgentMessage {
+    const message = [...this.options.cache.all()].find(
       (item) => item.message_id === message_id,
     );
     if (!message || message.role !== "agent") {
-      throw new Error(`Agent Message not found: ${message_id}`);
-    }
-    if (message.state !== "streaming") {
-      throw new Error(`Agent Message is already done: ${message_id}`);
+      throw new Error(`Writable Agent Message not found: ${message_id}`);
     }
     return message;
   }
 }
 
+/** 以新的 Tool Part 替换同 part_id 的旧值，其余 Part 保持原引用。 */
+function replace_tool_part(
+  parts: readonly SessionAgentMessagePart[],
+  tool: SessionAgentToolPart,
+): SessionAgentMessagePart[] {
+  return parts.map((part) => (part.part_id === tool.part_id ? tool : part));
+}
+
+/** 读取指定 Message 中的 Tool Part，否则抛出稳定领域错误。 */
+function require_tool_part_in(
+  message: SessionAgentMessage,
+  part_id: string,
+): SessionAgentToolPart {
+  const tool = message.parts.find(
+    (part): part is SessionAgentToolPart =>
+      part.type === "tool" && part.part_id === part_id,
+  );
+  if (!tool) throw new Error(`Open Tool Part not found: ${part_id}`);
+  return tool;
+}
+
+/** 就地替换 Tool 内指定 Interaction，丢弃不存在的历史来源。 */
+function update_tool_interaction(
+  tool: SessionAgentToolPart,
+  interaction_id: string,
+  update: (interaction: SessionAgentInteraction) => SessionAgentInteraction,
+): SessionAgentInteraction[] {
+  return (tool.interactions ?? []).map((item) =>
+    item.interaction_id === interaction_id ? update(item) : item,
+  );
+}
+
 /** 为 Message 终止原因创建最后一个 Error Part。 */
 function create_terminal_error_part(
   parts: readonly SessionAgentMessagePart[],
@@ -352,10 +578,7 @@ function create_terminal_error_part(
 ): SessionAgentErrorPart {
   return {
     part_id: `error:${generate_id()}`,
-    sequence: parts.reduce(
-      (sequence, part) => Math.max(sequence, part.sequence + 1),
-      1,
-    ),
+    sequence: next_agent_part_sequence(parts),
     type: "error",
     scope: "turn",
     code,
@@ -364,15 +587,3 @@ function create_terminal_error_part(
   };
 }
 
-/** 返回相较上次稳定检查点新增或变化的 Parts。 */
-function resolve_changed_parts(
-  current_parts: readonly SessionAgentMessagePart[],
-  next_parts: readonly SessionAgentMessagePart[],
-): SessionAgentMessagePart[] {
-  const current_by_id = new Map(
-    current_parts.map((part) => [part.part_id, JSON.stringify(part)]),
-  );
-  return next_parts.filter(
-    (part) => current_by_id.get(part.part_id) !== JSON.stringify(part),
-  );
-}