@downcity/agent 1.1.15 → 1.1.18

package/src/plugin/core/LocalExecution.ts

@@ -15,9 +15,9 @@ import { findBuiltinPlugin, listStaticPluginViews } from "@/plugin/core/Catalog.
 import {
   createAgentPathRuntime,
   createAgentPluginConfigRuntime,
-} from "@/host/runtime/AgentHostRuntime.js";
+} from "@/runtime/host/AgentHostRuntime.js";
 import type { JsonValue } from "@/types/common/Json.js";
-import type { AgentPlatformRuntime } from "@/types/host/AgentHost.js";
+import type { AgentPlatformRuntime } from "@/types/runtime/host/AgentHost.js";
 import type {
   PluginActionResult,
   PluginAvailability,

package/src/plugin/core/PluginManager.ts

@@ -13,7 +13,7 @@ import { isPluginEnabled } from "@/plugin/core/Activation.js";
 import { HookRegistry } from "@/plugin/core/HookRegistry.js";
 import { PluginRegistry } from "@/plugin/core/PluginRegistry.js";
 import { registerBuiltinPlugins } from "@/plugin/core/Plugins.js";
-import { getPluginRuntimeContextResolver } from "@/host/runtime/PluginRuntime.js";
+import { getPluginRuntimeContextResolver } from "@/runtime/host/PluginRuntime.js";
 
 let pluginManager: PluginRegistry | null = null;
 

package/src/plugin/types/Plugin.ts

@@ -13,7 +13,7 @@ import type {
   AgentPathRuntime,
   AgentPlatformRuntime,
   AgentPluginConfigRuntime,
-} from "@/types/host/AgentHost.js";
+} from "@/types/runtime/host/AgentHost.js";
 import type {
   AgentContext,
   StructuredConfig,
@@ -21,7 +21,7 @@ import type {
 import type { Logger } from "@/utils/logger/Logger.js";
 import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
 import type { JsonObject, JsonValue } from "@/types/common/Json.js";
-import type { AuthRoutePolicy } from "@/types/auth/AuthRoute.js";
+import type { AuthRoutePolicy } from "@/types/runtime/auth/AuthRoute.js";
 
 /**
  * Plugin 命令执行上下文。

package/src/{host/runtime → runtime/host}/AgentHostRuntime.ts

@@ -22,7 +22,7 @@ import { persistProjectPluginConfig } from "@/plugin/core/ProjectConfigStore.js"
 import type {
   AgentPathRuntime,
   AgentPluginConfigRuntime,
-} from "@/types/host/AgentHost.js";
+} from "@/types/runtime/host/AgentHost.js";
 import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
 
 /**

package/src/{host → runtime/host}/daemon/Client.ts

@@ -15,8 +15,8 @@ import {
 import {
   formatCliBearerHeaderValue,
   resolveCliAuthToken,
-} from "@/server/http/auth/CliAuthStateStore.js";
-import { getDaemonMetaPath } from "@/host/daemon/Paths.js";
+} from "@/runtime/server/http/auth/CliAuthStateStore.js";
+import { getDaemonMetaPath } from "@/runtime/host/daemon/Paths.js";
 import type { JsonObject, JsonValue } from "@/types/common/Json.js";
 
 /**

package/src/{host → runtime/host}/daemon/Paths.ts

@@ -12,7 +12,7 @@ import {
   DAEMON_LOG_FILENAME,
   DAEMON_META_FILENAME,
   DAEMON_PID_FILENAME,
-} from "@/types/daemon/Daemon.js";
+} from "@/types/runtime/daemon/Daemon.js";
 
 /**
  * 计算 daemon pid 文件路径。

package/src/{host → runtime/host}/daemon/ProjectSetup.ts

@@ -12,7 +12,7 @@ import { loadDowncityConfig } from "@/config/Config.js";
 import {
   readProjectPrimaryModelId,
 } from "@/config/ExecutionBinding.js";
-import type { AgentPlatformRuntime } from "@/types/host/AgentHost.js";
+import type { AgentPlatformRuntime } from "@/types/runtime/host/AgentHost.js";
 import {
   getCacheDirPath,
   getLogsDirPath,

package/src/{sandbox → runtime/sandbox}/MacOsSeatbeltSandbox.ts

@@ -13,7 +13,7 @@ import fs from "fs-extra";
 import type {
   SandboxSpawnParams,
   SandboxSpawnResult,
-} from "@/sandbox/types/SandboxRuntime.js";
+} from "@/runtime/sandbox/types/SandboxRuntime.js";
 
 const DEFAULT_PATH_VALUE =
   "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin";

package/src/{sandbox → runtime/sandbox}/SandboxConfigResolver.ts

@@ -9,7 +9,7 @@
 
 import path from "node:path";
 import type { AgentContext } from "@/core/AgentContextTypes.js";
-import type { ResolvedSandboxConfig } from "@/sandbox/types/SandboxRuntime.js";
+import type { ResolvedSandboxConfig } from "@/runtime/sandbox/types/SandboxRuntime.js";
 
 const DEFAULT_ENV_ALLOWLIST = [
   "PATH",

package/src/{sandbox → runtime/sandbox}/SandboxRunner.ts

@@ -8,9 +8,9 @@
  */
 
 import type { AgentContext } from "@/core/AgentContextTypes.js";
-import type { SandboxSpawnResult } from "@/sandbox/types/SandboxRuntime.js";
-import { resolveSandboxConfig, resolveSandboxCwd } from "@/sandbox/SandboxConfigResolver.js";
-import { spawnMacOsSeatbeltSandbox } from "@/sandbox/MacOsSeatbeltSandbox.js";
+import type { SandboxSpawnResult } from "@/runtime/sandbox/types/SandboxRuntime.js";
+import { resolveSandboxConfig, resolveSandboxCwd } from "@/runtime/sandbox/SandboxConfigResolver.js";
+import { spawnMacOsSeatbeltSandbox } from "@/runtime/sandbox/MacOsSeatbeltSandbox.js";
 
 /**
  * 启动 shell 子进程。

package/src/{sandbox → runtime/sandbox}/types/SandboxRuntime.ts

@@ -8,8 +8,8 @@
  */
 
 import type { ChildProcessWithoutNullStreams } from "node:child_process";
-import type { SandboxConfig } from "@/sandbox/types/Sandbox.js";
-import type { SandboxNetworkMode } from "@/sandbox/types/Sandbox.js";
+import type { SandboxConfig } from "@/runtime/sandbox/types/Sandbox.js";
+import type { SandboxNetworkMode } from "@/runtime/sandbox/types/Sandbox.js";
 
 /**
  * sandbox 会话状态。

package/src/{server → runtime/server}/http/Server.ts

@@ -12,14 +12,14 @@ import { cors } from "hono/cors";
 import { logger } from "hono/logger";
 import http from "node:http";
 import { logger as serverLogger } from "@/utils/logger/Logger.js";
-import { createExecuteRouter } from "@/server/http/execute/execute.js";
-import { healthRouter } from "@/server/http/health/health.js";
+import { createExecuteRouter } from "@/runtime/server/http/execute/execute.js";
+import { healthRouter } from "@/runtime/server/http/health/health.js";
 import {
   createServicesRouter,
-} from "@/server/http/services/services.js";
-import { createPluginsRouter } from "@/server/http/plugins/plugins.js";
-import { createStaticRouter } from "@/server/http/static/static.js";
-import { createControlRouter } from "@/server/http/control/ControlRouter.js";
+} from "@/runtime/server/http/services/services.js";
+import { createPluginsRouter } from "@/runtime/server/http/plugins/plugins.js";
+import { createStaticRouter } from "@/runtime/server/http/static/static.js";
+import { createControlRouter } from "@/runtime/server/http/control/ControlRouter.js";
 import {
   registerBuiltinPluginHttpRoutes,
 } from "@/plugin/core/HttpRoutes.js";

package/src/{server → runtime/server}/http/control/AuthControlService.ts

@@ -9,7 +9,7 @@
 
 import type { AgentContext } from "@/core/AgentContextTypes.js";
 import type { JsonObject } from "@/types/common/Json.js";
-import type { AuthControlPayload } from "@/server/http/control/types/AuthControl.js";
+import type { AuthControlPayload } from "@/runtime/server/http/control/types/AuthControl.js";
 import type {
   AuthSetUserRolePayload,
   AuthWriteConfigPayload,

package/src/{server → runtime/server}/http/control/ControlApiRoutes.ts

@@ -7,12 +7,12 @@
  * - 单 agent control API 统一暴露在 `/api/control/*` 下。
  */
 
-import type { ControlRouteRegistrationParams } from "@/server/http/control/types/ControlRoutes.js";
-import { registerControlAuthorizationRoutes } from "@/server/http/control/ControlAuthorizationRoutes.js";
-import { registerControlSessionRoutes } from "@/server/http/control/SessionRoutes.js";
-import { registerControlModelRoutes } from "@/server/http/control/ModelRoutes.js";
-import { registerControlOverviewRoutes } from "@/server/http/control/OverviewRoutes.js";
-import { registerControlTaskRoutes } from "@/server/http/control/TaskRoutes.js";
+import type { ControlRouteRegistrationParams } from "@/runtime/server/http/control/types/ControlRoutes.js";
+import { registerControlAuthorizationRoutes } from "@/runtime/server/http/control/ControlAuthorizationRoutes.js";
+import { registerControlSessionRoutes } from "@/runtime/server/http/control/SessionRoutes.js";
+import { registerControlModelRoutes } from "@/runtime/server/http/control/ModelRoutes.js";
+import { registerControlOverviewRoutes } from "@/runtime/server/http/control/OverviewRoutes.js";
+import { registerControlTaskRoutes } from "@/runtime/server/http/control/TaskRoutes.js";
 
 /**
  * 注册单 agent control API 路由。

package/src/{server → runtime/server}/http/control/ControlAuthorizationRoutes.ts

@@ -12,14 +12,14 @@ import {
   readAuthControlPayload,
   setAuthControlUserRole,
   writeAuthControlConfig,
-} from "@/server/http/control/AuthControlService.js";
+} from "@/runtime/server/http/control/AuthControlService.js";
 import {
   isChatAuthorizationChannel,
   type AuthSetUserRolePayload,
   type ChatAuthorizationConfig,
 } from "@/plugin/builtins/auth/types/AuthPlugin.js";
 import type { ChatAuthorizationChannel } from "@/plugin/builtins/auth/types/AuthPlugin.js";
-import { buildControlRouteAliases } from "@/server/http/control/CommonHelpers.js";
+import { buildControlRouteAliases } from "@/runtime/server/http/control/CommonHelpers.js";
 
 function normalizeChatChannel(value: unknown): ChatAuthorizationChannel | null {
   const text = String(value || "").trim().toLowerCase();

package/src/{server → runtime/server}/http/control/ControlRouter.ts

@@ -15,7 +15,7 @@
 import { Hono } from "hono";
 import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
 import type { AgentContext } from "@/core/AgentContextTypes.js";
-import { registerControlApiRoutes } from "@/server/http/control/ControlApiRoutes.js";
+import { registerControlApiRoutes } from "@/runtime/server/http/control/ControlApiRoutes.js";
 
 /**
  * control router 参数。

package/src/{server → runtime/server}/http/control/ExecuteBySession.ts

@@ -9,7 +9,7 @@
 import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
 import type { AgentContext } from "@/core/AgentContextTypes.js";
 import type { JsonObject } from "@/types/common/Json.js";
-import type { ControlSessionExecuteAttachmentInput } from "@/server/http/control/types/ControlSessionExecute.js";
+import type { ControlSessionExecuteAttachmentInput } from "@/runtime/server/http/control/types/ControlSessionExecute.js";
 import { drainDeferredPersistedUserMessages } from "@session/SessionRunScope.js";
 import { resolveChatQueueStore } from "@/service/builtins/chat/runtime/ChatQueue.js";
 import { resolveDispatchTargetByChatKey } from "@/service/builtins/chat/runtime/ChatkeySend.js";

package/src/{server → runtime/server}/http/control/ExecuteInput.ts

@@ -13,7 +13,7 @@ import { renderChatMessageFileTag } from "@/service/builtins/chat/runtime/ChatMe
 import type {
   ControlSessionExecuteAttachmentInput,
   ControlSessionExecuteAttachmentType,
-} from "@/server/http/control/types/ControlSessionExecute.js";
+} from "@/runtime/server/http/control/types/ControlSessionExecute.js";
 
 const EXECUTE_ATTACHMENT_MAX_COUNT = 8;
 const EXECUTE_ATTACHMENT_MAX_BYTES = 2 * 1024 * 1024;

package/src/{server → runtime/server}/http/control/MessageTimeline.ts

@@ -19,7 +19,7 @@ import type {
 } from "@/session/types/SessionMessages.js";
 import { pickLastSuccessfulChatSendText } from "@/service/builtins/chat/runtime/UserVisibleText.js";
 import { extractToolCallsFromUiMessage } from "@/service/builtins/chat/runtime/UIMessageTransformer.js";
-import type { ControlTimelineEvent, ControlTimelineRole } from "@/server/http/control/types/ControlViewData.js";
+import type { ControlTimelineEvent, ControlTimelineRole } from "@/runtime/server/http/control/types/ControlViewData.js";
 import { truncateText } from "./CommonHelpers.js";
 
 type AnyUiPart = UIMessagePart<Record<string, never>, Record<string, never>>;

package/src/{server → runtime/server}/http/control/ModelRoutes.ts

@@ -8,8 +8,8 @@
 
 import fs from "fs-extra";
 import { getDowncityJsonPath } from "@/config/Paths.js";
-import type { ControlRouteRegistrationParams } from "@/server/http/control/types/ControlRoutes.js";
-import { buildControlRouteAliases } from "@/server/http/control/CommonHelpers.js";
+import type { ControlRouteRegistrationParams } from "@/runtime/server/http/control/types/ControlRoutes.js";
+import { buildControlRouteAliases } from "@/runtime/server/http/control/CommonHelpers.js";
 
 /**
  * 注册模型相关路由。

package/src/{server → runtime/server}/http/control/OverviewRoutes.ts

@@ -13,7 +13,7 @@ import { listServiceStates } from "@/service/core/Manager.js";
 import { listTaskDefinitions } from "@/service/builtins/task/Action.js";
 import { buildControlRouteAliases, toLimit } from "./CommonHelpers.js";
 import { listControlSessionSummaries, readRecentLogs } from "./Helpers.js";
-import type { ControlRouteRegistrationParams } from "@/server/http/control/types/ControlRoutes.js";
+import type { ControlRouteRegistrationParams } from "@/runtime/server/http/control/types/ControlRoutes.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);

package/src/{server → runtime/server}/http/control/SessionRoutes.ts

@@ -17,8 +17,8 @@ import {
   getDowncitySessionMessagesArchivePath,
   getDowncitySessionMessagesPath,
 } from "@/config/Paths.js";
-import type { ControlSessionExecuteRequestBody } from "@/server/http/control/types/ControlSessionExecute.js";
-import type { ControlRouteRegistrationParams } from "@/server/http/control/types/ControlRoutes.js";
+import type { ControlSessionExecuteRequestBody } from "@/runtime/server/http/control/types/ControlSessionExecute.js";
+import type { ControlRouteRegistrationParams } from "@/runtime/server/http/control/types/ControlRoutes.js";
 import {
   buildControlRouteAliases,
   decodeMaybe,

package/src/{server → runtime/server}/http/control/SessionSummaryStore.ts

@@ -13,7 +13,7 @@ import {
   getDowncitySessionRootDirPath,
 } from "@/config/Paths.js";
 import { readChatMetaBySessionId } from "@/service/builtins/chat/runtime/ChatMetaStore.js";
-import type { ControlSessionSummary } from "@/server/http/control/types/ControlViewData.js";
+import type { ControlSessionSummary } from "@/runtime/server/http/control/types/ControlViewData.js";
 import { decodeMaybe, truncateText } from "./CommonHelpers.js";
 import { loadSessionMessagesFromFile, resolveUiMessagePreview } from "./MessageTimeline.js";
 

package/src/{server → runtime/server}/http/control/TaskRoutes.ts

@@ -12,7 +12,7 @@ import { getDowncityTasksDirPath } from "@/config/Paths.js";
 import { runServiceCommand } from "@/service/core/Manager.js";
 import { listTaskDefinitions } from "@/service/builtins/task/Action.js";
 import { resolveTaskIdByTitle } from "@/service/builtins/task/runtime/Store.js";
-import type { ControlRouteRegistrationParams } from "@/server/http/control/types/ControlRoutes.js";
+import type { ControlRouteRegistrationParams } from "@/runtime/server/http/control/types/ControlRoutes.js";
 import {
   buildControlRouteAliases,
   decodeMaybe,

package/src/{server → runtime/server}/http/control/TaskStore.ts

@@ -14,7 +14,7 @@ import type {
   ControlLogEntry,
   ControlTaskRunDetail,
   ControlTaskRunSummary,
-} from "@/server/http/control/types/ControlViewData.js";
+} from "@/runtime/server/http/control/types/ControlViewData.js";
 import { truncateText } from "./CommonHelpers.js";
 import { loadSessionMessagesFromFile, toUiMessageTimeline } from "./MessageTimeline.js";
 

package/src/{server → runtime/server}/rpc/Server.ts

@@ -13,8 +13,8 @@ import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
 import type { AgentContext } from "@/core/AgentContextTypes.js";
 import type { AgentCore } from "@/core/AgentCore.js";
 import type { JsonValue } from "@/types/common/Json.js";
-import type { LocalRpcRequest, LocalRpcResponse, LocalRpcServerHandle } from "@/types/rpc/LocalRpc.js";
-import type { ControlSessionExecuteRequestBody } from "@/server/http/control/types/ControlSessionExecute.js";
+import type { LocalRpcRequest, LocalRpcResponse, LocalRpcServerHandle } from "@/types/runtime/rpc/LocalRpc.js";
+import type { ControlSessionExecuteRequestBody } from "@/runtime/server/http/control/types/ControlSessionExecute.js";
 import type {
   PluginActionResponse,
   PluginAvailabilityResponse,
@@ -29,8 +29,8 @@ import type {
 import { listServiceStates, controlServiceState } from "@/service/core/ServiceStateController.js";
 import { runServiceCommand } from "@/service/core/ServiceActionRunner.js";
 import { parseServiceCommandRequestBody } from "@/service/core/ServiceCommandRequest.js";
-import { executeBySessionId } from "@/server/http/control/ExecuteBySession.js";
-import { getLocalRpcEndpoint } from "@/transport/rpc/Paths.js";
+import { executeBySessionId } from "@/runtime/server/http/control/ExecuteBySession.js";
+import { getLocalRpcEndpoint } from "@/runtime/transport/rpc/Paths.js";
 
 async function isSocketEndpointActive(endpoint: string): Promise<boolean> {
   return await new Promise<boolean>((resolve) => {

package/src/{transport → runtime/transport}/rpc/Client.ts

@@ -11,8 +11,8 @@ import { nanoid } from "nanoid";
 import type {
   DaemonJsonApiCallParams,
   DaemonJsonApiCallResult,
-} from "@/host/daemon/Api.js";
-import type { LocalRpcRequest, LocalRpcResponse } from "@/types/rpc/LocalRpc.js";
+} from "@/runtime/host/daemon/Api.js";
+import type { LocalRpcRequest, LocalRpcResponse } from "@/types/runtime/rpc/LocalRpc.js";
 import { getLocalRpcEndpoint } from "./Paths.js";
 
 const LOCAL_RPC_TIMEOUT_MS = 5_000;

package/src/{transport → runtime/transport}/rpc/Transport.ts

@@ -10,8 +10,8 @@
 import type {
   DaemonJsonApiCallParams,
   DaemonJsonApiCallResult,
-} from "@/host/daemon/Api.js";
-import { callServer } from "@/host/daemon/Client.js";
+} from "@/runtime/host/daemon/Api.js";
+import { callServer } from "@/runtime/host/daemon/Client.js";
 import { callLocalServer } from "./Client.js";
 
 /**

package/src/sdk/Agent.ts

@@ -27,8 +27,8 @@ import type {
 import { Session } from "@/sdk/Session.js";
 import { AgentCore } from "@/core/AgentCore.js";
 import { startAllServices, stopAllServices } from "@/service/core/Manager.js";
-import { startServer } from "@/server/http/Server.js";
-import { startLocalRpcServer } from "@/server/rpc/Server.js";
+import { startServer } from "@/runtime/server/http/Server.js";
+import { startLocalRpcServer } from "@/runtime/server/rpc/Server.js";
 
 /**
  * SDK 本地 Agent。

package/src/sdk/AgentSdkTypes.ts

@@ -12,9 +12,9 @@ import type { BaseService } from "@/service/builtins/BaseService.js";
 import type { JsonValue } from "@/types/common/Json.js";
 import type { Plugin } from "@/plugin/types/Plugin.js";
 import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
-import type { AgentPlatformRuntime } from "@/types/host/AgentHost.js";
-import type { LocalRpcServerHandle } from "@/types/rpc/LocalRpc.js";
-import type { ServerInstance } from "@/server/http/Server.js";
+import type { AgentPlatformRuntime } from "@/types/runtime/host/AgentHost.js";
+import type { LocalRpcServerHandle } from "@/types/runtime/rpc/LocalRpc.js";
+import type { ServerInstance } from "@/runtime/server/http/Server.js";
 import type { Session } from "@/sdk/Session.js";
 
 /**
@@ -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

@@ -4,13 +4,14 @@
  * 关键点（中文）
  * - 面向 `new Agent(...)` 的本地会话使用场景。
  * - 统一收口消息落盘、session 级模型配置、run/stream/fork 等高层 API。
- * - 内部继续复用 `Executor` / `JsonlSessionHistoryComposer` / `Runner`。
+ * - 内部继续复用 `Executor` / `JsonlSessionHistoryStore` / Composer 体系。
  */
 
 import { nanoid } from "nanoid";
 import type { LanguageModel, Tool } from "ai";
 import { Executor } from "@session/Executor.js";
 import { JsonlSessionHistoryComposer } from "@session/composer/history/jsonl/JsonlSessionHistoryComposer.js";
+import { JsonlSessionHistoryStore } from "@/session/store/history/jsonl/JsonlSessionHistoryStore.js";
 import { extractTextFromUiMessage } from "@/service/builtins/chat/runtime/UIMessageTransformer.js";
 import type {
   AgentSessionConfigSnapshot,
@@ -91,6 +92,15 @@ type SessionOptions = {
    * 读取当前 agent 显式注册 plugin 的 system blocks。
    */
   getPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
+
+  /**
+   * 在执行前确保当前 session 已完成宿主侧默认配置。
+   *
+   * 关键点（中文）
+   * - 这里通常由 `AgentCore` 注入，用于补齐默认 model、宿主覆写等一次性装配。
+   * - 所有执行入口都应通过这里兜底，避免只在 SDK `agent.session()` 链路上做配置。
+   */
+  ensureConfigured?: (session: Session) => Promise<void>;
 };
 
 /**
@@ -106,12 +116,15 @@ 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;
   private sessionConfig: AgentSessionConfigSnapshot = {};
   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) {
@@ -123,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");
     }
@@ -139,7 +153,7 @@ export class Session {
       this.id,
     );
     const messagesDirPath = `${sessionDirPath}/messages`;
-    this.historyComposer = new JsonlSessionHistoryComposer({
+    this.historyStore = new JsonlSessionHistoryStore({
       rootPath: this.projectRoot,
       sessionId: this.id,
       paths: {
@@ -154,9 +168,13 @@ export class Session {
         ),
       },
     });
+    this.historyComposer = new JsonlSessionHistoryComposer({
+      store: this.historyStore,
+    });
 
     this.executor = new Executor({
       sessionId: this.id,
+      historyStore: this.historyStore,
       historyComposer: this.historyComposer,
       getModel: () => this.sessionConfig.model,
       logger: this.logger as never,
@@ -275,7 +293,7 @@ export class Session {
    * 读取完整消息历史。
    */
   async history(): Promise<SessionMessageV1[]> {
-    return await this.historyComposer.list();
+    return await this.historyStore.list();
   }
 
   /**
@@ -332,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 });
@@ -360,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>();
@@ -404,7 +424,7 @@ export class Session {
    */
   async fork(input?: AgentSessionForkInput["messageId"]): Promise<Session> {
     const messageId = String(input || "").trim() || undefined;
-    const messages = await this.historyComposer.list();
+    const messages = await this.historyStore.list();
     const forkMessages =
       !messageId
         ? messages
@@ -437,7 +457,7 @@ export class Session {
       });
     }
     for (const message of forkMessages) {
-      await forked.historyComposer.append(message);
+      await forked.historyStore.append(message);
     }
     await forked.touchMetadata();
     return forked;
@@ -452,7 +472,7 @@ export class Session {
       agentId: this.agentId,
       sessionId: this.id,
     });
-    const messageCount = await this.historyComposer.size();
+    const messageCount = await this.historyStore.size();
     return {
       agentId: this.agentId,
       sessionId: this.id,
@@ -471,7 +491,10 @@ export class Session {
     this.servicePort = createSessionServicePort({
       sessionId: this.id,
       executor: this.executor,
-      historyComposer: this.historyComposer,
+      historyStore: this.historyStore,
+      ensureReadyForExecution: async () => {
+        await this.ensureReadyForExecution();
+      },
       touchMetadata: async () => {
         await this.touchMetadata();
       },
@@ -479,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/SessionSystemBuilder.ts

@@ -7,7 +7,7 @@
  * - SDK 不在 system 中注入动态变量；动态上下文应由调用方放入 user message。
  */
 
-import { SessionSystemComposer } from "@session/composer/system/SessionSystemComposer.js";
+import type { SessionSystemComposer } from "@session/composer/system/SessionSystemComposer.js";
 import { getSessionRunScope } from "@session/SessionRunScope.js";
 import type { SessionSystemMessage } from "@/session/types/SessionPrompts.js";
 import type {
@@ -211,7 +211,7 @@ export async function buildSessionSystemMessages(
 /**
  * SDK Session system composer 实现。
  */
-export class SessionSystemBuilder extends SessionSystemComposer {
+export class SessionSystemBuilder implements SessionSystemComposer {
   readonly name = "sdk_prompt_system";
 
   private readonly agentId: string;
@@ -223,7 +223,6 @@ export class SessionSystemBuilder extends SessionSystemComposer {
   private readonly getPluginSystemBlocks: SessionSystemBuilderOptions["getPluginSystemBlocks"];
 
   constructor(options: SessionSystemBuilderOptions) {
-    super();
     this.agentId = String(options.agentId || "").trim();
     this.projectRoot = String(options.projectRoot || "").trim();
     this.getSessionCreatedAt = options.getSessionCreatedAt;