@downcity/agent 1.1.237 → 1.1.258

package/src/session/{recorder/SessionRecorderCompaction.ts → messages/SessionMessageCompaction.ts}

@@ -1,22 +1,23 @@
 /**
- * SessionRecorder Active/Segment 上下文压缩。
+ * SessionMessages Active/Segment 上下文压缩计划生成。
  *
  * Compact 把 Active 前缀写入不可变 Segment，并在 footer 保存累计 Summary。
  */
 
-import { generateText } from "ai";
+import { generateText, type LanguageModel } from "ai";
 import { generateId } from "@/utils/Id.js";
-import type { SessionHistoryCompactInput } from "@/executor/store/history/SessionHistoryStore.js";
-import type { SessionActionRecordV1 } from "@/executor/types/SessionRecords.js";
 import {
   build_initial_session_compaction_prompt,
   build_update_session_compaction_prompt,
   SESSION_COMPACTION_SYSTEM_PROMPT,
 } from "@executor/composer/compaction/jsonl/JsonlSessionCompactionPrompts.js";
 import { fold_compacted_text } from "@executor/core-engine/CoreEngineContextCompaction.js";
-import { SessionRecorder } from "@/session/recorder/SessionRecorder.js";
-import { to_executor_ui_message } from "@/session/recorder/SessionMessageCodec.js";
+import { to_executor_ui_message } from "@/session/messages/SessionMessageCodec.js";
 import type { SessionMessage } from "@/types/session/SessionMessage.js";
+import type {
+  SessionCompactionPlan,
+} from "@/types/session/SessionComposer.js";
+import type { SessionContextSnapshot } from "@/types/session/SessionSegment.js";
 
 /** 单次摘要请求中 conversation 文本的最大字符数。 */
 const SUMMARY_CHUNK_MAX_CHARS = 20_000;
@@ -30,36 +31,30 @@ const PREVIOUS_SUMMARY_MAX_CHARS = 12_000;
 /** 摘要模型的最大输出 token，用于避免 Summary 自身无限增长。 */
 const SUMMARY_MAX_OUTPUT_TOKENS = 4_000;
 
-/** 必要时把 Active 前缀关闭为带累计 Summary 的 Segment。 */
-export async function compact_session_recorder_messages(input: {
-  /** 当前 Session Recorder。 */
-  recorder: SessionRecorder;
-  /** 压缩策略和模型。 */
-  compact_input: SessionHistoryCompactInput;
-}): Promise<{ compacted: boolean; reason?: string }> {
-  const snapshot = await input.recorder.context_snapshot();
-  const context_messages = snapshot.messages.filter(
+/**
+ * 根据只读 Message 快照生成持久化压缩计划。
+ *
+ * 该函数可以调用模型生成 Summary，但不会写文件、修改 Recorder 或发布事件。
+ */
+export async function compose_session_compaction(input: {
+  /** 当前 Session 标识。 */
+  session_id: string;
+  /** 当前累计 Summary 与 Active Message 快照。 */
+  snapshot: Readonly<SessionContextSnapshot>;
+  /** 生成累计 Summary 使用的模型。 */
+  model: LanguageModel;
+}): Promise<SessionCompactionPlan | null> {
+  const context_messages = input.snapshot.messages.filter(
     (message) => message.type === "user" || message.type === "assistant",
   );
-  if (!input.compact_input.force) {
-    return { compacted: false, reason: "not_requested" };
-  }
   const boundary = context_messages.at(-1);
-  if (!boundary) return { compacted: false, reason: "nothing_to_compact" };
-
-  const action_id = `compacting:${input.recorder.session_id}:${generateId()}`;
-  await publish_action(input.compact_input.onAction, {
-    id: action_id,
-    session_id: input.recorder.session_id,
-    title: "Compacting session messages",
-    state: "running",
-  });
+  if (!boundary) return null;
 
   const conversation_messages = context_messages
     .map((message) => message_to_compaction_text(message))
     .filter(Boolean);
   const chunks = build_summary_chunks(conversation_messages);
-  let summary = String(snapshot.summary?.text || "").trim();
+  let summary = String(input.snapshot.summary?.text || "").trim();
   let used_fallback = false;
   for (const chunk of chunks) {
     const prompt = summary
@@ -75,7 +70,7 @@ export async function compact_session_recorder_messages(input: {
         });
     try {
       const result = await generateText({
-        model: input.compact_input.model,
+        model: input.model,
         system: [{ role: "system", content: SESSION_COMPACTION_SYSTEM_PROMPT }],
         prompt,
         maxOutputTokens: SUMMARY_MAX_OUTPUT_TOKENS,
@@ -93,27 +88,19 @@ export async function compact_session_recorder_messages(input: {
     summary = build_deterministic_summary("", "(no textual context)");
   }
 
-  await input.recorder.compact_active({
+  return {
     through_sequence: boundary.sequence,
+    boundary_message_id: boundary.message_id,
+    used_fallback,
     summary: {
       record_type: "summary",
-      session_id: input.recorder.session_id,
-      summary_id: `summary:${input.recorder.session_id}:${generateId()}`,
+      session_id: input.session_id,
+      summary_id: `summary:${input.session_id}:${generateId()}`,
       through_sequence: boundary.sequence,
       text: summary,
       created_at: Date.now(),
     },
-  });
-  await publish_action(input.compact_input.onAction, {
-    id: action_id,
-    session_id: input.recorder.session_id,
-    title: "Session messages compacted",
-    description: used_fallback
-      ? `Closed Active through Message ${boundary.message_id} with deterministic fallback Summary.`
-      : `Closed Active through Message ${boundary.message_id}.`,
-    state: "completed",
-  });
-  return { compacted: true };
+  };
 }
 
 function message_to_compaction_text(message: SessionMessage): string {
@@ -183,29 +170,3 @@ function safe_stringify(value: unknown): string {
     return String(value || "");
   }
 }
-
-async function publish_action(
-  callback: SessionHistoryCompactInput["onAction"],
-  input: {
-    id: string;
-    session_id: string;
-    title: string;
-    description?: string;
-    state: "running" | "completed" | "failed";
-  },
-): Promise<void> {
-  if (!callback) return;
-  const action: SessionActionRecordV1 = {
-    type: "action",
-    id: input.id,
-    title: input.title,
-    ...(input.description ? { description: input.description } : {}),
-    state: input.state,
-    metadata: {
-      v: 1,
-      ts: Date.now(),
-      sessionId: input.session_id,
-    },
-  };
-  await callback(action);
-}

package/src/session/runtime/SessionEventHub.ts

@@ -8,29 +8,17 @@
 
 import type {
   SessionMutation,
-  SessionMutationReply,
   SessionMutationSubscriber,
   SessionMutationUnsubscribe,
 } from "@/types/session/SessionMutation.js";
 
-/** SessionEventHub 构造参数。 */
-export interface SessionEventHubOptions {
-  /** 为当前 Mutation 创建绑定 Session 和 Tool Part 的回复入口。 */
-  create_reply: (mutation: SessionMutation) => SessionMutationReply;
-}
-
 /**
  * SessionEventHub：最小事件总线实现。
  */
 export class SessionEventHub {
   private readonly subscribers = new Map<number, SessionMutationSubscriber>();
-  private readonly create_reply: SessionEventHubOptions["create_reply"];
   private next_subscriber_id = 1;
 
-  constructor(options: SessionEventHubOptions) {
-    this.create_reply = options.create_reply;
-  }
-
   /**
    * 注册一个新的 Session 事件订阅者。
    */
@@ -48,10 +36,9 @@ export class SessionEventHub {
    * 广播一条 Session 事件。
    */
   publish(mutation: SessionMutation): void {
-    const reply = this.create_reply(mutation);
     for (const subscriber of this.subscribers.values()) {
       try {
-        Promise.resolve(subscriber(mutation, reply)).catch(() => undefined);
+        Promise.resolve(subscriber(mutation)).catch(() => undefined);
       } catch {
         // ignore single subscriber failures
       }

package/src/session/storage/Metadata.ts

@@ -7,9 +7,31 @@
  */
 
 import fs from "fs-extra";
-import type { LanguageModel } from "ai";
+import {
+  inferAgentModelLabel,
+  type AgentModel,
+} from "@/agent/AgentModel.js";
 import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
 import { getSdkAgentSessionMetaPath } from "@/session/storage/Paths.js";
+import type { AgentSessionConfigSnapshot } from "@/types/agent/SessionTypes.js";
+
+/** 刷新 Session metadata 的参数。 */
+export interface TouchSessionMetadataParams {
+  /** 当前项目根目录。 */
+  projectRoot: string;
+  /** 当前 Agent 稳定标识。 */
+  agentId: string;
+  /** 当前 Session 稳定标识。 */
+  sessionId: string;
+  /** 当前 Session configured state。 */
+  sessionConfig: AgentSessionConfigSnapshot;
+  /** 当前 canonical Message 总数。 */
+  message_count?: number;
+  /** 当前 Message 日志总字节数。 */
+  history_bytes?: number;
+  /** 最近一条用户可见 Message 的文本摘要。 */
+  preview_text?: string;
+}
 
 type ReadSessionMetadataInput = {
   /**
@@ -33,11 +55,6 @@ function normalizeModelLabel(input: unknown): string | undefined {
   return label || undefined;
 }
 
-function normalize_model_id(input: unknown): string | undefined {
-  const model_id = typeof input === "string" ? input.trim() : "";
-  return model_id || undefined;
-}
-
 /**
  * 归一化 session 标题。
  */
@@ -82,26 +99,9 @@ function normalize_history_bytes(input: unknown): number | undefined {
  * 从模型实例推导轻量可读标签。
  */
 export function inferModelLabel(
-  model: LanguageModel | undefined,
+  model: AgentModel | undefined,
 ): string | undefined {
-  if (!model || typeof model !== "object") return undefined;
-  const record = model as Record<string, unknown>;
-  const candidates = [
-    record.modelId,
-    record.model,
-    record.id,
-    record.name,
-    record.label,
-  ];
-  for (const candidate of candidates) {
-    const text = normalizeModelLabel(candidate);
-    if (text) return text;
-  }
-  const constructorName =
-    model.constructor && typeof model.constructor.name === "string"
-      ? model.constructor.name.trim()
-      : "";
-  return constructorName || "configured-model";
+  return inferAgentModelLabel(model);
 }
 
 /**
@@ -158,9 +158,6 @@ export async function readSessionMetadataFromPath(input: {
       ...(normalizeModelLabel(raw.modelLabel)
         ? { modelLabel: normalizeModelLabel(raw.modelLabel) }
         : {}),
-      ...(normalize_model_id(raw.modelId)
-        ? { modelId: normalize_model_id(raw.modelId) }
-        : {}),
       ...(normalize_message_count(raw.messageCount) !== undefined
         ? { messageCount: normalize_message_count(raw.messageCount) }
         : {}),
@@ -211,9 +208,7 @@ export async function patchSessionModelLabel(
     /**
      * 当前模型实例。
      */
-    model?: LanguageModel;
-    /** 当前模型稳定 ID。 */
-    modelId?: string;
+    model?: AgentModel;
   },
 ): Promise<SessionHistoryMetaV1> {
   const current = await readSessionMetadata(input);
@@ -230,9 +225,6 @@ export async function patchSessionModelLabel(
           modelLabel,
         }
       : {}),
-    ...(normalize_model_id(input.modelId)
-      ? { modelId: normalize_model_id(input.modelId) }
-      : {}),
   };
   await writeSessionMetadata({
     ...input,
@@ -240,3 +232,37 @@ export async function patchSessionModelLabel(
   });
   return next;
 }
+
+/** 根据 canonical Message 统计刷新当前 Session metadata。 */
+export async function touchSessionMetadata(
+  params: TouchSessionMetadataParams,
+): Promise<void> {
+  const current = await readSessionMetadata({
+    projectRoot: params.projectRoot,
+    agentId: params.agentId,
+    sessionId: params.sessionId,
+  });
+  const next: SessionHistoryMetaV1 = {
+    ...current,
+    agentId: params.agentId,
+    createdAt:
+      typeof current.createdAt === "number" ? current.createdAt : Date.now(),
+    updatedAt: Date.now(),
+    ...(params.sessionConfig.modelLabel
+      ? { modelLabel: params.sessionConfig.modelLabel }
+      : {}),
+    ...(typeof params.message_count === "number"
+      ? { messageCount: params.message_count }
+      : {}),
+    ...(typeof params.history_bytes === "number"
+      ? { historyBytes: params.history_bytes }
+      : {}),
+    ...(params.preview_text ? { previewText: params.preview_text } : {}),
+  };
+  await writeSessionMetadata({
+    projectRoot: params.projectRoot,
+    agentId: params.agentId,
+    sessionId: params.sessionId,
+    meta: next,
+  });
+}

package/src/session/storage/RuntimeSessionPort.ts

@@ -6,8 +6,7 @@
  * - SDK 公开面只保留 `prompt()` / `subscribe()`；runtime/service 若要 one-shot 等待结果，也统一委托给 `prompt()`。
  */
 
-import type { SessionPort } from "@/types/runtime/agent/AgentContext.js";
-import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
+import type { SessionPort } from "@/types/session/SessionPort.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type {
@@ -24,6 +23,8 @@ export interface CreateRuntimeSessionPortParams {
    * 当前 sessionId。
    */
   sessionId: string;
+  /** 获取当前 Session 优先解析后的运行时模型实例。 */
+  getModel: SessionPort["getModel"];
   /**
    * 读取当前 session 底层执行端口。
    */
@@ -42,10 +43,6 @@ export interface CreateRuntimeSessionPortParams {
   subscribe: (
     subscriber: SessionMutationSubscriber,
   ) => SessionMutationUnsubscribe;
-  /**
-   * 发布一条 session runtime 事件。
-   */
-  publishEvent: SessionPort["publishEvent"];
   /**
    * 追加 user 消息到底层历史。
    */
@@ -58,10 +55,8 @@ export interface CreateRuntimeSessionPortParams {
    * 返回当前 session 是否正在执行。
    */
   isExecuting: () => boolean;
-  /**
-   * 当前 session 历史持久化端口。
-   */
-  historyStore: SessionHistoryStore;
+  /** 读取当前 Session 的只读上下文快照。 */
+  context: SessionPort["context"];
   /**
    * 在执行前确保当前 session 已完成初始化与宿主级配置。
    */
@@ -76,8 +71,9 @@ export function createRuntimeSessionPort(
 ): SessionPort {
   return {
     sessionId: params.sessionId,
+    getModel: () => params.getModel(),
     getExecutor: () => params.getExecutor(),
-    getHistoryStore: () => params.historyStore,
+    context: async () => await params.context(),
     prompt: async (input) => {
       await params.ensureReadyForExecution();
       return await params.prompt(input);
@@ -89,9 +85,6 @@ export function createRuntimeSessionPort(
     subscribe: (subscriber) => {
       return params.subscribe(subscriber);
     },
-    publishEvent: async (event) => {
-      await params.publishEvent(event);
-    },
     append_user_message: async (messageParams) => {
       await params.append_user_message(messageParams);
     },

package/src/types/agent/AgentOptions.ts

@@ -8,10 +8,8 @@
 
 import type { Tool } from "ai";
 import type { Shell } from "@downcity/shell";
+import type { AgentModel } from "@/agent/AgentModel.js";
 import type { Plugin } from "@/types/plugin/PluginDefinition.js";
-import type { AgentModel } from "@/model/CityModelAdapter.js";
-import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
-import type { AgentPluginConfigRuntime } from "@/types/agent/AgentRuntimeAssembly.js";
 import type {
   AgentManagedSession,
   SessionOptions,
@@ -73,27 +71,14 @@ export interface AgentOptions {
   instruction?: string | string[];
 
   /**
-   * 当前 agent 为新建 session 提供的默认模型实例。
+   * 当前 Agent 持有的运行时模型实例。
    *
    * 关键点（中文）
-   * - SDK 仍不负责“选择哪个模型”，这里只接收宿主已经创建好的模型实例。
-   * - 支持 AI SDK `LanguageModel`，也支持 City City 返回的 `CityModel`。
-   * - 该模型会作为 session 首次执行前的默认注入值。
+   * - Agent 不选择或恢复模型，只持有宿主传入的实例。
+   * - Session 未显式设置模型时，执行自动回退到该实例。
    */
   model?: AgentModel;
 
-  /** 当前 Agent 默认模型对应的稳定 ID。 */
-  model_id?: string;
-
-  /**
-   * 按稳定 ID 解析 Session 运行时模型。
-   *
-   * 关键点（中文）
-   * - Session 热切换与进程重启后的恢复统一使用该 resolver。
-   * - SDK 不维护模型目录，具体目录与鉴权由宿主负责。
-   */
-  resolve_model?: (model_id: string) => Promise<AgentModel>;
-
   /**
    * 当前 agent 显式持有的插件实例集合。
    *
@@ -110,7 +95,7 @@ export interface AgentOptions {
    *
    * 关键点（中文）
    * - Agent 只负责用这个类创建/恢复 session，不感知具体 Composer 策略。
-   * - 如果需要自定义 Composer，请在自定义 Session 类内部传给 `super({ composers })`。
+   * - 如果需要自定义 Composer，请在自定义 Session 类内部传给 `super({ composer })`。
    * - 该能力仅适用于本地 `Agent`。
    */
   Session?: AgentSessionConstructor;
@@ -121,25 +106,8 @@ export interface AgentOptions {
    * 关键点（中文）
    * - 这里表示宿主显式注入给 agent 的基础 env。
    * - `Agent` 会在这份基础 env 之上继续叠加项目 `.env`。
-   * - 覆盖后的最终 env 会参与配置解析与运行时上下文装配，但不会回写到宿主环境。
+   * - 覆盖后的最终值会成为 Agent 运行时 env，但不会回写到宿主环境。
    */
   env?: Record<string, string>;
 
-  /**
-   * 宿主显式传入的运行时配置。
-   *
-   * 关键点（中文）
-   * - SDK 不读取项目配置文件。
-   * - CLI / Console 从自己的全局配置存储读取后传入这里。
-   */
-  config?: DowncityConfig;
-
-  /**
-   * 宿主提供的 plugin 配置持久化能力。
-   *
-   * 关键点（中文）
-   * - SDK 默认会拒绝持久化操作；CLI 等宿主可在这里接入自己的全局数据库。
-   * - plugin 只依赖该稳定接口，不感知 SQLite、文件或远端服务等具体实现。
-   */
-  plugin_config?: AgentPluginConfigRuntime;
 }

package/src/types/agent/AgentState.ts

@@ -0,0 +1,33 @@
+/**
+ * AgentState 内部装配参数。
+ *
+ * 职责说明（中文）
+ * - 只描述 AgentState 连接 PluginRegistry、Session、tools 与 Shell 所需的稳定引用。
+ * - 这些对象都由 Agent 先完成创建，AgentState 只负责运行时连接和生命周期。
+ */
+
+import type { Tool } from "ai";
+import type { Shell } from "@downcity/shell";
+import type { AgentSessions } from "@/agent/AgentSessions.js";
+import type { PluginRegistry } from "@/plugin/core/PluginRegistry.js";
+import type { AgentContext } from "@/agent/AgentContext.js";
+
+/**
+ * AgentState 构造参数。
+ */
+export interface AgentStateOptions {
+  /** 当前 Agent 共用的执行上下文。 */
+  context: AgentContext;
+
+  /** 当前 Agent 唯一的 PluginRegistry 实例。 */
+  plugins: PluginRegistry;
+
+  /** 当前 Agent 唯一的 Session 集合。 */
+  sessions: AgentSessions;
+
+  /** 当前 Agent 与 Session 共享的可变工具集合。 */
+  tools: Record<string, Tool>;
+
+  /** 当前 Agent 持有的可选 Shell 实例。 */
+  shell?: Shell;
+}

package/src/types/agent/SessionActor.ts

@@ -133,9 +133,6 @@ export interface AgentSession extends AgentSessionActor {
  * 远程 Agent 返回的公开 session 接口。
  */
 export interface RemoteAgentSession extends AgentSessionActor {
-  /** 按稳定模型 ID 更新远程 Session 模型。 */
-  set(input: AgentSessionSetInput): Promise<void>;
-
   /** 从当前远程 session 创建一个分叉会话。 */
   fork(input?: AgentSessionForkInput | string): Promise<RemoteAgentSession>;
 }

package/src/types/agent/SessionTypes.ts

@@ -6,8 +6,7 @@
  * - session actor 方法接口拆到 `SessionActor.ts`。
  */
 
-import type { LanguageModel } from "ai";
-import type { AgentModel } from "@/model/CityModelAdapter.js";
+import type { AgentModel } from "@/agent/AgentModel.js";
 import type { SessionRecordV1 } from "@/executor/types/SessionRecords.js";
 
 /**
@@ -66,18 +65,10 @@ export interface AgentSessionSetInput {
    * 当前 session 默认模型实例。
    *
    * 关键点（中文）
-   * - 这里接受运行中的模型实例，而不是模型 ID。
-   * - 未同时提供 `modelId` 时，SDK 会从模型实例推导稳定 ID 并持久化。
+   * - SDK 只接受宿主已经解析完成的运行时模型实例。
+   * - 模型选择、ID 与持久化全部由宿主负责。
    */
-  model?: AgentModel;
-  /**
-   * 当前 session 使用的稳定模型 ID。
-   *
-   * 关键点（中文）
-   * - 由 Agent 宿主提供的模型 resolver 解析为运行时模型实例。
-   * - 该值会持久化到 session metadata，进程重启后可以恢复。
-   */
-  modelId?: string;
+  model: AgentModel;
 }
 
 /**
@@ -85,11 +76,9 @@ export interface AgentSessionSetInput {
  */
 export interface AgentSessionConfigSnapshot {
   /** 当前 session 绑定的默认模型实例。 */
-  model?: LanguageModel;
+  model?: AgentModel;
   /** 当前模型的轻量可读标签。 */
   modelLabel?: string;
-  /** 当前 session 绑定的稳定模型 ID。 */
-  modelId?: string;
   /** 当前模型支持的总上下文窗口长度，单位为 token。 */
   model_context_window?: number;
 }
@@ -265,8 +254,6 @@ export interface AgentSessionSummary {
   messageCount: number;
   /** 当前 session 绑定模型的可读标签。 */
   modelLabel?: string;
-  /** 当前 session 绑定的稳定模型 ID。 */
-  modelId?: string;
   /** 当前 session 是否处于执行中。 */
   executing?: boolean;
 }

package/src/types/executor/SessionRunContext.ts

@@ -4,7 +4,7 @@
  * 关键点（中文）
  * - 这里承载本轮执行过程中需要在多个组件间透传的运行期数据。
  * - 业务侧上下文优先通过该对象显式传递，避免分散读取隐式全局状态。
- * - tool 深层回调等无法直接传参的场景，才通过 run scope 间接读取这个对象。
+ * - tool 回调通过单次 tool execution context 显式读取该对象。
  */
 
 import type {
@@ -19,6 +19,8 @@ import type {
 import type { SessionUserMessageV1 } from "@/executor/types/SessionRecords.js";
 import type { FileUIPart } from "ai";
 import type { AgentPluginExecutionLease } from "@/types/plugin/PluginRuntime.js";
+import type { ShellApprovalGateway } from "@downcity/shell";
+import type { SessionToolInputReady } from "@/types/session/SessionTool.js";
 
 /**
  * 单次 session run 的运行上下文。
@@ -79,7 +81,7 @@ export interface SessionRunContext {
    *
    * 关键点（中文）
    * - 由 Session 统一输入队列在 step 检查点更新。
-   * - tool/plugin 深层调用通过 run scope 读取，避免看到刚写入但尚未生效的 env。
+   * - tool/plugin 调用通过显式 run_context 读取，避免看到刚写入但尚未生效的 env。
    */
   agentEnv?: Readonly<Record<string, string>>;
 
@@ -105,6 +107,12 @@ export interface SessionRunContext {
    */
   onUiMessageChunkCallback?: SessionUiMessageChunkCallback;
 
+  /** Tool 实现开始执行前提交完整输入的顺序屏障。 */
+  on_tool_input_ready?: (input: SessionToolInputReady) => Promise<void>;
+
+  /** 当前 Session 拥有的 unrestricted 审批网关。 */
+  shell_approval_gateway?: ShellApprovalGateway;
+
   /**
    * action 发布回调。
    *

package/src/types/executor/SessionToolExecutionContext.ts

@@ -0,0 +1,21 @@
+/**
+ * Session tool 显式执行上下文。
+ *
+ * 关键点（中文）
+ * - 该对象由 Executor 在每个 Session step 绑定到 tool.execute。
+ * - Agent 工具读取 session_run_context，Shell 工具只读取 shell_run_context。
+ * - 上下文归属单次 run，不通过进程级或异步全局容器共享。
+ */
+
+import type { ShellToolRunContext } from "@downcity/shell/types/ShellRuntime.js";
+import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
+
+/**
+ * Agent 与 Shell 工具共用的单次执行上下文。
+ */
+export interface SessionToolExecutionContext {
+  /** 当前 Shell tool 调用的显式上下文。 */
+  shell_run_context: ShellToolRunContext;
+  /** 当前工具调用所属的完整 Session run 上下文。 */
+  session_run_context: SessionRunContext;
+}

package/src/types/plugin/PluginAction.ts

@@ -9,7 +9,8 @@
 import type { Command } from "commander";
 import type { Context as HonoContext } from "hono";
 import type { z } from "zod";
-import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type { AgentContext } from "@/agent/AgentContext.js";
+import type { PluginRunContext } from "@/types/plugin/PluginRunContext.js";
 import type { JsonObject, JsonValue } from "@/types/common/Json.js";
 
 /**
@@ -147,6 +148,14 @@ export interface PluginAction<
   execute: (params: {
     /** 当前执行上下文。 */
     context: AgentContext;
+    /**
+     * 当前 action 所属的 Session run 上下文。
+     *
+     * 关键点（中文）
+     * - 模型 tool 调用时必定提供。
+     * - CLI、HTTP 或定时任务等非 Session 入口可能不提供。
+     */
+    run_context?: PluginRunContext;
     /** 已通过 schema 校验后的输入。 */
     input: P;
     /** 当前插件名称。 */