@downcity/agent 1.1.216 → 1.1.222

package/src/agent/remote/transports/RpcRemoteAgentTransport.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,
@@ -60,6 +67,13 @@ export class RpcRemoteAgentTransport implements RemoteAgentTransport {
     return await this.client.get_session(session_id);
   }
 
+  async set(
+    session_id: string,
+    input: AgentSessionSetInput,
+  ): Promise<AgentSessionInfo> {
+    return await this.client.set_session({ session_id, input });
+  }
+
   async prompt(
     session_id: string,
     input: AgentSessionPromptInput,
@@ -93,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/SessionHistoryMeta.ts

@@ -23,6 +23,8 @@ export type SessionHistoryMetaV1 = {
   title?: string;
   /** 当前 session 绑定模型的可读标签。 */
   modelLabel?: string;
+  /** 当前 session 绑定模型的稳定 ID，用于进程重启后恢复模型实例。 */
+  modelId?: string;
   /** 当前 session 已持久化记录数量，用于列表查询避免扫描完整历史。 */
   messageCount?: number;
   /** 当前 session 最后一条记录的用户可见摘要，用于列表预览。 */

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,12 +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";
@@ -168,6 +175,23 @@ export class RpcClient {
     return data.session;
   }
 
+  /** 按稳定模型 ID 更新远程 Session。 */
+  async set_session(params: {
+    /** 目标 session id。 */
+    session_id: string;
+    /** Session 配置更新输入。 */
+    input: AgentSessionSetInput;
+  }): Promise<AgentSessionInfo> {
+    const data = await this.request<{ session: AgentSessionInfo }>({
+      method: "sdk.sessions.set",
+      params: {
+        sessionId: params.session_id,
+        input: params.input,
+      },
+    });
+    return data.session;
+  }
+
   /**
    * 发送 prompt。
    */
@@ -201,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,
@@ -126,6 +147,7 @@ export class Session implements AgentSession {
             await this.ensureConfiguredHook?.(this);
           }
         : undefined,
+      ...(options.resolve_model ? { resolve_model: options.resolve_model } : {}),
       publish_event: (event) => {
         this.eventHub.publish(event);
       },
@@ -136,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(),
@@ -157,6 +181,7 @@ export class Session implements AgentSession {
         return {
           session,
           history_store: session.historyStore,
+          recorder: session.recorder,
           state_service: session.stateService,
         };
       },
@@ -167,6 +192,7 @@ export class Session implements AgentSession {
    * 初始化当前 session。
    */
   async initialize(): Promise<this> {
+    await this.recorder.initialize();
     await this.stateService.initialize();
     return this;
   }
@@ -202,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();
+    };
   }
 
   /**
@@ -238,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);
   }
 
   /**
@@ -328,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,
     });
   }
 

package/src/session/browse/Browse.ts

@@ -453,6 +453,7 @@ export function buildSessionInfo(
     ...(input.metadata.modelLabel
       ? { modelLabel: input.metadata.modelLabel }
       : {}),
+    ...(input.metadata.modelId ? { modelId: input.metadata.modelId } : {}),
     ...(typeof input.metadata.timezone === "string" && input.metadata.timezone.trim()
       ? { timezone: input.metadata.timezone.trim() }
       : {}),
@@ -632,6 +633,7 @@ export async function listAgentSessionSummaryPage(params: {
       ...(typeof info.createdAt === "number" ? { createdAt: info.createdAt } : {}),
       ...(typeof info.updatedAt === "number" ? { updatedAt: info.updatedAt } : {}),
       ...(info.modelLabel ? { modelLabel: info.modelLabel } : {}),
+      ...(info.modelId ? { modelId: info.modelId } : {}),
       ...(info.executing ? { executing: true } : {}),
     };
 
@@ -732,6 +734,7 @@ export async function listArchivedAgentSessionSummaryPage(params: {
       ...(typeof info.createdAt === "number" ? { createdAt: info.createdAt } : {}),
       ...(typeof info.updatedAt === "number" ? { updatedAt: info.updatedAt } : {}),
       ...(info.modelLabel ? { modelLabel: info.modelLabel } : {}),
+      ...(info.modelId ? { modelId: info.modelId } : {}),
     };
 
     if (query) {

package/src/session/recorder/JsonlSessionMessageStore.ts

@@ -0,0 +1,162 @@
+/**
+ * 基于单一 messages.jsonl 的 SessionMessage mutation store。
+ *
+ * 文件中每行是一条完整 mutation。消息快照通过 reducer 重放得到，不维护第二份文件。
+ */
+
+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";
+
+/** JSONL message store 构造参数。 */
+export interface JsonlSessionMessageStoreOptions {
+  /** 当前 session 标识。 */
+  session_id: string;
+  /** canonical messages.jsonl 的绝对路径。 */
+  file_path: string;
+}
+
+/** Recorder 在锁内构造下一条 mutation 时可用的序列状态。 */
+export interface SessionMessageCommitState {
+  /** 下一条 mutation 应使用的提交顺序。 */
+  commit_sequence: number;
+  /** 下一条新消息应使用的线性顺序。 */
+  message_sequence: number;
+  /** 当前已重放的线性消息列表。 */
+  messages: SessionMessage[];
+}
+
+/** 单一 JSONL mutation store。 */
+export class JsonlSessionMessageStore {
+  readonly session_id: string;
+  private readonly messages_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.lock_file_path = `${this.messages_file_path}.lock`;
+    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());
+  }
+
+  /** 读取全部合法 mutation；损坏行会带行号抛错，避免静默产生错误历史。 */
+  async list_mutations(): Promise<SessionMessageMutation[]> {
+    await this.ensure_layout();
+    return await this.read_mutations_unsafe();
+  }
+
+  /** 重放全部 mutation，得到当前 canonical 消息列表。 */
+  async list_messages(): Promise<SessionMessage[]> {
+    return reduce_session_messages(await this.list_mutations());
+  }
+
+  /**
+   * 在跨进程文件锁内计算并追加 mutation。
+   * 发布动作必须由调用方在此 Promise 成功后执行。
+   */
+  async commit(
+    build_mutation: (state: SessionMessageCommitState) => SessionMessageMutation,
+  ): Promise<SessionMessageMutation> {
+    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,
+          ),
+        messages,
+      });
+      await fs.appendFile(
+        this.messages_file_path,
+        `${JSON.stringify(mutation)}\n`,
+        "utf8",
+      );
+      return mutation;
+    });
+  }
+
+  private async ensure_layout(): Promise<void> {
+    await fs.ensureDir(path.dirname(this.messages_file_path));
+    await fs.ensureFile(this.messages_file_path);
+  }
+
+  private async read_mutations_unsafe(): Promise<SessionMessageMutation[]> {
+    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");
+        }
+        mutations.push(mutation);
+      } catch (error) {
+        throw new Error(
+          `Invalid session mutation at line ${String(index + 1)}: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    }
+    return mutations;
+  }
+
+  private async with_write_lock<T>(callback: () => Promise<T>): Promise<T> {
+    await this.ensure_layout();
+    const token = `${process.pid}:${Date.now()}:${generateId()}`;
+    const stale_ms = 30_000;
+    const started_at = Date.now();
+    while (true) {
+      try {
+        const file = await open(this.lock_file_path, "wx");
+        await file.writeFile(token, "utf8");
+        await file.close();
+        break;
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (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}`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, 40));
+      }
+    }
+    try {
+      return await callback();
+    } finally {
+      try {
+        if ((await readFile(this.lock_file_path, "utf8")).trim() === token) {
+          await fs.remove(this.lock_file_path);
+        }
+      } catch {
+        // 锁文件已被清理时无需额外处理。
+      }
+    }
+  }
+}