@downcity/agent 1.1.445 → 1.5.0

package/src/agent/SessionWork.ts

@@ -0,0 +1,235 @@
+/**
+ * SessionWork：Agent 会话安排与观察其他会话的实现。
+ *
+ * 职责说明（中文）
+ * - 把 AgentSessions 的能力投影成「一件活」的完整动作：开、看、答、停。
+ * - 只读取公开的摘要与消息投影，不缓存会话，也不持有存储。
+ *
+ * 关键点（中文）
+ * - 清单排除 Agent 自己的会话，否则清单里会出现「自己」。
+ * - `spawn` 不等待 Turn 结束：派活的意义就是 Agent 会话立刻能继续。
+ * - 详情按最近消息分页读取，让对话能回答「它做了什么」，而不把整段历史塞进上下文。
+ */
+
+import type { SessionInteractionResponse, WorkspaceRuntime } from "@downcity/type";
+import { is_agent_session_origin } from "@downcity/type";
+import type { SessionWorkContract } from "@/types/agent/SessionWork.js";
+import type {
+  SessionCheckDetailToolOutput,
+  SessionToolState,
+  SessionToolSummary,
+} from "@/types/tools/session/SessionTools.js";
+import type { AgentSession } from "@/types/agent/SessionActor.js";
+
+/** 清单默认返回的会话数量上限。 */
+const DEFAULT_SESSION_LIMIT = 20;
+
+/** 详情默认返回的最近消息条数。 */
+const DEFAULT_MESSAGE_LIMIT = 20;
+
+/** 清单中的一条会话列表项；由 AgentSessions 摘要投影而来。 */
+export interface SessionWorkListEntry {
+  /** 会话稳定标识。 */
+  session_id: string;
+  /** 用户可见标题；未生成时省略。 */
+  title?: string;
+  /** 最近更新的预览文本。 */
+  preview_text?: string;
+  /** 最近更新时间戳（ms）。 */
+  updated_at?: number;
+  /** 会话来源。 */
+  origin: { type: string };
+  /** 当前是否正在执行。 */
+  executing?: boolean;
+}
+
+/** SessionWork 构造参数。 */
+export interface SessionWorkOptions {
+  /** 列出活动会话摘要，`limit` 由本模块归一化后传入。 */
+  list_sessions: (input: { limit: number }) => Promise<{
+    items: SessionWorkListEntry[];
+  }>;
+  /** 恢复单条会话的运行时实例。 */
+  get_session: (session_id: string, origin_type: string) => Promise<AgentSession>;
+  /** 新建一条属于当前 Agent 的会话。 */
+  create_session: (input?: { workspace?: WorkspaceRuntime }) => Promise<AgentSession>;
+}
+
+/** Agent 会话的会话工作运行时。 */
+export class SessionWork implements SessionWorkContract {
+  private readonly options: SessionWorkOptions;
+
+  constructor(options: SessionWorkOptions) {
+    this.options = options;
+  }
+
+  /** 开一条工作会话并立刻把任务交给它。 */
+  async spawn(input: {
+    query: string;
+    title?: string;
+    workspace?: WorkspaceRuntime;
+  }): Promise<{ session_id: string }> {
+    const query = String(input.query || "").trim();
+    if (!query) throw new Error("session_start requires a non-empty query");
+    const session = await this.options.create_session(
+      input.workspace ? { workspace: input.workspace } : undefined,
+    );
+    const title = String(input.title || "").trim();
+    if (title) await session.rename(title);
+    // 不等待 Turn 结束：派活的意义就是 Agent 会话立刻能继续。
+    void session.prompt({ query }).catch(() => undefined);
+    return { session_id: session.id };
+  }
+
+  /** 列出当前 Agent 除自己那条之外的全部会话。 */
+  async list(input?: { limit?: number }): Promise<SessionToolSummary[]> {
+    const page = await this.options.list_sessions({
+      limit: normalize_limit(input?.limit, DEFAULT_SESSION_LIMIT),
+    });
+    const summaries: SessionToolSummary[] = [];
+    for (const item of page.items) {
+      if (is_agent_session_origin(item.origin)) continue;
+      const pending_interaction_count = await this.count_pending(item);
+      summaries.push({
+        session_id: item.session_id,
+        ...(item.title ? { title: item.title } : {}),
+        state: resolve_session_state({
+          executing: item.executing === true,
+          pending_interaction_count,
+        }),
+        ...(item.preview_text ? { preview_text: item.preview_text } : {}),
+        ...(typeof item.updated_at === "number" ? { updated_at: item.updated_at } : {}),
+        pending_interaction_count,
+      });
+    }
+    return summaries;
+  }
+
+  /** 读取单条会话的摘要、最近消息与待响应 Interaction。 */
+  async read(input: {
+    session_id: string;
+    limit?: number;
+  }): Promise<SessionCheckDetailToolOutput> {
+    const item = await this.require_list_entry(input.session_id);
+    const session = await this.options.get_session(item.session_id, item.origin.type);
+    const [messages, pending, status] = await Promise.all([
+      session.messages({ limit: normalize_limit(input.limit, DEFAULT_MESSAGE_LIMIT) }),
+      session.interactions(),
+      session.status(),
+    ]);
+    const failure = resolve_failure_text(messages.items);
+    return {
+      mode: "detail",
+      session: {
+        session_id: item.session_id,
+        ...(item.title ? { title: item.title } : {}),
+        state: resolve_session_state({
+          executing: status.state === "running",
+          pending_interaction_count: pending.length,
+        }),
+        ...(item.preview_text ? { preview_text: item.preview_text } : {}),
+        ...(typeof item.updated_at === "number" ? { updated_at: item.updated_at } : {}),
+        pending_interaction_count: pending.length,
+      },
+      messages: messages.items
+        .map((message) => project_message_text(message))
+        .filter((entry): entry is { role: "user" | "agent"; text: string } => Boolean(entry)),
+      pending_interactions: pending.map((interaction) => ({
+        interaction_id: interaction.interaction_id,
+        type: interaction.type,
+        ...(interaction.title ? { title: interaction.title } : {}),
+        ...(interaction.description ? { description: interaction.description } : {}),
+      })),
+      ...(failure ? { failure } : {}),
+    };
+  }
+
+  /** 代答某条会话正在等待的用户响应。 */
+  async reply(input: {
+    session_id: string;
+    interaction_id: string;
+    response: SessionInteractionResponse;
+  }): Promise<void> {
+    const item = await this.require_list_entry(input.session_id);
+    const session = await this.options.get_session(item.session_id, item.origin.type);
+    const pending = await session.interactions();
+    if (!pending.some((entry) => entry.interaction_id === input.interaction_id)) {
+      throw new Error(
+        `Interaction is not pending on session "${input.session_id}": ${input.interaction_id}`,
+      );
+    }
+    await session.respond({
+      interaction_id: input.interaction_id,
+      response: input.response,
+    });
+  }
+
+  /** 停止某条会话当前正在执行的 Turn。 */
+  async stop(input: { session_id: string }): Promise<void> {
+    const item = await this.require_list_entry(input.session_id);
+    const session = await this.options.get_session(item.session_id, item.origin.type);
+    await session.stop();
+  }
+
+  /** 按标识取出属于当前 Agent 的一条会话；不存在时明确失败。 */
+  private async require_list_entry(session_id_input: string): Promise<SessionWorkListEntry> {
+    const session_id = String(session_id_input || "").trim();
+    if (!session_id) throw new Error("Session id is required");
+    const page = await this.options.list_sessions({ limit: Number.MAX_SAFE_INTEGER });
+    const item = page.items.find((candidate) => candidate.session_id === session_id);
+    if (!item) throw new Error(`Session is not owned by this agent: ${session_id}`);
+    return item;
+  }
+
+  /** 读取一条会话当前待响应的 Interaction 数量；读取失败时按零处理。 */
+  private async count_pending(item: SessionWorkListEntry): Promise<number> {
+    try {
+      const session = await this.options.get_session(item.session_id, item.origin.type);
+      return (await session.interactions()).length;
+    } catch {
+      return 0;
+    }
+  }
+}
+
+/** 归一化可选数量上限；非法值回退到默认值。 */
+function normalize_limit(input: number | undefined, fallback: number): number {
+  return Number.isInteger(input) && (input as number) > 0 ? (input as number) : fallback;
+}
+
+/** 由执行态与待响应数量推导清单状态。 */
+function resolve_session_state(input: {
+  /** 该会话当前是否在执行 Turn。 */
+  executing: boolean;
+  /** 当前待用户响应的 Interaction 数量。 */
+  pending_interaction_count: number;
+}): SessionToolState {
+  if (input.pending_interaction_count > 0) return "waiting_for_user";
+  if (input.executing) return "running";
+  return "idle";
+}
+
+/** 把 canonical Message 投影为纯文本；没有可见文本时返回空。 */
+function project_message_text(message: {
+  role: string;
+  parts: readonly { type: string; text?: string }[];
+}): { role: "user" | "agent"; text: string } | null {
+  if (message.role !== "user" && message.role !== "agent") return null;
+  const text = message.parts
+    .flatMap((part) => (typeof part.text === "string" ? [part.text] : []))
+    .join("\n")
+    .trim();
+  return text ? { role: message.role, text } : null;
+}
+
+/** 读取最近一条 Agent 消息上的失败文本；没有失败时返回空。 */
+function resolve_failure_text(
+  messages: readonly {
+    role: string;
+    parts: readonly { type: string; message?: string }[];
+  }[],
+): string | undefined {
+  const latest_agent = [...messages].reverse().find((message) => message.role === "agent");
+  const error = latest_agent?.parts.find((part) => part.type === "error");
+  return error?.message ? error.message : undefined;
+}

package/src/index.ts

@@ -9,6 +9,25 @@
 
 // Agent 入口
 export { Agent } from "./agent/Agent.js";
+export type { AgentSessionInput } from "./types/agent/AgentSessionInput.js";
+export type { SessionWorkContract } from "./types/agent/SessionWork.js";
+export type { SessionContextResolution } from "./types/agent/SessionContext.js";
+export type {
+  AgentSessionStateKey,
+  AgentSessionStateValues,
+  RemoteSessionStateKey,
+  RemoteSessionStateValues,
+} from "./types/agent/SessionState.js";
+export type {
+  SessionCheckDetailToolOutput,
+  SessionCheckListToolOutput,
+  SessionCheckToolOutput,
+  SessionReplyToolOutput,
+  SessionStartToolOutput,
+  SessionStopToolOutput,
+  SessionToolState,
+  SessionToolSummary,
+} from "./types/tools/session/SessionTools.js";
 export { Group } from "./group/Group.js";
 export type {
   DispatchAssignment,

package/src/session/Session.ts

@@ -45,8 +45,12 @@ import {
 import { SessionLoop } from "@/session/loop/SessionLoop.js";
 import { SessionQueue } from "@/session/loop/SessionQueue.js";
 import type { SessionLocalState } from "@/types/session/SessionLocalState.js";
+import type {
+  AgentSessionStateKey,
+  AgentSessionStateValues,
+} from "@/types/agent/SessionState.js";
 import type { SessionOptions } from "@/types/session/SessionOptions.js";
-import type { ToolCallContext, ToolHookSet } from "@downcity/type";
+import type { ToolCallContext, ToolHookSet, WorkspaceRuntime } 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";
@@ -76,12 +80,15 @@ export class Session implements AgentSession {
   readonly agent_name: string;
   /** 当前 Agent 一句话能力描述；进入工具与扩展的调用环境。 */
   readonly agent_description: string;
-  /** 当前 Session 创建时绑定的 Workspace ID。 */
-  readonly workspace_id?: string;
+  /**
+   * 当前 Session 正在使用的 Workspace ID。
+   *
+   * 关键点（中文）：这是可变的会话状态，不是身份；切换目录后随之改变。
+   */
+  workspace_id?: string;
   /** 当前 Session 的创建来源。 */
   readonly origin: SessionOptions["origin"];
 
-  private readonly workspace_path: string;
   private readonly store: SessionStorage;
   private readonly create_session_store: SessionOptions["create_session_store"];
   private readonly register_forked_session: SessionOptions["register_forked_session"];
@@ -94,9 +101,6 @@ export class Session implements AgentSession {
   /** 当前执行面生效的审批模式；在 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:
@@ -116,16 +120,13 @@ export class Session implements AgentSession {
     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.workspace_id = String(options.workspace?.id || "").trim() || undefined;
     this.origin = options.origin;
-    this.workspace_path = String(options.workspace_path || "").trim();
     this.store = options.store;
     this.create_session_store = options.create_session_store;
     this.register_forked_session = options.register_forked_session;
     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;
@@ -136,7 +137,7 @@ export class Session implements AgentSession {
     if (!this.agent_id) {
       throw new Error("Session requires a non-empty agent_id");
     }
-    if (!this.workspace_path) {
+    if (!String(options.workspace_path || "").trim()) {
       throw new Error("Session requires a non-empty workspace_path");
     }
 
@@ -155,22 +156,24 @@ export class Session implements AgentSession {
       // 审批入口读执行面当前模式；configured 与 effective 的区别保留。
       read_approval_mode: () => this.effective_approval_mode,
     });
-    this.local_state = create_session_local_state();
+    this.local_state = create_session_local_state({
+      ...(options.workspace ? { workspace: options.workspace } : {}),
+      fallback_workspace_path: String(options.workspace_path || "").trim(),
+    });
     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,
+      get_workspace_path: () => this.get_workspace_path(),
       store: this.store,
       composer: this.composer,
       get_tools: this.get_tools,
       instruction_system_blocks: options.instruction_system_blocks,
       get_instruction_system_blocks: this.get_instruction_system_blocks,
       get_hooks: this.get_hooks,
-      get_workspace_env: this.get_workspace_env,
-      get_workspace: this.get_workspace,
+      get_workspace: () => this.local_state.current_workspace,
       get_model: () => this.get_model(),
       get_model_context_window: () => this.get_model_context_window(),
       get_created_at: () => this.local_state.created_at,
@@ -192,7 +195,7 @@ export class Session implements AgentSession {
     this.session_loop = new SessionLoop({
       session_id: this.id,
       session_origin: this.origin,
-      workspace_path: this.workspace_path,
+      get_workspace_path: () => this.get_workspace_path(),
       step_input: this.step_input,
       advance_context: async (trigger) => await this.advance_context(trigger),
       maintain_context: async () => {
@@ -260,9 +263,45 @@ export class Session implements AgentSession {
 
   /**
    * 读取当前 session 配置快照。
+   *
+   * 删除说明：它与 `get("model")` / `get("model_label")` 重复；
+   * 读取统一走 `get(key)`，不再保留属性形式的入口。
+   */
+
+  /**
+   * 读取当前 Session 状态。
+   *
+   * 关键点（中文）
+   * - 持久化字段与运行时实例共用这一个入口；键名即语义。
+   * - 只读，不产生副作用：不解析、不落盘、不发布 mutation。
    */
-  get config(): AgentSessionConfigSnapshot {
-    return this.state.get_config();
+  get<K extends AgentSessionStateKey>(key: K): AgentSessionStateValues[K] {
+    switch (key) {
+      case "workspace":
+        return this.local_state.current_workspace as AgentSessionStateValues[K];
+      case "workspace_id":
+        return this.workspace_id as AgentSessionStateValues[K];
+      case "model":
+        return this.get_selected_model() as AgentSessionStateValues[K];
+      case "model_label":
+        return this.state.get_config().model_label as AgentSessionStateValues[K];
+      case "model_context_window":
+        return this.state.get_config().model_context_window as AgentSessionStateValues[K];
+      case "approval_mode":
+        return this.state.get_approval_mode() as AgentSessionStateValues[K];
+      case "title":
+        return this.local_state.title as AgentSessionStateValues[K];
+      case "timezone":
+        return this.local_state.timezone as AgentSessionStateValues[K];
+      case "created_at":
+        return this.local_state.created_at as AgentSessionStateValues[K];
+      case "updated_at":
+        return this.local_state.updated_at as AgentSessionStateValues[K];
+      default: {
+        const unreachable: never = key;
+        throw new Error(`Unsupported session state key: ${String(unreachable)}`);
+      }
+    }
   }
 
   /**
@@ -272,8 +311,8 @@ export class Session implements AgentSession {
     input: AgentSessionSetInput,
     options?: AgentSessionSetOptions,
   ): Promise<void> {
-    if (!input.model && !input.security) {
-      throw new Error("session.set requires model or security");
+    if (!input.model && !input.security && input.workspace === undefined) {
+      throw new Error("session.set requires model, security, or workspace");
     }
     const requested_approval_mode = input.security?.approval_mode;
     if (
@@ -296,11 +335,28 @@ export class Session implements AgentSession {
     const model_result = input.model
       ? await this.state.set_model(input.model)
       : undefined;
+    const workspace_changed = input.workspace !== undefined
+      ? await this.state.apply_workspace(input.workspace ?? undefined)
+      : false;
+    const next_workspace = this.local_state.current_workspace;
     const next_approval_mode = requested_approval_mode;
     const security_changed = next_approval_mode !== undefined
       ? await this.state.set_approval_mode(next_approval_mode)
       : false;
-    if (!model_result && !security_changed) return;
+    if (!model_result && !security_changed && !workspace_changed) return;
+    if (workspace_changed) {
+      this.workspace_id = next_workspace?.id;
+    }
+    if (workspace_changed && publish_mutation) {
+      this.events.publish({
+        mutation_id: generate_id(),
+        variant: "session",
+        type: "workspace",
+        session_id: this.id,
+        created_at: Date.now(),
+        ...(next_workspace ? { workspace_id: next_workspace.id } : {}),
+      });
+    }
     if (model_result?.changed && publish_mutation) {
       this.events.publish({
         mutation_id: generate_id(),
@@ -320,6 +376,9 @@ export class Session implements AgentSession {
       ...(model_result?.changed
         ? [`model: ${String(model_result.config.model_label || "configured")}`]
         : []),
+      ...(workspace_changed
+        ? [`workspace: ${String(next_workspace?.id || "none")}`]
+        : []),
       ...(security_changed
         ? [`security.approval_mode: ${String(next_approval_mode)}`]
         : []),
@@ -431,7 +490,7 @@ export class Session implements AgentSession {
       "",
     ).trim();
     return build_session_info({
-      project_root: this.workspace_path,
+      project_root: this.get_workspace_path(),
       agent_id: this.agent_id,
       session_id: this.id,
       metadata: {
@@ -449,6 +508,20 @@ export class Session implements AgentSession {
     return await this.session_messages.list_messages(input);
   }
 
+  /**
+   * 返回当前目录；没有项目上下文时为空。
+   *
+   * 关键点（中文）：只读读取。修改走 `set({ workspace })`，与 `model` 同一手柄。
+   */
+  get_workspace(): WorkspaceRuntime | undefined {
+    return this.local_state.current_workspace;
+  }
+
+  /** 返回当前目录路径；没有 Workspace 时使用回退值。 */
+  private get_workspace_path(): string {
+    return this.state.get_workspace_path();
+  }
+
   /**
    * 读取当前 session 生效的 system 快照。
    */
@@ -552,7 +625,7 @@ export class Session implements AgentSession {
     /** 当前 Turn 的取消信号。 */
     readonly abort_signal: AbortSignal;
   }): ToolCallContext {
-    const workspace = this.get_workspace();
+    const workspace = this.local_state.current_workspace;
     return Object.freeze({
       agent_id: this.agent_id,
       agent_name: this.agent_name,
@@ -566,17 +639,28 @@ export class Session implements AgentSession {
       turn_id: input.turn_id,
       abort_signal: input.abort_signal,
       interactions: this.session_interactions,
-      workspace_env: Object.freeze({ ...this.get_workspace_env() }),
+      workspace_env: Object.freeze({ ...this.read_workspace_env() }),
     });
   }
 
+  /**
+   * 读取当前目录的环境变量快照。
+   *
+   * 关键点（中文）：环境属于目录（Workspace 实例），不是 Session 自身配置；没有目录时为空。
+   */
+  private read_workspace_env(): Record<string, string> {
+    return { ...(this.local_state.current_workspace?.get_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 } : {}),
+      workspace_path: this.local_state.fallback_workspace_path,
+      ...(this.local_state.current_workspace
+        ? { workspace: this.local_state.current_workspace }
+        : {}),
       origin: this.origin,
       store: this.create_session_store(session_id),
       create_session_store: this.create_session_store,
@@ -586,8 +670,7 @@ export class Session implements AgentSession {
       logger: this.logger,
       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_workspace: () => this.local_state.current_workspace,
       get_hooks: this.get_hooks,
       get_agent_model: this.get_agent_model,
       composer: this.composer,

package/src/session/input/StepInput.ts

@@ -15,6 +15,7 @@ import type {
   SessionHookContextBlock,
   SessionTurnContextHookValue,
   ToolCallContext,
+  WorkspaceRuntime,
 } from "@downcity/type";
 import type { BoundAgentTool, ToolCallSite } from "@/types/tool/BoundAgentTool.js";
 import type {
@@ -39,6 +40,10 @@ import { resolve_session_power_system_blocks } from "@/session/input/SessionSyst
 export class StepInput {
   private readonly options: StepInputOptions;
   private effective_instruction_blocks: AgentSessionSystemBlock[];
+  /** 当前目录对应的环境变量快照；由目录实例提供。 */
+  private readonly workspace_env_by_id = new Map<string, Record<string, string>>();
+  /** 当前目录变化时取消的旧订阅。 */
+  private workspace_env_unsubscribe?: () => void;
   /** 当前 Session 首次组装后冻结的完整 system；null 表示尚未冻结。 */
   private frozen_blocks: AgentSessionSystemBlock[] | null = null;
   /** 当前 Session 的一次性初始化任务。 */
@@ -128,8 +133,7 @@ export class StepInput {
   }
 
   /** 把当前完整 system 显式固化到 instruction.md。 */
-  async snapshot(): Promise<void> {
-    await this.run_mutation(async () => {
+  async snapshot(): Promise<void> {    await this.run_mutation(async () => {
       const system_snapshot = await this.read_system();
       await this.write_snapshot(system_snapshot.blocks);
     });
@@ -163,7 +167,7 @@ export class StepInput {
       session: {
         agent_id: this.options.agent_id,
         session_id: this.options.session_id,
-        project_root: this.options.workspace_path,
+        project_root: this.options.get_workspace_path(),
         created_at: new Date(this.options.get_created_at()).toISOString(),
         timezone: this.options.get_timezone(),
       },
@@ -176,12 +180,38 @@ export class StepInput {
     return this.effective_instruction_blocks.map((block) => ({ ...block }));
   }
 
+  /**
+   * 读取当前目录的环境变量。
+   *
+   * 关键点（中文）
+   * - 目录是可变会话配置，环境订阅也随之切换：首次遇到某个目录时建立订阅，
+   *   后续读取直接取其快照，不再重建。
+   * - 没有目录时返回空对象。
+   */
+  private read_workspace_env(): Record<string, string> {
+    const workspace = this.options.get_workspace?.();
+    if (!workspace) {
+      this.workspace_env_unsubscribe?.();
+      this.workspace_env_unsubscribe = undefined;
+      return {};
+    }
+    const cached = this.workspace_env_by_id.get(workspace.id);
+    if (cached) return cached;
+    // 同一 Session 只保留当前目录的订阅，避免旧目录继续推送。
+    this.workspace_env_unsubscribe?.();
+    this.workspace_env_by_id.set(workspace.id, { ...workspace.get_env() });
+    this.workspace_env_unsubscribe = workspace.subscribe_env(() => {
+      this.workspace_env_by_id.set(workspace.id, { ...workspace.get_env() });
+    });
+    return this.workspace_env_by_id.get(workspace.id) as Record<string, string>;
+  }
+
   /** 创建 Composer 共用的稳定 Session 身份快照。 */
   identity(): SessionComposeIdentity {
     return {
       agent_id: this.options.agent_id,
       session_id: this.options.session_id,
-      project_root: this.options.workspace_path,
+      project_root: this.options.get_workspace_path(),
       created_at: this.options.get_created_at(),
       timezone: this.options.get_timezone(),
     };
@@ -196,7 +226,7 @@ export class StepInput {
     const instruction_system_blocks = refresh_system
       ? this.options.get_instruction_system_blocks().map((block) => ({ ...block }))
       : this.instruction_blocks();
-    const workspace_env = Object.freeze({ ...this.options.get_workspace_env() });
+    const workspace_env = Object.freeze({ ...this.read_workspace_env() });
     // Power system 参与 Compose，必须先看到当前检查点已确定的 env 与 instruction。
     turn_context?.step.commit({
       workspace_env,
@@ -401,7 +431,7 @@ export class StepInput {
   private create_session_call_context(
     workspace_env: Readonly<Record<string, string>>,
   ): ToolCallContext {
-    const workspace = this.options.get_workspace?.();
+    const workspace = this.resolve_active_workspace();
     return Object.freeze({
       agent_id: this.options.agent_id,
       agent_name: this.options.agent_name,
@@ -424,7 +454,7 @@ export class StepInput {
   ): ToolCallContext {
     const workspace_env = turn_context.step.workspace_env;
     const agent_systems = turn_context.step.agent_systems;
-    const workspace = this.options.get_workspace?.();
+    const workspace = this.resolve_active_workspace();
     return Object.freeze({
       agent_id: this.options.agent_id,
       agent_name: this.options.agent_name,
@@ -441,6 +471,11 @@ export class StepInput {
       ...(workspace_env ? { workspace_env } : {}),
     });
   }
+
+  /** 解析当前生效的 Workspace 实例。 */
+  private resolve_active_workspace(): WorkspaceRuntime | undefined {
+    return this.options.get_workspace?.();
+  }
 }
 
 /** 把 Turn pipeline 输出限制为低权限动态参考内容块。 */