@downcity/agent 1.1.217 → 1.1.222

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,
@@ -124,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({
@@ -132,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);
@@ -140,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);
   }
 
   /**
@@ -197,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);
@@ -314,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,8 +15,6 @@ import type {
   AgentArchiveSessionsResult,
   AgentCleanArchiveResult,
   AgentSessionForkInput,
-  AgentSessionRecordsInput,
-  AgentSessionRecordsPage,
   AgentSessionInfo,
   AgentSessionSummaryPage,
   AgentSessionSystemSnapshot,
@@ -29,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,
@@ -69,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,13 +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,
@@ -213,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> {

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

@@ -15,13 +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,
@@ -101,16 +107,23 @@ export class RpcRemoteAgentTransport implements RemoteAgentTransport {
     };
   }
 
-  async records(
+  async messages(
     session_id: string,
-    input?: AgentSessionRecordsInput,
-  ): Promise<AgentSessionRecordsPage> {
-    return await this.client.get_session_records({
+    input?: ListSessionMessagesInput,
+  ): Promise<SessionMessagePage> {
+    return await this.client.get_session_messages({
       session_id,
       input,
     });
   }
 
+  async message_changes(
+    session_id: string,
+    input: ListSessionMessageChangesInput,
+  ): Promise<SessionMessageMutationPage> {
+    return await this.client.get_session_message_changes({ session_id, input });
+  }
+
   async system(session_id: string): Promise<AgentSessionSystemSnapshot> {
     return await this.client.get_session_system(session_id);
   }

package/src/executor/types/SessionRecords.ts

@@ -65,6 +65,8 @@ export type SessionMetadataV1 = {
   ts: number;
   /** 当前消息所属的 session ID。 */
   sessionId: string;
+  /** 当前消息所属 turn。 */
+  turnId?: string;
   /** 当前消息是普通消息还是摘要消息。 */
   kind?: SessionMessageKind;
   /** 当前消息来自入站、出站还是 compact。 */

package/src/index.ts

@@ -27,9 +27,6 @@ export type {
   AgentListSessionsInput,
   AgentSessionConfigSnapshot,
   AgentSessionForkInput,
-  AgentSessionRecordsInput,
-  AgentSessionRecordsPage,
-  AgentSessionRecordsView,
   AgentSessionInfo,
   AgentSessionSetInput,
   AgentSessionSummary,
@@ -38,8 +35,29 @@ export type {
   AgentSessionSystemBlockSource,
   AgentSessionSystemSessionInfo,
   AgentSessionSystemSnapshot,
-  AgentSessionTimelineEvent,
 } from "./types/agent/SessionTypes.js";
+export type {
+  ListSessionMessagesInput,
+  SessionActionMessage,
+  SessionAssistantMessage,
+  SessionAssistantMessagePart,
+  SessionAssistantToolPart,
+  SessionErrorMessage,
+  SessionMessage,
+  SessionMessagePage,
+  SessionUserMessage,
+  SessionUserMessagePart,
+} from "./types/session/SessionMessage.js";
+export {
+  is_session_message_mutation,
+} from "./types/session/SessionMessageMutation.js";
+export type {
+  ListSessionMessageChangesInput,
+  SessionMessageMutation,
+  SessionMessageMutationPage,
+  SessionMessageMutationSubscriber,
+  SessionMessageMutationUnsubscribe,
+} from "./types/session/SessionMessageMutation.js";
 export type {
   AgentOptions,
   AgentSessionConstructor,
@@ -67,7 +85,7 @@ export type {
   AgentSessionActionRecord,
   AgentSessionActionState,
 } from "./types/sdk/AgentSessionAction.js";
-export type { AgentSessionPromptInput, SessionUserMessagePart } from "./types/sdk/AgentSessionPrompt.js";
+export type { AgentSessionPromptInput } from "./types/sdk/AgentSessionPrompt.js";
 export type { AgentSessionStopResult } from "./types/sdk/AgentSessionStop.js";
 export type {
   AgentSessionTurnHandle,

package/src/rpc/Client.ts

@@ -16,13 +16,19 @@ import type {
   AgentArchiveSessionResult,
   AgentArchiveSessionsResult,
   AgentCleanArchiveResult,
-  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 { JsonValue } from "@/types/common/Json.js";
 import type { JsonObject } from "@/types/common/Json.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
@@ -219,18 +225,33 @@ export class RpcClient {
   /**
    * 读取 session records。
    */
-  async get_session_records(params: {
+  async get_session_messages(params: {
+    session_id: string;
+    input?: ListSessionMessagesInput;
+  }): Promise<SessionMessagePage> {
+    const data = await this.request<{ messages: SessionMessagePage }>({
+      method: "sdk.sessions.messages",
+      params: {
+        sessionId: params.session_id,
+        input: params.input,
+      },
+    });
+    return data.messages;
+  }
+
+  /** 读取指定 cursor 后的 Session Message Mutation。 */
+  async get_session_message_changes(params: {
     session_id: string;
-    input?: AgentSessionRecordsInput;
-  }): Promise<AgentSessionRecordsPage> {
-    const data = await this.request<{ records: AgentSessionRecordsPage }>({
-      method: "sdk.sessions.records",
+    input: ListSessionMessageChangesInput;
+  }): Promise<SessionMessageMutationPage> {
+    const data = await this.request<{ changes: SessionMessageMutationPage }>({
+      method: "sdk.sessions.message_changes",
       params: {
         sessionId: params.session_id,
         input: params.input,
       },
     });
-    return data.records;
+    return data.changes;
   }
 
   /**

package/src/session/Session.ts

@@ -10,12 +10,12 @@
 import { Executor } from "@executor/Executor.js";
 import type { Tool } from "ai";
 import { JsonlSessionHistoryComposer } from "@executor/composer/history/jsonl/JsonlSessionHistoryComposer.js";
-import { JsonlSessionHistoryStore } from "@/executor/store/history/jsonl/JsonlSessionHistoryStore.js";
+import { SessionRecorderHistoryStore } from "@/session/recorder/SessionRecorderHistoryStore.js";
+import { JsonlSessionMessageStore } from "@/session/recorder/JsonlSessionMessageStore.js";
+import { SessionRecorder } from "@/session/recorder/SessionRecorder.js";
 import type {
   AgentSessionConfigSnapshot,
   AgentSessionForkInput,
-  AgentSessionRecordsInput,
-  AgentSessionRecordsPage,
   AgentSessionInfo,
   AgentSessionSetInput,
   AgentSessionSystemBlock,
@@ -23,9 +23,7 @@ import type {
 } from "@/types/agent/SessionTypes.js";
 import type { AgentSession } from "@/types/agent/SessionActor.js";
 import {
-  getSdkAgentSessionArchiveDirPath,
   getSdkAgentSessionDirPath,
-  getSdkAgentSessionInflightPath,
 } from "@/session/storage/Paths.js";
 import { resolveSystemTimezone } from "@/session/storage/Metadata.js";
 import { createRuntimeSessionPort } from "@/session/storage/RuntimeSessionPort.js";
@@ -35,10 +33,21 @@ 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";
 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";
@@ -69,10 +78,13 @@ export class Session implements AgentSession {
   private readonly getPluginSystemBlocks: SessionOptions["getPluginSystemBlocks"];
   private readonly ensureConfiguredHook?: SessionOptions["ensureConfigured"];
   private readonly composers?: SessionComposerOptions;
-  private readonly historyStore: JsonlSessionHistoryStore;
+  private readonly historyStore: SessionRecorderHistoryStore;
+  private readonly messageStore: JsonlSessionMessageStore;
+  private readonly recorder: SessionRecorder;
   private readonly historyComposer: SessionHistoryComposer;
   private readonly executor: Executor;
   private readonly eventHub = new SessionEventHub();
+  private readonly messageEventHub = new SessionMessageEventHub();
   private readonly localState: SessionLocalState;
   private readonly stateService: SessionStateService;
   private readonly turnService: SessionTurnService;
@@ -100,6 +112,14 @@ export class Session implements AgentSession {
       throw new Error("Session requires a non-empty projectRoot");
     }
 
+    this.messageStore = this.create_message_store();
+    this.recorder = new SessionRecorder({
+      session_id: this.id,
+      store: this.messageStore,
+      publish: (mutation) => {
+        this.messageEventHub.publish(mutation);
+      },
+    });
     this.historyStore = this.create_history_store();
     this.localState = this.create_local_state();
     const composer_context = this.create_composer_context();
@@ -118,6 +138,7 @@ export class Session implements AgentSession {
       project_root: this.projectRoot,
       session_id: this.id,
       history_store: this.historyStore,
+      recorder: this.recorder,
       executor: this.executor,
       state: this.localState,
       logger: this.logger,
@@ -137,12 +158,14 @@ export class Session implements AgentSession {
       executor: this.executor,
       state_service: this.stateService,
       event_hub: this.eventHub,
+      recorder: this.recorder,
     });
     this.viewService = new SessionViewService<this>({
       agent_id: this.agentId,
       project_root: this.projectRoot,
       session_id: this.id,
       history_store: this.historyStore,
+      recorder: this.recorder,
       state_service: this.stateService,
       logger: this.logger,
       is_executing: () => this.isExecuting(),
@@ -158,6 +181,7 @@ export class Session implements AgentSession {
         return {
           session,
           history_store: session.historyStore,
+          recorder: session.recorder,
           state_service: session.stateService,
         };
       },
@@ -168,6 +192,7 @@ export class Session implements AgentSession {
    * 初始化当前 session。
    */
   async initialize(): Promise<this> {
+    await this.recorder.initialize();
     await this.stateService.initialize();
     return this;
   }
@@ -203,8 +228,20 @@ export class Session implements AgentSession {
   /**
    * 订阅当前 Session 的未来事件。
    */
-  subscribe(subscriber: AgentSessionSubscriber): AgentSessionUnsubscribe {
-    return this.turnService.subscribe(subscriber);
+  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();
+    };
   }
 
   /**
@@ -239,8 +276,15 @@ export class Session implements AgentSession {
   /**
    * 读取当前 session records 分页。
    */
-  async records(input?: AgentSessionRecordsInput): Promise<AgentSessionRecordsPage> {
-    return await this.viewService.records(input);
+  async messages(input?: ListSessionMessagesInput): Promise<SessionMessagePage> {
+    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);
   }
 
   /**
@@ -329,33 +373,23 @@ export class Session implements AgentSession {
     return new SessionClass(options) as this;
   }
 
-  private create_history_store(): JsonlSessionHistoryStore {
+  private create_message_store(): JsonlSessionMessageStore {
     const session_dir_path = getSdkAgentSessionDirPath(
       this.projectRoot,
       this.agentId,
       this.id,
     );
     const messages_dir_path = `${session_dir_path}/messages`;
-    return new JsonlSessionHistoryStore({
-      rootPath: this.projectRoot,
-      agentId: this.agentId,
-      sessionId: this.id,
-      paths: {
-        sessionDirPath: session_dir_path,
-        messagesDirPath: messages_dir_path,
-        messagesFilePath: `${messages_dir_path}/messages.jsonl`,
-        metaFilePath: `${messages_dir_path}/meta.json`,
-        archiveDirPath: getSdkAgentSessionArchiveDirPath(
-          this.projectRoot,
-          this.agentId,
-          this.id,
-        ),
-        inflightFilePath: getSdkAgentSessionInflightPath(
-          this.projectRoot,
-          this.agentId,
-          this.id,
-        ),
-      },
+    return new JsonlSessionMessageStore({
+      session_id: this.id,
+      file_path: `${messages_dir_path}/messages.jsonl`,
+    });
+  }
+
+  private create_history_store(): SessionRecorderHistoryStore {
+    return new SessionRecorderHistoryStore({
+      session_id: this.id,
+      recorder: this.recorder,
     });
   }