@downcity/agent 1.1.217 → 1.1.222

package/src/session/services/SessionViewService.ts

@@ -17,7 +17,7 @@ import { getSdkAgentSessionArchiveFilePath } from "@/session/storage/Paths.js";
 import { ensureSessionTitle } from "@/session/SessionTitle.js";
 import { readSessionMetadata } from "@/session/storage/Metadata.js";
 import { buildSessionSystemBlocks } from "@/session/SessionSystemBuilder.js";
-import type { JsonlSessionHistoryStore } from "@/executor/store/history/jsonl/JsonlSessionHistoryStore.js";
+import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
 import type { SessionSystemComposer } from "@/executor/composer/system/SessionSystemComposer.js";
 import type {
   AgentSessionForkInput,
@@ -32,6 +32,8 @@ import type { SessionRecordV1 } from "@/executor/types/SessionRecords.js";
 import { SessionStateService } from "@/session/services/SessionStateService.js";
 import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
 import type { Logger } from "@/utils/logger/Logger.js";
+import { SessionRecorder } from "@/session/recorder/SessionRecorder.js";
+import type { SessionMessage } from "@/types/session/SessionMessage.js";
 
 type SessionViewServiceOptions<TSession extends Pick<AgentSession, "set">> = {
   /**
@@ -52,7 +54,10 @@ type SessionViewServiceOptions<TSession extends Pick<AgentSession, "set">> = {
   /**
    * 当前 session 历史事实源。
    */
-  history_store: JsonlSessionHistoryStore;
+  history_store: SessionHistoryStore;
+
+  /** 当前 Session Message Recorder。 */
+  recorder: SessionRecorder;
 
   /**
    * 当前 session 状态服务。
@@ -98,7 +103,8 @@ type SessionViewServiceOptions<TSession extends Pick<AgentSession, "set">> = {
    */
   create_fork_session: (session_id: string) => Promise<{
     session: TSession;
-    history_store: JsonlSessionHistoryStore;
+    history_store: SessionHistoryStore;
+    recorder: SessionRecorder;
     state_service: SessionStateService;
   }>;
 };
@@ -110,7 +116,8 @@ export class SessionViewService<TSession extends Pick<AgentSession, "set">> {
   private readonly agent_id: string;
   private readonly project_root: string;
   private readonly session_id: string;
-  private readonly history_store: JsonlSessionHistoryStore;
+  private readonly history_store: SessionHistoryStore;
+  private readonly recorder: SessionRecorder;
   private readonly state_service: SessionStateService;
   private readonly logger: Logger;
   private readonly is_executing: SessionViewServiceOptions<TSession>["is_executing"];
@@ -125,6 +132,7 @@ export class SessionViewService<TSession extends Pick<AgentSession, "set">> {
     this.project_root = options.project_root;
     this.session_id = options.session_id;
     this.history_store = options.history_store;
+    this.recorder = options.recorder;
     this.state_service = options.state_service;
     this.logger = options.logger;
     this.is_executing = options.is_executing;
@@ -282,11 +290,14 @@ export class SessionViewService<TSession extends Pick<AgentSession, "set">> {
       typeof input === "string"
         ? String(input || "").trim() || undefined
         : String(input?.messageId || "").trim() || undefined;
-    const messages = await this.history_store.list_records();
+    const message_page = await this.recorder.list_messages({
+      limit: 500,
+      include_internal: true,
+    });
     const fork_messages =
       !message_id
-        ? messages
-        : this.resolve_fork_messages(messages, message_id);
+        ? message_page.items
+        : this.resolve_fork_messages(message_page.items, message_id);
     const action_id = `history-forking:${this.session_id}:${Date.now()}:${nanoid(8)}`;
 
     await this.state_service.emit_action_event({
@@ -333,11 +344,11 @@ export class SessionViewService<TSession extends Pick<AgentSession, "set">> {
   }
 
   private resolve_fork_messages(
-    messages: SessionRecordV1[],
+    messages: SessionMessage[],
     message_id: string,
-  ): SessionRecordV1[] {
+  ): SessionMessage[] {
     const target_index = messages.findIndex(
-      (message) => String(message.id || "").trim() === message_id,
+      (message) => message.message_id === message_id,
     );
     if (target_index < 0) {
       throw new Error(
@@ -349,12 +360,13 @@ export class SessionViewService<TSession extends Pick<AgentSession, "set">> {
 
   private async append_fork_messages(
     forked_bundle: {
-      history_store: JsonlSessionHistoryStore;
+      history_store: SessionHistoryStore;
+      recorder: SessionRecorder;
       state_service: SessionStateService;
     },
-    messages: SessionRecordV1[],
+    messages: SessionMessage[],
   ): Promise<void> {
-    await forked_bundle.history_store.write_records(messages);
+    await forked_bundle.recorder.import_messages(messages);
   }
 
   private stringify_system_content(content: unknown): string {

package/src/session/storage/Persistence.ts

@@ -39,6 +39,12 @@ export interface TouchSessionMetadataParams {
    * 当前 session 内存配置快照。
    */
   sessionConfig: AgentSessionConfigSnapshot;
+  /** 当前 canonical Message 总数。 */
+  message_count?: number;
+  /** 当前 Message 日志文件字节数。 */
+  history_bytes?: number;
+  /** 最近一条用户可见 Message 的文本摘要。 */
+  preview_text?: string;
 }
 
 /**
@@ -98,6 +104,13 @@ export async function touchSessionMetadata(
           modelId: params.sessionConfig.modelId,
         }
       : {}),
+    ...(typeof params.message_count === "number"
+      ? { messageCount: params.message_count }
+      : {}),
+    ...(typeof params.history_bytes === "number"
+      ? { historyBytes: params.history_bytes }
+      : {}),
+    ...(params.preview_text ? { previewText: params.preview_text } : {}),
   };
   await writeSessionMetadata({
     projectRoot: params.projectRoot,

package/src/session/storage/RuntimeSessionPort.ts

@@ -12,9 +12,11 @@ import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js"
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type {
   AgentSessionEvent,
-  AgentSessionSubscriber,
-  AgentSessionUnsubscribe,
 } from "@/types/sdk/AgentSessionEvent.js";
+import type {
+  SessionMessageMutationSubscriber,
+  SessionMessageMutationUnsubscribe,
+} from "@/types/session/SessionMessageMutation.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
 
 /**
@@ -41,8 +43,8 @@ export interface CreateRuntimeSessionPortParams {
    * 订阅当前 session 的 future 事件。
    */
   subscribe: (
-    subscriber: AgentSessionSubscriber,
-  ) => AgentSessionUnsubscribe;
+    subscriber: SessionMessageMutationSubscriber,
+  ) => SessionMessageMutationUnsubscribe;
   /**
    * 发布一条 session runtime 事件。
    */

package/src/types/agent/SessionActor.ts

@@ -16,8 +16,6 @@ import type {
   AgentListSessionsInput,
   AgentSessionConfigSnapshot,
   AgentSessionForkInput,
-  AgentSessionRecordsInput,
-  AgentSessionRecordsPage,
   AgentSessionInfo,
   AgentSessionSetInput,
   AgentSessionSummaryPage,
@@ -27,6 +25,16 @@ import type {
   AgentSessionSubscriber,
   AgentSessionUnsubscribe,
 } from "@/types/sdk/AgentSessionEvent.js";
+import type {
+  ListSessionMessageChangesInput,
+  SessionMessageMutationPage,
+  SessionMessageMutationSubscriber,
+  SessionMessageMutationUnsubscribe,
+} from "@/types/session/SessionMessageMutation.js";
+import type {
+  ListSessionMessagesInput,
+  SessionMessagePage,
+} from "@/types/session/SessionMessage.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
@@ -71,10 +79,22 @@ export interface AgentSessionActor {
   stop(): Promise<AgentSessionStopResult>;
 
   /** 订阅当前 session 的未来事件。 */
-  subscribe(subscriber: AgentSessionSubscriber): AgentSessionUnsubscribe;
-
-  /** 读取当前 session records 分页。 */
-  records(input?: AgentSessionRecordsInput): Promise<AgentSessionRecordsPage>;
+  subscribe(
+    subscriber: SessionMessageMutationSubscriber,
+  ): SessionMessageMutationUnsubscribe;
+
+  /** 订阅远程 transport 使用的 Message 与 turn lifecycle 事件。 */
+  subscribe_transport(
+    subscriber: AgentSessionSubscriber,
+  ): AgentSessionUnsubscribe;
+
+  /** 读取当前 session messages 分页。 */
+  messages(input?: ListSessionMessagesInput): Promise<SessionMessagePage>;
+
+  /** 读取指定 cursor 后的 Message Mutation。 */
+  message_changes(
+    input: ListSessionMessageChangesInput,
+  ): Promise<SessionMessageMutationPage>;
 
   /** 读取当前 session 生效的 system 快照。 */
   system(): Promise<AgentSessionSystemSnapshot>;

package/src/types/rpc/RpcProtocol.ts

@@ -15,13 +15,14 @@ import type {
   AgentArchiveSessionResult,
   AgentArchiveSessionsResult,
   AgentCleanArchiveResult,
-  AgentSessionRecordsInput,
   AgentSessionSystemSnapshot,
   AgentSessionSetInput,
 } from "@/types/agent/SessionTypes.js";
 import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
+import type { ListSessionMessagesInput } from "@/types/session/SessionMessage.js";
+import type { ListSessionMessageChangesInput } from "@/types/session/SessionMessageMutation.js";
 import type { JsonObject, JsonValue } from "@/types/common/Json.js";
 import type { PluginControlAction } from "@/types/plugin/PluginState.js";
 import type { ShellApprovalMode } from "@downcity/shell";
@@ -126,14 +127,27 @@ export type RpcRequest =
   | {
       /** 请求 id，用于匹配响应。 */
       id: string;
-      /** 读取 session records。 */
-      method: "sdk.sessions.records";
-      /** records 查询参数。 */
+      /** 读取 session messages。 */
+      method: "sdk.sessions.messages";
+      /** messages 查询参数。 */
       params: {
         /** 目标 session id。 */
         sessionId: string;
-        /** records 分页与视图参数。 */
-        input?: AgentSessionRecordsInput;
+        /** messages 分页参数。 */
+        input?: ListSessionMessagesInput;
+      };
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 读取 session message mutations。 */
+      method: "sdk.sessions.message_changes";
+      /** changes 查询参数。 */
+      params: {
+        /** 目标 session id。 */
+        sessionId: string;
+        /** Mutation 增量参数。 */
+        input: ListSessionMessageChangesInput;
       };
     }
   | {

package/src/types/runtime/agent/AgentContext.ts

@@ -33,6 +33,10 @@ import type {
   AgentSessionSubscriber,
   AgentSessionUnsubscribe,
 } from "@/types/sdk/AgentSessionEvent.js";
+import type {
+  SessionMessageMutationSubscriber,
+  SessionMessageMutationUnsubscribe,
+} from "@/types/session/SessionMessageMutation.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
 
 /**
@@ -133,9 +137,11 @@ export interface SessionPort {
    *
    * 关键点（中文）
    * - 只广播订阅之后产生的事件。
-   * - session records 仍通过 `getHistoryStore()` / SDK `records()` 读取。
+   * - 当前 Message snapshot 通过公开 SDK `session.messages()` 读取。
    */
-  subscribe(subscriber: AgentSessionSubscriber): AgentSessionUnsubscribe;
+  subscribe(
+    subscriber: SessionMessageMutationSubscriber,
+  ): SessionMessageMutationUnsubscribe;
   /**
    * 发布一条 session runtime 事件。
    *

package/src/types/sdk/AgentSessionEvent.ts

@@ -9,6 +9,7 @@
 import type { JsonValue } from "@/types/common/Json.js";
 import type { SessionAssistantStepVisibility } from "@/executor/types/SessionRun.js";
 import type { AgentSessionActionEvent } from "@/types/sdk/AgentSessionAction.js";
+import type { SessionMessageMutation } from "@/types/session/SessionMessageMutation.js";
 
 /**
  * 单个 turn 开始事件。
@@ -346,6 +347,7 @@ export interface AgentSessionErrorEvent {
  * Session 订阅可见事件联合类型。
  */
 export type AgentSessionEvent =
+  | SessionMessageMutation
   | AgentSessionTurnStartEvent
   | AgentSessionTextDeltaEvent
   | AgentSessionReasoningDeltaEvent

package/src/types/session/SessionMessage.ts

@@ -0,0 +1,247 @@
+/**
+ * Session canonical 消息类型。
+ *
+ * Session 只维护一条由 sequence 排序的消息序列；assistant 的 text、reasoning、tool、file
+ * 均为内部 part，不提升为顶层消息。
+ */
+
+import type { JsonObject, JsonValue } from "@/types/common/Json.js";
+
+/** Message 默认展示范围。 */
+export type SessionMessageVisibility = "visible" | "internal";
+
+/** 从其他 Session 导入时保留的来源身份。 */
+export interface SessionMessageOrigin {
+  /** 来源 Session 标识。 */
+  session_id: string;
+  /** 来源 Message 标识。 */
+  message_id: string;
+  /** 来源 turn 标识。 */
+  turn_id?: string;
+}
+
+/** Session Message 公共字段。 */
+export interface SessionMessageBase {
+  /** 当前 Message 在 Session 内的稳定唯一标识。 */
+  message_id: string;
+  /** 当前 Message 所属 Session 标识。 */
+  session_id: string;
+  /** 当前 Message 所属 turn；独立 action 可以省略。 */
+  turn_id?: string;
+  /** Message 的线性位置；创建后永远不变。 */
+  sequence: number;
+  /** Message 版本号；每次 Mutation 后递增。 */
+  revision: number;
+  /** 当前 Message 是否默认对用户可见。 */
+  visibility: SessionMessageVisibility;
+  /** Message 首次创建时间戳（ms）。 */
+  created_at: number;
+  /** Message 最近更新时间戳（ms）。 */
+  updated_at: number;
+  /** 从其他 Session 导入时的来源信息。 */
+  origin?: SessionMessageOrigin;
+}
+
+/** User 文本 part。 */
+export interface SessionUserTextPart {
+  /** User Message 内稳定的 part 标识。 */
+  part_id: string;
+  /** part 类型固定为 text。 */
+  type: "text";
+  /** 用户输入文本。 */
+  text: string;
+  /** User 文本已经完整，不参与流式更新。 */
+  state: "done";
+}
+
+/** User 文件 part。 */
+export interface SessionUserFilePart {
+  /** User Message 内稳定的 part 标识。 */
+  part_id: string;
+  /** part 类型固定为 file。 */
+  type: "file";
+  /** 文件可读取地址或 data URL。 */
+  url: string;
+  /** 文件 MIME 类型。 */
+  media_type: string;
+  /** 可选原始文件名。 */
+  filename?: string;
+}
+
+/** User 结构化数据 part。 */
+export interface SessionUserDataPart {
+  /** User Message 内稳定的 part 标识。 */
+  part_id: string;
+  /** part 类型固定为 data。 */
+  type: "data";
+  /** 对应 AI SDK 的 data-* 类型名称。 */
+  data_type: `data-${string}` | string;
+  /** 可 JSON 序列化的数据。 */
+  data: JsonValue;
+}
+
+/** User Message part。 */
+export type SessionUserMessagePart =
+  | SessionUserTextPart
+  | SessionUserFilePart
+  | SessionUserDataPart;
+
+/** User 顶层 Message。 */
+export interface SessionUserMessage extends SessionMessageBase {
+  /** Message 类型固定为 user。 */
+  type: "user";
+  /** 普通 prompt 或当前 turn 中的 steering 输入。 */
+  input_type: "prompt" | "steer";
+  /** 用户消息的结构化 parts。 */
+  parts: SessionUserMessagePart[];
+}
+
+/** Assistant 文本或推理 part。 */
+export interface SessionAssistantTextPart {
+  /** Assistant Message 内稳定的 part 标识。 */
+  part_id: string;
+  /** part 是可见文本或推理文本。 */
+  type: "text" | "reasoning";
+  /** 当前已经累计的完整文本。 */
+  text: string;
+  /** 文本 part 是否已经结束。 */
+  state: "streaming" | "done";
+}
+
+/** Assistant 工具 part。 */
+export interface SessionAssistantToolPart {
+  /** Assistant Message 内稳定的 part 标识。 */
+  part_id: string;
+  /** part 类型固定为 tool。 */
+  type: "tool";
+  /** 模型工具调用稳定标识。 */
+  tool_call_id: string;
+  /** 工具注册名称。 */
+  tool_name: string;
+  /** 工具当前生命周期状态。 */
+  state: "input-streaming" | "approval-required" | "running" | "completed" | "failed";
+  /** 流式接收中的参数原文。 */
+  input_text?: string;
+  /** 收敛后的结构化输入。 */
+  input?: JsonValue;
+  /** 工具成功输出。 */
+  output?: JsonValue;
+  /** 工具失败信息。 */
+  error?: string;
+  /** 工具审批请求标识。 */
+  approval_id?: string;
+}
+
+/** Assistant 文件 part。 */
+export interface SessionAssistantFilePart {
+  /** Assistant Message 内稳定的 part 标识。 */
+  part_id: string;
+  /** part 类型固定为 file。 */
+  type: "file";
+  /** 文件 MIME 类型。 */
+  media_type: string;
+  /** 文件可读取地址或 data URL。 */
+  url: string;
+  /** 可选原始文件名。 */
+  filename?: string;
+}
+
+/** Assistant 结构化数据 part。 */
+export interface SessionAssistantDataPart {
+  /** Assistant Message 内稳定的 part 标识。 */
+  part_id: string;
+  /** part 类型固定为 data。 */
+  type: "data";
+  /** 对应 AI SDK 的 data-* 类型名称。 */
+  data_type: `data-${string}` | string;
+  /** 可 JSON 序列化的数据。 */
+  data: JsonValue;
+}
+
+/** Assistant Message part。 */
+export type SessionAssistantMessagePart =
+  | SessionAssistantTextPart
+  | SessionAssistantToolPart
+  | SessionAssistantFilePart
+  | SessionAssistantDataPart;
+
+/** Assistant 顶层 Message。 */
+export interface SessionAssistantMessage extends SessionMessageBase {
+  /** Message 类型固定为 assistant。 */
+  type: "assistant";
+  /** 普通 assistant segment 或内部 compact summary。 */
+  kind: "normal" | "summary";
+  /** Assistant 在所属 turn 内的 segment 序号，从一开始。 */
+  segment_index: number;
+  /** Assistant 当前执行状态。 */
+  status: "streaming" | "completed" | "stopped" | "failed";
+  /** Assistant 内按真实生成顺序保存的 parts。 */
+  parts: SessionAssistantMessagePart[];
+  /** Summary 已覆盖到的来源 Message 标识。 */
+  summary_through_message_id?: string;
+}
+
+/** Action 顶层 Message。 */
+export interface SessionActionMessage extends SessionMessageBase {
+  /** Message 类型固定为 action。 */
+  type: "action";
+  /** Action 业务类型。 */
+  action_type: string;
+  /** Action 当前状态。 */
+  status: "running" | "completed" | "failed";
+  /** Action 展示标题。 */
+  title: string;
+  /** Action 展示描述。 */
+  description?: string;
+  /** Action 附加结构化信息。 */
+  data?: JsonObject;
+}
+
+/** Error 顶层 Message。 */
+export interface SessionErrorMessage extends SessionMessageBase {
+  /** Message 类型固定为 error。 */
+  type: "error";
+  /** 错误影响范围。 */
+  scope: "session" | "turn";
+  /** 稳定错误码。 */
+  code: string;
+  /** 用户可见错误信息。 */
+  message: string;
+  /** 当前错误是否允许重试恢复。 */
+  recoverable: boolean;
+}
+
+/** Session 唯一顶层 Message 联合类型。 */
+export type SessionMessage =
+  | SessionUserMessage
+  | SessionAssistantMessage
+  | SessionActionMessage
+  | SessionErrorMessage;
+
+/** 读取 Session Message snapshot 的分页输入。 */
+export interface ListSessionMessagesInput {
+  /** 单页数量上限。 */
+  limit?: number;
+  /** 上一页返回的透明游标。 */
+  cursor?: string;
+  /** 只返回 sequence 严格小于该值的 Message，供向前翻页。 */
+  before_sequence?: number;
+  /** 是否包含 internal Message。 */
+  include_internal?: boolean;
+  /** 只返回不大于该 sequence 的 Message。 */
+  through_sequence?: number;
+}
+
+/** Session Message snapshot 分页结果。 */
+export interface SessionMessagePage {
+  /** 当前页按 sequence 升序排列的 Message。 */
+  items: SessionMessage[];
+  /** 当前过滤条件下的 Message 总数。 */
+  total: number;
+  /** 下一页透明游标。 */
+  next_cursor?: string;
+  /** 是否仍有更多 Message。 */
+  has_more: boolean;
+  /** 当前 snapshot 已包含的最大 commit_sequence。 */
+  latest_commit_sequence: number;
+}

package/src/types/session/SessionMessageMutation.ts

@@ -0,0 +1,121 @@
+/**
+ * Session Message Mutation 与增量读取类型。
+ *
+ * Mutation 只按变化层级分成 message、part、delta 三种 variant；`type` 在各 variant
+ * 内直接表达对应的 Message 或 Part 类型。
+ */
+
+import type { SessionAssistantMessagePart, SessionMessage } from "@/types/session/SessionMessage.js";
+
+/** Mutation 公共字段。 */
+export interface SessionMessageMutationBase {
+  /** Mutation 稳定唯一标识。 */
+  mutation_id: string;
+  /** Mutation 在 Session 内的单调提交序号。 */
+  commit_sequence: number;
+  /** Mutation 目标 Message。 */
+  message_id: string;
+  /** 应用 Mutation 后的 Message revision。 */
+  revision: number;
+  /** Mutation 所属 Session。 */
+  session_id: string;
+  /** Mutation 所属 turn。 */
+  turn_id?: string;
+  /** Mutation 创建时间戳（ms）。 */
+  created_at: number;
+}
+
+/** 顶层 Message 创建或状态更新 Mutation。 */
+export type SessionMessageSnapshotMutation = {
+  [TType in SessionMessage["type"]]: SessionMessageMutationBase & {
+    /** Mutation 层级固定为 message。 */
+    variant: "message";
+    /** 当前完整 Message 类型。 */
+    type: TType;
+    /** Message 在线性 Session 中的固定位置。 */
+    sequence: number;
+    /** 创建或更新后的完整 Message 快照。 */
+    message: Extract<SessionMessage, { type: TType }>;
+  };
+}[SessionMessage["type"]];
+
+/** Assistant Part 创建或状态更新 Mutation。 */
+export type SessionPartSnapshotMutation = {
+  [TType in SessionAssistantMessagePart["type"]]: SessionMessageMutationBase & {
+    /** Mutation 层级固定为 part。 */
+    variant: "part";
+    /** 当前完整 Part 类型。 */
+    type: TType;
+    /** 被创建或更新的 Part 标识。 */
+    part_id: string;
+    /** 创建或更新后的完整 Part 快照。 */
+    part: SessionAssistantMessagePart & { type: TType };
+  };
+}[SessionAssistantMessagePart["type"]];
+
+/** Assistant 文本或推理原始增量 Mutation。 */
+export interface SessionDeltaMutation extends SessionMessageMutationBase {
+  /** Mutation 层级固定为 delta。 */
+  variant: "delta";
+  /** Delta 类型只允许 text 或 reasoning。 */
+  type: "text" | "reasoning";
+  /** Delta 所属 Part 标识。 */
+  part_id: string;
+  /** 本次模型新增的原始文本，不是累计全文。 */
+  delta: string;
+}
+
+/** 全部合法 Session Message Mutation。 */
+export type SessionMessageMutation =
+  | SessionMessageSnapshotMutation
+  | SessionPartSnapshotMutation
+  | SessionDeltaMutation;
+
+/** 从 commit cursor 增量读取 Mutation 的输入。 */
+export interface ListSessionMessageChangesInput {
+  /** 只返回 commit_sequence 严格大于该值的 Mutation。 */
+  after_commit_sequence: number;
+  /** 单页数量上限。 */
+  limit?: number;
+}
+
+/** Mutation 增量分页结果。 */
+export interface SessionMessageMutationPage {
+  /** 当前页按 commit_sequence 升序排列的 Mutation。 */
+  items: SessionMessageMutation[];
+  /** 当前页之后是否仍有 Mutation。 */
+  has_more: boolean;
+  /** 下一次增量读取应使用的 commit_sequence。 */
+  next_commit_sequence: number;
+  /** 当前 Session 已提交的最大 commit_sequence。 */
+  latest_commit_sequence: number;
+}
+
+/** Session Mutation 订阅回调。 */
+export type SessionMessageMutationSubscriber = (mutation: SessionMessageMutation) => void;
+
+/** 取消 Session Mutation 订阅的函数。 */
+export type SessionMessageMutationUnsubscribe = () => void;
+
+/** 判断未知事件是否为 Session Message Mutation。 */
+export function is_session_message_mutation(input: unknown): input is SessionMessageMutation {
+  if (!input || typeof input !== "object") return false;
+  const candidate = input as {
+    variant?: unknown;
+    type?: unknown;
+    mutation_id?: unknown;
+    commit_sequence?: unknown;
+  };
+  if (
+    typeof candidate.mutation_id !== "string" ||
+    typeof candidate.commit_sequence !== "number" ||
+    typeof candidate.type !== "string"
+  ) {
+    return false;
+  }
+  return (
+    candidate.variant === "message" ||
+    candidate.variant === "part" ||
+    candidate.variant === "delta"
+  );
+}