@downcity/agent 1.1.222 → 1.1.226

package/src/session/recorder/SessionMessageCodec.ts

@@ -109,6 +109,7 @@ export function from_ui_assistant_parts(
     if (type === "text" || type === "reasoning") {
       return [{
         part_id: `${type}:${index + 1}`,
+        sequence: index + 1,
         type: type as "text" | "reasoning",
         text: String(candidate.text || ""),
         state: "done" as const,
@@ -117,6 +118,7 @@ export function from_ui_assistant_parts(
     if (type === "file") {
       return [{
         part_id: `file:${index + 1}`,
+        sequence: index + 1,
         type: "file" as const,
         url: String(candidate.url || ""),
         media_type: String(candidate.mediaType || "application/octet-stream"),
@@ -127,6 +129,7 @@ export function from_ui_assistant_parts(
       const state = String(candidate.state || "");
       return [{
         part_id: String(candidate.toolCallId || `tool:${index + 1}`),
+        sequence: index + 1,
         type: "tool" as const,
         tool_call_id: String(candidate.toolCallId || `tool:${index + 1}`),
         tool_name:
@@ -142,7 +145,9 @@ export function from_ui_assistant_parts(
                 ? "approval-required" as const
                 : state === "input-streaming"
                   ? "input-streaming" as const
-                  : "running" as const,
+                  : state === "input-available"
+                    ? "ready" as const
+                    : "running" as const,
         ...(candidate.input !== undefined
           ? { input: to_json_value(candidate.input) }
           : {}),

package/src/session/recorder/SessionRecorder.ts

@@ -1,13 +1,12 @@
 /**
  * SessionRecorder：Session Message 的唯一持久化与发布入口。
  *
- * Mutation 先写入单一 messages.jsonl，成功后更新内存 snapshot，最后发布同一个对象。
+ * 完整 Message 与 Assistant 草稿先持久化，成功后再发布实时 Mutation。
  */
 
 import type { UIMessage, UIMessageChunk } from "ai";
 import { generateId } from "@/utils/Id.js";
 import { JsonlSessionMessageStore } from "@/session/recorder/JsonlSessionMessageStore.js";
-import { reduce_session_message } from "@/session/recorder/SessionMessageReducer.js";
 import type { JsonObject, JsonValue } from "@/types/common/Json.js";
 import type {
   ListSessionMessagesInput,
@@ -22,23 +21,18 @@ import type {
   SessionUserMessagePart,
 } from "@/types/session/SessionMessage.js";
 import type {
-  ListSessionMessageChangesInput,
-  SessionMessageMutation,
-  SessionMessageMutationPage,
-  SessionMessageMutationSubscriber,
-  SessionMessageMutationUnsubscribe,
-  SessionMessageSnapshotMutation,
-  SessionPartSnapshotMutation,
-} from "@/types/session/SessionMessageMutation.js";
+  SessionMutation,
+  SessionMessageMutation as SessionMessageSnapshotMutation,
+} from "@/types/session/SessionMutation.js";
 
 /** SessionRecorder 构造参数。 */
 export interface SessionRecorderOptions {
   /** 当前 Session 标识。 */
   session_id: string;
-  /** 单一 JSONL Mutation store。 */
+  /** Message 快照 store。 */
   store: JsonlSessionMessageStore;
-  /** Mutation 成功提交后的发布函数。 */
-  publish: (mutation: SessionMessageMutation) => void;
+  /** 持久化成功后的实时 Mutation 发布函数。 */
+  publish: (mutation: SessionMutation) => void;
 }
 
 /** User Message 创建参数。 */
@@ -120,7 +114,6 @@ export class SessionRecorder {
   readonly session_id: string;
   private readonly store: JsonlSessionMessageStore;
   private readonly publish: SessionRecorderOptions["publish"];
-  private readonly subscribers = new Set<SessionMessageMutationSubscriber>();
   private readonly messages_by_id = new Map<string, SessionMessage>();
   private initialized = false;
 
@@ -131,7 +124,7 @@ export class SessionRecorder {
     if (!this.session_id) throw new Error("SessionRecorder requires session_id");
   }
 
-  /** 重放已有 Mutation，并收口进程中断遗留的运行状态。 */
+  /** 恢复已有 Message，并收口进程中断遗留的运行状态。 */
   async initialize(): Promise<void> {
     if (this.initialized) return;
     await this.store.initialize();
@@ -202,7 +195,7 @@ export class SessionRecorder {
       ...(input.summary_through_message_id
         ? { summary_through_message_id: input.summary_through_message_id }
         : {}),
-    }))) as SessionAssistantMessage;
+    }), true)) as SessionAssistantMessage;
     return new SessionAssistantMessageWriter(this, message.message_id);
   }
 
@@ -256,10 +249,10 @@ export class SessionRecorder {
     status: "running" | "completed" | "failed",
     changes?: { title?: string; description?: string; data?: JsonObject },
   ): Promise<SessionActionMessage> {
-    const mutation = await this.store.commit((state) => {
+    const message = await this.store.append_message((state) => {
       const current = require_message(state.messages, message_id, "action");
       const created_at = Date.now();
-      const message: SessionActionMessage = {
+      return {
         ...current,
         status,
         ...(changes?.title ? { title: changes.title } : {}),
@@ -269,11 +262,10 @@ export class SessionRecorder {
         ...(changes?.data ? { data: structuredClone(changes.data) } : {}),
         revision: current.revision + 1,
         updated_at: created_at,
-      };
-      return this.build_message_mutation(state.commit_sequence, message);
+      } satisfies SessionActionMessage;
     });
-    this.accept_mutation(mutation);
-    return this.get_message(message_id) as SessionActionMessage;
+    this.accept_message(message);
+    return message as SessionActionMessage;
   }
 
   /** 创建用户可见 Error Message。 */
@@ -302,9 +294,6 @@ export class SessionRecorder {
     input?: ListSessionMessagesInput,
   ): Promise<SessionMessagePage> {
     await this.ensure_initialized();
-    const mutations = await this.store.list_mutations();
-    const latest_commit_sequence =
-      mutations[mutations.length - 1]?.commit_sequence || 0;
     const include_internal = input?.include_internal === true;
     const through_sequence = Number.isFinite(input?.through_sequence)
       ? Number(input?.through_sequence)
@@ -329,38 +318,9 @@ export class SessionRecorder {
       total: all.length,
       ...(next_offset < all.length ? { next_cursor: encode_cursor(next_offset) } : {}),
       has_more: next_offset < all.length,
-      latest_commit_sequence,
-    };
-  }
-
-  /** 从指定 commit_sequence 增量读取 Mutation。 */
-  async list_message_changes(
-    input: ListSessionMessageChangesInput,
-  ): Promise<SessionMessageMutationPage> {
-    await this.ensure_initialized();
-    const after = Math.max(0, Math.floor(input.after_commit_sequence || 0));
-    const limit = normalize_limit(input.limit, 200, 1000);
-    const all = await this.store.list_mutations();
-    const matching = all.filter((item) => item.commit_sequence > after);
-    const items = matching.slice(0, limit);
-    const latest_commit_sequence = all[all.length - 1]?.commit_sequence || 0;
-    return {
-      items,
-      has_more: matching.length > items.length,
-      next_commit_sequence:
-        items[items.length - 1]?.commit_sequence || after,
-      latest_commit_sequence,
     };
   }
 
-  /** 订阅已成功持久化的未来 Mutation。 */
-  subscribe(
-    subscriber: SessionMessageMutationSubscriber,
-  ): SessionMessageMutationUnsubscribe {
-    this.subscribers.add(subscriber);
-    return () => this.subscribers.delete(subscriber);
-  }
-
   /** 向当前 Session 导入 fork 来源 Message，并重新分配全部身份和顺序。 */
   async import_messages(messages: SessionMessage[]): Promise<void> {
     const turn_ids = new Map<string, string>();
@@ -400,23 +360,37 @@ export class SessionRecorder {
     delta: string,
   ): Promise<void> {
     if (!delta) return;
-    const mutation = await this.store.commit((state) => {
-      const current = require_message(state.messages, message_id, "assistant");
-      return {
-        mutation_id: generateId(),
-        variant: "delta",
-        type,
-        commit_sequence: state.commit_sequence,
-        message_id,
-        revision: current.revision + 1,
-        session_id: this.session_id,
-        turn_id: current.turn_id,
-        created_at: Date.now(),
-        part_id,
-        delta,
-      } satisfies SessionMessageMutation;
-    });
-    this.accept_mutation(mutation);
+    const current = require_message([...this.messages_by_id.values()], message_id, "assistant");
+    require_streaming_assistant(current);
+    const part = current.parts.find((item) => item.part_id === part_id);
+    if (!part || (part.type !== "text" && part.type !== "reasoning")) {
+      throw new Error(`Delta target Part does not exist: ${part_id}`);
+    }
+    if (part.type !== type) throw new Error(`Delta type changed for Part: ${part_id}`);
+    const created_at = Date.now();
+    const message: SessionAssistantMessage = {
+      ...current,
+      revision: current.revision + 1,
+      updated_at: created_at,
+      parts: current.parts.map((item) =>
+        item.part_id === part_id && (item.type === "text" || item.type === "reasoning")
+          ? { ...item, text: item.text + delta }
+          : item,
+      ),
+    };
+    await this.store.write_assistant_message(message);
+    this.accept_mutation({
+      mutation_id: generateId(),
+      variant: "delta",
+      type,
+      message_id,
+      revision: message.revision,
+      session_id: this.session_id,
+      turn_id: message.turn_id,
+      created_at,
+      part_id,
+      delta,
+    }, message);
   }
 
   /** @internal 写入 Assistant 完整 part。 */
@@ -424,23 +398,36 @@ export class SessionRecorder {
     message_id: string,
     part: SessionAssistantMessagePart,
   ): Promise<void> {
-    const mutation = await this.store.commit((state) => {
-      const current = require_message(state.messages, message_id, "assistant");
-      return {
-        mutation_id: generateId(),
-        variant: "part",
-        type: part.type,
-        commit_sequence: state.commit_sequence,
-        message_id,
-        revision: current.revision + 1,
-        session_id: this.session_id,
-        turn_id: current.turn_id,
-        created_at: Date.now(),
-        part_id: part.part_id,
-        part: structuredClone(part),
-      } as SessionPartSnapshotMutation;
-    });
-    this.accept_mutation(mutation);
+    const current = require_message([...this.messages_by_id.values()], message_id, "assistant");
+    require_streaming_assistant(current);
+    const existing = current.parts.find((item) => item.part_id === part.part_id);
+    if (existing && existing.sequence !== part.sequence) {
+      throw new Error(`Assistant Part sequence changed: ${part.part_id}`);
+    }
+    const created_at = Date.now();
+    const next_part = structuredClone(part);
+    const message: SessionAssistantMessage = {
+      ...current,
+      revision: current.revision + 1,
+      updated_at: created_at,
+      parts: (existing
+        ? current.parts.map((item) => item.part_id === part.part_id ? next_part : item)
+        : [...current.parts, next_part]
+      ).sort((left, right) => left.sequence - right.sequence),
+    };
+    await this.store.write_assistant_message(message);
+    this.accept_mutation({
+      mutation_id: generateId(),
+      variant: "part",
+      type: next_part.type,
+      message_id,
+      revision: message.revision,
+      session_id: this.session_id,
+      turn_id: message.turn_id,
+      created_at,
+      part_id: next_part.part_id,
+      part: next_part,
+    } as SessionMutation, message);
   }
 
   /** @internal 收口 Assistant Message。 */
@@ -448,45 +435,100 @@ export class SessionRecorder {
     message_id: string,
     status: "completed" | "stopped" | "failed",
   ): Promise<void> {
-    const mutation = await this.store.commit((state) => {
-      const current = require_message(state.messages, message_id, "assistant");
-      const created_at = Date.now();
-      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,
-        ),
-      };
-      return this.build_message_mutation(state.commit_sequence, message);
+    const current = require_message([...this.messages_by_id.values()], message_id, "assistant");
+    require_streaming_assistant(current);
+    const created_at = Date.now();
+    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,
+      ),
+    };
+    await this.store.finalize_assistant_message(message);
+    this.accept_message(message);
+  }
+
+  /** @internal 将 Shell Runtime 审批请求更新到当前 Tool Part。 */
+  async require_tool_approval(input: {
+    tool_call_id: string;
+    approval_id: string;
+  }): Promise<void> {
+    const tool = this.find_streaming_tool(input.tool_call_id);
+    await this.update_assistant_part(tool.message_id, {
+      ...tool.part,
+      state: "approval-required",
+      approval_id: input.approval_id,
+    });
+  }
+
+  /** @internal 将审批结果更新到当前 Tool Part。 */
+  async resolve_tool_approval(input: {
+    tool_call_id: string;
+    approval_id: string;
+    decision: "approved" | "denied" | "expired";
+  }): Promise<void> {
+    const tool = this.find_streaming_tool(input.tool_call_id);
+    if (tool.part.approval_id && tool.part.approval_id !== input.approval_id) {
+      throw new Error(`Tool approval identity mismatch: ${input.approval_id}`);
+    }
+    await this.update_assistant_part(tool.message_id, {
+      ...tool.part,
+      state: input.decision === "approved" ? "running" : "failed",
+      ...(input.decision === "approved"
+        ? {}
+        : { error: input.decision === "expired" ? "Approval expired" : "Approval denied" }),
     });
-    this.accept_mutation(mutation);
   }
 
   private async create_message(
     factory: (sequence: number, created_at: number) => SessionMessage,
+    draft = false,
   ): Promise<SessionMessage> {
-    const mutation = await this.store.commit((state) => {
-      const message = factory(state.message_sequence, Date.now());
-      return this.build_message_mutation(state.commit_sequence, message);
-    });
-    this.accept_mutation(mutation);
-    return (mutation as SessionMessageSnapshotMutation).message;
+    if (draft) {
+      const message = await this.store.create_assistant_message((state) => {
+        const candidate = factory(state.message_sequence, Date.now());
+        if (candidate.type !== "assistant" || candidate.status !== "streaming") {
+          throw new Error("Draft Message must be a streaming Assistant");
+        }
+        return candidate;
+      });
+      this.accept_message(message);
+      return message;
+    }
+    const message = await this.store.append_message((state) =>
+      factory(state.message_sequence, Date.now()),
+    );
+    this.accept_message(message);
+    return message;
+  }
+
+  private find_streaming_tool(tool_call_id: string): {
+    message_id: string;
+    part: SessionAssistantToolPart;
+  } {
+    for (const message of this.messages_by_id.values()) {
+      if (message.type !== "assistant" || message.status !== "streaming") continue;
+      const part = message.parts.find(
+        (item): item is SessionAssistantToolPart =>
+          item.type === "tool" && item.tool_call_id === tool_call_id,
+      );
+      if (part) return { message_id: message.message_id, part };
+    }
+    throw new Error(`Streaming Tool Part not found: ${tool_call_id}`);
   }
 
   private build_message_mutation(
-    commit_sequence: number,
     message: SessionMessage,
   ): SessionMessageSnapshotMutation {
     return {
       mutation_id: generateId(),
       variant: "message",
       type: message.type,
-      commit_sequence,
       message_id: message.message_id,
       sequence: message.sequence,
       revision: message.revision,
@@ -497,18 +539,13 @@ export class SessionRecorder {
     } as SessionMessageSnapshotMutation;
   }
 
-  private accept_mutation(mutation: SessionMessageMutation): void {
-    const current = this.messages_by_id.get(mutation.message_id);
-    const next = reduce_session_message(current, mutation);
-    this.messages_by_id.set(next.message_id, next);
+  private accept_message(message: SessionMessage): void {
+    this.accept_mutation(this.build_message_mutation(message), message);
+  }
+
+  private accept_mutation(mutation: SessionMutation, message: SessionMessage): void {
+    this.messages_by_id.set(message.message_id, structuredClone(message));
     this.publish(mutation);
-    for (const subscriber of this.subscribers) {
-      try {
-        subscriber(mutation);
-      } catch {
-        // 单个订阅者异常不能影响已经完成的提交。
-      }
-    }
   }
 
   private async ensure_initialized(): Promise<void> {
@@ -520,6 +557,7 @@ export class SessionRecorder {
 export class SessionAssistantMessageWriter {
   readonly message_id: string;
   private readonly recorder: SessionRecorder;
+  private readonly pending_text_parts = new Map<string, "text" | "reasoning">();
   private closed = false;
 
   constructor(recorder: SessionRecorder, message_id: string) {
@@ -533,29 +571,35 @@ export class SessionAssistantMessageWriter {
     const current = this.current_message();
     switch (chunk.type) {
       case "text-start":
-      case "reasoning-start":
-        await this.upsert_part({
-          part_id: `${chunk.type === "text-start" ? "text" : "reasoning"}:${chunk.id}`,
-          type: chunk.type === "text-start" ? "text" : "reasoning",
-          text: "",
-          state: "streaming",
-        });
+      case "reasoning-start": {
+        const type = chunk.type === "text-start" ? "text" : "reasoning";
+        const part_id = `${type}:${chunk.id}`;
+        if (!current.parts.some((part) => part.part_id === part_id)) {
+          this.pending_text_parts.set(part_id, type);
+        }
         return;
+      }
       case "text-delta":
-      case "reasoning-delta":
+      case "reasoning-delta": {
+        const type = chunk.type === "text-delta" ? "text" : "reasoning";
+        const part_id = `${type}:${chunk.id}`;
+        await this.ensure_text_part(part_id, type);
         await this.recorder.append_assistant_delta(
           this.message_id,
-          `${chunk.type === "text-delta" ? "text" : "reasoning"}:${chunk.id}`,
-          chunk.type === "text-delta" ? "text" : "reasoning",
+          part_id,
+          type,
           chunk.delta,
         );
         return;
+      }
       case "text-end":
       case "reasoning-end": {
         const part_id = `${chunk.type === "text-end" ? "text" : "reasoning"}:${chunk.id}`;
         const part = current.parts.find((item) => item.part_id === part_id);
         if (part?.type === "text" || part?.type === "reasoning") {
           await this.upsert_part({ ...part, state: "done" });
+        } else {
+          this.pending_text_parts.delete(part_id);
         }
         return;
       }
@@ -578,7 +622,7 @@ export class SessionAssistantMessageWriter {
       case "tool-input-available":
         await this.upsert_tool(chunk.toolCallId, {
           tool_name: chunk.toolName,
-          state: "running",
+          state: "ready",
           input: to_json_value(chunk.input),
         });
         return;
@@ -624,6 +668,7 @@ export class SessionAssistantMessageWriter {
       case "file":
         await this.upsert_part({
           part_id: `file:${generateId()}`,
+          sequence: this.next_part_sequence(),
           type: "file",
           media_type: chunk.mediaType,
           url: chunk.url,
@@ -672,6 +717,41 @@ export class SessionAssistantMessageWriter {
     );
   }
 
+  private next_part_sequence(): number {
+    return this.current_message().parts.reduce(
+      (value, part) => Math.max(value, part.sequence + 1),
+      1,
+    );
+  }
+
+  /** 在首个有效 Delta 到达时才固定文本 Part 的真实顺序。 */
+  private async ensure_text_part(
+    part_id: string,
+    type: "text" | "reasoning",
+  ): Promise<void> {
+    const existing = this.current_message().parts.find(
+      (part) => part.part_id === part_id,
+    );
+    if (existing) {
+      if (existing.type !== type) {
+        throw new Error(`Assistant Part type changed: ${part_id}`);
+      }
+      return;
+    }
+    const pending_type = this.pending_text_parts.get(part_id);
+    if (pending_type && pending_type !== type) {
+      throw new Error(`Assistant pending Part type changed: ${part_id}`);
+    }
+    await this.upsert_part({
+      part_id,
+      sequence: this.next_part_sequence(),
+      type,
+      text: "",
+      state: "streaming",
+    });
+    this.pending_text_parts.delete(part_id);
+  }
+
   private async upsert_tool(
     tool_call_id: string,
     changes: Pick<SessionAssistantToolPart, "tool_name" | "state"> &
@@ -681,6 +761,7 @@ export class SessionAssistantMessageWriter {
     await this.upsert_part({
       ...(current || {}),
       part_id: `tool:${tool_call_id}`,
+      sequence: current?.sequence || this.next_part_sequence(),
       type: "tool",
       tool_call_id,
       ...changes,
@@ -689,6 +770,7 @@ export class SessionAssistantMessageWriter {
 
   private async close(status: "completed" | "stopped" | "failed"): Promise<void> {
     if (this.closed) return;
+    this.pending_text_parts.clear();
     await this.recorder.complete_assistant_message(this.message_id, status);
     this.closed = true;
   }
@@ -771,6 +853,18 @@ function require_message<TType extends SessionMessage["type"]>(
   return message as Extract<SessionMessage, { type: TType }>;
 }
 
+function require_streaming_assistant(
+  message: SessionMessage,
+): SessionAssistantMessage {
+  if (message.type !== "assistant") {
+    throw new Error(`Session Message is not assistant: ${message.message_id}`);
+  }
+  if (message.status !== "streaming") {
+    throw new Error(`Assistant Message is already closed: ${message.message_id}`);
+  }
+  return message;
+}
+
 function to_json_value(input: unknown): JsonValue {
   if (input === undefined || input === null) return null;
   if (typeof input === "string" || typeof input === "number" || typeof input === "boolean") return input;

package/src/session/recorder/SessionRecorderCompaction.ts

@@ -102,6 +102,7 @@ export async function compact_session_recorder_messages(input: {
     summary_through_message_id: boundary.message_id,
     parts: [{
       part_id: `summary-text:${generateId()}`,
+      sequence: 1,
       type: "text",
       text: summary,
       state: "done",

package/src/session/recorder/SessionRecorderHistoryStore.ts

@@ -2,9 +2,9 @@
  * SessionRecorder 到 Executor SessionHistoryStore 的内部投影适配器。
  *
  * 关键点（中文）
- * - Recorder messages.jsonl 是唯一持久化事实源。
+ * - Recorder 的 messages.jsonl 与 assistant_message.json 共同组成持久化事实源。
  * - Executor 继续读取临时 UIMessage 投影，不直接拥有文件写入权。
- * - inflight 写入已经由 AssistantMessageWriter 取代，因此对应接口只提供投影兼容。
+ * - 流式草稿写入由 AssistantMessageWriter 负责，Executor 的旧接口只提供投影兼容。
  */
 
 import { nanoid } from "nanoid";
@@ -109,7 +109,7 @@ export class SessionRecorderHistoryStore implements SessionHistoryStore {
     });
   }
 
-  /** Recorder 已经逐 delta 保存 assistant，不再维护第二份 inflight。 */
+  /** 从 Recorder 当前快照投影运行中的 Assistant。 */
   async read_inflight(): Promise<SessionRecordV1 | null> {
     const page = await this.recorder.list_messages({
       limit: 500,
@@ -124,10 +124,10 @@ export class SessionRecorderHistoryStore implements SessionHistoryStore {
     return assistant ? to_executor_ui_message(assistant) : null;
   }
 
-  /** 旧 inflight 写入口已废弃；流式内容由 Recorder writer 负责。 */
+  /** Executor 草稿写入口不持久化；流式内容由 Recorder writer 负责。 */
   async write_inflight(_message: SessionRecordV1): Promise<void> {}
 
-  /** 旧 inflight 收口入口已废弃；Assistant writer 负责 complete。 */
+  /** Executor 草稿收口入口不持久化；Assistant writer 负责 complete。 */
   async finalize_inflight(_message?: SessionRecordV1 | null): Promise<void> {}
 
   /** 返回 Context Composer 使用的 UIMessage 投影。 */