@downcity/agent 1.1.32 → 1.1.35

package/src/config/Paths.ts

@@ -111,7 +111,7 @@ export function getDowncityMemoryDailyPath(cwd: string, date: string): string {
 }
 
 /**
- * Service Schedule JSONL 路径。
+ * Plugin Schedule JSONL 路径。
  *
  * 关键点（中文）
  * - 调度任务属于项目 runtime 本地状态，因此放在项目 `.downcity/` 下。
@@ -226,7 +226,7 @@ export function getDowncityDebugDirPath(cwd: string): string {
 }
 
 /**
- * Chat 元信息目录（由 service/builtins/chat 维护）。
+ * Chat 元信息目录（由 chat plugin runtime 维护）。
  *
  * 关键点（中文）
  * - 该目录存放 `sessionId -> chat` 的最近映射快照

package/src/config/project/AgentInitializer.ts

@@ -29,10 +29,11 @@ import {
 import { DEFAULT_DOWNCITY_JSON } from "@/config/Defaults.js";
 import { DOWNCITY_JSON_SCHEMA } from "@/config/DowncitySchema.js";
 import type { DowncityConfig } from "@/config/Config.js";
+import type { DowncityChatPluginChannelsConfig } from "@/types/config/DowncityConfig.js";
 import {
   DEFAULT_PROFILE_MD_TEMPLATE,
   DEFAULT_SOUL_MD_TEMPLATE,
-} from "@session/composer/system/default/InitPrompts.js";
+} from "@executor/composer/system/default/InitPrompts.js";
 import { renderTemplateVariables } from "@/utils/Template.js";
 import { ensureDir, saveJson } from "@/utils/storage/index.js";
 import type {
@@ -325,9 +326,7 @@ export async function initializeAgentProject(
     createdFiles.push(file.filename);
   }
 
-  const channelsConfig: NonNullable<
-    NonNullable<NonNullable<DowncityConfig["services"]>["chat"]>["channels"]
-  > = {};
+  const channelsConfig: DowncityChatPluginChannelsConfig = {};
   if (channels.includes("telegram")) {
     channelsConfig.telegram = { enabled: true };
   }
@@ -353,7 +352,7 @@ export async function initializeAgentProject(
     },
     ...(Object.keys(channelsConfig).length > 0
       ? {
-          services: {
+          plugins: {
             chat: {
               channels: channelsConfig,
             },

package/src/core/AgentContextTypes.ts

@@ -2,7 +2,7 @@
  * AgentCore 执行上下文类型定义。
  *
  * 关键点（中文）
- * - 这里定义 runtime plugin / plugin / prompt system 共用的统一执行上下文。
+ * - 这里定义 plugin runtime / plugin / prompt system 共用的统一执行上下文。
  * - `AgentContext` 表达的是“当前一次执行可见的能力面”，不是宿主状态本体。
  * - `AgentRuntime` 负责保存长期状态；`AgentContext` 负责把这些状态暴露成执行接口。
  */
@@ -26,12 +26,12 @@ import type {
 import type {
   SessionMetadataV1,
   SessionMessageV1,
-} from "@/session/types/SessionMessages.js";
+} from "@/executor/types/SessionMessages.js";
 import type {
   SessionRunInput,
   SessionRunResult,
-} from "@/session/types/SessionRun.js";
-import type { SessionHistoryStore } from "@/session/store/history/SessionHistoryStore.js";
+} from "@/executor/types/SessionRun.js";
+import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type {
   AgentSessionSubscriber,
@@ -40,7 +40,7 @@ import type {
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
 
 /**
- * 跨 runtime plugin 调用参数。
+ * 跨 plugin runtime 调用参数。
  */
 export interface InvokePluginParams {
   /**
@@ -58,7 +58,7 @@ export interface InvokePluginParams {
 }
 
 /**
- * 跨 runtime plugin 调用结果。
+ * 跨 plugin runtime 调用结果。
  */
 export interface InvokePluginResult {
   /**
@@ -76,7 +76,7 @@ export interface InvokePluginResult {
 }
 
 /**
- * 跨 runtime plugin 调用端口。
+ * 跨 plugin runtime 调用端口。
  */
 export interface InvokePluginPort {
   /**
@@ -214,7 +214,7 @@ export interface SessionCollectionPort {
  *
  * 关键点（中文）
  * - 这是当前 agent 已装配好的 chat 运行时视图。
- * - 其他 runtime plugin 只能通过这里消费 chat 能力，不能直接 import chat runtime 模块。
+ * - 其他 plugin runtime 只能通过这里消费 chat 能力，不能直接 import chat runtime 模块。
  */
 export interface ChatRuntimePort {
   /**
@@ -279,12 +279,12 @@ export interface AgentContext {
    * Session 能力入口。
    *
    * 关键点（中文）
-   * - runtime plugin 与 plugin 都通过这里访问 session 执行与持久化能力。
+   * - plugin runtime 与 plugin 都通过这里访问 session 执行与持久化能力。
    * - 内外统一使用 `sessionId` 语义。
    */
   session: SessionCollectionPort;
   /**
-   * 跨 runtime plugin 调用主入口。
+   * 跨 plugin runtime 调用主入口。
    */
   invoke: InvokePluginPort;
   /**

package/src/core/AgentCore.ts

@@ -19,19 +19,24 @@ import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
 import type { JsonValue } from "@/types/common/Json.js";
 import type { AgentPlatformRuntime } from "@/types/runtime/host/AgentHost.js";
 import type {
-  Plugin,
   PluginAvailability,
   PluginPort,
   PluginView,
 } from "@/plugin/types/Plugin.js";
 import type {
+  AgentMode,
+  AgentCreateSessionInput,
+  AgentListSessionsInput,
   AgentOptions,
-  AgentSessionMetadata,
+  AgentSessionSummaryPage,
   AgentSessionSystemBlock,
 } from "@/sdk/AgentSdkTypes.js";
 import { Session } from "@/sdk/Session.js";
-import { DEFAULT_SHIP_PROMPTS } from "@session/composer/system/default/SystemDomain.js";
-import { getSdkAgentSessionsRootDirPath } from "@/sdk/session/index.js";
+import { DEFAULT_SHIP_PROMPTS } from "@executor/composer/system/default/SystemDomain.js";
+import {
+  getSdkAgentSessionDirPath,
+  listAgentSessionSummaryPage,
+} from "@/sdk/session/index.js";
 import {
   createAgentPathRuntime,
   createAgentPluginConfigRuntime,
@@ -42,9 +47,8 @@ import { resolveChatQueueStore } from "@/plugin/builtins/chat/runtime/ChatQueueS
 import { HookRegistry } from "@/plugin/core/HookRegistry.js";
 import { PluginRegistry } from "@/plugin/core/PluginRegistry.js";
 import { isPluginEnabled } from "@/plugin/core/Activation.js";
-import { PLUGINS } from "@/plugin/core/Plugins.js";
 import { createRegisteredPluginInstances } from "@/plugin/core/PluginClassRegistry.js";
-import { setShellToolRuntime } from "@session/tools/shell/ShellToolDefinition.js";
+import { setShellToolRuntime } from "@executor/tools/shell/ShellToolDefinition.js";
 
 const EMPTY_SDK_PLATFORM: AgentPlatformRuntime = {
   getGlobalEnv: () => ({}),
@@ -114,7 +118,7 @@ export class AgentCore {
   readonly id: string;
   readonly path: string;
   readonly tools: Record<string, Tool>;
-  readonly runtimePlugins: Map<string, BasePlugin>;
+  readonly pluginInstances: Map<string, BasePlugin>;
   readonly plugins: PluginPort;
 
   private readonly logger: Logger;
@@ -122,7 +126,6 @@ export class AgentCore {
   private readonly runtime: AgentRuntime;
   private readonly agentContext: AgentContext;
   private readonly pluginRegistry: PluginRegistry;
-  private readonly pluginSystemProviders: Plugin[];
   private readonly config: DowncityConfig;
   private readonly platform: AgentPlatformRuntime;
   private readonly env: Record<string, string>;
@@ -130,7 +133,7 @@ export class AgentCore {
   private readonly defaultModel?: LanguageModel;
   private readonly configureSessionHook?: AgentOptions["configureSession"];
   private instruction: string[];
-  private runtimePluginsStartPromise: Promise<void> | null = null;
+  private pluginsStartPromise: Promise<void> | null = null;
   private configuredSessionIds = new Set<string>();
 
   constructor(options: AgentOptions) {
@@ -155,17 +158,13 @@ export class AgentCore {
     this.defaultModel = options.model;
     this.configureSessionHook = options.configureSession;
     this.config = this.loadConfig();
-    this.runtimePlugins = new Map<string, BasePlugin>();
+    this.pluginInstances = new Map<string, BasePlugin>();
     this.runtime = this.createRuntime();
-    this.registerRuntimePlugins({
-      explicitRuntimePlugins: options.runtimePlugins || [],
-      useBuiltinRuntimePlugins: options.useBuiltinRuntimePlugins === true,
-    });
-    this.pluginSystemProviders = this.resolvePlugins({
-      explicitPlugins: options.plugins,
-      useBuiltinPlugins: options.useBuiltinPlugins === true,
+    this.registerPlugins({
+      explicitPlugins: options.plugins || [],
+      mode: options.mode || "custom",
     });
-    this.pluginRegistry = this.createPluginRegistry(this.pluginSystemProviders);
+    this.pluginRegistry = this.createPluginRegistry([...this.pluginInstances.values()]);
     this.plugins = this.createPluginPort();
     this.agentContext = this.createAgentContext();
     setShellToolRuntime(this.agentContext.invoke);
@@ -200,53 +199,78 @@ export class AgentCore {
   }
 
   /**
-   * 获取或创建一个 session。
+   * 新建一个 session。
    */
-  async session(sessionId?: string): Promise<Session> {
-    const session = this.getOrCreateSession(sessionId);
+  async createSession(input?: AgentCreateSessionInput): Promise<Session> {
+    const explicitSessionId = String(input?.sessionId || "").trim() || undefined;
+    if (
+      explicitSessionId &&
+      (this.sessionsById.has(explicitSessionId) ||
+        (await fs.pathExists(
+          getSdkAgentSessionDirPath(this.path, this.id, explicitSessionId),
+        )))
+    ) {
+      throw new Error(`Session "${explicitSessionId}" already exists`);
+    }
+    const session = this.getOrCreateSession(explicitSessionId);
     await session.initialize();
     await this.configureSession(session);
     return session;
   }
 
   /**
-   * 列出当前 agent 的全部 session 元数据。
+   * 获取一个已存在的 session。
    */
-  async sessions(): Promise<AgentSessionMetadata[]> {
-    const rootDir = getSdkAgentSessionsRootDirPath(this.path, this.id);
-    if (!(await fs.pathExists(rootDir))) return [];
-    const entries = await fs.readdir(rootDir, { withFileTypes: true });
-    const items: AgentSessionMetadata[] = [];
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      let sessionId = "";
-      try {
-        sessionId = decodeURIComponent(entry.name);
-      } catch {
-        sessionId = entry.name;
-      }
-      if (!sessionId) continue;
-      const session = await this.session(sessionId);
-      items.push(await session.toMetadata());
+  async getSession(sessionId: string): Promise<Session> {
+    const resolvedSessionId = String(sessionId || "").trim();
+    if (!resolvedSessionId) {
+      throw new Error("getSession requires a non-empty sessionId");
+    }
+    const sessionDirPath = getSdkAgentSessionDirPath(
+      this.path,
+      this.id,
+      resolvedSessionId,
+    );
+    if (
+      !this.sessionsById.has(resolvedSessionId) &&
+      !(await fs.pathExists(sessionDirPath))
+    ) {
+      throw new Error(`Session "${resolvedSessionId}" not found`);
     }
-    items.sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
-    return items;
+    const session = this.getOrCreateSession(resolvedSessionId);
+    await session.initialize();
+    await this.configureSession(session);
+    return session;
   }
 
   /**
-   * 确保显式注入的 runtime plugins 已启动。
+   * 列出当前 agent 的 session 摘要页。
    */
-  async ensureRuntimePluginsStarted(): Promise<void> {
-    if (this.runtimePluginsStartPromise) {
-      await this.runtimePluginsStartPromise;
+  async listSessions(
+    input?: AgentListSessionsInput,
+  ): Promise<AgentSessionSummaryPage> {
+    return await listAgentSessionSummaryPage({
+      projectRoot: this.path,
+      agentId: this.id,
+      input,
+      executingSessionIds: new Set(this.runtime.listExecutingSessionIds()),
+    });
+  }
+
+  /**
+   * 确保当前 plugins 已启动。
+   */
+  async ensurePluginsStarted(): Promise<void> {
+    if (this.pluginsStartPromise) {
+      await this.pluginsStartPromise;
       return;
     }
-    this.runtimePluginsStartPromise = (async () => {
-      for (const plugin of this.runtimePlugins.values()) {
+    this.pluginsStartPromise = (async () => {
+      for (const plugin of this.pluginInstances.values()) {
         await plugin.lifecycle?.start?.(this.agentContext);
       }
     })();
-    await this.runtimePluginsStartPromise;
+    await this.pluginsStartPromise;
   }
 
   /**
@@ -268,39 +292,27 @@ export class AgentCore {
     }
   }
 
-  private registerRuntimePlugins(input: {
-    explicitRuntimePlugins: BasePlugin[];
-    useBuiltinRuntimePlugins: boolean;
+  private registerPlugins(input: {
+    explicitPlugins: BasePlugin[];
+    mode: AgentMode;
   }): void {
-    const explicitRuntimePlugins = input.explicitRuntimePlugins;
-    const builtinRuntimePlugins = input.useBuiltinRuntimePlugins
+    const presetPlugins = input.mode === "preset"
       ? [...createRegisteredPluginInstances(this.runtime).values()]
       : [];
-    for (const plugin of [...builtinRuntimePlugins, ...explicitRuntimePlugins]) {
+    for (const plugin of [...presetPlugins, ...input.explicitPlugins]) {
       const name = String(plugin?.name || "").trim();
       if (!name) {
-        throw new Error("Agent received a runtime plugin without a valid name");
+        throw new Error("Agent received a plugin without a valid name");
       }
-      if (this.runtimePlugins.has(name)) {
-        throw new Error(`Duplicate runtime plugin registration: ${name}`);
+      if (this.pluginInstances.has(name)) {
+        throw new Error(`Duplicate plugin registration: ${name}`);
       }
       plugin.bindAgent(this.runtime);
-      this.runtimePlugins.set(name, plugin);
-    }
-  }
-
-  private resolvePlugins(input: {
-    explicitPlugins?: Plugin[];
-    useBuiltinPlugins: boolean;
-  }): Plugin[] {
-    const plugins = input.useBuiltinPlugins ? [...PLUGINS] : [];
-    if (Array.isArray(input.explicitPlugins)) {
-      plugins.push(...input.explicitPlugins);
+      this.pluginInstances.set(name, plugin);
     }
-    return plugins;
   }
 
-  private createPluginRegistry(input: Plugin[]): PluginRegistry {
+  private createPluginRegistry(input: BasePlugin[]): PluginRegistry {
     let pluginRegistryRef: PluginRegistry | null = null;
     const hookRegistry = new HookRegistry({
       contextResolver: () => this.agentContext,
@@ -349,7 +361,7 @@ export class AgentCore {
 
   private async loadPluginSystemBlocks(): Promise<AgentSessionSystemBlock[]> {
     const out: AgentSessionSystemBlock[] = [];
-    for (const plugin of this.pluginSystemProviders) {
+    for (const plugin of this.pluginInstances.values()) {
       if (typeof plugin.system !== "function") continue;
       try {
         if (!isPluginEnabled({ plugin, context: this.agentContext })) continue;
@@ -371,25 +383,6 @@ export class AgentCore {
     return out;
   }
 
-  private async loadRuntimePluginSystemBlocks(): Promise<AgentSessionSystemBlock[]> {
-    const out: AgentSessionSystemBlock[] = [];
-    for (const plugin of this.runtimePlugins.values()) {
-      if (typeof plugin.system !== "function") continue;
-      try {
-        const text = String(await plugin.system(this.agentContext)).trim();
-        if (!text) continue;
-        out.push({
-          source: "plugin",
-          name: plugin.name,
-          content: text,
-        });
-      } catch {
-        // 单个 runtime plugin system 失败不应阻断 SDK session 主链路。
-      }
-    }
-    return out;
-  }
-
   private createRuntime(): AgentRuntime {
     const runtime = {
       cwd: this.path,
@@ -410,7 +403,7 @@ export class AgentCore {
           .map((session) => session.id),
       getExecutingSessionCount: () =>
         [...this.sessionsById.values()].filter((session) => session.isExecuting()).length,
-      runtimePlugins: this.runtimePlugins,
+      pluginInstances: this.pluginInstances,
     } satisfies AgentRuntime;
     return runtime;
   }
@@ -434,7 +427,7 @@ export class AgentCore {
         listExecutingSessionIds: () => this.runtime.listExecutingSessionIds(),
         getExecutingSessionCount: () => this.runtime.getExecutingSessionCount(),
         resolveModel: async (sessionId) => {
-          const session = await this.session(sessionId);
+          const session = await this.getSession(sessionId);
           return session.config.model;
         },
       },
@@ -446,7 +439,7 @@ export class AgentCore {
         }) => {
           const pluginName = String(params.plugin || "").trim();
           const actionName = String(params.action || "").trim();
-          const plugin = this.runtimePlugins.get(pluginName);
+          const plugin = this.pluginInstances.get(pluginName);
           if (!plugin) {
             return {
               success: false,
@@ -505,7 +498,7 @@ export class AgentCore {
       tools: this.tools,
       logger: this.logger,
       getInstructionSystemBlocks: () => this.loadInstructionSystemBlocks(),
-      getRuntimePluginSystemBlocks: () => this.loadRuntimePluginSystemBlocks(),
+      getManagedPluginSystemBlocks: async () => [],
       getPluginSystemBlocks: () => this.loadPluginSystemBlocks(),
       ensureConfigured: async (session) => {
         await this.configureSession(session);

package/src/core/AgentCoreTypes.ts

@@ -4,7 +4,7 @@
  * 关键点（中文）
  * - 这里表达的是单个 `AgentCore` 实例持有的长期运行状态。
  * - 它不再依赖 `runtime/*` 兼容层，而是作为实例级主类型来源。
- * - Session / runtime plugin / plugin 这些长期对象都从这里挂出。
+ * - Session / plugin 这些长期对象都从这里挂出。
  */
 
 import type { Logger } from "@/utils/logger/Logger.js";
@@ -72,7 +72,7 @@ export interface AgentRuntime extends AgentRuntimeBase {
    *
    * 关键点（中文）
    * - 返回值是统一的 `SessionPort`，而不是裸 `Executor`。
-   * - 这样 HTTP / runtime plugin / chat queue / contact 等入口都能复用同一层会话装配与执行兜底。
+   * - 这样 HTTP / plugin runtime / chat queue / contact 等入口都能复用同一层会话装配与执行兜底。
    */
   getSession(sessionId: string): SessionPort;
   /**
@@ -84,7 +84,7 @@ export interface AgentRuntime extends AgentRuntimeBase {
    */
   getExecutingSessionCount(): number;
   /**
-   * 当前 agent 持有的 runtime plugin instances。
+   * 当前 agent 持有的插件实例集合。
    */
-  runtimePlugins: Map<string, BasePlugin>;
+  pluginInstances: Map<string, BasePlugin>;
 }

package/src/{session → executor}/Executor.ts

@@ -8,17 +8,17 @@
  */
 
 import { streamText, type LanguageModel, type Tool } from "ai";
-import { SessionHistoryWriter } from "@session/composer/history/SessionHistoryWriter.js";
-import type { SessionHistoryComposer } from "@session/composer/history/SessionHistoryComposer.js";
-import type { SessionHistoryStore } from "@/session/store/history/SessionHistoryStore.js";
-import { withSessionRunScope } from "@session/SessionRunScope.js";
-import type { SessionRunScope } from "@session/SessionRunScope.js";
-import { buildSessionStepEventMessages } from "@session/messages/SessionStepEventMapper.js";
-import { JsonlSessionCompactionComposer } from "@session/composer/compaction/jsonl/JsonlSessionCompactionComposer.js";
-import { LocalSessionContextComposer } from "@session/composer/context/LocalSessionContextComposer.js";
-import type { SessionCompactionComposer } from "@session/composer/compaction/SessionCompactionComposer.js";
-import type { SessionContextComposer } from "@session/composer/context/SessionContextComposer.js";
-import type { SessionSystemComposer } from "@session/composer/system/SessionSystemComposer.js";
+import { SessionHistoryWriter } from "@executor/composer/history/SessionHistoryWriter.js";
+import type { SessionHistoryComposer } from "@executor/composer/history/SessionHistoryComposer.js";
+import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
+import { withSessionRunScope } from "@executor/SessionRunScope.js";
+import type { SessionRunScope } from "@executor/SessionRunScope.js";
+import { buildSessionStepEventMessages } from "@executor/messages/SessionStepEventMapper.js";
+import { JsonlSessionCompactionComposer } from "@executor/composer/compaction/jsonl/JsonlSessionCompactionComposer.js";
+import { LocalSessionContextComposer } from "@executor/composer/context/LocalSessionContextComposer.js";
+import type { SessionCompactionComposer } from "@executor/composer/compaction/SessionCompactionComposer.js";
+import type { SessionContextComposer } from "@executor/composer/context/SessionContextComposer.js";
+import type { SessionSystemComposer } from "@executor/composer/system/SessionSystemComposer.js";
 import {
   MAX_INCOMPLETE_RESPONSE_RECOVERIES,
   MAX_TEXT_ONLY_CONTINUATIONS,
@@ -31,30 +31,30 @@ import {
   summarizeStepForDebug,
   summarizeUiMessageForDebug,
   toInlinePreview,
-} from "@session/core-engine/CoreEngineSignals.js";
+} from "@executor/core-engine/CoreEngineSignals.js";
 import {
   evaluateCoreEngineLoopDecision,
   shouldContinueForTailMergedUserMessages,
-} from "@session/core-engine/CoreEngineLoopDecision.js";
+} from "@executor/core-engine/CoreEngineLoopDecision.js";
 import {
   resolveEffectiveCoreEngineError,
   summarizeStreamError,
-} from "@session/core-engine/CoreEngineError.js";
-import { collectFinalAssistantMessageFromUiStream } from "@session/core-engine/CoreEngineUiStreamCollector.js";
-import { CoreEngineMessageState } from "@session/core-engine/CoreEngineMessageState.js";
+} from "@executor/core-engine/CoreEngineError.js";
+import { collectFinalAssistantMessageFromUiStream } from "@executor/core-engine/CoreEngineUiStreamCollector.js";
+import { CoreEngineMessageState } from "@executor/core-engine/CoreEngineMessageState.js";
 import {
   buildOpenAIResponsesProviderOptions,
-} from "@session/messages/SessionMessageCodec.js";
-import { logAssistantMessageNow } from "@session/messages/SessionMessageLog.js";
+} from "@executor/messages/SessionMessageCodec.js";
+import { logAssistantMessageNow } from "@executor/messages/SessionMessageLog.js";
 import type { Logger } from "@/utils/logger/Logger.js";
 import type { JsonObject } from "@/types/common/Json.js";
-import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
-import type { SessionExecutor } from "@/session/types/SessionExecutor.js";
+import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+import type { SessionExecutor } from "@/executor/types/SessionExecutor.js";
 import type {
   SessionExecuteInput,
   SessionRunInput,
   SessionRunResult,
-} from "@/session/types/SessionRun.js";
+} from "@/executor/types/SessionRun.js";
 
 /**
  * 可压缩错误的最大重试次数。

package/src/{session → executor}/README.md

@@ -1,6 +1,6 @@
-# Session Module
+# Executor Module
 
-`session/` 是单 Agent 会话执行内核。它不直接面向普通 SDK 用户；普通用户通过 `sdk/Session.ts` 使用 `session.prompt()`、`session.subscribe()`、`session.history()` 等 API。
+`executor/` 是单 Agent 的内部执行内核。它不直接面向普通 SDK 用户；普通用户通过 `sdk/Session.ts` 使用 `session.prompt()`、`session.subscribe()`、`session.history()` 等 API。
 
 ## 核心概念
 
@@ -17,7 +17,7 @@
 sdk/Session.prompt({ query })
   -> SessionPromptRuntime 绑定 turn
   -> append user message
-  -> session/Executor 执行当前 turn
+  -> executor/Executor 执行当前 turn
      -> ContextComposer.compose()
      -> SystemComposer.resolve()
      -> CompactionComposer.run()
@@ -31,7 +31,7 @@ sdk/Session.prompt({ query })
 
 ## Composer 分工
 
-- `composer/system/`：组装本轮 system messages，例如 instruction、service system、plugin system 和 session context。
+- `composer/system/`：组装本轮 system messages，例如 instruction、plugin system 和 session context。
 - `composer/history/`：只组装本轮 model messages，不负责历史落盘。
 - `composer/context/`：组装 tools、step hooks、fallback assistant message 等运行上下文。
 - `composer/compaction/`：判断上下文错误和压缩历史，必要时写入 summary 与 archive。
@@ -83,7 +83,7 @@ Executor.prepareExecuteInput()
 ## 当前目录结构
 
 ```text
-session/
+executor/
 ├── Executor.ts
 ├── SessionRunScope.ts
 ├── composer/

package/src/{session → executor}/SessionRunScope.ts

@@ -1,15 +1,15 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import type { SessionUserMessageV1 } from "@/session/types/SessionMessages.js";
+import type { SessionUserMessageV1 } from "@/executor/types/SessionMessages.js";
 import type {
   SessionAssistantStepCallback,
   SessionUiMessageChunkCallback,
-} from "@/session/types/SessionRun.js";
+} from "@/executor/types/SessionRun.js";
 
 /**
  * SessionRunScope（单次请求作用域）。
  *
  * 关键点（中文）
- * - 这是 session run 层请求作用域上下文，不属于具体 service 模块。
+ * - 这是 session run 层请求作用域上下文，不属于具体 plugin 业务模块。
  * - 统一承载请求链需要透传的字段（如 `sessionId`）。
  */
 export type SessionRunScope = {
@@ -46,7 +46,7 @@ export type SessionRunScope = {
    *
    * 关键点（中文）
    * - 用于在 tool 执行后向下一 step 注入结构化 user 消息。
-   * - 队列内容由 service 侧通过统一协议下发，main 不感知业务语义。
+   * - 队列内容由上层 plugin runtime 通过统一协议下发，main 不感知业务语义。
    */
   injectedUserMessages?: SessionUserMessageV1[];
 };
@@ -56,7 +56,7 @@ export type SessionRunScope = {
  *
  * 关键点（中文）
  * - 同一条异步调用链内可读取一致的 SessionRunScope。
- * - 用于把 `sessionId` 从入口透传到 service 与工具层。
+ * - 用于把 `sessionId` 从入口透传到 plugin runtime 与工具层。
  */
 export const sessionRunScopeStorage = new AsyncLocalStorage<SessionRunScope>();
 

package/src/{session → executor}/composer/compaction/SessionCompactionComposer.ts

@@ -7,7 +7,7 @@
  */
 
 import type { LanguageModel, SystemModelMessage } from "ai";
-import type { SessionHistoryStore } from "@/session/store/history/SessionHistoryStore.js";
+import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
 
 /**
  * compaction Composer 执行输入。

package/src/{session → executor}/composer/compaction/jsonl/JsonlSessionCompactionComposer.ts

@@ -9,7 +9,7 @@
 import type {
   SessionCompactionComposer,
   SessionCompactionInput,
-} from "@session/composer/compaction/SessionCompactionComposer.js";
+} from "@executor/composer/compaction/SessionCompactionComposer.js";
 
 type JsonlSessionCompactionComposerOptions = {
   keepLastMessages?: number;

package/src/{session → executor}/composer/compaction/jsonl/JsonlSessionCompactionExecutor.ts

@@ -20,8 +20,8 @@ import { getLogger } from "@/utils/logger/Logger.js";
 import type {
   SessionMessageV1,
   SessionMetadataV1,
-} from "@/session/types/SessionMessages.js";
-import type { SessionHistoryMetaV1 } from "@/session/types/SessionHistoryMeta.js";
+} from "@/executor/types/SessionMessages.js";
+import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
 
 export type SessionCompactParams = {
   model: LanguageModel;