@downcity/agent 1.1.287 → 1.1.310

package/src/session/SessionMessages.ts

@@ -7,14 +7,15 @@
  */
 
 import type { UIMessage } from "ai";
-import { generateId } from "@/utils/Id.js";
+import { generate_id } from "@/utils/Id.js";
 import { SessionAssistantMessageWriter } from "@/session/messages/SessionAssistantMessageWriter.js";
+import { SessionMessageInteractionWriter } from "@/session/messages/SessionMessageInteractionWriter.js";
 import { to_session_json_value } from "@/session/messages/SessionJsonValue.js";
-import { JsonlSessionMessageStore } from "@/session/messages/JsonlSessionMessageStore.js";
 import type { JsonObject } from "@/types/common/Json.js";
 import type {
   ListSessionMessagesInput,
   SessionActionMessage,
+  SessionAssistantInteractionPart,
   SessionAssistantMessage,
   SessionAssistantMessagePart,
   SessionAssistantToolPart,
@@ -34,7 +35,10 @@ import type {
   SessionSegmentSummary,
 } from "@/types/session/SessionSegment.js";
 import type { SessionStreamingToolLocation } from "@/types/session/SessionTool.js";
-import type { SessionApproval } from "@/types/session/SessionApproval.js";
+import type {
+  SessionInteractionRequest,
+  SessionInteractionResponse,
+} from "@/types/session/SessionInteraction.js";
 import type {
   SessionActionRecordV1,
   SessionRecordV1,
@@ -46,7 +50,7 @@ import {
   from_ui_user_parts,
   to_executor_ui_message,
 } from "@/session/messages/SessionMessageCodec.js";
-import { hydrateUserPromptFileParts } from "@executor/messages/SessionAttachmentMapper.js";
+import { hydrate_user_prompt_file_parts } from "@executor/messages/SessionAttachmentMapper.js";
 import type {
   AppendCompletedAssistantMessageInput,
   AppendExternalSessionAssistantMessageInput,
@@ -58,17 +62,20 @@ import type {
   OpenSessionAssistantMessageInput,
   SessionMessagesOptions,
 } from "@/types/session/SessionMessages.js";
+import type { SessionMessageStore } from "@/types/store/SessionStore.js";
 
 export { SessionAssistantMessageWriter } from "@/session/messages/SessionAssistantMessageWriter.js";
 
 /** 唯一 Session Message 写入服务。 */
 export class SessionMessages {
   readonly session_id: string;
-  private readonly store: JsonlSessionMessageStore;
+  private readonly store: SessionMessageStore;
   private readonly publish: SessionMessagesOptions["publish"];
   private readonly messages_by_id = new Map<string, SessionMessage>();
   /** 按 Assistant Message 隔离的完整写事务链。 */
   private readonly assistant_write_chains = new Map<string, Promise<void>>();
+  /** Assistant Message 内 Interaction Part 的原子状态写入器。 */
+  private readonly interaction_writer: SessionMessageInteractionWriter;
   private initialized = false;
 
   constructor(options: SessionMessagesOptions) {
@@ -76,6 +83,14 @@ export class SessionMessages {
     this.store = options.store;
     this.publish = options.publish;
     if (!this.session_id) throw new Error("SessionMessages requires session_id");
+    this.interaction_writer = new SessionMessageInteractionWriter({
+      list_messages: () => this.messages_by_id.values(),
+      find_streaming_tool: (tool_call_id) => this.find_streaming_tool(tool_call_id),
+      enqueue_assistant_write: (message_id, operation) =>
+        this.enqueue_assistant_write(message_id, operation),
+      commit_assistant_snapshot: (current, parts) =>
+        this.commit_assistant_snapshot(current, parts),
+    });
   }
 
   /** 恢复已有 Message，并收口进程中断遗留的运行状态。 */
@@ -111,7 +126,7 @@ export class SessionMessages {
     const message = await this.create_message((sequence, created_at) => ({
       message_id:
         String(input.message_id || "").trim() ||
-        `user:${this.session_id}:${generateId()}`,
+        `user:${this.session_id}:${generate_id()}`,
       session_id: this.session_id,
       turn_id: input.turn_id,
       sequence,
@@ -126,14 +141,14 @@ export class SessionMessages {
     return message as SessionUserMessage;
   }
 
-  /** 创建可持续接收 chunk 的 Assistant segment。 */
+  /** 创建可持续接收 chunk 的 Assistant Message。 */
   async open_assistant_message(
     input: OpenSessionAssistantMessageInput,
   ): Promise<SessionAssistantMessageWriter> {
     const message = (await this.create_message((sequence, created_at) => ({
       message_id:
         String(input.message_id || "").trim() ||
-        `assistant:${this.session_id}:${generateId()}`,
+        `assistant:${this.session_id}:${generate_id()}`,
       session_id: this.session_id,
       turn_id: input.turn_id,
       sequence,
@@ -143,7 +158,6 @@ export class SessionMessages {
       updated_at: created_at,
       type: "assistant",
       kind: input.kind || "normal",
-      segment_index: input.segment_index,
       status: "streaming",
       parts: [],
       ...(input.summary_through_message_id
@@ -157,10 +171,9 @@ export class SessionMessages {
   async append_completed_assistant_message(
     input: AppendCompletedAssistantMessageInput,
   ): Promise<SessionAssistantMessage> {
-    const turn_id = input.turn_id || `external:${this.session_id}:${generateId()}`;
+    const turn_id = input.turn_id || `external:${this.session_id}:${generate_id()}`;
     const writer = await this.open_assistant_message({
       turn_id,
-      segment_index: 1,
       kind: input.kind || "normal",
       visibility: input.visibility || "visible",
       ...(input.summary_through_message_id
@@ -188,7 +201,7 @@ export class SessionMessages {
       }
       const writer = await this.open_action_message({
         message_id: action.id,
-        turn_id: action.metadata.turnId,
+        turn_id: action.metadata.turn_id,
         action_type: String(action.id || "").split(":")[0] || "action",
         title: action.title,
         description: action.description,
@@ -201,7 +214,7 @@ export class SessionMessages {
     }
 
     const turn_id = String(
-      record.metadata?.turnId || `external:${this.session_id}:${generateId()}`,
+      record.metadata?.turn_id || `external:${this.session_id}:${generate_id()}`,
     );
     if (record.role === "user") {
       await this.append_user_message({
@@ -269,7 +282,7 @@ export class SessionMessages {
     const query = input.prompt.query;
     const ui_parts = typeof query === "string"
       ? [{ type: "text" as const, text: query.trim() }]
-      : await hydrateUserPromptFileParts(
+      : await hydrate_user_prompt_file_parts(
           Array.isArray(query) ? query : [],
           input.project_root,
         );
@@ -291,7 +304,7 @@ export class SessionMessages {
     for (const message of messages) {
       await this.append_user_message({
         turn_id: String(
-          message.metadata?.turnId ||
+          message.metadata?.turn_id ||
             `deferred:${this.session_id}:${Date.now()}`,
         ),
         input_type: "steer",
@@ -307,7 +320,7 @@ export class SessionMessages {
     if (!existing) {
       const writer = await this.open_action_message({
         message_id: event.id,
-        turn_id: event.metadata.turnId,
+        turn_id: event.metadata.turn_id,
         action_type: infer_action_type(event.id),
         title: event.title,
         description: event.description,
@@ -333,7 +346,7 @@ export class SessionMessages {
     const message = (await this.create_message((sequence, created_at) => ({
       message_id:
         String(input.message_id || "").trim() ||
-        `action:${this.session_id}:${generateId()}`,
+        `action:${this.session_id}:${generate_id()}`,
       session_id: this.session_id,
       ...(input.turn_id ? { turn_id: input.turn_id } : {}),
       sequence,
@@ -381,7 +394,7 @@ export class SessionMessages {
     input: AppendSessionErrorMessageInput,
   ): Promise<SessionErrorMessage> {
     return (await this.create_message((sequence, created_at) => ({
-      message_id: `error:${this.session_id}:${generateId()}`,
+      message_id: `error:${this.session_id}:${generate_id()}`,
       session_id: this.session_id,
       ...(input.turn_id ? { turn_id: input.turn_id } : {}),
       sequence,
@@ -550,7 +563,7 @@ export class SessionMessages {
     };
     await this.store.write_assistant_message(message);
     this.accept_mutation({
-      mutation_id: generateId(),
+      mutation_id: generate_id(),
       variant: "delta",
       type,
       message_id,
@@ -597,7 +610,7 @@ export class SessionMessages {
     };
     await this.store.write_assistant_message(message);
     this.accept_mutation({
-      mutation_id: generateId(),
+      mutation_id: generate_id(),
       variant: "part",
       type: next_part.type,
       message_id,
@@ -659,16 +672,49 @@ export class SessionMessages {
     const current = require_message([...this.messages_by_id.values()], message_id, "assistant");
     require_streaming_assistant(current);
     const created_at = Date.now();
+    const interrupted_interactions = status === "stopped"
+      ? current.parts.filter(
+          (part): part is SessionAssistantInteractionPart =>
+            part.type === "interaction" && part.status === "pending",
+        )
+      : [];
+    const interrupted_tool_ids = new Set(
+      interrupted_interactions.flatMap((part) =>
+        part.request.source.type === "tool"
+          ? [part.request.source.tool_call_id]
+          : [],
+      ),
+    );
     const message: SessionAssistantMessage = {
       ...current,
       revision: current.revision + 1,
       status,
       updated_at: created_at,
-      parts: current.parts.map((part) =>
-        part.type === "text" || part.type === "reasoning"
-          ? { ...part, state: "done" as const }
-          : part,
-      ),
+      parts: current.parts.map((part) => {
+        if (part.type === "text" || part.type === "reasoning") {
+          return { ...part, state: "done" as const };
+        }
+        if (part.type === "interaction" && part.status === "pending") {
+          return {
+            ...part,
+            status: "cancelled" as const,
+            cancel_reason: "runtime_interrupted" as const,
+            resolved_at: created_at,
+          };
+        }
+        if (
+          part.type === "tool" &&
+          part.state === "waiting-user" &&
+          interrupted_tool_ids.has(part.tool_call_id)
+        ) {
+          return {
+            ...part,
+            state: "failed" as const,
+            error: "Interaction cancelled",
+          };
+        }
+        return part;
+      }),
     };
     await this.store.finalize_assistant_message(message);
     this.accept_message(message);
@@ -710,71 +756,37 @@ export class SessionMessages {
     return undefined;
   }
 
-  /** 把完整审批请求写入对应的流式 Tool Part。 */
-  async request_tool_approval(approval: SessionApproval): Promise<void> {
-    const { message_id } = this.require_streaming_tool(approval.tool_call_id);
-    await this.enqueue_assistant_write(message_id, async () => {
-      const tool = this.require_streaming_tool(approval.tool_call_id);
-      if (tool.message_id !== message_id) {
-        throw new Error(`Tool Assistant Message changed: ${approval.tool_call_id}`);
-      }
-      if (tool.part.state !== "ready") {
-        throw new Error(
-          `Tool approval requires ready input: ${approval.tool_call_id} (${tool.part.state})`,
-        );
-      }
-      await this.update_assistant_part_serialized(message_id, {
-        ...tool.part,
-        state: "approval-required",
-        approval: {
-          approval_id: approval.approval_id,
-          request: approval,
-        },
-      });
-    });
+  /** 返回当前 Session 中全部等待用户响应的 canonical Interaction。 */
+  list_pending_interactions(): SessionAssistantInteractionPart[] {
+    return this.interaction_writer.list_pending();
   }
 
-  /** 在 Tool 恢复执行前提交审批决定对应的 Part 状态。 */
-  async resolve_tool_approval(input: {
-    /** 当前审批请求标识。 */
-    approval_id: string;
-    /** 当前审批最终决定。 */
-    decision: "approved" | "denied" | "expired";
-    /** 当前审批关联的 Tool Call。 */
-    tool_call_id: string;
-  }): Promise<void> {
-    const { message_id } = this.require_streaming_tool(input.tool_call_id);
-    await this.enqueue_assistant_write(message_id, async () => {
-      const tool = this.require_streaming_tool(input.tool_call_id);
-      if (tool.message_id !== message_id) {
-        throw new Error(`Tool Assistant Message changed: ${input.tool_call_id}`);
-      }
-      if (tool.part.approval?.approval_id !== input.approval_id) {
-        throw new Error(`Tool approval identity mismatch: ${input.approval_id}`);
-      }
-      await this.update_assistant_part_serialized(message_id, {
-        ...tool.part,
-        state: input.decision === "approved" ? "running" : "failed",
-        approval: {
-          ...tool.part.approval,
-          approval_id: input.approval_id,
-          approved: input.decision === "approved",
-          ...(input.decision === "expired"
-            ? { reason: "Approval expired" }
-            : input.decision === "denied"
-              ? { reason: "Approval denied" }
-              : {}),
+  /** 原子创建 Interaction，并把关联 Tool 转为 waiting-user。 */
+  async request_interaction(
+    request: SessionInteractionRequest,
+  ): Promise<SessionAssistantInteractionPart> {
+    return this.interaction_writer.request(request);
+  }
+
+  /** 原子保存用户响应，并按 Interaction 结果恢复或终止关联 Tool。 */
+  async resolve_interaction(
+    interaction_id: string,
+    response: SessionInteractionResponse,
+  ): Promise<SessionAssistantInteractionPart> {
+    return this.interaction_writer.resolve(interaction_id, response);
+  }
+
+  /** 原子结束未响应 Interaction，并把关联 Tool 标记为失败。 */
+  async close_interaction(
+    interaction_id: string,
+    input:
+      | { status: "expired" }
+      | {
+          status: "cancelled";
+          reason: "turn_stopped" | "session_disposed" | "runtime_interrupted";
         },
-        ...(input.decision === "approved"
-          ? {}
-          : {
-              error:
-                input.decision === "expired"
-                  ? "Approval expired"
-                  : "Approval denied",
-            }),
-      });
-    });
+  ): Promise<SessionAssistantInteractionPart> {
+    return this.interaction_writer.close(interaction_id, input);
   }
 
   /**
@@ -799,18 +811,53 @@ export class SessionMessages {
     }
   }
 
-  /** 查找当前流式 Assistant 中的 Tool Part，否则抛出明确错误。 */
-  private require_streaming_tool(tool_call_id: string): SessionStreamingToolLocation {
-    const tool = this.find_streaming_tool(tool_call_id);
-    if (tool) return tool;
-    throw new Error(`Streaming Tool Part not found: ${tool_call_id}`);
+  /** 原子提交包含多个 Part 状态变化的 Assistant 完整快照。 */
+  private async commit_assistant_snapshot(
+    current: SessionAssistantMessage,
+    parts: SessionAssistantMessagePart[],
+  ): Promise<void> {
+    const created_at = Date.now();
+    const message: SessionAssistantMessage = {
+      ...current,
+      revision: current.revision + 1,
+      updated_at: created_at,
+      parts: structuredClone(parts).sort(
+        (left, right) => left.sequence - right.sequence,
+      ),
+    };
+    await this.store.write_assistant_message(message);
+    const current_by_id = new Map(
+      current.parts.map((part) => [part.part_id, part]),
+    );
+    const changed_parts = message.parts.filter((part) => {
+      const previous = current_by_id.get(part.part_id);
+      return !previous || JSON.stringify(previous) !== JSON.stringify(part);
+    });
+    if (changed_parts.length === 0) {
+      this.accept_message(message);
+      return;
+    }
+    for (const part of changed_parts) {
+      this.accept_mutation({
+        mutation_id: generate_id(),
+        variant: "part",
+        type: part.type,
+        message_id: message.message_id,
+        revision: message.revision,
+        session_id: this.session_id,
+        turn_id: message.turn_id,
+        created_at,
+        part_id: part.part_id,
+        part: structuredClone(part),
+      } as SessionMutation, message);
+    }
   }
 
   private build_message_mutation(
     message: SessionMessage,
   ): SessionMessageSnapshotMutation {
     return {
-      mutation_id: generateId(),
+      mutation_id: generate_id(),
       variant: "message",
       type: message.type,
       message_id: message.message_id,
@@ -929,7 +976,7 @@ function require_streaming_assistant(
 function resolve_import_id(map: Map<string, string>, source_id: string, prefix: string): string {
   const existing = map.get(source_id);
   if (existing) return existing;
-  const created = `${prefix}:${generateId()}`;
+  const created = `${prefix}:${generate_id()}`;
   map.set(source_id, created);
   return created;
 }

package/src/session/SessionQueue.ts

@@ -1,86 +1,53 @@
 /**
  * Session FIFO 输入队列。
  *
- * 只负责保存和按顺序取出 Prompt/Command，不执行命令，也不持有 active Turn。
+ * 只负责保存 SessionCommand 对象和维护顺序，不识别任何业务输入种类，
+ * 也不持有 active Turn。
  */
 
-import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
-import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
-import type {
-  SessionQueueCommand,
-  SessionQueueDeferred,
-  SessionQueueItem,
-  SessionQueuedPrompt,
-} from "@/types/session/SessionQueue.js";
+import { SessionCommand } from "@/session/SessionCommand.js";
 
 /** 单个 Session 的进程内 FIFO。 */
 export class SessionQueue {
-  private readonly items: SessionQueueItem[] = [];
+  private readonly commands: SessionCommand[] = [];
 
-  /** 追加 Prompt 并返回等待 Turn Handle 的 Promise。 */
-  enqueue_prompt(input: AgentSessionPromptInput): Promise<AgentSessionTurnHandle> {
-    const deferred_handle = create_deferred<AgentSessionTurnHandle>();
-    this.items.push({ type: "prompt", input, deferred_handle });
-    return deferred_handle.promise;
+  /** 追加一个可执行 Command 对象。 */
+  enqueue_command(command: SessionCommand): void {
+    this.commands.push(command);
   }
 
-  /** 追加明确的领域命令。 */
-  enqueue_command(command: SessionQueueCommand): void {
-    this.items.push(command);
-  }
-
-  /** 当前队列是否包含 Prompt。 */
-  has_prompt(): boolean {
-    return this.items.some((item) => item.type === "prompt");
-  }
-
-  /** 当前队列是否包含 Command。 */
+  /** 当前队列是否包含尚未执行的 Command。 */
   has_command(): boolean {
-    return this.items.some((item) => item.type !== "prompt");
+    return this.commands.length > 0;
   }
 
-  /** 取出第一条 Prompt，以及它之前按顺序排队的命令。 */
-  take_next_prompt(): {
-    /** 当前 Prompt 之前的命令。 */
-    commands: SessionQueueCommand[];
-    /** 当前等待执行的 Prompt。 */
-    prompt: SessionQueuedPrompt;
-  } | null {
-    const prompt_index = this.items.findIndex((item) => item.type === "prompt");
-    if (prompt_index < 0) return null;
-    const commands = this.items.splice(0, prompt_index) as SessionQueueCommand[];
-    const prompt = this.items.shift();
-    return prompt?.type === "prompt" ? { commands, prompt } : null;
+  /** 按 FIFO 取出下一条 Command。 */
+  take_next(): SessionCommand | undefined {
+    return this.commands.shift();
   }
 
-  /** 取出当前全部输入，供下一个 Step 检查点按顺序提交。 */
-  drain(): SessionQueueItem[] {
-    return this.items.splice(0, this.items.length);
+  /** 取出当前全部 Command，供下一个 Step 检查点按顺序执行。 */
+  drain(): SessionCommand[] {
+    return this.commands.splice(0, this.commands.length);
   }
 
-  /** 把尚未处理的输入恢复到队列头部。 */
-  restore_front(items: SessionQueueItem[]): void {
-    this.items.unshift(...items);
+  /** 把尚未处理的 Command 恢复到队列头部。 */
+  restore_front(commands: SessionCommand[]): void {
+    this.commands.unshift(...commands);
   }
 
-  /** 取消全部排队 Prompt，同时保留等待下一 Step 的命令。 */
-  cancel_prompts(): SessionQueuedPrompt[] {
-    const prompts = this.items.filter(
-      (item): item is SessionQueuedPrompt => item.type === "prompt",
-    );
-    const commands = this.items.filter(
-      (item): item is SessionQueueCommand => item.type !== "prompt",
-    );
-    this.items.splice(0, this.items.length, ...commands);
-    return prompts;
+  /** 调用 Command 自己的取消行为，并保留不可取消的 Command。 */
+  cancel(): number {
+    let cancelled_count = 0;
+    const retained_commands: SessionCommand[] = [];
+    for (const command of this.commands) {
+      if (command.cancel()) {
+        cancelled_count += 1;
+      } else {
+        retained_commands.push(command);
+      }
+    }
+    this.commands.splice(0, this.commands.length, ...retained_commands);
+    return cancelled_count;
   }
 }
-
-/** 创建最小 Promise 控制器。 */
-function create_deferred<T>(): SessionQueueDeferred<T> {
-  let resolve!: (value: T) => void;
-  const promise = new Promise<T>((next) => {
-    resolve = next;
-  });
-  return { promise, resolve };
-}