@downcity/agent 1.1.216 → 1.1.222

package/scripts/session-recorder.test.mjs

@@ -0,0 +1,245 @@
+/**
+ * @file 验证 SessionRecorder 单一 Mutation 日志与实时/历史一致性。
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { JsonlSessionMessageStore } from "../bin/session/recorder/JsonlSessionMessageStore.js";
+import { SessionRecorder } from "../bin/session/recorder/SessionRecorder.js";
+import { SessionRecorderHistoryStore } from "../bin/session/recorder/SessionRecorderHistoryStore.js";
+import { MockLanguageModelV3 } from "ai/test";
+
+async function create_recorder(session_id = "session-recorder-test") {
+  const root_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-session-recorder-"),
+  );
+  const file_path = path.join(root_path, "messages.jsonl");
+  const events = [];
+  const recorder = new SessionRecorder({
+    session_id,
+    store: new JsonlSessionMessageStore({ session_id, file_path }),
+    publish: (mutation) => events.push(mutation),
+  });
+  await recorder.initialize();
+  return { recorder, events, file_path };
+}
+
+test("每个 assistant delta 都先持久化为独立 Mutation 再发布", async () => {
+  const { recorder, events, file_path } = await create_recorder();
+  await recorder.append_user_message({
+    turn_id: "turn-1",
+    input_type: "prompt",
+    parts: [{
+      part_id: "user-text-1",
+      type: "text",
+      text: "你好",
+      state: "done",
+    }],
+  });
+  const writer = await recorder.open_assistant_message({
+    turn_id: "turn-1",
+    segment_index: 1,
+  });
+  await writer.apply_chunk({ type: "text-start", id: "text-1" });
+  await writer.apply_chunk({ type: "text-delta", id: "text-1", delta: "你" });
+  await writer.apply_chunk({ type: "text-delta", id: "text-1", delta: "好" });
+  await writer.apply_chunk({ type: "text-end", id: "text-1" });
+  await writer.complete();
+
+  const changes = await recorder.list_message_changes({
+    after_commit_sequence: 0,
+  });
+  const persisted_lines = (await fs.readFile(file_path, "utf8"))
+    .trim()
+    .split("\n");
+  assert.equal(persisted_lines.length, changes.items.length);
+  assert.deepEqual(
+    changes.items.map((item) => item.commit_sequence),
+    events.map((item) => item.commit_sequence),
+  );
+  assert.deepEqual(
+    changes.items.map((item) => `${item.variant}:${item.type}`),
+    [
+      "message:user",
+      "message:assistant",
+      "part:text",
+      "delta:text",
+      "delta:text",
+      "part:text",
+      "message:assistant",
+    ],
+  );
+  assert.deepEqual(
+    changes.items
+      .filter((item) => item.variant === "delta")
+      .map((item) => item.delta),
+    ["你", "好"],
+  );
+
+  const page = await recorder.list_messages();
+  assert.deepEqual(page.items.map((item) => item.type), ["user", "assistant"]);
+  const assistant = page.items[1];
+  assert.equal(assistant.status, "completed");
+  assert.equal(assistant.parts[0].text, "你好");
+});
+
+test("tool 与 action 在原 Message 和 part 上更新", async () => {
+  const { recorder } = await create_recorder("tool-action-test");
+  const writer = await recorder.open_assistant_message({
+    turn_id: "turn-1",
+    segment_index: 1,
+  });
+  await writer.apply_chunk({
+    type: "tool-input-start",
+    toolCallId: "call-1",
+    toolName: "search",
+  });
+  await writer.apply_chunk({
+    type: "tool-input-available",
+    toolCallId: "call-1",
+    toolName: "search",
+    input: { query: "downcity" },
+  });
+  await writer.apply_chunk({
+    type: "tool-output-available",
+    toolCallId: "call-1",
+    output: { count: 1 },
+  });
+  await writer.complete();
+
+  const action = await recorder.open_action_message({
+    message_id: "action-1",
+    action_type: "compact",
+    title: "Compacting",
+  });
+  const running = recorder.get_message("action-1");
+  await action.complete({ title: "Compacted" });
+  const completed = recorder.get_message("action-1");
+
+  const assistant = (await recorder.list_messages()).items[0];
+  assert.equal(assistant.parts.length, 1);
+  assert.equal(assistant.parts[0].state, "completed");
+  assert.deepEqual(assistant.parts[0].output, { count: 1 });
+  assert.equal(running.sequence, completed.sequence);
+  assert.equal(completed.revision, running.revision + 1);
+  assert.equal(completed.status, "completed");
+});
+
+test("snapshot、changes 分页和重启恢复保持单调顺序", async () => {
+  const { recorder, file_path } = await create_recorder("recovery-test");
+  await recorder.append_user_message({
+    turn_id: "turn-1",
+    input_type: "prompt",
+    parts: [{ part_id: "u1", type: "text", text: "one", state: "done" }],
+  });
+  await recorder.open_assistant_message({
+    turn_id: "turn-1",
+    segment_index: 1,
+  });
+  await recorder.open_action_message({
+    message_id: "running-action",
+    action_type: "fork",
+    title: "Forking",
+  });
+
+  const recovered_events = [];
+  const recovered = new SessionRecorder({
+    session_id: "recovery-test",
+    store: new JsonlSessionMessageStore({
+      session_id: "recovery-test",
+      file_path,
+    }),
+    publish: (mutation) => recovered_events.push(mutation),
+  });
+  await recovered.initialize();
+
+  const first_page = await recovered.list_messages({ limit: 2 });
+  const second_page = await recovered.list_messages({
+    limit: 2,
+    cursor: first_page.next_cursor,
+  });
+  assert.equal(first_page.items.length, 2);
+  assert.equal(second_page.items.length, 1);
+  assert.ok(first_page.items[1].sequence < second_page.items[0].sequence);
+
+  const messages = [...first_page.items, ...second_page.items];
+  assert.equal(messages[1].status, "stopped");
+  assert.equal(messages[2].status, "failed");
+  assert.deepEqual(
+    recovered_events.map((item) => `${item.variant}:${item.type}`),
+    ["message:assistant", "message:action"],
+  );
+
+  const first_changes = await recovered.list_message_changes({
+    after_commit_sequence: 0,
+    limit: 2,
+  });
+  const next_changes = await recovered.list_message_changes({
+    after_commit_sequence: first_changes.next_commit_sequence,
+    limit: 100,
+  });
+  assert.equal(first_changes.has_more, true);
+  assert.ok(
+    first_changes.items.at(-1).commit_sequence <
+      next_changes.items[0].commit_sequence,
+  );
+});
+
+test("compact 追加 internal summary 且不重写 Mutation 日志", async () => {
+  const { recorder, file_path } = await create_recorder("compact-test");
+  for (let index = 1; index <= 6; index += 1) {
+    await recorder.append_user_message({
+      turn_id: `turn-${String(index)}`,
+      input_type: "prompt",
+      parts: [{
+        part_id: `user-${String(index)}`,
+        type: "text",
+        text: `message ${String(index)}`,
+        state: "done",
+      }],
+    });
+  }
+  const before = await fs.readFile(file_path, "utf8");
+  const history_store = new SessionRecorderHistoryStore({
+    session_id: "compact-test",
+    recorder,
+  });
+  const model = new MockLanguageModelV3({
+    modelId: "compact-model",
+    doGenerate: async () => ({
+      content: [{ type: "text", text: "Compact summary" }],
+      finishReason: { unified: "stop", raw: "stop" },
+      usage: {
+        inputTokens: { total: 0, noCache: 0, cacheRead: 0, cacheWrite: 0 },
+        outputTokens: { total: 0, text: 0, reasoning: 0 },
+      },
+      warnings: [],
+    }),
+  });
+  const result = await history_store.compact({
+    model,
+    system: [],
+    keepLastMessages: 2,
+    maxInputTokensApprox: 1,
+    archiveOnCompact: false,
+    compactRatio: 0.5,
+  });
+  assert.equal(result.compacted, true);
+
+  const after = await fs.readFile(file_path, "utf8");
+  assert.equal(after.startsWith(before), true);
+  const all = await recorder.list_messages({
+    limit: 100,
+    include_internal: true,
+  });
+  const summary = all.items.find(
+    (message) => message.type === "assistant" && message.kind === "summary",
+  );
+  assert.equal(summary.visibility, "internal");
+  assert.equal(summary.summary_through_message_id, all.items[2].message_id);
+  assert.equal((await history_store.list_records()).length, 4);
+});

package/scripts/session-title-event.test.mjs

@@ -110,11 +110,13 @@ test("Session keeps title empty when no model is available", async () => {
       text: "Use shell tools to inspect the current workspace",
     });
 
-    const title_event = events.find((event) => event.type === "session-title");
-    assert.equal(title_event, undefined);
-
-    const records = await session.records();
-    assert.equal(records.session.title, undefined);
+    assert.equal(
+      events.some(
+        (event) => event.variant === "message" && event.type === "user",
+      ),
+      true,
+    );
+    assert.equal((await session.get_info()).title, undefined);
   } finally {
     unsubscribe();
     await agent.dispose();
@@ -137,8 +139,7 @@ test("Session logs title generation failure without blocking the session", async
       text: "Diagnose why session title generation is flaky",
     });
 
-    const records = await session.records();
-    assert.equal(records.session.title, undefined);
+    assert.equal((await session.get_info()).title, undefined);
 
     await agent.getLogger().saveAllLogs();
     const log_lines = await read_log_lines(agent_path);
@@ -185,8 +186,7 @@ test("Session retries title generation after model becomes available", async ()
       text: "Investigate flaky session title generation in the SDK",
     });
 
-    const history_before_model = await session.records();
-    assert.equal(history_before_model.session.title, undefined);
+    assert.equal((await session.get_info()).title, undefined);
 
     await session.set({
       model: create_mock_title_model("排查 session 标题"),
@@ -195,15 +195,7 @@ test("Session retries title generation after model becomes available", async ()
       text: "Need another prompt to trigger the retry path",
     });
 
-    const title_event = events.find((event) => event.type === "session-title");
-    assert.deepEqual(title_event, {
-      type: "session-title",
-      sessionId: session.id,
-      title: "排查 session 标题",
-    });
-
-    const records = await session.records();
-    assert.equal(records.session.title, "排查 session 标题");
+    assert.equal((await session.get_info()).title, "排查 session 标题");
   } finally {
     unsubscribe();
     await agent.dispose();

package/src/agent/local/Agent.ts

@@ -47,6 +47,8 @@ export class Agent {
   private readonly config: DowncityConfig;
   private readonly env: Record<string, string>;
   private readonly defaultModel?: AgentModel;
+  private readonly default_model_id?: string;
+  private readonly resolve_model?: AgentOptions["resolve_model"];
   private readonly SessionClass: AgentOptions["Session"];
   private readonly backgroundService: AgentBackgroundService;
   private readonly shell?: AgentOptions["shell"];
@@ -55,6 +57,8 @@ export class Agent {
 
   constructor(options: AgentOptions) {
     this.defaultModel = options.model;
+    this.default_model_id = String(options.model_id || "").trim() || undefined;
+    this.resolve_model = options.resolve_model;
     this.SessionClass = options.Session;
     let sessions_ref: LocalAgentSessions | null = null;
     const assembly_service = new AgentAssemblyService({
@@ -261,6 +265,8 @@ export class Agent {
         await this.backgroundService.ready();
       },
       default_model: this.defaultModel,
+      default_model_id: this.default_model_id,
+      resolve_model: this.resolve_model,
       SessionClass: this.SessionClass,
     });
   }

package/src/agent/local/services/AgentSessions.ts

@@ -92,6 +92,12 @@ type AgentSessionsOptions = {
    */
   default_model?: AgentModel;
 
+  /** 当前默认模型的稳定 ID。 */
+  default_model_id?: string;
+
+  /** 按稳定 ID 解析 Session 模型。 */
+  resolve_model?: (model_id: string) => Promise<AgentModel>;
+
   /**
    * 当前 agent 使用的本地 Session 类。
    */
@@ -110,6 +116,8 @@ export class AgentSessions implements AgentSessionsApi<AgentSession> {
   private readonly get_instruction: AgentSessionsOptions["get_instruction"];
   private readonly ensure_agent_ready: AgentSessionsOptions["ensure_agent_ready"];
   private readonly default_model?: AgentModel;
+  private readonly default_model_id?: string;
+  private readonly resolve_model?: AgentSessionsOptions["resolve_model"];
   private readonly SessionClass: AgentSessionConstructor;
   private readonly sessions_by_id = new Map<string, AgentManagedSession>();
   private readonly configured_session_ids = new Set<string>();
@@ -123,6 +131,8 @@ export class AgentSessions implements AgentSessionsApi<AgentSession> {
     this.get_instruction = options.get_instruction;
     this.ensure_agent_ready = options.ensure_agent_ready;
     this.default_model = options.default_model;
+    this.default_model_id = options.default_model_id;
+    this.resolve_model = options.resolve_model;
     this.SessionClass = options.SessionClass || Session;
   }
 
@@ -337,6 +347,7 @@ export class AgentSessions implements AgentSessionsApi<AgentSession> {
         await this.ensure_agent_ready();
         await this.apply_session_defaults(session);
       },
+      ...(this.resolve_model ? { resolve_model: this.resolve_model } : {}),
     });
     this.sessions_by_id.set(resolved_session_id, created);
     return created;
@@ -346,9 +357,11 @@ export class AgentSessions implements AgentSessionsApi<AgentSession> {
     session: AgentManagedSession,
   ): Promise<void> {
     if (this.configured_session_ids.has(session.id)) return;
-    if (this.default_model) {
+    const persisted_model_id = String(session.config.modelId || "").trim();
+    if (!persisted_model_id && this.default_model) {
       await session.set({
         model: this.default_model,
+        ...(this.default_model_id ? { modelId: this.default_model_id } : {}),
       });
     }
     this.configured_session_ids.add(session.id);

package/src/agent/remote/RemoteSession.ts

@@ -9,8 +9,6 @@
 import type {
   AgentSessionConfigSnapshot,
   AgentSessionForkInput,
-  AgentSessionRecordsInput,
-  AgentSessionRecordsPage,
   AgentSessionInfo,
   AgentSessionSetInput,
   AgentSessionSystemSnapshot,
@@ -28,6 +26,17 @@ import type {
   AgentSessionTurnHandle,
   AgentSessionTurnResult,
 } from "@/types/sdk/AgentSessionTurn.js";
+import type {
+  ListSessionMessagesInput,
+  SessionMessagePage,
+} from "@/types/session/SessionMessage.js";
+import {
+  is_session_message_mutation,
+  type ListSessionMessageChangesInput,
+  type SessionMessageMutationPage,
+  type SessionMessageMutationSubscriber,
+  type SessionMessageMutationUnsubscribe,
+} from "@/types/session/SessionMessageMutation.js";
 import { SessionEventHub } from "@/session/runtime/SessionEventHub.js";
 import type {
   RemoteSessionTransport,
@@ -71,17 +80,25 @@ export class RemoteSession implements RemoteAgentSession {
     this.transport = transport;
     this.id = info.sessionId;
     this.agentId = info.agentId;
-    // 远程 session 不暴露服务端模型实例，config 返回空快照。
-    this.config = {} as AgentSessionConfigSnapshot;
+    // 远程 session 不暴露服务端模型实例，只保留可序列化配置。
+    this.config = {
+      ...(info.modelId ? { modelId: info.modelId } : {}),
+      ...(info.modelLabel ? { modelLabel: info.modelLabel } : {}),
+    };
   }
 
-  /**
-   * 远程 session 当前不支持直接注入本地模型实例。
-   */
-  async set(_input: AgentSessionSetInput): Promise<void> {
-    throw new Error(
-      "Remote session.set({ model }) is not supported in v1. Configure the model on the server-side local Agent session instead.",
-    );
+  /** 按稳定模型 ID 更新远程 Session 模型。 */
+  async set(input: AgentSessionSetInput): Promise<void> {
+    if (input.model) {
+      throw new Error("Remote session.set does not accept a local model instance.");
+    }
+    const model_id = String(input.modelId || "").trim();
+    if (!model_id) {
+      throw new Error("Remote session.set requires modelId.");
+    }
+    const info = await this.transport.set(this.id, { modelId: model_id });
+    this.config.modelId = info.modelId;
+    this.config.modelLabel = info.modelLabel;
   }
 
   /**
@@ -116,7 +133,9 @@ export class RemoteSession implements RemoteAgentSession {
   /**
    * 订阅当前远程 session 的 future 事件。
    */
-  subscribe(subscriber: AgentSessionSubscriber): AgentSessionUnsubscribe {
+  subscribe(
+    subscriber: SessionMessageMutationSubscriber,
+  ): SessionMessageMutationUnsubscribe {
     this.event_subscriber_count += 1;
     void this.ensure_event_pump().catch((error) => {
       this.event_hub.publish({
@@ -124,7 +143,9 @@ export class RemoteSession implements RemoteAgentSession {
         message: error instanceof Error ? error.message : String(error),
       });
     });
-    const unsubscribe = this.event_hub.subscribe(subscriber);
+    const unsubscribe = this.event_hub.subscribe((event) => {
+      if (is_session_message_mutation(event)) subscriber(event);
+    });
     return () => {
       unsubscribe();
       this.event_subscriber_count = Math.max(0, this.event_subscriber_count - 1);
@@ -132,11 +153,23 @@ export class RemoteSession implements RemoteAgentSession {
     };
   }
 
+  /** 订阅 transport 使用的 Message 与 lifecycle 事件。 */
+  subscribe_transport(subscriber: AgentSessionSubscriber): AgentSessionUnsubscribe {
+    return this.event_hub.subscribe(subscriber);
+  }
+
   /**
    * 读取远程消息历史。
    */
-  async records(input?: AgentSessionRecordsInput): Promise<AgentSessionRecordsPage> {
-    return await this.transport.records(this.id, input);
+  async messages(input?: ListSessionMessagesInput): Promise<SessionMessagePage> {
+    return await this.transport.messages(this.id, input);
+  }
+
+  /** 读取远程增量 Message Mutation。 */
+  async message_changes(
+    input: ListSessionMessageChangesInput,
+  ): Promise<SessionMessageMutationPage> {
+    return await this.transport.message_changes(this.id, input);
   }
 
   /**
@@ -189,7 +222,7 @@ export class RemoteSession implements RemoteAgentSession {
   }
 
   private handle_event(event: AgentSessionEvent): void {
-    if (event.type === "error") {
+    if (!is_session_message_mutation(event) && event.type === "error") {
       this.fail_pending_turns(event.message);
     }
     const turn_id = extract_turn_id(event);
@@ -306,6 +339,9 @@ function create_turn_handle(
 }
 
 function extract_turn_id(event: AgentSessionEvent): string | null {
+  if (is_session_message_mutation(event)) {
+    return event.turn_id || null;
+  }
   switch (event.type) {
     case "turn-start":
     case "text-delta":

package/src/agent/remote/RemoteTransport.ts

@@ -15,11 +15,10 @@ import type {
   AgentArchiveSessionsResult,
   AgentCleanArchiveResult,
   AgentSessionForkInput,
-  AgentSessionRecordsInput,
-  AgentSessionRecordsPage,
   AgentSessionInfo,
   AgentSessionSummaryPage,
   AgentSessionSystemSnapshot,
+  AgentSessionSetInput,
 } from "@/types/agent/SessionTypes.js";
 import type {
   RemoteAgentPluginActionInput,
@@ -28,6 +27,14 @@ import type {
 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,
+  SessionMessagePage,
+} from "@/types/session/SessionMessage.js";
+import type {
+  ListSessionMessageChangesInput,
+  SessionMessageMutationPage,
+} from "@/types/session/SessionMessageMutation.js";
 import type {
   ShellApprovalMode,
   ShellApprovalDecisionResult,
@@ -51,6 +58,8 @@ export type TransportSubscription = {
 export type RemoteSessionTransport = {
   /** 读取 session 信息。 */
   get_info(session_id: string): Promise<AgentSessionInfo>;
+  /** 按稳定模型 ID 更新远程 session 配置。 */
+  set(session_id: string, input: AgentSessionSetInput): Promise<AgentSessionInfo>;
   /** 发送 prompt。 */
   prompt(
     session_id: string,
@@ -66,11 +75,16 @@ export type RemoteSessionTransport = {
     /** 底层事件连接结束后的通知；主动关闭不触发。 */
     on_close: (error?: unknown) => void;
   }): Promise<TransportSubscription>;
-  /** 读取 history。 */
-  records(
+  /** 读取 Session Message。 */
+  messages(
+    session_id: string,
+    input?: ListSessionMessagesInput,
+  ): Promise<SessionMessagePage>;
+  /** 读取增量 Message Mutation。 */
+  message_changes(
     session_id: string,
-    input?: AgentSessionRecordsInput,
-  ): Promise<AgentSessionRecordsPage>;
+    input: ListSessionMessageChangesInput,
+  ): Promise<SessionMessageMutationPage>;
   /** 读取 system snapshot。 */
   system(session_id: string): Promise<AgentSessionSystemSnapshot>;
   /** 分叉 session。 */

package/src/agent/remote/transports/HttpRemoteAgentTransport.ts

@@ -15,12 +15,19 @@ import type {
   AgentArchiveSessionsResult,
   AgentCleanArchiveResult,
   AgentSessionForkInput,
-  AgentSessionRecordsInput,
-  AgentSessionRecordsPage,
   AgentSessionInfo,
   AgentSessionSummaryPage,
   AgentSessionSystemSnapshot,
+  AgentSessionSetInput,
 } from "@/types/agent/SessionTypes.js";
+import type {
+  ListSessionMessagesInput,
+  SessionMessagePage,
+} from "@/types/session/SessionMessage.js";
+import type {
+  ListSessionMessageChangesInput,
+  SessionMessageMutationPage,
+} from "@/types/session/SessionMessageMutation.js";
 import type {
   RemoteAgentPluginActionInput,
   RemoteAgentPluginActionResult,
@@ -100,6 +107,27 @@ export class HttpRemoteAgentTransport implements RemoteAgentTransport {
     return payload.session;
   }
 
+  async set(
+    session_id: string,
+    input: AgentSessionSetInput,
+  ): Promise<AgentSessionInfo> {
+    const payload = await read_http_json<{
+      success?: boolean;
+      error?: string;
+      session?: AgentSessionInfo;
+    }>(`${this.base_url}/api/sdk/sessions/${encodeURIComponent(session_id)}/model`, {
+      method: "PUT",
+      headers: this.headers({
+        "Content-Type": "application/json",
+      }),
+      body: JSON.stringify({ modelId: input.modelId }),
+    });
+    if (!payload.success || !payload.session?.sessionId) {
+      throw new Error(String(payload.error || "Remote session model update failed"));
+    }
+    return payload.session;
+  }
+
   async prompt(
     session_id: string,
     input: AgentSessionPromptInput,
@@ -191,32 +219,58 @@ export class HttpRemoteAgentTransport implements RemoteAgentTransport {
     };
   }
 
-  async records(
+  async messages(
     session_id: string,
-    input?: AgentSessionRecordsInput,
-  ): Promise<AgentSessionRecordsPage> {
+    input?: ListSessionMessagesInput,
+  ): Promise<SessionMessagePage> {
     const query = new URLSearchParams();
     if (input?.limit !== undefined) query.set("limit", String(input.limit));
     if (input?.cursor) query.set("cursor", input.cursor);
-    if (input?.archive_id) query.set("archive_id", input.archive_id);
-    if (input?.order) query.set("order", input.order);
-    if (input?.view) query.set("view", input.view);
+    if (input?.before_sequence !== undefined) {
+      query.set("before_sequence", String(input.before_sequence));
+    }
+    if (input?.include_internal) query.set("include_internal", "true");
+    if (input?.through_sequence !== undefined) {
+      query.set("through_sequence", String(input.through_sequence));
+    }
     const payload = await read_http_json<{
       success?: boolean;
       error?: string;
-      records?: AgentSessionRecordsPage;
+      messages?: SessionMessagePage;
     }>(
-      `${this.base_url}/api/sdk/sessions/${encodeURIComponent(session_id)}/records${
+      `${this.base_url}/api/sdk/sessions/${encodeURIComponent(session_id)}/messages${
         query.size > 0 ? `?${query.toString()}` : ""
       }`,
       {
         headers: this.headers(),
       },
     );
-    if (!payload.success || !payload.records || !Array.isArray(payload.records.items)) {
-      throw new Error(String(payload.error || "Remote session records failed"));
+    if (!payload.success || !payload.messages || !Array.isArray(payload.messages.items)) {
+      throw new Error(String(payload.error || "Remote session messages failed"));
+    }
+    return payload.messages;
+  }
+
+  async message_changes(
+    session_id: string,
+    input: ListSessionMessageChangesInput,
+  ): Promise<SessionMessageMutationPage> {
+    const query = new URLSearchParams({
+      after_commit_sequence: String(input.after_commit_sequence),
+    });
+    if (input.limit !== undefined) query.set("limit", String(input.limit));
+    const payload = await read_http_json<{
+      success?: boolean;
+      error?: string;
+      changes?: SessionMessageMutationPage;
+    }>(
+      `${this.base_url}/api/sdk/sessions/${encodeURIComponent(session_id)}/message-changes?${query.toString()}`,
+      { headers: this.headers() },
+    );
+    if (!payload.success || !payload.changes) {
+      throw new Error(String(payload.error || "Remote session message changes failed"));
     }
-    return payload.records;
+    return payload.changes;
   }
 
   async system(session_id: string): Promise<AgentSessionSystemSnapshot> {