@downcity/agent 1.1.216 → 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({
@@ -306,6 +317,9 @@ export class SessionViewService<TSession extends Pick<AgentSession, "set">> {
         await forked_bundle.state_service.set(
           {
             model: session_config.model,
+            ...(session_config.modelId
+              ? { modelId: session_config.modelId }
+              : {}),
           },
           { emit_action: false },
         );
@@ -330,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(
@@ -346,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/Metadata.ts

@@ -33,6 +33,11 @@ function normalizeModelLabel(input: unknown): string | undefined {
   return label || undefined;
 }
 
+function normalize_model_id(input: unknown): string | undefined {
+  const model_id = typeof input === "string" ? input.trim() : "";
+  return model_id || undefined;
+}
+
 /**
  * 归一化 session 标题。
  */
@@ -153,6 +158,9 @@ export async function readSessionMetadataFromPath(input: {
       ...(normalizeModelLabel(raw.modelLabel)
         ? { modelLabel: normalizeModelLabel(raw.modelLabel) }
         : {}),
+      ...(normalize_model_id(raw.modelId)
+        ? { modelId: normalize_model_id(raw.modelId) }
+        : {}),
       ...(normalize_message_count(raw.messageCount) !== undefined
         ? { messageCount: normalize_message_count(raw.messageCount) }
         : {}),
@@ -204,6 +212,8 @@ export async function patchSessionModelLabel(
      * 当前模型实例。
      */
     model?: LanguageModel;
+    /** 当前模型稳定 ID。 */
+    modelId?: string;
   },
 ): Promise<SessionHistoryMetaV1> {
   const current = await readSessionMetadata(input);
@@ -220,6 +230,9 @@ export async function patchSessionModelLabel(
           modelLabel,
         }
       : {}),
+    ...(normalize_model_id(input.modelId)
+      ? { modelId: normalize_model_id(input.modelId) }
+      : {}),
   };
   await writeSessionMetadata({
     ...input,

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;
 }
 
 /**
@@ -93,6 +99,18 @@ export async function touchSessionMetadata(
           modelLabel: params.sessionConfig.modelLabel,
         }
       : {}),
+    ...(params.sessionConfig.modelId
+      ? {
+          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/AgentOptions.ts

@@ -82,6 +82,18 @@ export interface AgentOptions {
    */
   model?: AgentModel;
 
+  /** 当前 Agent 默认模型对应的稳定 ID。 */
+  model_id?: string;
+
+  /**
+   * 按稳定 ID 解析 Session 运行时模型。
+   *
+   * 关键点（中文）
+   * - Session 热切换与进程重启后的恢复统一使用该 resolver。
+   * - SDK 不维护模型目录，具体目录与鉴权由宿主负责。
+   */
+  resolve_model?: (model_id: string) => Promise<AgentModel>;
+
   /**
    * 当前 agent 显式持有的插件实例集合。
    *

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;
+  subscribe(
+    subscriber: SessionMessageMutationSubscriber,
+  ): SessionMessageMutationUnsubscribe;
+
+  /** 订阅远程 transport 使用的 Message 与 turn lifecycle 事件。 */
+  subscribe_transport(
+    subscriber: AgentSessionSubscriber,
+  ): AgentSessionUnsubscribe;
 
-  /** 读取当前 session records 分页。 */
-  records(input?: AgentSessionRecordsInput): Promise<AgentSessionRecordsPage>;
+  /** 读取当前 session messages 分页。 */
+  messages(input?: ListSessionMessagesInput): Promise<SessionMessagePage>;
+
+  /** 读取指定 cursor 后的 Message Mutation。 */
+  message_changes(
+    input: ListSessionMessageChangesInput,
+  ): Promise<SessionMessageMutationPage>;
 
   /** 读取当前 session 生效的 system 快照。 */
   system(): Promise<AgentSessionSystemSnapshot>;
@@ -101,6 +121,9 @@ export interface AgentSession extends AgentSessionActor {
  * 远程 Agent 返回的公开 session 接口。
  */
 export interface RemoteAgentSession extends AgentSessionActor {
+  /** 按稳定模型 ID 更新远程 Session 模型。 */
+  set(input: AgentSessionSetInput): Promise<void>;
+
   /** 从当前远程 session 创建一个分叉会话。 */
   fork(input?: AgentSessionForkInput | string): Promise<RemoteAgentSession>;
 }

package/src/types/agent/SessionTypes.ts

@@ -67,9 +67,17 @@ export interface AgentSessionSetInput {
    *
    * 关键点（中文）
    * - 这里接受运行中的模型实例，而不是模型 ID。
-   * - 由于模型实例通常不可序列化，落盘只保留轻量可读标签用于展示。
+   * - 未同时提供 `modelId` 时，SDK 会从模型实例推导稳定 ID 并持久化。
    */
   model?: AgentModel;
+  /**
+   * 当前 session 使用的稳定模型 ID。
+   *
+   * 关键点（中文）
+   * - 由 Agent 宿主提供的模型 resolver 解析为运行时模型实例。
+   * - 该值会持久化到 session metadata，进程重启后可以恢复。
+   */
+  modelId?: string;
 }
 
 /**
@@ -80,6 +88,8 @@ export interface AgentSessionConfigSnapshot {
   model?: LanguageModel;
   /** 当前模型的轻量可读标签。 */
   modelLabel?: string;
+  /** 当前 session 绑定的稳定模型 ID。 */
+  modelId?: string;
 }
 
 /**
@@ -253,6 +263,8 @@ export interface AgentSessionSummary {
   messageCount: number;
   /** 当前 session 绑定模型的可读标签。 */
   modelLabel?: string;
+  /** 当前 session 绑定的稳定模型 ID。 */
+  modelId?: string;
   /** 当前 session 是否处于执行中。 */
   executing?: boolean;
 }

package/src/types/rpc/RpcProtocol.ts

@@ -15,12 +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";
@@ -60,6 +62,19 @@ export type RpcRequest =
         sessionId: string;
       };
     }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 更新 session 模型。 */
+      method: "sdk.sessions.set";
+      /** Session 配置更新参数。 */
+      params: {
+        /** 目标 session id。 */
+        sessionId: string;
+        /** 仅包含稳定 modelId 的配置输入。 */
+        input: AgentSessionSetInput;
+      };
+    }
   | {
       /** 请求 id，用于匹配响应。 */
       id: string;
@@ -112,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;
+        /** messages 分页参数。 */
+        input?: ListSessionMessagesInput;
+      };
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 读取 session message mutations。 */
+      method: "sdk.sessions.message_changes";
+      /** changes 查询参数。 */
       params: {
         /** 目标 session id。 */
         sessionId: string;
-        /** records 分页与视图参数。 */
-        input?: AgentSessionRecordsInput;
+        /** 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