@downcity/agent 1.1.222 → 1.1.224

package/src/session/Session.ts

@@ -23,6 +23,7 @@ import type {
 } from "@/types/agent/SessionTypes.js";
 import type { AgentSession } from "@/types/agent/SessionActor.js";
 import {
+  getSdkAgentSessionAssistantMessagePath,
   getSdkAgentSessionDirPath,
 } from "@/session/storage/Paths.js";
 import { resolveSystemTimezone } from "@/session/storage/Metadata.js";
@@ -30,15 +31,18 @@ import { createRuntimeSessionPort } from "@/session/storage/RuntimeSessionPort.j
 import { SessionSystemBuilder } from "@/session/SessionSystemBuilder.js";
 import type { SessionPort } from "@/types/runtime/agent/AgentContext.js";
 import type {
-  AgentSessionSubscriber,
-  AgentSessionUnsubscribe,
-} from "@/types/sdk/AgentSessionEvent.js";
+  SessionMutation,
+  SessionMutationSubscriber,
+  SessionMutationUnsubscribe,
+} from "@/types/session/SessionMutation.js";
 import type {
-  ListSessionMessageChangesInput,
-  SessionMessageMutationPage,
-  SessionMessageMutationSubscriber,
-  SessionMessageMutationUnsubscribe,
-} from "@/types/session/SessionMessageMutation.js";
+  ResolveSessionApprovalInput,
+  SessionApproval,
+  SessionApprovalModeSnapshot,
+  SessionApprovalResult,
+  SetSessionApprovalModeInput,
+  SessionApprovalRuntimeEvent,
+} from "@/types/session/SessionApproval.js";
 import type {
   ListSessionMessagesInput,
   SessionMessagePage,
@@ -47,7 +51,6 @@ import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js"
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
 import { SessionEventHub } from "@/session/runtime/SessionEventHub.js";
-import { SessionMessageEventHub } from "@/session/runtime/SessionMessageEventHub.js";
 import { SessionStateService } from "@/session/services/SessionStateService.js";
 import { SessionTurnService } from "@/session/services/SessionTurnService.js";
 import { SessionViewService } from "@/session/services/SessionViewService.js";
@@ -83,8 +86,11 @@ export class Session implements AgentSession {
   private readonly recorder: SessionRecorder;
   private readonly historyComposer: SessionHistoryComposer;
   private readonly executor: Executor;
-  private readonly eventHub = new SessionEventHub();
-  private readonly messageEventHub = new SessionMessageEventHub();
+  private readonly eventHub: SessionEventHub;
+  private readonly list_approvals: SessionOptions["list_approvals"];
+  private readonly get_approval_mode: SessionOptions["get_approval_mode"];
+  private readonly set_approval_mode_hook: SessionOptions["set_approval_mode"];
+  private readonly resolve_approval_hook: SessionOptions["resolve_approval"];
   private readonly localState: SessionLocalState;
   private readonly stateService: SessionStateService;
   private readonly turnService: SessionTurnService;
@@ -102,6 +108,10 @@ export class Session implements AgentSession {
     this.getPluginSystemBlocks = options.getPluginSystemBlocks;
     this.ensureConfiguredHook = options.ensureConfigured;
     this.composers = options.composers;
+    this.list_approvals = options.list_approvals;
+    this.get_approval_mode = options.get_approval_mode;
+    this.set_approval_mode_hook = options.set_approval_mode;
+    this.resolve_approval_hook = options.resolve_approval;
     if (!this.id) {
       throw new Error("Session requires a non-empty sessionId");
     }
@@ -112,12 +122,20 @@ export class Session implements AgentSession {
       throw new Error("Session requires a non-empty projectRoot");
     }
 
+    this.eventHub = new SessionEventHub({
+      create_reply: (mutation) => ({
+        approval: async ({ decision }) => {
+          const approval_id = require_approval_id(mutation);
+          return await this.resolve_approval({ approval_id, decision });
+        },
+      }),
+    });
     this.messageStore = this.create_message_store();
     this.recorder = new SessionRecorder({
       session_id: this.id,
       store: this.messageStore,
       publish: (mutation) => {
-        this.messageEventHub.publish(mutation);
+        this.eventHub.publish(mutation);
       },
     });
     this.historyStore = this.create_history_store();
@@ -229,19 +247,44 @@ export class Session implements AgentSession {
    * 订阅当前 Session 的未来事件。
    */
   subscribe(
-    subscriber: SessionMessageMutationSubscriber,
-  ): SessionMessageMutationUnsubscribe {
-    return this.messageEventHub.subscribe(subscriber);
-  }
-
-  /** 订阅远程 transport 所需的 Message 与 lifecycle 事件。 */
-  subscribe_transport(subscriber: AgentSessionSubscriber): AgentSessionUnsubscribe {
-    const unsubscribe_message = this.messageEventHub.subscribe(subscriber);
-    const unsubscribe_lifecycle = this.turnService.subscribe(subscriber);
-    return () => {
-      unsubscribe_message();
-      unsubscribe_lifecycle();
-    };
+    subscriber: SessionMutationSubscriber,
+  ): SessionMutationUnsubscribe {
+    return this.eventHub.subscribe(subscriber);
+  }
+
+  /** 列出当前 Session 的 pending 工具审批。 */
+  async approvals(): Promise<SessionApproval[]> {
+    return await this.list_approvals(this.id);
+  }
+
+  /** 读取当前 Session 的工具审批模式。 */
+  async approval_mode(): Promise<SessionApprovalModeSnapshot> {
+    return await this.get_approval_mode(this.id);
+  }
+
+  /** 更新当前 Session 的工具审批模式。 */
+  async set_approval_mode(input: SetSessionApprovalModeInput): Promise<SessionApprovalModeSnapshot> {
+    return await this.set_approval_mode_hook(this.id, input);
+  }
+
+  /** 处理当前 Session 的 pending 工具审批。 */
+  async resolve_approval(input: ResolveSessionApprovalInput): Promise<SessionApprovalResult> {
+    return await this.resolve_approval_hook(this.id, input);
+  }
+
+  private async apply_runtime_event(event: SessionApprovalRuntimeEvent): Promise<void> {
+    if (event.type === "tool-approval-request") {
+      await this.recorder.require_tool_approval({
+        tool_call_id: event.tool_call_id,
+        approval_id: event.approval_id,
+      });
+      return;
+    }
+    await this.recorder.resolve_tool_approval({
+      tool_call_id: event.tool_call_id,
+      approval_id: event.approval_id,
+      decision: event.decision,
+    });
   }
 
   /**
@@ -280,13 +323,6 @@ export class Session implements AgentSession {
     return await this.recorder.list_messages(input);
   }
 
-  /** 读取当前 Session 的增量 Message Mutation。 */
-  async message_changes(
-    input: ListSessionMessageChangesInput,
-  ): Promise<SessionMessageMutationPage> {
-    return await this.recorder.list_message_changes(input);
-  }
-
   /**
    * 读取当前 session 生效的 system 快照。
    */
@@ -319,8 +355,8 @@ export class Session implements AgentSession {
       prompt: async (input) => await this.prompt(input),
       stop: async () => await this.stop(),
       subscribe: (subscriber) => this.subscribe(subscriber),
-      publishEvent: (event) => {
-        this.eventHub.publish(event);
+      publishEvent: async (event) => {
+        await this.apply_runtime_event(event);
       },
       append_user_message: async (message_params) => {
         await this.stateService.append_user_message(message_params);
@@ -356,6 +392,10 @@ export class Session implements AgentSession {
       getPluginSystemBlocks: this.getPluginSystemBlocks,
       ensureConfigured: this.ensureConfiguredHook,
       composers: this.composers,
+      list_approvals: this.list_approvals,
+      get_approval_mode: this.get_approval_mode,
+      set_approval_mode: this.set_approval_mode_hook,
+      resolve_approval: this.resolve_approval_hook,
     });
   }
 
@@ -383,6 +423,11 @@ export class Session implements AgentSession {
     return new JsonlSessionMessageStore({
       session_id: this.id,
       file_path: `${messages_dir_path}/messages.jsonl`,
+      assistant_message_file_path: getSdkAgentSessionAssistantMessagePath(
+        this.projectRoot,
+        this.agentId,
+        this.id,
+      ),
     });
   }
 
@@ -505,3 +550,15 @@ export class Session implements AgentSession {
     return input;
   }
 }
+
+function require_approval_id(mutation: SessionMutation): string {
+  if (
+    mutation.variant === "part" &&
+    mutation.type === "tool" &&
+    mutation.part.state === "approval-required" &&
+    mutation.part.approval_id
+  ) {
+    return mutation.part.approval_id;
+  }
+  throw new Error("Current Session Mutation is not an approval-required Tool Part");
+}

package/src/session/browse/Browse.ts

@@ -45,6 +45,8 @@ import { getSdkAgentArchivedSessionsDirPath } from "@/session/storage/Paths.js";
 import { getSdkAgentArchivedSessionMessagesPath } from "@/session/storage/Paths.js";
 import { getSdkAgentArchivedSessionMetaPath } from "@/session/storage/Paths.js";
 import { readSessionMetadataFromPath } from "@/session/storage/Metadata.js";
+import { to_executor_ui_message } from "@/session/recorder/SessionMessageCodec.js";
+import type { SessionMessage } from "@/types/session/SessionMessage.js";
 
 type AnyUiPart = UIMessagePart<Record<string, never>, Record<string, never>>;
 
@@ -324,46 +326,73 @@ export function toSessionTimelineEvents(
 export async function loadSessionMessagesFromPath(
   filePath: string,
 ): Promise<SessionRecordV1[]> {
-  const messages: SessionRecordV1[] = [];
+  const messages_by_id = new Map<string, SessionMessage>();
   if (await fs.pathExists(filePath)) {
     const raw = await fs.readFile(filePath, "utf-8");
     const lines = raw.split("\n").filter(Boolean);
     for (const line of lines) {
       try {
-        const parsed = JSON.parse(line) as SessionRecordV1;
-        if (!parsed || typeof parsed !== "object") continue;
-        const candidate = parsed as { type?: unknown; role?: unknown };
-        if (
-          candidate.type !== "action" &&
-          candidate.role !== "user" &&
-          candidate.role !== "assistant"
-        ) {
-          continue;
+        const message = JSON.parse(line) as SessionMessage;
+        if (!is_canonical_session_message(message)) continue;
+        const previous = messages_by_id.get(message.message_id);
+        if (!previous || message.revision > previous.revision) {
+          messages_by_id.set(message.message_id, message);
         }
-        messages.push(parsed);
       } catch {
         // 关键点（中文）：单行损坏不影响整个 session 的可读性。
       }
     }
   }
 
-  const inflight_path = filePath.replace(/messages\.jsonl$/, "inflight.json");
+  const inflight_path = filePath.replace(/messages\.jsonl$/, "assistant_message.json");
   if (await fs.pathExists(inflight_path)) {
     try {
-      const parsed = (await fs.readJson(inflight_path)) as SessionRecordV1;
-      if (
-        is_session_message_record(parsed) &&
-        parsed.role === "assistant" &&
-        Array.isArray(parsed.parts)
-      ) {
-        messages.push(parsed);
+      const message = (await fs.readJson(inflight_path)) as SessionMessage;
+      if (is_canonical_session_message(message) && message.type === "assistant") {
+        messages_by_id.set(message.message_id, message);
       }
     } catch {
-      // ignore invalid inflight snapshot
+      // 运行中快照损坏时仍返回已经完成的历史。
     }
   }
 
-  return messages;
+  return [...messages_by_id.values()]
+    .sort((left, right) => left.sequence - right.sequence)
+    .flatMap(project_canonical_message_record);
+}
+
+function is_canonical_session_message(input: unknown): input is SessionMessage {
+  if (!input || typeof input !== "object") return false;
+  const candidate = input as Partial<SessionMessage>;
+  return (
+    typeof candidate.message_id === "string" &&
+    typeof candidate.session_id === "string" &&
+    typeof candidate.sequence === "number" &&
+    typeof candidate.revision === "number" &&
+    (candidate.type === "user" ||
+      candidate.type === "assistant" ||
+      candidate.type === "action" ||
+      candidate.type === "error")
+  );
+}
+
+function project_canonical_message_record(message: SessionMessage): SessionRecordV1[] {
+  const projected = to_executor_ui_message(message);
+  if (projected) return [projected];
+  if (message.type !== "action") return [];
+  return [{
+    type: "action",
+    id: message.message_id,
+    title: message.title,
+    ...(message.description ? { description: message.description } : {}),
+    state: message.status,
+    metadata: {
+      v: 1,
+      ts: message.updated_at,
+      sessionId: message.session_id,
+      ...(message.turn_id ? { turnId: message.turn_id } : {}),
+    },
+  }];
 }
 
 /**
@@ -481,7 +510,7 @@ async function resolve_session_summary_metadata(input: {
   const history_bytes = await fs.stat(input.messagesPath)
     .then((file_stat) => file_stat.size)
     .catch(() => 0);
-  const inflight_path = `${input.messagesPath.slice(0, -"messages.jsonl".length)}inflight.json`;
+  const inflight_path = `${input.messagesPath.slice(0, -"messages.jsonl".length)}assistant_message.json`;
   const has_inflight = await fs.pathExists(inflight_path);
   if (
     !input.refresh &&

package/src/session/recorder/JsonlSessionMessageStore.ts

@@ -1,121 +1,217 @@
 /**
- * 基于单一 messages.jsonl 的 SessionMessage mutation store。
+ * SessionMessage 的 JSONL 快照存储。
  *
- * 文件中每行是一条完整 mutation。消息快照通过 reducer 重放得到，不维护第二份文件。
+ * messages.jsonl 只保存完整 Message 快照；运行中的唯一 Assistant 使用
+ * assistant_message.json 原子覆盖，避免把每个 delta 写入历史文件。
  */
 
 import fs from "fs-extra";
 import { open, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { generateId } from "@/utils/Id.js";
-import { reduce_session_messages } from "@/session/recorder/SessionMessageReducer.js";
-import type { SessionMessage } from "@/types/session/SessionMessage.js";
-import type { SessionMessageMutation } from "@/types/session/SessionMessageMutation.js";
+import type { SessionAssistantMessage, SessionMessage } from "@/types/session/SessionMessage.js";
 
-/** JSONL message store 构造参数。 */
+/** JSONL 快照存储构造参数。 */
 export interface JsonlSessionMessageStoreOptions {
-  /** 当前 session 标识。 */
+  /** 当前 Session 标识。 */
   session_id: string;
-  /** canonical messages.jsonl 的绝对路径。 */
+  /** messages.jsonl 的绝对或相对路径。 */
   file_path: string;
+  /** Assistant 运行中快照路径，默认与 messages.jsonl 同目录。 */
+  assistant_message_file_path?: string;
 }
 
-/** Recorder 在锁内构造下一条 mutation 时可用的序列状态。 */
+/** 在写锁内计算新 Message 所需的状态。 */
 export interface SessionMessageCommitState {
-  /** 下一条 mutation 应使用的提交顺序。 */
-  commit_sequence: number;
-  /** 下一条新消息应使用的线性顺序。 */
+  /** 下一条新 Message 的线性顺序。 */
   message_sequence: number;
-  /** 当前已重放的线性消息列表。 */
+  /** 当前已持久化的完整 Message 快照。 */
   messages: SessionMessage[];
 }
 
-/** 单一 JSONL mutation store。 */
+/** 单一 JSONL 快照存储。 */
 export class JsonlSessionMessageStore {
   readonly session_id: string;
-  private readonly messages_file_path: string;
+  readonly messages_file_path: string;
+  readonly assistant_message_file_path: string;
   private readonly lock_file_path: string;
 
   constructor(options: JsonlSessionMessageStoreOptions) {
     this.session_id = String(options.session_id || "").trim();
     this.messages_file_path = path.resolve(options.file_path);
+    this.assistant_message_file_path = path.resolve(
+      options.assistant_message_file_path ||
+        path.join(path.dirname(this.messages_file_path), "assistant_message.json"),
+    );
     this.lock_file_path = `${this.messages_file_path}.lock`;
-    if (!this.session_id) {
-      throw new Error("JsonlSessionMessageStore requires session_id");
-    }
+    if (!this.session_id) throw new Error("JsonlSessionMessageStore requires session_id");
   }
 
-  /** 创建空文件并校验已有 Mutation 可重放。 */
+  /** 创建目录和文件，并验证已有快照。 */
   async initialize(): Promise<void> {
     await this.ensure_layout();
-    reduce_session_messages(await this.read_mutations_unsafe());
+    const messages = await this.read_messages_unsafe();
+    const draft = await this.read_assistant_message();
+    if (draft && draft.session_id !== this.session_id) {
+      throw new Error("assistant_message.json session_id mismatch");
+    }
+    const finalized = draft && messages.find((message) => message.message_id === draft.message_id);
+    if (draft && finalized && finalized.revision >= draft.revision && finalized.type === "assistant" && finalized.status !== "streaming") {
+      await fs.remove(this.assistant_message_file_path);
+    }
   }
 
-  /** 读取全部合法 mutation；损坏行会带行号抛错，避免静默产生错误历史。 */
-  async list_mutations(): Promise<SessionMessageMutation[]> {
+  /** 读取 JSONL 中每一行完整快照，并按 Message revision 折叠。 */
+  async list_messages(): Promise<SessionMessage[]> {
     await this.ensure_layout();
-    return await this.read_mutations_unsafe();
+    const by_id = new Map<string, SessionMessage>();
+    const raw = await fs.readFile(this.messages_file_path, "utf8").catch(() => "");
+    for (const [index, line] of raw.split("\n").entries()) {
+      const value = line.trim();
+      if (!value) continue;
+      try {
+        const message = JSON.parse(value) as SessionMessage;
+        this.validate_message(message);
+        const previous = by_id.get(message.message_id);
+        if (!previous || message.revision > previous.revision) by_id.set(message.message_id, message);
+      } catch (error) {
+        throw new Error(`Invalid session message at line ${String(index + 1)}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    const draft = await this.read_assistant_message();
+    if (draft) {
+      const previous = by_id.get(draft.message_id);
+      if (!previous || draft.revision > previous.revision) by_id.set(draft.message_id, draft);
+    }
+    return [...by_id.values()].sort((left, right) => left.sequence - right.sequence);
   }
 
-  /** 重放全部 mutation，得到当前 canonical 消息列表。 */
-  async list_messages(): Promise<SessionMessage[]> {
-    return reduce_session_messages(await this.list_mutations());
+  /** 读取当前运行中的 Assistant 草稿。 */
+  async read_assistant_message(): Promise<SessionAssistantMessage | null> {
+    try {
+      const value = await fs.readJson(this.assistant_message_file_path) as SessionAssistantMessage;
+      this.validate_message(value);
+      if (value.type !== "assistant" || value.status !== "streaming") return null;
+      return value;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+      if (error instanceof SyntaxError) throw error;
+      throw error;
+    }
+  }
+
+  /** 原子覆盖运行中的 Assistant 草稿。 */
+  async write_assistant_message(message: SessionAssistantMessage): Promise<void> {
+    this.validate_message(message);
+    if (message.status !== "streaming") throw new Error("Assistant draft must be streaming");
+    await this.with_write_lock(async () => {
+      const current = await this.read_assistant_message();
+      if (!current || current.message_id !== message.message_id) {
+        throw new Error(`Assistant draft does not exist: ${message.message_id}`);
+      }
+      if (message.revision !== current.revision + 1) {
+        throw new Error(`Invalid Assistant draft revision: ${message.message_id}`);
+      }
+      await this.write_assistant_message_unsafe(message);
+    });
   }
 
-  /**
-   * 在跨进程文件锁内计算并追加 mutation。
-   * 发布动作必须由调用方在此 Promise 成功后执行。
-   */
-  async commit(
-    build_mutation: (state: SessionMessageCommitState) => SessionMessageMutation,
-  ): Promise<SessionMessageMutation> {
+  /** 在写锁内分配 Message sequence 并创建唯一 Assistant 草稿。 */
+  async create_assistant_message(
+    build_message: (state: SessionMessageCommitState) => SessionAssistantMessage,
+  ): Promise<SessionAssistantMessage> {
     return await this.with_write_lock(async () => {
-      const mutations = await this.read_mutations_unsafe();
-      const messages = reduce_session_messages(mutations);
-      const mutation = build_mutation({
-        commit_sequence:
-          (mutations[mutations.length - 1]?.commit_sequence || 0) + 1,
-        message_sequence:
-          messages.reduce(
-            (value, message) => Math.max(value, message.sequence + 1),
-            1,
-          ),
+      const current = await this.read_assistant_message();
+      if (current) throw new Error(`Assistant draft already exists: ${current.message_id}`);
+      const messages = await this.read_messages_unsafe();
+      const message = build_message({
+        message_sequence: messages.reduce((max, item) => Math.max(max, item.sequence + 1), 1),
         messages,
       });
-      await fs.appendFile(
-        this.messages_file_path,
-        `${JSON.stringify(mutation)}\n`,
-        "utf8",
-      );
-      return mutation;
+      this.validate_message(message);
+      if (message.status !== "streaming" || message.revision !== 1) {
+        throw new Error("New Assistant draft must be streaming at revision 1");
+      }
+      await this.write_assistant_message_unsafe(message);
+      return message;
     });
   }
 
-  private async ensure_layout(): Promise<void> {
-    await fs.ensureDir(path.dirname(this.messages_file_path));
-    await fs.ensureFile(this.messages_file_path);
+  /** 创建新 Message 或追加已有 Message revision 快照。 */
+  async append_message(
+    build_message: (state: SessionMessageCommitState) => SessionMessage,
+  ): Promise<SessionMessage> {
+    return await this.with_write_lock(async () => {
+      const messages = await this.read_messages_unsafe();
+      const draft = await this.read_assistant_message();
+      const current_messages = draft ? [...messages, draft] : messages;
+      const message = build_message({
+        message_sequence: current_messages.reduce((max, item) => Math.max(max, item.sequence + 1), 1),
+        messages: current_messages,
+      });
+      this.validate_message(message);
+      await fs.appendFile(this.messages_file_path, `${JSON.stringify(message)}\n`, "utf8");
+      return message;
+    });
+  }
+
+  /** 将 Assistant 草稿最终追加为历史快照，并删除草稿文件。 */
+  async finalize_assistant_message(message: SessionAssistantMessage): Promise<void> {
+    this.validate_message(message);
+    if (message.status === "streaming") throw new Error("Final Assistant message cannot be streaming");
+    await this.with_write_lock(async () => {
+      const current = await this.read_assistant_message();
+      if (!current || current.message_id !== message.message_id) {
+        throw new Error(`Assistant draft does not exist: ${message.message_id}`);
+      }
+      if (message.revision !== current.revision + 1) {
+        throw new Error(`Invalid final Assistant revision: ${message.message_id}`);
+      }
+      await fs.appendFile(this.messages_file_path, `${JSON.stringify(message)}\n`, "utf8");
+      await fs.remove(this.assistant_message_file_path);
+    });
   }
 
-  private async read_mutations_unsafe(): Promise<SessionMessageMutation[]> {
+  private async read_messages_unsafe(): Promise<SessionMessage[]> {
     const raw = await fs.readFile(this.messages_file_path, "utf8").catch(() => "");
-    const mutations: SessionMessageMutation[] = [];
-    const lines = raw.split("\n");
-    for (let index = 0; index < lines.length; index += 1) {
-      const line = lines[index]?.trim();
-      if (!line) continue;
-      try {
-        const mutation = JSON.parse(line) as SessionMessageMutation;
-        if (mutation.session_id !== this.session_id) {
-          throw new Error("session_id mismatch");
+    const by_id = new Map<string, SessionMessage>();
+    for (const line of raw.split("\n")) {
+      if (!line.trim()) continue;
+      const message = JSON.parse(line) as SessionMessage;
+      this.validate_message(message);
+      const previous = by_id.get(message.message_id);
+      if (!previous || message.revision > previous.revision) by_id.set(message.message_id, message);
+    }
+    return [...by_id.values()].sort((left, right) => left.sequence - right.sequence);
+  }
+
+  private async write_assistant_message_unsafe(message: SessionAssistantMessage): Promise<void> {
+    const temporary_path = `${this.assistant_message_file_path}.${process.pid}.${Date.now()}.tmp`;
+    await fs.ensureDir(path.dirname(this.assistant_message_file_path));
+    await fs.writeJson(temporary_path, message, { spaces: 2 });
+    await fs.move(temporary_path, this.assistant_message_file_path, { overwrite: true });
+  }
+
+  private validate_message(message: SessionMessage): void {
+    if (!message || typeof message !== "object") throw new Error("message must be an object");
+    if (message.session_id !== this.session_id) throw new Error("session_id mismatch");
+    if (!message.message_id || !Number.isInteger(message.sequence) || !Number.isInteger(message.revision)) {
+      throw new Error("message identity, sequence and revision are required");
+    }
+    if (message.type === "assistant") {
+      const sequences = new Set<number>();
+      for (const part of message.parts) {
+        if (!Number.isInteger(part.sequence) || sequences.has(part.sequence)) {
+          throw new Error(`invalid Assistant part sequence: ${part.part_id}`);
         }
-        mutations.push(mutation);
-      } catch (error) {
-        throw new Error(
-          `Invalid session mutation at line ${String(index + 1)}: ${error instanceof Error ? error.message : String(error)}`,
-        );
+        sequences.add(part.sequence);
       }
     }
-    return mutations;
+  }
+
+  private async ensure_layout(): Promise<void> {
+    await fs.ensureDir(path.dirname(this.messages_file_path));
+    await fs.ensureFile(this.messages_file_path);
   }
 
   private async with_write_lock<T>(callback: () => Promise<T>): Promise<T> {
@@ -130,20 +226,12 @@ export class JsonlSessionMessageStore {
         await file.close();
         break;
       } catch (error) {
-        const code = (error as NodeJS.ErrnoException).code;
-        if (code !== "EEXIST") throw error;
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
         try {
           const lock_stat = await stat(this.lock_file_path);
-          if (Date.now() - lock_stat.mtimeMs > stale_ms) {
-            await fs.remove(this.lock_file_path);
-            continue;
-          }
-        } catch {
-          continue;
-        }
-        if (Date.now() - started_at > stale_ms * 2) {
-          throw new Error(`Session message lock timeout: ${this.lock_file_path}`);
-        }
+          if (Date.now() - lock_stat.mtimeMs > stale_ms) await fs.remove(this.lock_file_path);
+        } catch { /* 锁文件可能刚被释放。 */ }
+        if (Date.now() - started_at > stale_ms * 2) throw new Error(`Session message lock timeout: ${this.lock_file_path}`);
         await new Promise((resolve) => setTimeout(resolve, 40));
       }
     }
@@ -151,12 +239,8 @@ export class JsonlSessionMessageStore {
       return await callback();
     } finally {
       try {
-        if ((await readFile(this.lock_file_path, "utf8")).trim() === token) {
-          await fs.remove(this.lock_file_path);
-        }
-      } catch {
-        // 锁文件已被清理时无需额外处理。
-      }
+        if ((await readFile(this.lock_file_path, "utf8")).trim() === token) await fs.remove(this.lock_file_path);
+      } catch { /* 锁已被清理。 */ }
     }
   }
 }