@downcity/agent 1.1.215 → 1.1.217

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/services/SessionStateService.ts

@@ -42,6 +42,7 @@ import { to_session_action_record } from "@/executor/types/SessionRecords.js";
 import type { SessionLocalState } from "@/types/session/SessionLocalState.js";
 import { generateId } from "@/utils/Id.js";
 import type { Logger } from "@/utils/logger/Logger.js";
+import type { AgentModel } from "@/model/CityModelAdapter.js";
 
 type SessionStateServiceOptions = {
   /**
@@ -84,6 +85,9 @@ type SessionStateServiceOptions = {
    */
   ensure_configured_hook?: () => Promise<void>;
 
+  /** 按稳定 ID 解析当前 Session 的运行时模型。 */
+  resolve_model?: (model_id: string) => Promise<AgentModel>;
+
   /**
    * 发布 session 事件。
    */
@@ -115,6 +119,7 @@ export class SessionStateService {
   private readonly state: SessionLocalState;
   private readonly logger: Logger;
   private readonly ensure_configured_hook?: SessionStateServiceOptions["ensure_configured_hook"];
+  private readonly resolve_model?: SessionStateServiceOptions["resolve_model"];
   private readonly publish_event: SessionStateServiceOptions["publish_event"];
 
   constructor(options: SessionStateServiceOptions) {
@@ -126,6 +131,7 @@ export class SessionStateService {
     this.state = options.state;
     this.logger = options.logger;
     this.ensure_configured_hook = options.ensure_configured_hook;
+    this.resolve_model = options.resolve_model;
     this.publish_event = options.publish_event;
   }
 
@@ -189,6 +195,7 @@ export class SessionStateService {
         ...(metadata.modelLabel
           ? { modelLabel: metadata.modelLabel }
           : {}),
+        ...(metadata.modelId ? { modelId: metadata.modelId } : {}),
       };
     })();
     await this.state.initializePromise;
@@ -199,6 +206,7 @@ export class SessionStateService {
    */
   async ensure_ready_for_execution(): Promise<void> {
     await this.initialize();
+    await this.restore_persisted_model();
     if (this.state.ensureConfiguredPromise) {
       await this.state.ensureConfiguredPromise;
       return;
@@ -231,11 +239,16 @@ export class SessionStateService {
   async set(input: AgentSessionSetInput, options?: SessionSetOptions): Promise<void> {
     const should_emit_action = options?.emit_action !== false;
     const previous_model_label = this.state.sessionConfig.modelLabel;
-    const next_model_label = input.model
-      ? inferAgentModelLabel(input.model)
+    const requested_model_id = String(input.modelId || "").trim();
+    const next_model = input.model || (requested_model_id
+      ? await this.resolve_model_by_id(requested_model_id)
+      : undefined);
+    const next_model_label = next_model
+      ? inferAgentModelLabel(next_model)
       : undefined;
+    const next_model_id = requested_model_id || next_model_label || "";
     const should_emit_model_switch_action = Boolean(
-      input.model &&
+      next_model &&
         should_emit_action &&
         this.state.sessionConfig.model &&
         previous_model_label &&
@@ -256,15 +269,19 @@ export class SessionStateService {
     }
 
     try {
-      if (input.model) {
-        this.state.sessionConfig.model = normalizeAgentModel(input.model);
+      if (next_model) {
+        this.state.sessionConfig.model = normalizeAgentModel(next_model);
         this.state.sessionConfig.modelLabel = next_model_label;
       }
+      if (next_model_id) {
+        this.state.sessionConfig.modelId = next_model_id;
+      }
       await patchSessionModelLabel({
         projectRoot: this.project_root,
         agentId: this.agent_id,
         sessionId: this.session_id,
         model: this.state.sessionConfig.model,
+        modelId: this.state.sessionConfig.modelId,
       });
     } catch (error) {
       if (should_emit_model_switch_action) {
@@ -290,6 +307,23 @@ export class SessionStateService {
     }
   }
 
+  /** 恢复 metadata 中持久化的模型覆盖。 */
+  private async restore_persisted_model(): Promise<void> {
+    const model_id = String(this.state.sessionConfig.modelId || "").trim();
+    if (!model_id || this.state.sessionConfig.model) return;
+    const model = await this.resolve_model_by_id(model_id);
+    this.state.sessionConfig.model = normalizeAgentModel(model);
+    this.state.sessionConfig.modelLabel = inferAgentModelLabel(model);
+  }
+
+  /** 使用宿主 resolver 解析稳定模型 ID。 */
+  private async resolve_model_by_id(model_id: string): Promise<AgentModel> {
+    if (!this.resolve_model) {
+      throw new Error("Session model resolver is not configured.");
+    }
+    return await this.resolve_model(model_id);
+  }
+
   /**
    * 追加一条 user 消息并刷新标题与 metadata。
    */

package/src/session/services/SessionViewService.ts

@@ -306,6 +306,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 },
         );

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

@@ -93,6 +93,11 @@ export async function touchSessionMetadata(
           modelLabel: params.sessionConfig.modelLabel,
         }
       : {}),
+    ...(params.sessionConfig.modelId
+      ? {
+          modelId: params.sessionConfig.modelId,
+        }
+      : {}),
   };
   await writeSessionMetadata({
     projectRoot: params.projectRoot,

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

@@ -101,6 +101,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

@@ -17,6 +17,7 @@ import type {
   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";
@@ -60,6 +61,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;

package/src/types/session/SessionOptions.ts

@@ -13,6 +13,7 @@ import type { SessionPort } from "@/types/runtime/agent/AgentContext.js";
 import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
 import type { SessionComposerOptions } from "@/types/session/SessionComposerOptions.js";
 import type { Logger } from "@/utils/logger/Logger.js";
+import type { AgentModel } from "@/model/CityModelAdapter.js";
 
 /**
  * Agent 可管理的本地 Session 实例。
@@ -83,6 +84,9 @@ export interface SessionOptions {
    */
   ensureConfigured?: (session: AgentManagedSession) => Promise<void>;
 
+  /** 按稳定模型 ID 解析当前 Session 的运行时模型。 */
+  resolve_model?: (model_id: string) => Promise<AgentModel>;
+
   /**
    * 当前 session 的 Composer 覆盖项。
    */