@downcity/agent 1.1.237 → 1.1.258

package/src/types/plugin/PluginCommand.ts

@@ -6,13 +6,8 @@
  * - lifecycle 面向 runtime 主动 start/stop 钩子。
  */
 
-import type {
-  AgentPathRuntime,
-  AgentPluginConfigRuntime,
-} from "@/types/agent/AgentRuntimeAssembly.js";
-import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type { AgentContext } from "@/agent/AgentContext.js";
 import type { Logger } from "@/utils/logger/Logger.js";
-import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
 import type { JsonValue } from "@/types/common/Json.js";
 
 /**
@@ -24,14 +19,12 @@ import type { JsonValue } from "@/types/common/Json.js";
  * - agent runtime 在需要复用 action 时，直接传入自身更完整的 AgentContext 即可。
  */
 export interface PluginCommandContext {
-  /** 当前命令工作目录。 */
-  cwd: string;
+  /** 当前 Agent 稳定标识。 */
+  agent_id: string;
   /** 当前项目根目录。 */
   rootPath: string;
   /** 当前统一日志器。 */
   logger: Logger;
-  /** 当前解析后的项目配置。 */
-  config: DowncityConfig;
   /**
    * 当前项目环境变量快照。
    *
@@ -40,10 +33,6 @@ export interface PluginCommandContext {
    * - plugin 不再区分 global env 与 agent env，避免上下文语义膨胀。
    */
   env: Record<string, string>;
-  /** 当前可见的路径能力集合。 */
-  paths: AgentPathRuntime;
-  /** 当前可见的 plugin 配置持久化能力集合。 */
-  pluginConfig: AgentPluginConfigRuntime;
 }
 
 /**

package/src/types/plugin/PluginConfig.ts

@@ -0,0 +1,13 @@
+/**
+ * Plugin 配置协议类型。
+ */
+
+import type { JsonValue } from "@/types/common/Json.js";
+
+/**
+ * 允许 optional 字段的结构化 Plugin 配置对象。
+ */
+export type StructuredConfig = {
+  /** 当前配置字段；省略或 `undefined` 表示未配置。 */
+  [key: string]: JsonValue | undefined;
+};

package/src/types/plugin/PluginDefinition.ts

@@ -6,10 +6,8 @@
  * - 细节类型分散在 State / Command / Action / Runtime / Setup / HTTP 模块。
  */
 
-import type {
-  AgentContext,
-  StructuredConfig,
-} from "@/types/runtime/agent/AgentContext.js";
+import type { AgentContext } from "@/agent/AgentContext.js";
+import type { StructuredConfig } from "@/types/plugin/PluginConfig.js";
 import type { PluginActions } from "@/types/plugin/PluginAction.js";
 import type {
   PluginAvailability,
@@ -26,6 +24,7 @@ import type {
   PluginUsageDefinition,
 } from "@/types/plugin/PluginSetup.js";
 import type { PluginHttpDefinition } from "@/types/plugin/PluginHttp.js";
+import type { PluginRunContext } from "@/types/plugin/PluginRunContext.js";
 
 /**
  * Plugin 定义。
@@ -61,8 +60,16 @@ export interface Plugin {
   hooks?: PluginHooks;
   /** Plugin resolve 点集合（可选）。 */
   resolves?: PluginResolves;
-  /** Plugin system 文本构建器（可选）。 */
-  system?: (context: AgentContext) => string | Promise<string>;
+  /**
+   * Plugin system 文本构建器（可选）。
+   *
+   * @param context Agent 稳定能力上下文。
+   * @param run_context 当前 Session run 上下文；非 Session 快照读取时可缺省。
+   */
+  system?: (
+    context: AgentContext,
+    run_context?: PluginRunContext,
+  ) => string | Promise<string>;
   /** Plugin 生命周期定义（可选）。 */
   lifecycle?: PluginLifecycle;
   /** Plugin 可用性检查器（可选）。 */

package/src/types/plugin/PluginHttp.ts

@@ -7,7 +7,7 @@
  */
 
 import type { Hono } from "hono";
-import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type { AgentContext } from "@/agent/AgentContext.js";
 import type { AuthRoutePolicy } from "@/types/runtime/auth/AuthRoute.js";
 
 /**

package/src/types/plugin/PluginRunContext.ts

@@ -0,0 +1,31 @@
+/**
+ * Plugin 单次调用的运行上下文。
+ *
+ * 关键点（中文）
+ * - 只暴露 plugin 业务需要的只读 Session 快照。
+ * - 不暴露 Executor 内部队列、callback 或 plugin lease。
+ * - CLI、HTTP 与 scheduler 等非 Session 调用可能不提供该对象。
+ */
+
+/**
+ * Plugin action 与 system provider 可读取的 Session 运行快照。
+ */
+export interface PluginRunContext {
+  /** 当前调用所属的 Session 标识。 */
+  readonly sessionId: string;
+
+  /** 当前调用所属的 turn 标识。 */
+  readonly turnId?: string;
+
+  /** 当前 Agent 绑定的项目根目录。 */
+  readonly projectRoot?: string;
+
+  /** 当前 Session step 已提交生效的 Agent env 快照。 */
+  readonly agentEnv?: Readonly<Record<string, string>>;
+
+  /** 当前 Session step 已提交生效的 instruction 快照。 */
+  readonly agentSystems?: readonly string[];
+
+  /** 当前 turn 的取消信号。 */
+  readonly abortSignal?: AbortSignal;
+}

package/src/types/plugin/PluginRuntime.ts

@@ -6,16 +6,15 @@
  * - setup/usage UI 协议与 action 输入适配不放在这里。
  */
 
-import type {
-  AgentContext,
-  StructuredConfig,
-} from "@/types/runtime/agent/AgentContext.js";
+import type { AgentContext } from "@/agent/AgentContext.js";
+import type { StructuredConfig } from "@/types/plugin/PluginConfig.js";
 import type { JsonValue } from "@/types/common/Json.js";
 import type { PluginActionResult } from "@/types/plugin/PluginAction.js";
 import type { PluginActionExample } from "@/types/plugin/PluginAction.js";
 import type { Plugin } from "@/types/plugin/PluginDefinition.js";
 import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
 import type { PluginSnapshot } from "@/types/plugin/PluginState.js";
+import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
 
 /**
  * Plugin 概览视图。
@@ -134,9 +133,13 @@ export interface AgentPlugins {
     action: string;
     /** Action Payload（可选）。 */
     payload?: JsonValue;
+    /** 当前 action 所属的显式 Session run 上下文。 */
+    run_context?: SessionRunContext;
   }): Promise<PluginActionResult<JsonValue>>;
   /** 读取当前生效的 plugin system blocks。 */
-  systemBlocks(): Promise<AgentSessionSystemBlock[]>;
+  systemBlocks(
+    run_context?: SessionRunContext,
+  ): Promise<AgentSessionSystemBlock[]>;
   /** 运行 pipeline 点，按顺序链式变换值。 */
   pipeline<T = JsonValue>(pointName: string, value: T): Promise<T>;
   /** 运行 guard 点；任一插件抛错即终止。 */
@@ -171,10 +174,14 @@ export interface AgentPluginExecutionView {
     action: string;
     /** Action Payload（可选）。 */
     payload?: JsonValue;
+    /** 当前 action 所属的显式 Session run 上下文。 */
+    run_context?: SessionRunContext;
   }): Promise<PluginActionResult<JsonValue>>;
 
   /** 解析当前视图中捕获的 plugin system blocks。 */
-  systemBlocks(): Promise<AgentSessionSystemBlock[]>;
+  systemBlocks(
+    run_context?: SessionRunContext,
+  ): Promise<AgentSessionSystemBlock[]>;
 }
 
 /**

package/src/types/plugin/PluginToolRuntime.ts

@@ -12,6 +12,7 @@ import type {
   PluginCallInput,
   PluginReadInput,
 } from "@/executor/tools/plugin/types/PluginTool.js";
+import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
 
 /**
  * 创建 plugin tools 的参数。
@@ -63,6 +64,15 @@ export interface InvokePluginCallToolOptions {
    */
   plugins: AgentPlugins;
 
+  /**
+   * 当前 tool 调用所属的 Session run 上下文。
+   *
+   * 关键点（中文）
+   * - 由 Executor 在每个 step 显式绑定。
+   * - 用于选择当前 plugin lease、资源目录与 assistant file 队列。
+   */
+  run_context: SessionRunContext;
+
   /**
    * 模型提交给 plugin_call 的结构化输入。
    */
@@ -78,9 +88,11 @@ export interface InvokePluginReadToolOptions {
    */
   plugins: AgentPlugins;
 
+  /** 当前 tool 调用所属的 Session run 上下文。 */
+  run_context: SessionRunContext;
+
   /**
    * 模型提交给 plugin_read 的结构化输入。
    */
   input: PluginReadInput;
 }
-

package/src/types/rpc/RpcProtocol.ts

@@ -16,7 +16,6 @@ import type {
   AgentArchiveSessionsResult,
   AgentCleanArchiveResult,
   AgentSessionSystemSnapshot,
-  AgentSessionSetInput,
 } from "@/types/agent/SessionTypes.js";
 import type { SessionMutation } from "@/types/session/SessionMutation.js";
 import type {
@@ -64,19 +63,6 @@ export type RpcRequest =
         sessionId: string;
       };
     }
-  | {
-      /** 请求 id，用于匹配响应。 */
-      id: string;
-      /** 更新 session 模型。 */
-      method: "sdk.sessions.set";
-      /** Session 配置更新参数。 */
-      params: {
-        /** 目标 session id。 */
-        sessionId: string;
-        /** 仅包含稳定 modelId 的配置输入。 */
-        input: AgentSessionSetInput;
-      };
-    }
   | {
       /** 请求 id，用于匹配响应。 */
       id: string;

package/src/types/session/SessionApproval.ts

@@ -17,9 +17,9 @@ export interface SessionApproval {
   /** 当前审批所属 Session 标识。 */
   session_id: string;
   /** 当前审批所属 Turn 标识。 */
-  turn_id?: string;
+  turn_id: string;
   /** 当前审批对应的工具调用标识。 */
-  tool_call_id?: string;
+  tool_call_id: string;
   /** 当前审批对应的工具注册名称。 */
   tool_name: string;
   /** 请求执行的命令或输入文本。 */
@@ -32,6 +32,8 @@ export interface SessionApproval {
   operation: "exec" | "start" | "write";
   /** 当前审批创建时间戳（ms）。 */
   created_at: number;
+  /** 当前审批自动过期时间戳（ms）。 */
+  expires_at: number;
 }
 
 /** 提交 Session 工具审批决策的参数。 */
@@ -65,44 +67,3 @@ export interface SetSessionApprovalModeInput {
   /** 需要设置的新审批模式。 */
   mode: SessionApprovalMode;
 }
-
-/** Shell Runtime 发给 Session 的工具审批请求。 */
-export interface SessionToolApprovalRequest {
-  /** Runtime 事件类型固定为工具审批请求。 */
-  type: "tool-approval-request";
-  /** 当前审批所属 Turn 标识。 */
-  turn_id: string;
-  /** 当前审批对应的工具调用标识。 */
-  tool_call_id: string;
-  /** 当前审批对应的工具注册名称。 */
-  tool_name: string;
-  /** 当前审批请求的稳定唯一标识。 */
-  approval_id: string;
-  /** 请求执行的命令或输入文本。 */
-  command: string;
-  /** 当前工具执行工作目录。 */
-  cwd: string;
-  /** 工具申请 unrestricted 权限的原因。 */
-  reason: string;
-  /** 当前审批对应的工具操作类型。 */
-  operation: "exec" | "start" | "write";
-}
-
-/** Shell Runtime 发给 Session 的工具审批结果。 */
-export interface SessionToolApprovalResult {
-  /** Runtime 事件类型固定为工具审批结果。 */
-  type: "tool-approval-result";
-  /** 当前审批所属 Turn 标识。 */
-  turn_id: string;
-  /** 当前审批对应的工具调用标识。 */
-  tool_call_id: string;
-  /** 当前审批请求的稳定唯一标识。 */
-  approval_id: string;
-  /** 当前审批的最终结果，超时由 Runtime 标记为 expired。 */
-  decision: SessionApprovalDecision | "expired";
-}
-
-/** Session 内部接收的工具审批 Runtime 事件。 */
-export type SessionApprovalRuntimeEvent =
-  | SessionToolApprovalRequest
-  | SessionToolApprovalResult;

package/src/types/session/SessionApprovalBroker.ts

@@ -0,0 +1,18 @@
+/**
+ * Session Approval Broker 内部类型。
+ *
+ * Broker 是单个 Session 内 pending approval 与审批模式的唯一所有者。
+ */
+
+import type { SessionApproval } from "@/types/session/SessionApproval.js";
+import type { ShellApprovalStatus } from "@downcity/shell";
+
+/** Broker 内部保存的单个 pending approval。 */
+export interface SessionPendingApproval {
+  /** 对外发布的完整审批快照。 */
+  approval: SessionApproval;
+  /** 兑现 Shell 等待 Promise 的回调。 */
+  resolve: (decision: ShellApprovalStatus) => void;
+  /** 审批自动过期定时器。 */
+  timer: ReturnType<typeof setTimeout>;
+}

package/src/types/session/SessionComposer.ts

@@ -0,0 +1,114 @@
+/**
+ * Session Composer 类型。
+ *
+ * Composer 是自定义 Session 的执行策略边界：它只读取 Session 的只读快照，
+ * 负责组装模型输入和生成压缩计划，不持久化 Message、Metadata 或事件。
+ */
+
+import type {
+  LanguageModel,
+  SystemModelMessage,
+  Tool,
+} from "ai";
+import type { SessionRecordV1 } from "@/executor/types/SessionRecords.js";
+import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
+import type { SessionContextSnapshot, SessionSegmentSummary } from "@/types/session/SessionSegment.js";
+
+/** Composer 可读取的 Session 身份快照。 */
+export interface SessionComposeIdentity {
+  /** 当前 Agent 的稳定标识。 */
+  agent_id: string;
+  /** 当前 Session 的稳定标识。 */
+  session_id: string;
+  /** 当前 Agent 项目的绝对根目录。 */
+  project_root: string;
+  /** 当前 Session 的创建时间戳，单位为毫秒。 */
+  created_at: number;
+  /** 当前 Session 使用的参考时区。 */
+  timezone: string;
+}
+
+/** Composer 可读取的当前 Step 生效状态。 */
+export interface SessionComposeState {
+  /** 当前 Step 使用的模型实例；只读查询允许为空。 */
+  model?: LanguageModel;
+  /** 当前模型声明的上下文窗口，单位为 token。 */
+  model_context_window?: number;
+  /** 当前 Step 生效的 Agent 环境变量快照。 */
+  env: Readonly<Record<string, string>>;
+  /** 当前 Step 生效的 Agent instruction 文本。 */
+  systems: readonly string[];
+  /** 当前 Step 可使用的工具集合。 */
+  tools: Readonly<Record<string, Tool>>;
+  /** 当前 Step 生效的 instruction system blocks。 */
+  instruction_system_blocks: readonly AgentSessionSystemBlock[];
+  /** 当前 Session 由宿主注入的 system blocks。 */
+  managed_plugin_system_blocks: readonly AgentSessionSystemBlock[];
+  /** 当前 Step 捕获的 Plugin system blocks。 */
+  plugin_system_blocks: readonly AgentSessionSystemBlock[];
+}
+
+/** Composer 可读取的当前 Turn 快照。 */
+export interface SessionComposeTurn {
+  /** 当前 Turn 标识；只读查询场景允许为空。 */
+  turn_id?: string;
+  /** 当前执行因上下文超限而进行的重试次数。 */
+  retry_count: number;
+}
+
+/** 单次模型输入组装参数。 */
+export interface SessionComposeInput {
+  /** 当前 Session 身份快照。 */
+  session: SessionComposeIdentity;
+  /** 当前 Step 已生效的运行状态。 */
+  state: SessionComposeState;
+  /** 当前 Session 的累计 Summary 与 Active Message 快照。 */
+  history: Readonly<SessionContextSnapshot>;
+  /** 当前 Turn 快照。 */
+  turn: SessionComposeTurn;
+}
+
+/** Composer 为一次模型 Step 生成的完整输入。 */
+export interface SessionStepInput {
+  /** 当前 Step 的 system messages。 */
+  system: SystemModelMessage[];
+  /** 当前 Step 的可解释 system block；自定义 Composer 可以省略。 */
+  system_blocks?: AgentSessionSystemBlock[];
+  /** 当前 Step 的历史与用户消息。 */
+  messages: SessionRecordV1[];
+  /** 当前 Step 可调用的工具集合。 */
+  tools: Record<string, Tool>;
+}
+
+/** 持久化上下文压缩的组装参数。 */
+export interface SessionCompactionInput extends SessionComposeInput {
+  /** 是否由调用方明确要求执行持久化压缩。 */
+  force: boolean;
+}
+
+/** Composer 生成、等待 SessionMessages 提交的压缩计划。 */
+export interface SessionCompactionPlan {
+  /** Active 中最后一条需要移入 Segment 的 Message sequence。 */
+  through_sequence: number;
+  /** 新 Segment 使用的累计 Summary。 */
+  summary: SessionSegmentSummary;
+  /** 当前计划覆盖到的最后一条 Message 标识。 */
+  boundary_message_id: string;
+  /** Summary 是否因为模型失败而使用了确定性降级内容。 */
+  used_fallback: boolean;
+}
+
+/** Session 级可替换执行策略。 */
+export interface SessionComposer {
+  /** Composer 的稳定可读名称。 */
+  readonly name: string;
+
+  /** 组装一次模型 Step 使用的 system、history 与 tools。 */
+  compose(input: SessionComposeInput): Promise<SessionStepInput>;
+
+  /** 根据只读历史生成压缩计划；无需压缩时返回空。 */
+  compact(input: SessionCompactionInput): Promise<SessionCompactionPlan | null>;
+
+  /** 判断给定错误是否应在持久化压缩后重试。 */
+  should_compact(error: unknown): boolean;
+}

package/src/types/session/SessionLocalState.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 这里承载本地 Session 在内存中的可变运行态。
- * - state / turn / view 三类 service 通过共享该对象协作，避免彼此复制状态。
+ * - `SessionState` 与 `Session` 共享该对象，避免重复维护配置状态。
  * - 这里只保存运行态，不承载行为逻辑。
  */
 
@@ -16,13 +16,13 @@ export interface SessionLocalState {
   /**
    * 当前 session 配置快照。
    */
-  sessionConfig: AgentSessionConfigSnapshot;
+  session_config: AgentSessionConfigSnapshot;
 
   /**
    * 当前 Session step 实际使用的 Session 配置。
    *
    * 关键点（中文）
-   * - `sessionConfig` 是配置 API 最近一次成功写入的 configured state。
+   * - `session_config` 是配置 API 最近一次成功写入的 configured state。
    * - 该字段只在 Session step 检查点由队列 mutation 更新。
    */
   effective_session_config: AgentSessionConfigSnapshot;
@@ -30,7 +30,7 @@ export interface SessionLocalState {
   /**
    * 当前 session 创建时间（毫秒时间戳）。
    */
-  createdAt: number;
+  created_at: number;
 
   /**
    * 当前 session 参考时区。
@@ -40,10 +40,10 @@ export interface SessionLocalState {
   /**
    * initialize() 过程中的并发复用 Promise。
    */
-  initializePromise: Promise<void> | null;
+  initialize_promise: Promise<void> | null;
 
   /**
    * ensureReadyForExecution() 过程中的并发复用 Promise。
    */
-  ensureConfiguredPromise: Promise<void> | null;
+  ensure_configured_promise: Promise<void> | null;
 }

package/src/types/session/SessionMessage.ts

@@ -6,6 +6,7 @@
  */
 
 import type { JsonObject, JsonValue } from "@/types/common/Json.js";
+import type { SessionApproval } from "@/types/session/SessionApproval.js";
 
 /** Message 默认展示范围。 */
 export type SessionMessageVisibility = "visible" | "internal";
@@ -132,8 +133,8 @@ export interface SessionAssistantToolPart {
   output?: JsonValue;
   /** 工具失败信息。 */
   error?: string;
-  /** 工具审批请求标识。 */
-  approval_id?: string;
+  /** 当前 Tool 等待或已经处理过的完整审批快照。 */
+  approval?: SessionApproval;
 }
 
 /** Assistant 文件 part。 */

package/src/types/session/SessionMessages.ts

@@ -0,0 +1,127 @@
+/**
+ * SessionMessages 输入与构造类型。
+ *
+ * 这些类型只描述 canonical Message 领域入口的参数，不包含持久化行为。
+ */
+
+import type { JsonObject } from "@/types/common/Json.js";
+import type { SessionRecordV1 } from "@/executor/types/SessionRecords.js";
+import type { JsonlSessionMessageStore } from "@/session/messages/JsonlSessionMessageStore.js";
+import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
+import type {
+  SessionAssistantMessagePart,
+  SessionUserMessagePart,
+} from "@/types/session/SessionMessage.js";
+import type { SessionMutation } from "@/types/session/SessionMutation.js";
+
+/** SessionMessages 构造参数。 */
+export interface SessionMessagesOptions {
+  /** 当前 Session 标识。 */
+  session_id: string;
+  /** Message 快照持久化 Store。 */
+  store: JsonlSessionMessageStore;
+  /** 持久化成功后的实时 Mutation 发布函数。 */
+  publish: (mutation: SessionMutation) => void;
+}
+
+/** User Message 创建参数。 */
+export interface AppendSessionUserMessageInput {
+  /** 当前输入所属 Turn。 */
+  turn_id: string;
+  /** 当前输入是普通 Prompt 还是 Steering 输入。 */
+  input_type: "prompt" | "steer";
+  /** User 结构化 Part。 */
+  parts: SessionUserMessagePart[];
+  /** 可选的稳定 Message 标识。 */
+  message_id?: string;
+  /** 当前 Message 的默认展示范围。 */
+  visibility?: "visible" | "internal";
+}
+
+/** Assistant Message 创建参数。 */
+export interface OpenSessionAssistantMessageInput {
+  /** 当前 Assistant 所属 Turn。 */
+  turn_id: string;
+  /** 当前 Assistant 在 Turn 内的 Segment 序号。 */
+  segment_index: number;
+  /** 当前 Assistant 是普通回复还是压缩 Summary。 */
+  kind?: "normal" | "summary";
+  /** 当前 Message 的默认展示范围。 */
+  visibility?: "visible" | "internal";
+  /** 可选的稳定 Message 标识。 */
+  message_id?: string;
+  /** Summary 已覆盖到的来源 Message 标识。 */
+  summary_through_message_id?: string;
+}
+
+/** 已完成 Assistant Message 的直接写入参数。 */
+export interface AppendCompletedAssistantMessageInput {
+  /** 当前 Assistant 所属 Turn。 */
+  turn_id?: string;
+  /** Assistant 完整结构化 Part。 */
+  parts: SessionAssistantMessagePart[];
+  /** 当前 Assistant 是普通回复还是压缩 Summary。 */
+  kind?: "normal" | "summary";
+  /** 当前 Message 的默认展示范围。 */
+  visibility?: "visible" | "internal";
+  /** Summary 已覆盖到的来源 Message 标识。 */
+  summary_through_message_id?: string;
+}
+
+/** Action Message 创建参数。 */
+export interface OpenSessionActionMessageInput {
+  /** 可选的稳定 Message 标识，用于更新同一个 Action 生命周期。 */
+  message_id?: string;
+  /** 当前 Action 所属 Turn。 */
+  turn_id?: string;
+  /** 当前 Action 的业务类型。 */
+  action_type: string;
+  /** 当前 Action 标题。 */
+  title: string;
+  /** 当前 Action 描述。 */
+  description?: string;
+  /** 当前 Action 附加数据。 */
+  data?: JsonObject;
+}
+
+/** Error Message 创建参数。 */
+export interface AppendSessionErrorMessageInput {
+  /** 当前错误影响 Session 还是单个 Turn。 */
+  scope: "session" | "turn";
+  /** 当前错误所属 Turn。 */
+  turn_id?: string;
+  /** 当前错误的稳定业务码。 */
+  code: string;
+  /** 当前错误的用户可见文本。 */
+  message: string;
+  /** 当前错误是否允许恢复。 */
+  recoverable: boolean;
+}
+
+/** 公开 Session API 追加 User Message 的输入。 */
+export interface AppendExternalSessionUserMessageInput {
+  /** 可选的结构化 User Record。 */
+  message?: SessionRecordV1 | null;
+  /** 未提供结构化 Record 时使用的纯文本。 */
+  text?: string;
+}
+
+/** 公开 Session API 追加 Assistant Message 的输入。 */
+export interface AppendExternalSessionAssistantMessageInput {
+  /** 可选的结构化 Assistant Record。 */
+  message?: SessionRecordV1 | null;
+  /** 未提供结构化 Record 时使用的纯文本。 */
+  fallback_text?: string;
+}
+
+/** Session Prompt 转换并持久化的输入。 */
+export interface AppendSessionPromptMessageInput {
+  /** 当前 Agent 项目的绝对根目录，用于解析本地附件。 */
+  project_root: string;
+  /** 当前 Session Prompt 输入。 */
+  prompt: AgentSessionPromptInput;
+  /** 当前输入所属 Turn。 */
+  turn_id: string;
+  /** 当前输入是普通 Prompt 还是 Steering 输入。 */
+  input_type: "prompt" | "steer";
+}

package/src/types/session/SessionMutation.ts

@@ -5,7 +5,6 @@
  */
 
 import type { SessionAssistantMessagePart, SessionMessage } from "@/types/session/SessionMessage.js";
-import type { ResolveSessionApprovalInput, SessionApprovalResult } from "@/types/session/SessionApproval.js";
 
 /** 所有 Session Mutation 的公共字段。 */
 export interface SessionMutationBase {
@@ -108,19 +107,9 @@ export type SessionMutation =
   | SessionTurnMutation
   | SessionStateMutation;
 
-/** 当前 Mutation 可用的命令回复入口。 */
-export interface SessionMutationReply {
-  /**
-   * 回复当前 Tool Part 的审批请求。
-   * 只有 approval-required Tool Part Mutation 可以成功调用。
-   */
-  approval(input: Pick<ResolveSessionApprovalInput, "decision">): Promise<SessionApprovalResult>;
-}
-
 /** Session Mutation 订阅回调。 */
 export type SessionMutationSubscriber = (
   mutation: SessionMutation,
-  reply: SessionMutationReply,
 ) => void | Promise<void>;
 
 /** 取消 Session Mutation 订阅的函数。 */