@downcity/agent 1.1.438 → 1.1.445

package/src/session/messages/SessionAgentMessageWriter.ts

@@ -2,11 +2,12 @@
  * 单个 canonical Assistant Message 的流式写入器。
  *
  * Writer 直接消费 Downcity `ModelStreamEvent`，并把模型内容、Tool 状态和 Action 内容
- * 串行写入 `SessionMessages`。它不理解 UI Message 或 Provider 私有事件。
+ * 串行写入 Agent Message 状态与运行缓存。它不理解 UI Message 或 Provider 私有事件。
  */
 
 import type { ModelStreamEvent } from "@downcity/type";
-import type { SessionMessages } from "@/session/SessionMessages.js";
+import type { SessionAgentMessageState } from "@/session/messages/SessionAgentMessageState.js";
+import type { SessionMessageCache } from "@/session/messages/SessionMessageCache.js";
 import { to_session_json_value } from "@/session/messages/SessionJsonValue.js";
 import { SessionToolPartGate } from "@/session/messages/SessionToolPartGate.js";
 import type { SessionAgentContent } from "@downcity/type";
@@ -22,13 +23,25 @@ import type {
 } from "@/types/session/SessionTool.js";
 import { generate_id } from "@/utils/Id.js";
 import { create_session_agent_content_part } from "@/session/messages/SessionAgentContent.js";
+import { next_agent_part_sequence } from "@/session/messages/SessionAgentParts.js";
+
+/** Writer 构造参数。 */
+export interface SessionAgentMessageWriterOptions {
+  /** 当前 canonical Assistant Message 标识。 */
+  message_id: string;
+  /** Agent Message 写入状态转换器。 */
+  state: SessionAgentMessageState;
+  /** Message 运行缓存。 */
+  cache: SessionMessageCache;
+}
 
 /** 单个 Assistant Message 的流式 Writer。 */
 export class SessionAgentMessageWriter {
   /** 当前 canonical Assistant Message 标识。 */
   readonly message_id: string;
 
-  private readonly recorder: SessionMessages;
+  private readonly state: SessionAgentMessageState;
+  private readonly cache: SessionMessageCache;
   private readonly content_part_ids = new Map<string, string>();
   private readonly tool_call_ids = new Map<string, string>();
   private readonly current_step_part_ids = new Set<string>();
@@ -39,9 +52,10 @@ export class SessionAgentMessageWriter {
   private step_active = false;
   private closed = false;
 
-  constructor(recorder: SessionMessages, message_id: string) {
-    this.recorder = recorder;
-    this.message_id = message_id;
+  constructor(options: SessionAgentMessageWriterOptions) {
+    this.state = options.state;
+    this.cache = options.cache;
+    this.message_id = options.message_id;
   }
 
   /** 建立一个独立模型 Step 的 canonical Part 作用域。 */
@@ -85,7 +99,7 @@ export class SessionAgentMessageWriter {
         state: "ready",
         input: to_session_json_value(input.input),
       });
-      await this.recorder.checkpoint_agent_message(this.message_id);
+      await this.state.checkpoint(this.message_id);
     });
   }
 
@@ -105,7 +119,7 @@ export class SessionAgentMessageWriter {
             state: "failed",
             error: read_tool_error(result.output),
           });
-      await this.recorder.checkpoint_agent_message(this.message_id);
+      await this.state.checkpoint(this.message_id);
     });
   }
 
@@ -121,7 +135,7 @@ export class SessionAgentMessageWriter {
       }
       const current = this.current_message();
       const current_parts = current.parts.filter((part) =>
-        this.current_step_part_ids.has(part.part_id) && part.type !== "interaction"
+        this.current_step_part_ids.has(part.part_id)
       );
       if (current_parts.length !== parts.length) {
         throw this.step_snapshot_error(
@@ -137,7 +151,7 @@ export class SessionAgentMessageWriter {
           this.merge_step_part(current_part, final_part, index),
         );
       }
-      await this.recorder.commit_agent_step(
+      await this.state.commit_step(
         this.message_id,
         current.parts.map((part) => merged_parts.get(part.part_id) ?? part),
       );
@@ -150,7 +164,7 @@ export class SessionAgentMessageWriter {
     await this.enqueue_write(async () => {
       this.tool_part_gate.reject_pending("Assistant canonical step was aborted");
       if (this.step_active) {
-        await this.recorder.rollback_agent_projection(this.message_id);
+        await this.state.rollback_projection(this.message_id);
         this.reset_step_state();
       }
     });
@@ -171,7 +185,7 @@ export class SessionAgentMessageWriter {
         appended_parts.push(canonical);
         sequence += 1;
       }
-      await this.recorder.commit_agent_parts(this.message_id, appended_parts);
+      await this.state.commit_parts(this.message_id, appended_parts);
       return appended_parts;
     });
   }
@@ -198,13 +212,13 @@ export class SessionAgentMessageWriter {
         message: input.message,
         recoverable: input.recoverable,
       } satisfies SessionAgentErrorPart;
-      await this.recorder.commit_agent_parts(this.message_id, [part]);
+      await this.state.commit_parts(this.message_id, [part]);
     });
   }
 
   /** 写入一个完整 canonical Assistant Part。 */
   async upsert_part(part: SessionAgentMessagePart): Promise<void> {
-    this.recorder.project_agent_part(this.message_id, part);
+    this.state.project_part(this.message_id, part);
     if (this.step_active) this.current_step_part_ids.add(part.part_id);
   }
 
@@ -254,7 +268,7 @@ export class SessionAgentMessageWriter {
       if (!event.delta) return;
       const type = event.type === "text_delta" ? "text" : "reasoning";
       const part_id = this.require_content_part_id(event.content_id);
-      this.recorder.project_agent_delta(
+      this.state.project_delta(
         this.message_id,
         part_id,
         type,
@@ -291,11 +305,12 @@ export class SessionAgentMessageWriter {
       if (!event.input_delta) return;
       const tool_call_id = this.require_tool_call_id(event.content_id);
       const tool = this.require_tool(tool_call_id);
-      this.recorder.project_agent_tool_input_delta(
+      this.state.project_delta(
         this.message_id,
         tool.part_id,
-        tool_call_id,
+        "tool_input",
         event.input_delta,
+        tool_call_id,
       );
       return;
     }
@@ -313,7 +328,7 @@ export class SessionAgentMessageWriter {
 
   /** 读取当前 Assistant Message 快照。 */
   private current_message(): SessionAgentMessage {
-    const message = this.recorder.get_message(this.message_id);
+    const message = this.cache.get(this.message_id);
     if (!message || message.role !== "agent") {
       throw new Error(`Assistant Message not found: ${this.message_id}`);
     }
@@ -389,27 +404,15 @@ export class SessionAgentMessageWriter {
         `part ${index + 1} type ${current_part.type} != ${final_part.type}`,
       );
     }
-    if (
-      (current_part.type === "text" || current_part.type === "reasoning") &&
-      (final_part.type === "text" || final_part.type === "reasoning") &&
-      current_part.text !== final_part.text
-    ) {
+    if (is_text_like(current_part) && is_text_like(final_part)
+      && current_part.text !== final_part.text) {
       throw this.step_snapshot_error(`part ${index + 1} text differs`);
     }
-    if (
-      current_part.type === "tool" &&
-      final_part.type === "tool" &&
-      current_part.tool_call_id !== final_part.tool_call_id
-    ) {
+    if (is_agent_part_type(current_part, "tool") && is_agent_part_type(final_part, "tool")
+      && current_part.tool_call_id !== final_part.tool_call_id) {
       throw this.step_snapshot_error(`part ${index + 1} tool_call_id differs`);
     }
-    return {
-      ...current_part,
-      ...final_part,
-      part_id: current_part.part_id,
-      sequence: current_part.sequence,
-      step_id: current_part.step_id,
-    } as SessionAgentMessagePart;
+    return merge_same_part(current_part, final_part);
   }
 
   /** 构造不包含正文与 Tool 输出的结构化 Step 快照错误。 */
@@ -436,10 +439,7 @@ export class SessionAgentMessageWriter {
 
   /** 计算下一个不可变 Part 顺序号。 */
   private next_part_sequence(): number {
-    return this.current_message().parts.reduce(
-      (sequence, part) => Math.max(sequence, part.sequence + 1),
-      1,
-    );
+    return next_agent_part_sequence(this.current_message().parts);
   }
 
   /** 串行执行对当前 Assistant Message 的全部写操作。 */
@@ -459,18 +459,55 @@ export class SessionAgentMessageWriter {
       `Assistant Message writer closed with status ${status}`,
     );
     this.reset_step_state();
-    await this.recorder.complete_agent_message(this.message_id, status, error);
+    await this.state.complete(this.message_id, status, error);
     this.closed = true;
   }
 }
 
+/** 文本与推理 Part 都携带可直接比较的正文。 */
+type TextLikeAgentPart = Extract<SessionAgentMessagePart, { type: "text" | "reasoning" }>;
+
+/** 判断 Part 是否属于指定类型。 */
+function is_agent_part_type<T extends SessionAgentMessagePart["type"]>(
+  part: SessionAgentMessagePart,
+  type: T,
+): part is Extract<SessionAgentMessagePart, { type: T }> {
+  return part.type === type;
+}
+
+/** 判断 Part 是否携带可直接比较的正文。 */
+function is_text_like(part: SessionAgentMessagePart): part is TextLikeAgentPart {
+  return part.type === "text" || part.type === "reasoning";
+}
+
+/** 合并同一类型的两个 Part，只保留当前快照的规范身份字段。 */
+function merge_same_part<T extends SessionAgentMessagePart["type"]>(
+  current: Extract<SessionAgentMessagePart, { type: T }>,
+  final: Extract<SessionAgentMessagePart, { type: T }>,
+): Extract<SessionAgentMessagePart, { type: T }> {
+  return {
+    ...current,
+    ...final,
+    part_id: current.part_id,
+    sequence: current.sequence,
+    step_id: current.step_id,
+  };
+}
+
 /** 从 Tool 失败输出中提取稳定错误文本。 */
 function read_tool_error(output: unknown): string {
-  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;
-    }
+  for (const candidate of read_tool_error_candidates(output)) {
+    if (typeof candidate === "string" && candidate.trim()) return candidate;
   }
   return "Tool execution failed";
 }
+
+/** 读取 Tool 失败输出中可能携带错误文本的字段。 */
+function read_tool_error_candidates(output: unknown): unknown[] {
+  if (typeof output !== "object" || output === null) return [];
+  return [
+    "error" in output ? output.error : undefined,
+    "message" in output ? output.message : undefined,
+    "output" in output ? output.output : undefined,
+  ];
+}

package/src/session/messages/SessionAgentParts.ts

@@ -0,0 +1,39 @@
+/**
+ * canonical Agent Message Part 的共享纯函数。
+ *
+ * Part 变更比较与顺序号计算在 Canonical Message、运行投影和流式 Writer 中含义完全一致，
+ * 只在本模块实现一次，避免同一表达式在多处漂移。
+ */
+
+import type { SessionAgentMessagePart } from "@downcity/type";
+
+/** 判断两个 Part 快照是否表示同一个 canonical 版本。 */
+export function is_same_agent_part(
+  left: SessionAgentMessagePart | undefined,
+  right: SessionAgentMessagePart,
+): boolean {
+  return left !== undefined && JSON.stringify(left) === JSON.stringify(right);
+}
+
+/** 返回相较上一稳定快照新增或载荷发生变化的 Parts。 */
+export function resolve_changed_agent_parts(
+  current: readonly SessionAgentMessagePart[],
+  next: readonly SessionAgentMessagePart[],
+): SessionAgentMessagePart[] {
+  const current_by_id = new Map(
+    current.map((part) => [part.part_id, part]),
+  );
+  return next.filter(
+    (part) => !is_same_agent_part(current_by_id.get(part.part_id), part),
+  );
+}
+
+/** 计算追加到 Agent Message 末尾的下一个 Part 顺序号。 */
+export function next_agent_part_sequence(
+  parts: readonly SessionAgentMessagePart[],
+): number {
+  return parts.reduce(
+    (sequence, part) => Math.max(sequence, part.sequence + 1),
+    1,
+  );
+}

package/src/session/{execution → messages}/SessionAssistantOutputAdapter.ts

@@ -9,10 +9,10 @@ import type { ModelStreamEvent } from "@downcity/type";
 import {
   SessionAgentMessageWriter,
   SessionMessages,
-} from "@/session/SessionMessages.js";
+} from "@/session/messages/SessionMessages.js";
 import type { SessionAgentContent } from "@downcity/type";
 import type { SessionAgentMessagePart } from "@downcity/type";
-import type { SessionAssistantOutput } from "@/types/executor/SessionAssistantOutput.js";
+import type { SessionAssistantOutput } from "@/types/turn/SessionAssistantOutput.js";
 import type {
   SessionToolExecutionResult,
   SessionToolInputReady,

package/src/session/messages/SessionInteractions.ts

@@ -0,0 +1,227 @@
+/**
+ * Session 用户异步交互运行时。
+ *
+ * 关键点（中文）
+ * - 本模块只拥有 pending waiter 与恢复执行；Interaction 的权威状态由 SessionMessages 持久化。
+ *   任何终态都必须先提交 canonical Message，再兑现等待 Promise。
+ * - 原语只认识信封与 type 字符串：payload 的解释属于它的生产者。
+ * - 审批的专用入口（模式判断与决定解释）由 {@link ApprovalInteraction} 承担。
+ *
+ * Interaction 没有超时：它只能由用户响应，或随所属 Turn/Session 结束而被取消。
+ */
+
+import type { SessionMessages } from "@/session/messages/SessionMessages.js";
+import { ApprovalInteraction } from "@/session/messages/ApprovalInteraction.js";
+import type {
+  RespondSessionInteractionInput,
+  SessionApprovalMode,
+  SessionInteractionHandle,
+  SessionInteractionLifecycle,
+  SessionInteractionPort,
+  SessionInteractionRequest,
+  SessionInteractionRequestInput,
+  SessionInteractionResponse,
+  SessionInteractionResult,
+} from "@downcity/type";
+import type { SessionPendingInteractionRuntime } from "@/types/session/SessionInteractions.js";
+import { generate_id } from "@/utils/Id.js";
+
+/** 单个 Session 的异步用户交互入口。 */
+export class SessionInteractions implements SessionInteractionPort, SessionInteractionLifecycle {
+  /** 审批专用入口；长生命周期，每次调用只传身份与 payload。 */
+  readonly approval: ApprovalInteraction;
+  private readonly session_id: string;
+  private readonly messages: SessionMessages;
+  private readonly pending_by_id = new Map<
+    string,
+    SessionPendingInteractionRuntime
+  >();
+
+  constructor(options: {
+    /** 当前 Interaction 运行时所属 Session 标识。 */
+    session_id: string;
+    /** 当前 Session 的 canonical Message 入口。 */
+    messages: SessionMessages;
+    /** 读取当前 Session 审批模式；always-allow 在审批入口内生效。 */
+    read_approval_mode?: () => SessionApprovalMode;
+  }) {
+    this.session_id = String(options.session_id || "").trim();
+    this.messages = options.messages;
+    if (!this.session_id) {
+      throw new Error("SessionInteractions requires a non-empty session_id");
+    }
+    this.approval = new ApprovalInteraction({
+      interactions: this,
+      read_mode: options.read_approval_mode ?? (() => "ask"),
+    });
+  }
+
+  /**
+   * 创建并持久化一次 Interaction，返回等待终态结果的句柄。
+   *
+   * 关键点（中文）
+   * - 调用方只提供语义字段；`interaction_id`、`created_at` 与 `source` 在这里补齐。
+   */
+  async request(
+    input: SessionInteractionRequestInput,
+  ): Promise<SessionInteractionHandle> {
+    const request: SessionInteractionRequest = {
+      interaction_id: `interaction:${generate_id()}`,
+      turn_id: input.turn_id,
+      type: input.type,
+      source: {
+        type: input.source_type ?? "tool",
+        tool_call_id: input.tool_call_id,
+        ...(input.tool_name ? { tool_name: input.tool_name } : {}),
+      },
+      ...(input.title ? { title: input.title } : {}),
+      ...(input.description ? { description: input.description } : {}),
+      payload: input.payload,
+      ...(input.response_schema ? { response_schema: input.response_schema } : {}),
+      created_at: Date.now(),
+    };
+    this.validate_request(request);
+    if (this.pending_by_id.has(request.interaction_id)) {
+      throw new Error(`Session Interaction is already pending: ${request.interaction_id}`);
+    }
+
+    let resolve_result!: (result: SessionInteractionResult) => void;
+    const result = new Promise<SessionInteractionResult>((resolve) => {
+      resolve_result = resolve;
+    });
+    const pending: SessionPendingInteractionRuntime = {
+      request: structuredClone(request),
+      resolve: resolve_result,
+    };
+    this.pending_by_id.set(request.interaction_id, pending);
+
+    try {
+      await this.messages.request_interaction(request);
+    } catch (error) {
+      this.pending_by_id.delete(request.interaction_id);
+      throw error;
+    }
+
+    return {
+      interaction_id: request.interaction_id,
+      result,
+    };
+  }
+
+  /** 返回当前 Session 全部 pending Interaction 请求快照。 */
+  list(): SessionInteractionRequest[] {
+    return this.messages.list_pending_interactions().map((interaction) => interaction.request);
+  }
+
+  /** 保存用户响应，并在提交成功后恢复原执行。 */
+  async respond(
+    input: RespondSessionInteractionInput,
+  ): Promise<SessionInteractionResult> {
+    const pending = this.require_pending(input.interaction_id);
+    this.validate_response(pending.request, input.response);
+    await this.messages.resolve_interaction(
+      input.interaction_id,
+      input.response,
+    );
+    const result: SessionInteractionResult = input.response.outcome === "denied"
+      ? {
+        status: "denied",
+        interaction_id: input.interaction_id,
+        reason: extract_interaction_reason(input.response.payload),
+      }
+      : {
+        status: "resolved",
+        interaction_id: input.interaction_id,
+        response: structuredClone(input.response),
+      };
+    this.finish_pending(input.interaction_id, result);
+    return result;
+  }
+
+  /** 取消当前 Session 的全部 pending Interaction。 */
+  async cancel_all(
+    reason: "turn_stopped" | "session_disposed" | "runtime_interrupted",
+  ): Promise<void> {
+    let first_error: unknown;
+    for (const interaction_id of [...this.pending_by_id.keys()]) {
+      const result: SessionInteractionResult = {
+        status: "cancelled",
+        interaction_id,
+        reason,
+      };
+      try {
+        await this.messages.close_interaction(interaction_id, { reason });
+        this.finish_pending(interaction_id, result);
+      } catch (error) {
+        first_error ??= error;
+      }
+    }
+    if (first_error) throw first_error;
+  }
+
+  /**
+   * 校验执行面提交的 Interaction 信封。
+   *
+   * 核心不认识业务类型：`payload` 的类型就是 `JsonValue`，怎么解释由它的生产者负责。
+   * 因此这里只检查信封自身，不拆业务字段。
+   */
+  private validate_request(request: SessionInteractionRequest): void {
+    if (!String(request.interaction_id || "").trim()) {
+      throw new Error("Session Interaction requires interaction_id");
+    }
+    if (!String(request.turn_id || "").trim()) {
+      throw new Error("Session Interaction requires turn_id");
+    }
+    if (!String(request.type || "").trim()) {
+      throw new Error("Session Interaction requires a non-empty type");
+    }
+    if (!request.source || typeof request.source !== "object") {
+      throw new Error("Session Interaction requires a source");
+    }
+    if (!String(request.source.tool_call_id || "").trim()) {
+      throw new Error("Session Interaction requires the Tool Call it belongs to");
+    }
+  }
+
+  /** 校验响应信封：type 必须与请求一致，outcome 必须合法。 */
+  private validate_response(
+    request: SessionInteractionRequest,
+    response: SessionInteractionResponse,
+  ): void {
+    if (request.type !== response.type) {
+      throw new Error("Session Interaction response type mismatch");
+    }
+    if (response.outcome !== "resolved" && response.outcome !== "denied") {
+      throw new Error("Session Interaction response requires a valid outcome");
+    }
+  }
+
+  /** 读取当前 pending Interaction 运行态。 */
+  private require_pending(
+    interaction_id: string,
+  ): SessionPendingInteractionRuntime {
+    const pending = this.pending_by_id.get(interaction_id);
+    if (pending) return pending;
+    throw new Error(`Pending Session Interaction not found: ${interaction_id}`);
+  }
+
+  /** 清理运行态并兑现执行方等待 Promise。 */
+  private finish_pending(
+    interaction_id: string,
+    result: SessionInteractionResult,
+  ): void {
+    const pending = this.pending_by_id.get(interaction_id);
+    if (!pending) return;
+    this.pending_by_id.delete(interaction_id);
+    pending.resolve(result);
+  }
+}
+
+/** 从通用响应 payload 中读取可选的人类可读拒绝原因。 */
+function extract_interaction_reason(payload: unknown): string | undefined {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    return undefined;
+  }
+  const reason = (payload as { reason?: unknown }).reason;
+  return typeof reason === "string" ? reason : undefined;
+}

package/src/session/messages/SessionJsonValue.ts

@@ -5,7 +5,7 @@
  * 避免 Tool、User Data 等外部输入污染 canonical Message。
  */
 
-import type { JsonObject, JsonValue } from "@downcity/type";
+import type { JsonValue } from "@downcity/type";
 
 /** 把任意运行时输入转换为可持久化的 JSON 值。 */
 export function to_session_json_value(input: unknown): JsonValue {
@@ -24,20 +24,3 @@ export function to_session_json_value(input: unknown): JsonValue {
   }
 }
 
-/** 把任意运行时输入转换为可持久化 JSON 对象，非对象输入返回 undefined。 */
-export function to_session_json_object(input: unknown): JsonObject | undefined {
-  if (!is_plain_object(input)) return undefined;
-  try {
-    const value = JSON.parse(JSON.stringify(input)) as unknown;
-    return is_plain_object(value) ? value as JsonObject : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-/** 判断未知值是否为普通对象。 */
-function is_plain_object(input: unknown): input is Record<string, unknown> {
-  if (!input || typeof input !== "object" || Array.isArray(input)) return false;
-  const prototype = Object.getPrototypeOf(input);
-  return prototype === Object.prototype || prototype === null;
-}