@downcity/agent 1.1.338 → 1.1.400

package/src/session/storage/Metadata.ts

@@ -2,12 +2,13 @@
  * SDK Session 元数据辅助。
  *
  * 关键点（中文）
- * - 统一负责 `.downcity/agents/<agent_id>/sessions/<session_id>/messages/meta.json` 的规范化读取。
+ * - 统一负责 Workspace `sessions/<session_id>/meta.json` 的规范化读取。
  * - 仅处理轻量配置摘要与索引信息，不负责消息 JSONL 的读写。
  */
 
 import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
-import type { FileSystem } from "@/types/workspace/FileSystem.js";
+import type { SessionOrigin } from "@/types/session/SessionOrigin.js";
+import type { FileSystem } from "@downcity/workspace";
 
 function normalizeModelLabel(input: unknown): string | undefined {
   const label = typeof input === "string" ? input.trim() : "";
@@ -61,6 +62,17 @@ function normalize_history_bytes(input: unknown): number | undefined {
     : undefined;
 }
 
+/** 归一化 Session 来源元数据。 */
+function normalize_session_origin(input: unknown): SessionOrigin | undefined {
+  if (!input || typeof input !== "object") return undefined;
+  const raw = input as { type?: unknown; group_id?: unknown; group_session_id?: unknown };
+  if (raw.type === "user") return { type: "user" };
+  if (raw.type !== "group") return undefined;
+  const group_id = typeof raw.group_id === "string" ? raw.group_id.trim() : "";
+  const group_session_id = typeof raw.group_session_id === "string" ? raw.group_session_id.trim() : "";
+  return group_id && group_session_id ? { type: "group", group_id, group_session_id } : undefined;
+}
+
 /**
  * 从指定路径读取 session meta.json。
  *
@@ -75,17 +87,29 @@ export async function read_session_metadata_from_path(input: {
   session_id: string;
   /** 当前 agent_id。 */
   agent_id: string;
+  /** 当前查询上下文的 workspace_id；存在时必须与 metadata 严格匹配。 */
+  workspace_id?: string;
   /** 当前 Workspace 的统一文件能力。 */
   files: FileSystem;
 }): Promise<SessionHistoryMetaV1> {
-  try {
-    const raw = JSON.parse(
-      (await input.files.read_file(input.filePath)).toString("utf8"),
-    ) as Partial<SessionHistoryMetaV1>;
-    return normalize_session_metadata(raw, input.session_id, input.agent_id);
-  } catch {
-    return normalize_session_metadata({}, input.session_id, input.agent_id);
+  const raw = JSON.parse(
+    (await input.files.read_file(input.filePath)).toString("utf8"),
+  ) as Partial<SessionHistoryMetaV1>;
+  if (
+    raw.session_id !== input.session_id ||
+    raw.agent_id !== input.agent_id
+  ) {
+    throw new Error(`Invalid Session ownership metadata: ${input.session_id}`);
   }
+  if (input.workspace_id && raw.workspace_id !== input.workspace_id) {
+    throw new Error(`Invalid Session Workspace metadata: ${input.session_id}`);
+  }
+  return normalize_session_metadata(
+    raw,
+    input.session_id,
+    input.agent_id,
+    raw.workspace_id,
+  );
 }
 
 /** 将未知 Metadata 内容规范化为当前 Session 的稳定结构。 */
@@ -93,11 +117,16 @@ export function normalize_session_metadata(
   raw: Partial<SessionHistoryMetaV1>,
   session_id: string,
   agent_id: string,
+  workspace_id?: string,
 ): SessionHistoryMetaV1 {
   return {
     v: 1,
     session_id: session_id,
     agent_id: agent_id,
+    ...(workspace_id ? { workspace_id: workspace_id } : {}),
+    ...(normalize_session_origin(raw.origin)
+      ? { origin: normalize_session_origin(raw.origin) }
+      : {}),
     created_at:
       typeof raw.created_at === "number" && Number.isFinite(raw.created_at)
         ? raw.created_at

package/src/tools/ask/AskQuestionsTool.ts

@@ -6,7 +6,10 @@
  * 再把用户答案作为 Tool Result 交回同一 Turn 的后续模型 Step。
  */
 
-import { tool, type ToolExecutionOptions } from "ai";
+import {
+  define_runtime_tool,
+  type RuntimeToolExecutionOptions as ToolExecutionOptions,
+} from "@downcity/type";
 import { ask_questions_input_schema } from "./AskQuestionsToolSchemas.js";
 import type {
   AskQuestionsToolInput,
@@ -15,6 +18,8 @@ import type {
 import type { SessionToolExecutionContext } from "@/types/executor/SessionToolExecutionContext.js";
 import { generate_id } from "@/utils/Id.js";
 import type { ActionResult } from "@/types/action/ActionResult.js";
+import type { JsonValue } from "@/types/common/Json.js";
+import type { SessionInteractionAnswer } from "@/types/session/SessionInteraction.js";
 
 /**
  * 由调用方显式注册、按当前 Session Turn 上下文执行的提问 Tool。
@@ -28,21 +33,21 @@ import type { ActionResult } from "@/types/action/ActionResult.js";
  * });
  * ```
  */
-export const AskQuestionsTool = tool({
+export const AskQuestionsTool = define_runtime_tool<AskQuestionsToolInput, ActionResult<AskQuestionsToolOutput>>({
   description:
     "Ask the user one or more questions when missing information would materially change the outcome. The call waits for every answer, then returns them so you can continue the same task. Do not use it for information that can be inferred safely. For single_select and multi_select questions, every option MUST contain both a machine-readable value and a user-visible label; never omit value or use label as value. Example: { value: 'cn', label: '中国' }.",
-  inputSchema: ask_questions_input_schema,
+  input_schema: ask_questions_input_schema,
   execute: async (
     input: AskQuestionsToolInput,
     execution_options: ToolExecutionOptions,
   ): Promise<ActionResult<AskQuestionsToolOutput>> => {
-    const execution_context = execution_options.experimental_context as
+    const execution_context = execution_options.context as
       | Partial<SessionToolExecutionContext>
       | undefined;
-    const turn_context = execution_context?.session_turn_context;
-    const interaction_port = turn_context?.interactions;
-    const turn_id = String(turn_context?.session.turn_id || "").trim();
-    const tool_call_id = String(execution_options.toolCallId || "").trim();
+    const action_execution = execution_context?.action_execution_context;
+    const interaction_port = action_execution?.session.interactions;
+    const turn_id = String(action_execution?.session.turn_id || "").trim();
+    const tool_call_id = String(action_execution?.call_id || "").trim();
     if (!interaction_port || !turn_id || !tool_call_id) {
       throw new Error(
         "ask_question requires an active Session tool execution context",
@@ -52,19 +57,21 @@ export const AskQuestionsTool = tool({
     const handle = await interaction_port.request({
       interaction_id: `interaction:${generate_id()}`,
       turn_id,
-      kind: "question",
+      type: "question",
       source: {
         type: "tool",
         tool_call_id,
         tool_name: "ask_question",
       },
       title: input.title,
-      questions: input.questions.map((question) => ({
-        question_id: `question:${generate_id()}`,
-        prompt: question.question,
-        response_type: question.type,
-        ...(question.options ? { options: question.options } : {}),
-      })),
+      payload: {
+        questions: input.questions.map((question) => ({
+          question_id: `question:${generate_id()}`,
+          prompt: question.question,
+          response_type: question.type,
+          ...(question.options ? { options: question.options } : {}),
+        })),
+      } as unknown as JsonValue,
       created_at: Date.now(),
     });
     const result = await handle.result;
@@ -74,7 +81,11 @@ export const AskQuestionsTool = tool({
     if (result.status === "expired") {
       throw new Error("ask_question expired before the user responded");
     }
-    if (result.response.kind !== "question") {
+    if (
+      result.status !== "resolved" ||
+      result.response.type !== "question" ||
+      result.response.outcome !== "resolved"
+    ) {
       throw new Error(
         "ask_question received an incompatible Interaction response",
       );
@@ -82,7 +93,7 @@ export const AskQuestionsTool = tool({
     return {
       output: {
         status: "resolved",
-        answers: result.response.answers,
+        answers: (result.response.payload as unknown as { answers: SessionInteractionAnswer[] }).answers,
       },
       messages: [],
     };

package/src/types/action/ActionResult.ts

@@ -2,25 +2,34 @@
  * Action 与 Session Tool 共用的执行结果协议。
  *
  * 关键点（中文）
- * - `output` 是标准 Tool Result，原样交给 AI SDK 和 canonical Tool Part。
+ * - `output` 是标准 Tool Result，原样交给模型执行器和 canonical Tool Part。
  * - `messages` 是执行后写入 Session 的真实 User / Assistant Message 内容。
- * - Message Parts 直接复用 AI SDK UIMessage 协议，不再建立文件、图片或 Plugin 专用桥接。
+ * - Message Parts 复用 Downcity Session UI 协议，不再建立文件、图片或 Plugin 专用桥接。
  */
 
-import type { UIMessage } from "ai";
+import type {
+  SessionAssistantResultPart,
+  SessionPromptPart,
+} from "@/types/session/SessionContent.js";
 
 /** Action 执行后产生的一条 Session 消息。 */
-export interface ActionResultMessage {
-  /** 消息归属；User 消息在下一 Step 生效，Assistant Parts 写入当前回复。 */
-  role: "user" | "assistant";
-
-  /** 应写入对应 Session Message 的标准 UI Parts。 */
-  parts: UIMessage["parts"];
-}
+export type ActionResultMessage =
+  | {
+      /** User 内容在下一 Step 生效。 */
+      role: "user";
+      /** 等待进入 canonical User Message 的内容。 */
+      parts: SessionPromptPart[];
+    }
+  | {
+      /** Assistant 内容写入当前回复。 */
+      role: "assistant";
+      /** 等待进入 canonical Assistant Message 的内容。 */
+      parts: SessionAssistantResultPart[];
+    };
 
 /** Action 或 Tool 内部实现返回的统一结果。 */
 export interface ActionResult<TOutput = unknown> {
-  /** 返回给调用方、AI SDK 与 canonical Tool Part 的标准执行输出。 */
+  /** 返回给调用方、模型执行器与 canonical Tool Part 的标准执行输出。 */
   output: TOutput;
 
   /** 执行产生的真实 Session 消息；没有附加消息时传入空数组。 */

package/src/types/agent/AgentOptions.ts

@@ -6,10 +6,10 @@
  * - RemoteAgent 与 Session 数据结构拆到独立类型文件。
  */
 
-import type { Tool } from "ai";
+import type { RuntimeTool as Tool } from "@downcity/type";
 import type { AgentModel } from "@/agent/AgentModel.js";
-import type { WorkspaceBase } from "@/workspace/WorkspaceBase.js";
 import type { Plugin } from "@/types/plugin/PluginDefinition.js";
+import type { PluginWebServices } from "@/types/plugin/PluginServices.js";
 import type {
   AgentManagedSession,
   SessionOptions,
@@ -34,21 +34,11 @@ export interface AgentOptions {
    * 当前 agent 的稳定标识。
    *
    * 关键点（中文）
-   * - 用于 `.downcity/agents/<agent_id>/...` 目录分区。
+   * - 用于用户级数据根下的 `agents/<agent_id>/...` 目录分区。
    * - 应保持稳定、可 URL 编码、尽量不要依赖展示名称。
    */
   id: string;
 
-  /**
-   * 当前 Agent 可以访问的项目资源与安全边界。
-   *
-   * 关键点（中文）
-   * - Workspace 统一持有项目根目录、文件/搜索能力与可选 Shell。
-   * - 每个 Workspace 实例只能绑定一个 Agent，并由 Agent dispose 统一释放。
-   * - 多个 Agent 可以指向同一物理目录，但必须分别创建 Workspace 实例。
-   */
-  workspace: WorkspaceBase;
-
   /**
    * 当前 agent 默认可用的工具集合。
    *
@@ -77,6 +67,9 @@ export interface AgentOptions {
    */
   model?: AgentModel;
 
+  /** 当前 Agent 持有的 Web 搜索与文档能力。 */
+  web?: PluginWebServices;
+
   /**
    * 当前 agent 显式持有的插件实例集合。
    *

package/src/types/agent/AgentSessionCollection.ts

@@ -0,0 +1,61 @@
+/**
+ * Agent 面向 SDK 用户的 Session 集合类型。
+ *
+ * Session 归 Agent 所有；Workspace 只在创建时声明本次执行使用的资源环境。
+ */
+
+import type { WorkspaceBase } from "@downcity/workspace";
+import type { SessionOrigin } from "@/types/session/SessionOrigin.js";
+import type { AgentSession } from "@/types/agent/SessionActor.js";
+import type { AgentCreateSessionInput } from "@/types/agent/SessionTypes.js";
+import type { SessionPort } from "@/types/session/SessionPort.js";
+import type {
+  AgentArchiveSessionInput,
+  AgentArchiveSessionResult,
+  AgentArchiveSessionsInput,
+  AgentArchiveSessionsResult,
+  AgentCleanArchiveResult,
+  AgentListSessionsInput,
+  AgentSessionSummaryPage,
+} from "@/types/agent/SessionTypes.js";
+
+/** 创建 Agent Session 的公开参数。 */
+export interface AgentCreateSessionOptions extends AgentCreateSessionInput {
+  /** 本次 Session 可选使用的 Workspace 资源；未传入时使用内存执行上下文。 */
+  workspace?: WorkspaceBase;
+  /** 当前 Session 的创建来源；未填写时视为用户直接创建。 */
+  origin?: SessionOrigin;
+}
+
+/** Agent 公开的 Session 创建入口。 */
+export interface AgentSessionCollection {
+  /** 在指定 Workspace 中创建一个属于当前 Agent 的 Session。 */
+  create(options?: AgentCreateSessionOptions): Promise<AgentSession>;
+
+  /** 在指定 Workspace 中恢复一个已经属于当前 Agent 的 Session。 */
+  get(session_id: string, options?: AgentCreateSessionOptions): Promise<AgentSession>;
+
+  /** 列出当前 Agent 的活动 Session。 */
+  list(input?: AgentListSessionsInput): Promise<AgentSessionSummaryPage>;
+
+  /** 归档一个 Session。 */
+  archive(input: AgentArchiveSessionInput): Promise<AgentArchiveSessionResult>;
+
+  /** 列出已归档 Session。 */
+  archived(input?: AgentArchiveSessionsInput): Promise<AgentArchiveSessionsResult>;
+
+  /** 清空已归档 Session。 */
+  clean_archive(): Promise<AgentCleanArchiveResult>;
+
+  /** 获取 Session runtime port。 */
+  runtime(session_id: string): SessionPort;
+
+  /** 返回当前 Agent 正在执行的 Session 标识。 */
+  list_executing_session_ids(): string[];
+
+  /** 永久删除 Session。 */
+  remove(session_id: string): Promise<boolean>;
+
+  /** 清空 Session 消息。 */
+  clear_messages(session_id: string): Promise<boolean>;
+}

package/src/types/agent/AgentStorage.ts

@@ -0,0 +1,19 @@
+/**
+ * Agent 级持久化存储。
+ *
+ * Agent 在 City 中使用持久化文件系统；未加入 City 时使用进程内文件系统。
+ * Workspace 只提供执行上下文，不拥有这份存储。
+ */
+
+import type { SessionStore } from "@/types/store/SessionStore.js";
+import type { FileSystem } from "@downcity/workspace";
+
+/** Agent 持有的 Session、日志与调度共享存储。 */
+export interface AgentStorage {
+  /** Agent 内部数据的稳定根路径。 */
+  root_path: string;
+  /** 受当前 Agent 根路径约束的文件能力。 */
+  files: FileSystem;
+  /** 当前 Agent 的 Session 集合存储。 */
+  sessions: SessionStore;
+}

package/src/types/agent/RemoteAgentOptions.ts

@@ -14,7 +14,7 @@ export interface RemoteAgentOptions {
    * 远程 agent 访问地址。
    *
    * 例如：`https://city.example.com/agents/lucas`、`http://127.0.0.1:5314/agents/lucas`
-   * 或 `rpc://127.0.0.1:15314`
+   * 或 `rpc://127.0.0.1:15314/lucas`
    */
   url: string;
 

package/src/types/agent/SessionActor.ts

@@ -41,6 +41,7 @@ import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js"
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type { AgentSessionCompactHandle } from "@/types/sdk/AgentSessionCompact.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
+import type { SessionOrigin } from "@/types/session/SessionOrigin.js";
 
 /**
  * SDK Session 集合入口。
@@ -72,6 +73,11 @@ export interface AgentSessionActor {
   /** 当前 session 稳定标识。 */
   readonly id: string;
 
+  /** 当前 Session 创建时绑定的 Workspace ID；无 Workspace 时为空。 */
+  readonly workspace_id?: string;
+  /** 当前 Session 的创建来源。 */
+  readonly origin?: SessionOrigin;
+
   /** 读取当前 session 详情。 */
   get_info(): Promise<AgentSessionInfo>;
 
@@ -124,6 +130,9 @@ export interface AgentSession extends AgentSessionActor {
   /** 写入当前 session 默认配置。 */
   set(input: AgentSessionSetInput, options?: AgentSessionSetOptions): Promise<void>;
 
+  /** 修改当前 Session 的用户可见标题并发布 canonical mutation。 */
+  rename(title: string): Promise<string>;
+
   /** 把当前 Session 首次生成后固定的完整 system 显式固化到 instruction.md。 */
   snapshot(): Promise<void>;
 

package/src/types/agent/SessionTypes.ts

@@ -8,27 +8,31 @@
 
 import type { AgentModel } from "@/agent/AgentModel.js";
 import type { SessionApprovalMode } from "@/types/session/SessionInteraction.js";
+import type { SessionOrigin } from "@/types/session/SessionOrigin.js";
 
 /**
- * 新建 session 的输入参数。
+ * 新建 Session 的输入参数。
+ *
+ * Session ID 由 AgentSessions 在创建时生成，调用方只能在恢复时通过
+ * `sessions.get(session_id)` 指定已有 ID。
  */
 export interface AgentCreateSessionInput {
-  /**
-   * 可选显式 session_id。
-   *
-   * 关键点（中文）
-   * - 传入时表达“创建意图”。
-   * - 若该 session 已存在，SDK 应直接报错，而不是静默复用。
-   * - 省略时由 SDK 自动生成稳定且不可推导的 session_id。
-   */
-  session_id?: string;
-
+  /** 保持创建输入为无配置字段的协议对象。 */
+  readonly __create_session_input?: never;
 }
 
 /**
  * Session 列表查询输入。
  */
 export interface AgentListSessionsInput {
+  /**
+   * 只返回绑定到指定 Workspace 的 Session。
+   *
+   * 省略时查询当前 Agent 的全部 Session；传入时没有 Workspace metadata 的
+   * 历史 Session 不会匹配任何 Workspace。
+   */
+  workspace_id?: string;
+
   /**
    * 当前页返回上限。
    *
@@ -321,6 +325,8 @@ export interface AgentSessionSummary {
   message_count: number;
   /** 当前 session 绑定模型的可读标签。 */
   model_label?: string;
+  /** 当前 Session 的创建来源。 */
+  origin?: SessionOrigin;
   /** 当前 session 是否处于执行中。 */
   executing?: boolean;
 }
@@ -365,6 +371,12 @@ export interface AgentSessionForkInput {
    * - 传入时复制到该消息为止（包含该消息）。
    */
   message_id?: string;
+  /**
+   * 是否将 `message_id` 指向的锚点消息复制到新 Session。
+   *
+   * 省略时默认为 `true`；编辑并重新发送历史消息时传入 `false`，避免新旧消息同时出现。
+   */
+  include_message?: boolean;
 }
 
 /**
@@ -385,6 +397,14 @@ export interface AgentArchiveSessionInput {
  * 列出已归档 session 的输入参数。
  */
 export interface AgentArchiveSessionsInput {
+  /**
+   * 只返回绑定到指定 Workspace 的归档 Session。
+   *
+   * 省略时查询当前 Agent 的全部归档 Session；传入时没有 Workspace metadata
+   * 的历史 Session 不会匹配任何 Workspace。
+   */
+  workspace_id?: string;
+
   /**
    * 当前页返回上限。
    *

package/src/types/agent/WorkspaceEntryOptions.ts

@@ -0,0 +1,18 @@
+/**
+ * WorkspaceEntry 装配参数。
+ *
+ * WorkspaceEntry 只表达 Agent 已进入某个 Workspace，不拥有 Agent 身份或 Plugin
+ * 定义。Workspace 资源的生命周期在离开时由该作用域统一关闭。
+ */
+
+import type { Agent } from "@/agent/Agent.js";
+import type { WorkspaceBase } from "@downcity/workspace";
+
+/** Agent 进入 Workspace 时使用的内部装配参数。 */
+export interface WorkspaceEntryOptions {
+  /** 拥有当前作用域的 Agent。 */
+  agent: Agent;
+
+  /** 当前进入的项目资源容器。 */
+  workspace: WorkspaceBase;
+}

package/src/types/executor/SessionAssistantOutput.ts

@@ -1,30 +1,35 @@
 /**
- * Executor 到 Session canonical Message 的 Assistant 输出端口。
+ * Executor 到 canonical Session Assistant Message 的输出端口。
  *
- * 该端口集中隔离 AI SDK 流协议。SessionLoop 只装配端口，不解析 Chunk，具体转换
- * 由 execution Adapter 完成，SessionMessages 仍是唯一 Assistant Message 事实源。
+ * 该端口直接消费 Downcity Model Protocol 事件，不定义或转发 UI-shaped chunk。
  */
 
-import type { UIMessage, UIMessageChunk } from "ai";
-import type { SessionMessageRecordV1 } from "@/executor/types/SessionRecords.js";
-import type { SessionToolInputReady } from "@/types/session/SessionTool.js";
+import type { ModelStreamEvent } from "@downcity/type";
+import type { SessionAssistantResultPart } from "@/types/session/SessionContent.js";
+import type { SessionAssistantMessagePart } from "@/types/session/SessionMessage.js";
+import type {
+  SessionToolExecutionResult,
+  SessionToolInputReady,
+} from "@/types/session/SessionTool.js";
 
-/** 单次 Turn 的 Assistant 输出写入端口。 */
+/** Executor 写入当前 Turn Assistant Message 的稳定能力。 */
 export interface SessionAssistantOutput {
-  /** 开始一个 Provider Step 的独立 Part 作用域。 */
+  /** 开始一个模型 Step 的独立 Part 作用域。 */
   begin_step(): Promise<void>;
-  /** 写入一个 AI SDK 流式 Chunk。 */
-  write_chunk(chunk: UIMessageChunk): Promise<void>;
-  /** 使用 Provider 最终快照校验并补齐当前 Step metadata。 */
-  finish_step(message: SessionMessageRecordV1): Promise<void>;
+  /** 直接写入单个标准模型流事件。 */
+  write_model_event(event: ModelStreamEvent): Promise<void>;
+  /** 在 Tool 审批或执行前提交完整输入。 */
+  prepare_tool_input(input: SessionToolInputReady): Promise<void>;
+  /** 写入 Tool 执行终态。 */
+  write_tool_result(result: SessionToolExecutionResult): Promise<void>;
+  /** 使用模型流聚合出的 canonical Parts 校验当前 Step。 */
+  finish_step(parts: SessionAssistantMessagePart[]): Promise<void>;
   /** 放弃当前未完成 Step 的临时作用域。 */
   abort_step(): Promise<void>;
-  /** 在 Tool 实现执行前提交完整输入。 */
-  prepare_tool_input(input: SessionToolInputReady): Promise<void>;
-  /** User steer 已插入会话后，关闭它之前的当前 Assistant Message。 */
+  /** User steer 插入前关闭当前连续 Assistant Message。 */
   close_current_message(): Promise<void>;
-  /** 把 Action 产生的完整 Parts 追加到当前 canonical Assistant Message。 */
-  append_parts(parts: UIMessage["parts"]): Promise<void>;
+  /** 把 Action 产生的封闭内容追加到当前 Assistant Message。 */
+  append_result_parts(parts: readonly SessionAssistantResultPart[]): Promise<void>;
   /** 按 Turn 最终结果收口 Assistant 输出。 */
   finish(input: {
     /** Assistant 最终状态。 */

package/src/types/executor/SessionToolExecutionContext.ts

@@ -3,19 +3,24 @@
  *
  * 关键点（中文）
  * - 该对象由 Executor 在每个 Session step 绑定到 tool.execute。
- * - Agent 工具读取 session_turn_context，Shell 工具只读取 shell_run_context。
+ * - Agent 工具读取 session_turn_context，Shell 工具只读取 shell_execution_context。
  * - 上下文归属当前 Turn，不通过进程级或异步全局容器共享。
  */
 
-import type { ShellToolRunContext } from "@downcity/shell/types/ShellRuntime.js";
+import type {
+  ShellExecutionContext,
+} from "@downcity/workspace/shell/types/ShellRuntime.js";
 import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js";
+import type { ToolActionExecutionContext } from "@/types/tools/ToolActionExecutionContext.js";
 
 /**
  * Agent 与 Shell 工具共用的单次执行上下文。
  */
 export interface SessionToolExecutionContext {
-  /** 当前 Shell tool 调用的显式上下文。 */
-  shell_run_context: ShellToolRunContext;
+  /** 业务 Tool 读取的最小执行上下文。 */
+  action_execution_context: ToolActionExecutionContext;
+  /** 当前 Shell Tool 的 canonical 执行上下文。 */
+  shell_execution_context: ShellExecutionContext;
   /** 当前工具调用所属的完整 Session Turn 上下文。 */
   session_turn_context: SessionTurnContext;
 }

package/src/types/executor/SessionTurnContext.ts

@@ -7,9 +7,9 @@
  * - 可变状态只能通过行为方法更新，消费者不能直接操作内部数组、lease 或 callback。
  */
 
-import type { UIMessage } from "ai";
-import type { ShellApprovalGateway } from "@downcity/shell";
-import type { SessionUserMessageV1 } from "@/executor/types/SessionRecords.js";
+import type { ShellApprovalGateway } from "@downcity/workspace";
+import type { SessionUserMessage } from "@/types/session/SessionMessage.js";
+import type { SessionAssistantResultPart } from "@/types/session/SessionContent.js";
 import type { SessionAssistantOutput } from "@/types/executor/SessionAssistantOutput.js";
 import type { AgentPluginExecutionLease } from "@/types/plugin/PluginRuntime.js";
 import type { PluginExecutionContext } from "@/types/plugin/PluginExecutionContext.js";
@@ -39,7 +39,7 @@ export interface SessionTurnContextInit {
   abort_signal?: AbortSignal;
 
   /** 在 Step 检查点消费 Session 队列，并返回应并入模型上下文的 User 消息。 */
-  merge_step_input?: () => Promise<SessionUserMessageV1[]>;
+  merge_step_input?: () => Promise<SessionUserMessage[]>;
 
   /** 判断是否仍有等待下一个 Step 消费的 User prompt。 */
   has_pending_step_input?: () => boolean;
@@ -115,25 +115,25 @@ export interface SessionTurnContext {
     release(): Promise<void>;
 
     /** 为 Plugin 生成只包含稳定、只读运行快照的新对象。 */
-    plugin_execution_context(): PluginExecutionContext;
+    plugin_execution_context(call_id?: string): PluginExecutionContext;
   };
 
   /** 当前运行的动态 User 输入及延迟持久化输入。 */
   readonly input: {
     /** 在 Step 边界消费运行期注入消息与 Session 队列消息。 */
-    checkpoint(): Promise<SessionUserMessageV1[]>;
+    checkpoint(): Promise<SessionUserMessage[]>;
 
     /** 判断是否有等待下一个 Step 消费的 Session prompt。 */
     has_pending(): boolean;
 
     /** 注入一条只影响当前运行、在下一 Step 生效的 User 消息。 */
-    inject_user_message(message: SessionUserMessageV1): void;
+    inject_user_message(message: SessionUserMessage): void;
 
     /** 延迟到 Assistant 结果落盘后再持久化一条 User 消息。 */
-    defer_user_message(message: SessionUserMessageV1): void;
+    defer_user_message(message: SessionUserMessage): void;
 
     /** 返回延迟持久化 User 消息的不可变快照。 */
-    deferred_user_messages(): readonly SessionUserMessageV1[];
+    deferred_user_messages(): readonly SessionUserMessage[];
 
     /** 消费一次 canonical history 重载请求。 */
     consume_history_reload(): boolean;
@@ -145,10 +145,10 @@ export interface SessionTurnContext {
     readonly assistant?: SessionAssistantOutput;
 
     /** 把 Action 产生的 Assistant Parts 加入当前 Step 收口队列。 */
-    enqueue_assistant_parts(parts: readonly UIMessage["parts"][number][]): void;
+    enqueue_assistant_parts(parts: readonly SessionAssistantResultPart[]): void;
 
     /** 消费当前 Step 中等待写入 canonical Assistant Message 的 Parts。 */
-    take_assistant_parts(): UIMessage["parts"];
+    take_assistant_parts(): SessionAssistantResultPart[];
 
     /** 发布一条不进入 LLM 输入的 Session Action。 */
     publish_action(event: AgentSessionActionEvent): Promise<void>;