@downcity/agent 1.1.17 → 1.1.18

package/src/core/AgentCore.ts

@@ -4,15 +4,16 @@
  * 关键点（中文）
  * - 一个 `AgentCore` 只服务一个 agent 实例，不依赖进程级 singleton runtime。
  * - SDK `Agent`、实例绑定式 HTTP server、实例绑定式 local RPC 都应基于它工作。
- * - 宿主若需要统一 session 默认配置，应通过 `configureSession` 注入，而不是把策略写死在 SDK 中。
+ * - 宿主若需要统一 session 默认配置，应通过 `model` / `configureSession` 注入，而不是把策略写死在 SDK 中。
  */
 
 import fs from "fs-extra";
 import { nanoid } from "nanoid";
-import type { Tool } from "ai";
+import type { LanguageModel, Tool } from "ai";
 import { Logger } from "@/utils/logger/Logger.js";
 import type { BaseService } from "@/service/builtins/BaseService.js";
 import type { AgentContext } from "@/core/AgentContextTypes.js";
+import type { SessionPort } from "@/core/AgentContextTypes.js";
 import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
 import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
 import type { JsonValue } from "@/types/common/Json.js";
@@ -127,6 +128,7 @@ export class AgentCore {
   private readonly platform: AgentPlatformRuntime;
   private readonly env: Record<string, string>;
   private readonly globalEnv: Record<string, string>;
+  private readonly defaultModel?: LanguageModel;
   private readonly configureSessionHook?: AgentOptions["configureSession"];
   private instruction: string[];
   private servicesStartPromise: Promise<void> | null = null;
@@ -151,6 +153,7 @@ export class AgentCore {
     this.globalEnv = this.platform.getGlobalEnv?.() || {};
     this.env = this.platform.getAgentEnv?.(this.path) || {};
     this.instruction = normalizeInstructionInput(options.instruction);
+    this.defaultModel = options.model;
     this.configureSessionHook = options.configureSession;
     this.config = this.loadConfig();
     this.services = new Map<string, BaseService>();
@@ -400,9 +403,8 @@ export class AgentCore {
       paths: createAgentPathRuntime(this.path),
       pluginConfig: createAgentPluginConfigRuntime(this.path),
       platform: this.platform,
-      getSession: (sessionId: string) => {
-        return this.getOrCreateSession(sessionId).getServicePort() as never;
-      },
+      getSession: (sessionId: string): SessionPort =>
+        this.getOrCreateSession(sessionId).getServicePort(),
       listExecutingSessionIds: () =>
         [...this.sessionsById.values()]
           .filter((session) => session.isExecuting())
@@ -410,10 +412,8 @@ export class AgentCore {
       getExecutingSessionCount: () =>
         [...this.sessionsById.values()].filter((session) => session.isExecuting()).length,
       services: this.services,
-    } satisfies Omit<AgentRuntime, "getSession"> & {
-      getSession(sessionId: string): never;
-    };
-    return runtime as unknown as AgentRuntime;
+    } satisfies AgentRuntime;
+    return runtime;
   }
 
   private createServiceContext(): AgentContext {
@@ -516,15 +516,24 @@ export class AgentCore {
       getInstructionSystemBlocks: () => this.loadInstructionSystemBlocks(),
       getServiceSystemBlocks: () => this.loadServiceSystemBlocks(),
       getPluginSystemBlocks: () => this.loadPluginSystemBlocks(),
+      ensureConfigured: async (session) => {
+        await this.configureSession(session);
+      },
     });
     this.sessionsById.set(resolvedSessionId, created);
     return created;
   }
 
   private async configureSession(session: Session): Promise<void> {
-    if (!this.configureSessionHook) return;
     if (this.configuredSessionIds.has(session.id)) return;
-    await this.configureSessionHook(session);
+    if (this.defaultModel) {
+      await session.set({
+        model: this.defaultModel,
+      });
+    }
+    if (this.configureSessionHook) {
+      await this.configureSessionHook(session);
+    }
     this.configuredSessionIds.add(session.id);
   }
 }

package/src/core/AgentCoreTypes.ts

@@ -15,7 +15,7 @@ import type {
   AgentPluginConfigRuntime,
 } from "@/types/runtime/host/AgentHost.js";
 import type { BaseService } from "@/service/builtins/BaseService.js";
-import type { Executor } from "@session/Executor.js";
+import type { SessionPort } from "@/core/AgentContextTypes.js";
 
 /**
  * AgentCore 启动早期的基础状态。
@@ -68,9 +68,13 @@ export interface AgentRuntimeBase {
  */
 export interface AgentRuntime extends AgentRuntimeBase {
   /**
-   * 读取指定 sessionId 对应的内部 Executor 实例。
+   * 读取指定 sessionId 对应的 session 端口。
+   *
+   * 关键点（中文）
+   * - 返回值是统一的 `SessionPort`，而不是裸 `Executor`。
+   * - 这样 HTTP / service / chat queue / contact 等入口都能复用同一层会话装配与执行兜底。
    */
-  getSession(sessionId: string): Executor;
+  getSession(sessionId: string): SessionPort;
   /**
    * 返回当前执行中的 sessionId 列表。
    */

package/src/sdk/AgentSdkTypes.ts

@@ -54,6 +54,16 @@ export interface AgentOptions {
    */
   instruction?: string | string[];
 
+  /**
+   * 当前 agent 为新建 session 提供的默认模型实例。
+   *
+   * 关键点（中文）
+   * - SDK 仍不负责“选择哪个模型”，这里只接收宿主已经创建好的 `LanguageModel`。
+   * - 该模型会作为 session 首次执行前的默认注入值。
+   * - 若同时提供 `configureSession`，则先应用这里的默认模型，再允许宿主继续覆写。
+   */
+  model?: LanguageModel;
+
   /**
    * 当前 agent 显式持有的 service 实例集合。
    *
@@ -106,7 +116,9 @@ export interface AgentOptions {
    *
    * 关键点（中文）
    * - SDK 不负责默认模型策略，宿主可在这里统一为 session 注入 model 等运行配置。
-   * - 该钩子只在 session 首次创建时触发一次，适合做实例级默认装配。
+   * - 若同时传入 `model`，则会先写入默认模型，再执行这里的宿主覆写逻辑。
+   * - 该钩子对每个 session 只触发一次，适合做实例级默认装配。
+   * - 触发时机可能来自显式 `agent.session()`，也可能来自该 session 的首次执行入口。
    */
   configureSession?: (session: Session) => Promise<void> | void;
 }

package/src/sdk/Session.ts

@@ -92,6 +92,15 @@ type SessionOptions = {
    * 读取当前 agent 显式注册 plugin 的 system blocks。
    */
   getPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
+
+  /**
+   * 在执行前确保当前 session 已完成宿主侧默认配置。
+   *
+   * 关键点（中文）
+   * - 这里通常由 `AgentCore` 注入，用于补齐默认 model、宿主覆写等一次性装配。
+   * - 所有执行入口都应通过这里兜底，避免只在 SDK `agent.session()` 链路上做配置。
+   */
+  ensureConfigured?: (session: Session) => Promise<void>;
 };
 
 /**
@@ -107,6 +116,7 @@ export class Session {
   private readonly getInstructionSystemBlocks: SessionOptions["getInstructionSystemBlocks"];
   private readonly getServiceSystemBlocks: SessionOptions["getServiceSystemBlocks"];
   private readonly getPluginSystemBlocks: SessionOptions["getPluginSystemBlocks"];
+  private readonly ensureConfiguredHook?: SessionOptions["ensureConfigured"];
   private readonly historyStore: JsonlSessionHistoryStore;
   private readonly historyComposer: JsonlSessionHistoryComposer;
   private readonly executor: Executor;
@@ -114,6 +124,7 @@ export class Session {
   private createdAt = Date.now();
   private timezone = resolveSystemTimezone();
   private initializePromise: Promise<this> | null = null;
+  private ensureConfiguredPromise: Promise<void> | null = null;
   private servicePort: SessionPort | null = null;
 
   constructor(options: SessionOptions) {
@@ -125,6 +136,7 @@ export class Session {
     this.getInstructionSystemBlocks = options.getInstructionSystemBlocks;
     this.getServiceSystemBlocks = options.getServiceSystemBlocks;
     this.getPluginSystemBlocks = options.getPluginSystemBlocks;
+    this.ensureConfiguredHook = options.ensureConfigured;
     if (!this.id) {
       throw new Error("Session requires a non-empty sessionId");
     }
@@ -338,9 +350,10 @@ export class Session {
     if (!query) {
       throw new Error("session.run requires a non-empty query");
     }
+    await this.ensureReadyForExecution();
     if (!this.sessionConfig.model) {
       throw new Error(
-        `Session "${this.id}" requires a configured model. Call session.set({ model }) first or let the host configure the session during creation.`,
+        `Session "${this.id}" requires a configured model. Pass model to new Agent({ model }), call session.set({ model }) first, or let the host configure the session during creation.`,
       );
     }
     await this.appendUserMessage({ text: query });
@@ -366,9 +379,10 @@ export class Session {
     if (!query) {
       throw new Error("session.stream requires a non-empty query");
     }
+    await this.ensureReadyForExecution();
     if (!this.sessionConfig.model) {
       throw new Error(
-        `Session "${this.id}" requires a configured model. Call session.set({ model }) first or let the host configure the session during creation.`,
+        `Session "${this.id}" requires a configured model. Pass model to new Agent({ model }), call session.set({ model }) first, or let the host configure the session during creation.`,
       );
     }
     const queue = new AsyncQueue<AgentSessionStreamEvent>();
@@ -478,6 +492,9 @@ export class Session {
       sessionId: this.id,
       executor: this.executor,
       historyStore: this.historyStore,
+      ensureReadyForExecution: async () => {
+        await this.ensureReadyForExecution();
+      },
       touchMetadata: async () => {
         await this.touchMetadata();
       },
@@ -485,6 +502,27 @@ export class Session {
     return this.servicePort;
   }
 
+  /**
+   * 在执行前确保 session 已完成初始化与宿主装配。
+   */
+  async ensureReadyForExecution(): Promise<void> {
+    await this.initialize();
+    if (this.ensureConfiguredPromise) {
+      await this.ensureConfiguredPromise;
+      return;
+    }
+    this.ensureConfiguredPromise = (async () => {
+      if (!this.ensureConfiguredHook) return;
+      await this.ensureConfiguredHook(this);
+    })();
+    try {
+      await this.ensureConfiguredPromise;
+    } catch (error) {
+      this.ensureConfiguredPromise = null;
+      throw error;
+    }
+  }
+
   private async touchMetadata(): Promise<void> {
     await touchSessionMetadata({
       projectRoot: this.projectRoot,

package/src/sdk/session/ServicePort.ts

@@ -25,6 +25,10 @@ export interface CreateSessionServicePortParams {
    * 当前 session 历史持久化端口。
    */
   historyStore: SessionHistoryStore;
+  /**
+   * 在执行前确保当前 session 已完成初始化与宿主级配置。
+   */
+  ensureReadyForExecution: () => Promise<void>;
   /**
    * session 更新后需要同步执行的持久化回调。
    */
@@ -42,6 +46,7 @@ export function createSessionServicePort(
     getExecutor: () => params.executor.getExecutor(),
     getHistoryStore: () => params.historyStore,
     run: async (runParams) => {
+      await params.ensureReadyForExecution();
       return await params.executor.run(runParams);
     },
     clearExecutor: () => {

package/src/session/Executor.ts

@@ -717,7 +717,7 @@ export class Executor implements SessionExecutor {
     const model = this.getModel();
     if (!model) {
       throw new Error(
-        `Executor for session "${this.sessionId}" requires a configured model`,
+        `Executor for session "${this.sessionId}" requires a configured model. Pass model to new Agent({ model }), call session.set({ model }), or let the host configure the session before execution.`,
       );
     }
     return model;