@downcity/agent 1.1.438 → 1.1.445

package/src/session/Session.ts

@@ -7,14 +7,13 @@
  * - 内部使用 `SessionMessages` 管理 SQLite 中的 canonical Message 聚合。
  */
 
-import { Executor } from "@executor/Executor.js";
 import {
   type ModelClient,
   read_model_context_window,
   read_model_label,
-  type RuntimeTool as Tool,
+  type AgentTool as Tool,
 } from "@downcity/type";
-import { SessionMessages } from "@/session/SessionMessages.js";
+import { SessionMessages } from "@/session/messages/SessionMessages.js";
 import type {
   AgentSessionConfigSnapshot,
   AgentSessionForkInput,
@@ -32,42 +31,40 @@ import type {
   RespondSessionInteractionInput,
   SessionApprovalMode,
   SessionInteractionResult,
-  SessionPendingInteraction,
+  SessionInteractionRequest,
 } from "@downcity/type";
 import type { ListSessionMessagesInput, SessionMessagePage } from "@downcity/type";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
-import { SessionEventHub } from "@/session/runtime/SessionEventHub.js";
+import { SessionEventHub } from "@/session/messages/SessionEventHub.js";
 import {
   create_session_local_state,
   SessionState,
-} from "@/session/SessionState.js";
-import { SessionLoop } from "@/session/SessionLoop.js";
-import { SessionQueue } from "@/session/SessionQueue.js";
+} from "@/session/loop/SessionState.js";
+import { SessionLoop } from "@/session/loop/SessionLoop.js";
+import { SessionQueue } from "@/session/loop/SessionQueue.js";
 import type { SessionLocalState } from "@/types/session/SessionLocalState.js";
 import type { SessionOptions } from "@/types/session/SessionOptions.js";
-import type { SessionHookRuntime } from "@downcity/type";
-import { SessionInteractions } from "@/session/control/SessionInteractions.js";
-import { SessionShellApprovalAdapter } from "@/session/execution/tools/SessionShellApprovalAdapter.js";
-import { DefaultSessionComposer } from "@/session/DefaultSessionComposer.js";
+import type { ToolCallContext, ToolHookSet } from "@downcity/type";
+import { SessionInteractions } from "@/session/messages/SessionInteractions.js";
+import { DefaultSessionComposer } from "@/session/input/composer/DefaultSessionComposer.js";
 import type { SessionComposer } from "@/types/session/SessionComposer.js";
 import { generate_id } from "@/utils/Id.js";
 import { nanoid } from "nanoid";
-import { build_session_info } from "@/session/browse/Browse.js";
-import type { SessionActionEventInput } from "@downcity/type";
+import { build_session_info } from "@/session/storage/Browse.js";
 import type { SessionStorage } from "@/types/store/SessionStorage.js";
 import type {
   AppendExternalSessionAgentMessageInput,
   AppendExternalSessionUserMessageInput,
 } from "@/types/session/SessionMessages.js";
-import { SessionComposition } from "@/session/SessionComposition.js";
+import { StepInput } from "@/session/input/StepInput.js";
 import {
   relocate_fork_message_files,
   resolve_session_fork_messages,
 } from "@/session/messages/SessionForkMessageFiles.js";
-import { create_session_model_request_warning } from "@/session/runtime/SessionModelRequestWarning.js";
-import type { SessionContextRecoveryReason } from "@/types/session/SessionContextPolicy.js";
+import { create_session_model_request_warning } from "@/session/messages/SessionModelRequestWarning.js";
+import type { SessionContextAdvanceTrigger } from "@/types/session/SessionComposer.js";
 
 /**
  * SDK 本地 Session。
@@ -75,6 +72,10 @@ import type { SessionContextRecoveryReason } from "@/types/session/SessionContex
 export class Session implements AgentSession {
   readonly id: string;
   readonly agent_id: string;
+  /** 当前 Agent 用户可见名称；进入工具与扩展的调用环境。 */
+  readonly agent_name: string;
+  /** 当前 Agent 一句话能力描述；进入工具与扩展的调用环境。 */
+  readonly agent_description: string;
   /** 当前 Session 创建时绑定的 Workspace ID。 */
   readonly workspace_id?: string;
   /** 当前 Session 的创建来源。 */
@@ -86,17 +87,16 @@ export class Session implements AgentSession {
   private readonly register_forked_session: SessionOptions["register_forked_session"];
   private readonly get_tools: SessionOptions["get_tools"];
   private readonly logger: SessionOptions["logger"];
-  private readonly get_managed_plugin_system_blocks: SessionOptions["get_managed_plugin_system_blocks"];
-  private readonly ensure_configured_hook?: SessionOptions["ensure_configured"];
   private readonly composer: SessionComposer;
-  private readonly create_composer: () => SessionComposer;
   private readonly session_messages: SessionMessages;
-  private readonly executor: Executor;
   private readonly events: SessionEventHub;
   private readonly session_interactions: SessionInteractions;
-  private readonly shell_approval_adapter: SessionShellApprovalAdapter;
+  /** 当前执行面生效的审批模式；在 Step 检查点从 configured 同步。 */
+  private effective_approval_mode: SessionApprovalMode = "ask";
   private readonly local_state: SessionLocalState;
   private readonly get_workspace_env: SessionOptions["get_workspace_env"];
+  /** 读取当前 Session 绑定的 Workspace 实例。 */
+  private readonly get_workspace: SessionOptions["get_workspace"];
   private readonly get_agent_model: SessionOptions["get_agent_model"];
   private readonly get_hooks: SessionOptions["get_hooks"];
   private readonly get_instruction_system_blocks:
@@ -104,7 +104,7 @@ export class Session implements AgentSession {
   /** 当前 Session 的一次性初始化任务，避免缓存实例被重复恢复运行时状态。 */
   private initialize_promise: Promise<void> | null = null;
   /** 当前 Session 的 system snapshot 与 Step 组装边界。 */
-  private readonly session_composition: SessionComposition;
+  private readonly step_input: StepInput;
   private readonly state: SessionState;
   /** 当前 Session 独享的 Command FIFO。 */
   private readonly session_queue = new SessionQueue();
@@ -114,6 +114,8 @@ export class Session implements AgentSession {
   constructor(options: SessionOptions) {
     this.id = String(options.session_id || "").trim();
     this.agent_id = String(options.agent_id || "").trim();
+    this.agent_name = String(options.agent_name || "").trim() || this.agent_id;
+    this.agent_description = String(options.agent_description || "").trim();
     this.workspace_id = String(options.workspace_id || "").trim() || undefined;
     this.origin = options.origin;
     this.workspace_path = String(options.workspace_path || "").trim();
@@ -123,14 +125,11 @@ export class Session implements AgentSession {
     this.get_tools = options.get_tools;
     this.logger = options.logger;
     this.get_workspace_env = options.get_workspace_env;
+    this.get_workspace = options.get_workspace;
     this.get_agent_model = options.get_agent_model;
     this.get_hooks = options.get_hooks;
     this.get_instruction_system_blocks = options.get_instruction_system_blocks;
-    this.get_managed_plugin_system_blocks = options.get_managed_plugin_system_blocks;
-    this.ensure_configured_hook = options.ensure_configured;
-    this.create_composer = options.create_composer ||
-      (() => new DefaultSessionComposer());
-    this.composer = this.create_composer();
+    this.composer = options.composer ?? new DefaultSessionComposer();
     if (!this.id) {
       throw new Error("Session requires a non-empty session_id");
     }
@@ -153,14 +152,14 @@ export class Session implements AgentSession {
     this.session_interactions = new SessionInteractions({
       session_id: this.id,
       messages: this.session_messages,
-    });
-    this.shell_approval_adapter = new SessionShellApprovalAdapter({
-      session_id: this.id,
-      interactions: this.session_interactions,
+      // 审批入口读执行面当前模式；configured 与 effective 的区别保留。
+      read_approval_mode: () => this.effective_approval_mode,
     });
     this.local_state = create_session_local_state();
-    this.session_composition = new SessionComposition({
+    this.step_input = new StepInput({
       agent_id: this.agent_id,
+      agent_name: this.agent_name,
+      agent_description: this.agent_description,
       session_id: this.id,
       session_origin: this.origin,
       workspace_path: this.workspace_path,
@@ -171,14 +170,13 @@ export class Session implements AgentSession {
       get_instruction_system_blocks: this.get_instruction_system_blocks,
       get_hooks: this.get_hooks,
       get_workspace_env: this.get_workspace_env,
-      get_managed_plugin_system_blocks: this.get_managed_plugin_system_blocks,
+      get_workspace: this.get_workspace,
       get_model: () => this.get_model(),
       get_model_context_window: () => this.get_model_context_window(),
       get_created_at: () => this.local_state.created_at,
       get_timezone: () => this.local_state.timezone,
       logger: this.logger,
     });
-    this.executor = this.create_executor();
     this.state = new SessionState({
       agent_id: this.agent_id,
       session_id: this.id,
@@ -186,11 +184,6 @@ export class Session implements AgentSession {
       store: this.store,
       state: this.local_state,
       logger: this.logger,
-      ensure_configured_hook: this.ensure_configured_hook
-        ? async () => {
-            await this.ensure_configured_hook?.(this);
-          }
-        : undefined,
       get_model: () => this.get_model(),
       publish_event: (event) => {
         this.events.publish(event);
@@ -200,17 +193,19 @@ export class Session implements AgentSession {
       session_id: this.id,
       session_origin: this.origin,
       workspace_path: this.workspace_path,
-      executor: this.executor,
+      step_input: this.step_input,
+      advance_context: async (trigger) => await this.advance_context(trigger),
       maintain_context: async () => {
-        await this.recover_context("usage_pressure");
+        await this.advance_context("usage_pressure");
       },
       state: this.state,
       events: this.events,
       logger: this.logger,
       messages: this.session_messages,
       interactions: this.session_interactions,
-      shell_approval_gateway: this.shell_approval_adapter,
       queue: this.session_queue,
+      get_hooks: this.get_hooks,
+      create_call_context: (input) => this.create_turn_call_context(input),
     });
   }
 
@@ -221,13 +216,11 @@ export class Session implements AgentSession {
     if (!this.initialize_promise) {
       this.initialize_promise = (async () => {
         await Promise.all([
-          this.session_composition.initialize(),
+          this.step_input.initialize(),
           this.session_messages.initialize(),
           this.state.initialize(),
         ]);
-        this.shell_approval_adapter.set_effective_mode(
-          this.state.get_approval_mode(),
-        );
+        this.effective_approval_mode = this.state.get_approval_mode();
       })();
     }
     const initialize_promise = this.initialize_promise;
@@ -246,23 +239,23 @@ export class Session implements AgentSession {
    * 把当前 Session 首次生成后固定的完整 system 显式固化到 instruction.md。
    *
    * 关键点（中文）
-   * - 包含 instruction、SDK core、Plugin system 与 Session context。
+   * - 包含 instruction、SDK core、Power system 与 Session context。
    * - 多个 system block 按原顺序合并为一个 Markdown 文档。
    */
   async snapshot(): Promise<void> {
-    await this.session_composition.snapshot();
+    await this.step_input.snapshot();
   }
 
   /**
-   * 使用 Agent 当前 instruction 与 Plugin 重新生成一次完整 system。
+   * 使用 Agent 当前 instruction 与 Power 重新生成一次完整 system。
    *
    * 关键点（中文）
-   * - 只替换内存 snapshot，不改变 Plugin execution view。
+   * - 只替换内存 snapshot，不改变 Power execution view。
    * - instruction.md 已存在时同步覆盖；不存在时不自动创建。
    * - 当前已经发出的 provider 请求不受影响，后续 step 使用新 snapshot。
    */
   async syncshot(): Promise<void> {
-    await this.session_composition.syncshot();
+    await this.step_input.syncshot();
   }
 
   /**
@@ -345,7 +338,7 @@ export class Session implements AgentSession {
       execute: async () => {
         if (model_result) this.state.apply_model_config(model_result.config);
         if (security_changed && next_approval_mode) {
-          this.shell_approval_adapter.set_effective_mode(next_approval_mode);
+          this.effective_approval_mode = next_approval_mode;
         }
       },
       ...(completion ? { completion } : {}),
@@ -361,7 +354,7 @@ export class Session implements AgentSession {
    * 追加一条新的 Session prompt。
    */
   async prompt(input: AgentSessionPromptInput): Promise<AgentSessionTurnHandle> {
-    await this.session_composition.initialize();
+    await this.step_input.initialize();
     return await this.session_loop.prompt(input);
   }
 
@@ -382,7 +375,7 @@ export class Session implements AgentSession {
   }
 
   /** 列出当前 Session 正在等待用户响应的 Interaction。 */
-  async interactions(): Promise<SessionPendingInteraction[]> {
+  async interactions(): Promise<SessionInteractionRequest[]> {
     return this.session_interactions.list();
   }
 
@@ -391,11 +384,11 @@ export class Session implements AgentSession {
     const active_turn_id = this.session_loop.current_turn_id();
     return {
       session_id: this.id,
-      state: active_turn_id || this.executor.is_executing() ? "running" : "idle",
+      state: active_turn_id || this.session_loop.is_executing() ? "running" : "idle",
       ...(active_turn_id ? { active_turn_id } : {}),
       security: {
         approval_mode: this.state.get_approval_mode(),
-        effective_approval_mode: this.shell_approval_adapter.get_effective_mode(),
+        effective_approval_mode: this.effective_approval_mode,
       },
     };
   }
@@ -460,18 +453,21 @@ export class Session implements AgentSession {
    * 读取当前 session 生效的 system 快照。
    */
   async system(): Promise<AgentSessionSystemSnapshot> {
-    return await this.session_composition.read();
+    return await this.step_input.read_system();
   }
 
   /**
    * 返回当前 session 是否正在执行。
    */
   is_executing(): boolean {
-    return this.session_loop.is_active() || this.executor.is_executing();
+    return this.session_loop.is_active() || this.session_loop.is_executing();
   }
 
   /**
    * 从当前 session 创建一个分叉会话。
+   *
+   * 复制历史与附件是分叉 Session 自身的建立过程，因此 fork 的 Action 只记录在新 Session
+   * 时间线末尾，源 Session 不留下任何痕迹；失败时直接抛错，由调用方决定半成品 Session 的去留。
    */
   async fork(input?: AgentSessionForkInput | string): Promise<this> {
     const message_id = typeof input === "string"
@@ -487,48 +483,29 @@ export class Session implements AgentSession {
           include_message,
         })
       : messages;
-    const action_id = `history-forking:${this.id}:${Date.now()}:${nanoid(8)}`;
-    await this.emit_action_event({
-      action_id,
+    const forked = this.create_fork_session(
+      `fork-${Date.now()}-${nanoid(8)}`,
+    );
+    await forked.initialize();
+    const session_config = this.state.get_config();
+    if (session_config.model) {
+      const forked_model = await forked.state.set_model(session_config.model);
+      forked.state.apply_model_config(forked_model.config);
+    }
+    const approval_mode = this.state.get_approval_mode();
+    await forked.state.set_approval_mode(approval_mode);
+    forked.effective_approval_mode = approval_mode;
+    const relocated_messages = await relocate_fork_message_files(fork_messages, this.store.attachments, forked.store.attachments);
+    await forked.session_messages.import_messages(relocated_messages);
+    await forked.session_messages.persist_action({
+      action_id: `history-fork:${forked.id}:${Date.now()}:${nanoid(8)}`,
       action_type: "history-fork",
-      title: "Forking session messages",
-      description: `Preparing ${String(fork_messages.length)} messages for the new session.`,
-      status: "running",
+      title: "Session messages forked",
+      description: `Copied ${String(fork_messages.length)} messages from session ${this.id}.`,
+      status: "completed",
     });
-    try {
-      const forked = this.create_fork_session(
-        `fork-${Date.now()}-${nanoid(8)}`,
-      );
-      await forked.initialize();
-      const session_config = this.state.get_config();
-      if (session_config.model) {
-        const forked_model = await forked.state.set_model(session_config.model);
-        forked.state.apply_model_config(forked_model.config);
-      }
-      const approval_mode = this.state.get_approval_mode();
-      await forked.state.set_approval_mode(approval_mode);
-      forked.shell_approval_adapter.set_effective_mode(approval_mode);
-      const relocated_messages = await relocate_fork_message_files(fork_messages, this.store.attachments, forked.store.attachments);
-      await forked.session_messages.import_messages(relocated_messages);
-      this.register_forked_session(forked);
-      await this.emit_action_event({
-        action_id,
-        action_type: "history-fork",
-        title: "Session messages forked",
-        description: `Created ${forked.id} with ${String(fork_messages.length)} messages.`,
-        status: "completed",
-      });
-      return forked;
-    } catch (error) {
-      await this.emit_action_event({
-        action_id,
-        action_type: "history-fork",
-        title: "Session messages fork failed",
-        description: error instanceof Error ? error.message : String(error),
-        status: "failed",
-      });
-      throw error;
-    }
+    this.register_forked_session(forked);
+    return forked;
   }
 
   /**
@@ -539,7 +516,6 @@ export class Session implements AgentSession {
     this.runtime_port = create_runtime_session_port({
       session_id: this.id,
       get_model: () => this.get_model(),
-      get_executor: () => this.executor,
       messages: async () => await this.session_messages.list_history_messages(),
       prompt: async (input) => await this.prompt(input),
       stop: async () => await this.stop(),
@@ -565,13 +541,40 @@ export class Session implements AgentSession {
    * 在执行前确保 session 已完成初始化与宿主装配。
    */
   async ensure_ready_for_execution(): Promise<void> {
-    await this.session_composition.initialize();
+    await this.step_input.initialize();
     await this.state.ensure_ready_for_execution();
   }
 
+  /** 构造当前 Turn 的调用环境快照。 */
+  private create_turn_call_context(input: {
+    /** 当前 Turn 稳定标识。 */
+    readonly turn_id: string;
+    /** 当前 Turn 的取消信号。 */
+    readonly abort_signal: AbortSignal;
+  }): ToolCallContext {
+    const workspace = this.get_workspace();
+    return Object.freeze({
+      agent_id: this.agent_id,
+      agent_name: this.agent_name,
+      agent_description: this.agent_description,
+      agent_instructions: Object.freeze(
+        this.get_instruction_system_blocks().map((block) => block.content),
+      ),
+      session_id: this.id,
+      session_origin: this.origin,
+      ...(workspace ? { workspace } : {}),
+      turn_id: input.turn_id,
+      abort_signal: input.abort_signal,
+      interactions: this.session_interactions,
+      workspace_env: Object.freeze({ ...this.get_workspace_env() }),
+    });
+  }
+
   private create_fork_session(session_id: string): this {
     return this.create_child_session({
       agent_id: this.agent_id,
+      agent_name: this.agent_name,
+      agent_description: this.agent_description,
       workspace_path: this.workspace_path,
       ...(this.workspace_id ? { workspace_id: this.workspace_id } : {}),
       origin: this.origin,
@@ -581,14 +584,13 @@ export class Session implements AgentSession {
       session_id: session_id,
       get_tools: this.get_tools,
       logger: this.logger,
-      instruction_system_blocks: this.session_composition.instruction_blocks(),
+      instruction_system_blocks: this.step_input.instruction_blocks(),
       get_instruction_system_blocks: this.get_instruction_system_blocks,
       get_workspace_env: this.get_workspace_env,
+      get_workspace: this.get_workspace,
       get_hooks: this.get_hooks,
-      get_managed_plugin_system_blocks: this.get_managed_plugin_system_blocks,
-      ensure_configured: this.ensure_configured_hook,
       get_agent_model: this.get_agent_model,
-      create_composer: this.create_composer,
+      composer: this.composer,
     });
   }
 
@@ -606,40 +608,87 @@ export class Session implements AgentSession {
     return new session_class(options) as this;
   }
 
-  /** 创建只依赖统一 Composer 的 Turn Executor。 */
-  private create_executor(): Executor {
-    return new Executor({
-      session_id: this.id,
-      composer: this.composer,
-      get_compose_input: async (turn_context, retry_count) =>
-        await this.session_composition.create_compose_input(
-          turn_context,
-          retry_count,
-        ),
-      recover_context: async (reason) => await this.recover_context(reason),
-      logger: this.logger,
-      get_hooks: () => this.get_hooks(),
-      apply_system_snapshot: (input) => this.session_composition.apply_snapshot(input),
-    });
+  /**
+   * 让 Composer 尝试推进派生上下文状态。
+   *
+   * 上下文推进是用户可见的 Session 操作，因此结果记录为 Action：写入派生边界时记为
+   * completed，抛错时记为 failed。Composer 判定没有可推进区间时返回 false，此时不产生
+   * Action，避免空操作污染时间线。
+   */
+  private async advance_context(
+    trigger: SessionContextAdvanceTrigger,
+  ): Promise<boolean> {
+    const turn_id = this.session_loop.current_turn_id();
+    const action_id = `context-compaction:${this.id}:${generate_id()}`;
+    try {
+      const advanced = await this.composer.advance_context({
+        session: this.step_input.identity(),
+        model: this.get_model(),
+        history: await this.store.list_messages(),
+        derived: this.store.derived_store(this.composer.name),
+        trigger,
+        on_model_request_failure: (notice) => {
+          this.events.publish(create_session_model_request_warning({
+            session_id: this.id,
+            turn_id: this.session_loop.current_turn_id(),
+            notice,
+          }));
+        },
+      });
+      if (advanced) {
+        await this.record_compaction_action({
+          action_id,
+          turn_id,
+          status: "completed",
+          title: "Session context compacted",
+          description: "Older stable parts were folded into the context summary.",
+        });
+      }
+      return advanced;
+    } catch (error) {
+      await this.record_compaction_action({
+        action_id,
+        turn_id,
+        status: "failed",
+        title: "Session context compaction failed",
+        description: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
+    }
   }
 
-  /** 让 Composer 的 Context Policy 尝试推进派生上下文状态。 */
-  private async recover_context(
-    reason: SessionContextRecoveryReason,
-  ): Promise<boolean> {
-    return await this.composer.recover_context({
-      session: this.session_composition.compose_identity(),
-      model: this.get_model(),
-      storage: this.store,
-      reason,
-      on_model_request_failure: (notice) => {
-        this.events.publish(create_session_model_request_warning({
+  /** 记录一次上下文压缩结果；Action 观测失败不能改变压缩本身的执行结果。 */
+  private async record_compaction_action(input: {
+    /** 本次压缩生命周期的稳定标识。 */
+    action_id: string;
+    /** 压缩所属 Turn；独立的 Session 压缩可以省略。 */
+    turn_id?: string;
+    /** 压缩结果状态。 */
+    status: "completed" | "failed";
+    /** Action 展示标题。 */
+    title: string;
+    /** Action 展示描述。 */
+    description?: string;
+  }): Promise<void> {
+    try {
+      await this.session_messages.persist_action({
+        action_id: input.action_id,
+        action_type: "context-compaction",
+        ...(input.turn_id ? { turn_id: input.turn_id } : {}),
+        title: input.title,
+        ...(input.description ? { description: input.description } : {}),
+        status: input.status,
+      });
+    } catch (error) {
+      try {
+        await this.logger.log("warn", "[agent] context compaction action failed", {
           session_id: this.id,
-          turn_id: this.session_loop.current_turn_id(),
-          notice,
-        }));
-      },
-    });
+          action_id: input.action_id,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      } catch {
+        // 压缩结果已经确定，日志失败同样不能反向改变执行结果。
+      }    }
   }
 
   /**
@@ -688,19 +737,4 @@ export class Session implements AgentSession {
       input,
     );
   }
-
-  /** 持久化并发布一条只包含 Action Part 的 canonical Agent Message。 */
-  private async emit_action_event(input: SessionActionEventInput): Promise<void> {
-    const action_id = String(input.action_id || "").trim() ||
-      `action:${this.id}:${Date.now()}`;
-    await this.session_messages.persist_action({
-      action_id,
-      action_type: input.action_type,
-      ...(input.turn_id ? { turn_id: input.turn_id } : {}),
-      title: input.title,
-      ...(input.description ? { description: input.description } : {}),
-      status: input.status,
-    });
-  }
-
 }