@downcity/agent 1.1.287 → 1.1.310

package/src/types/rpc/RpcProtocol.ts

@@ -15,18 +15,15 @@ import type {
   AgentArchiveSessionResult,
   AgentArchiveSessionsResult,
   AgentCleanArchiveResult,
+  RemoteSessionSetInput,
   AgentSessionSystemSnapshot,
 } from "@/types/agent/SessionTypes.js";
 import type { SessionMutation } from "@/types/session/SessionMutation.js";
-import type {
-  ResolveSessionApprovalInput,
-  SetSessionApprovalModeInput,
-} from "@/types/session/SessionApproval.js";
+import type { RespondSessionInteractionInput } from "@/types/session/SessionInteraction.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type { ListSessionMessagesInput } from "@/types/session/SessionMessage.js";
 import type { JsonObject, JsonValue } from "@/types/common/Json.js";
-import type { PluginControlAction } from "@/types/plugin/PluginState.js";
 
 /**
  * RPC 请求。
@@ -60,7 +57,7 @@ export type RpcRequest =
       /** 目标 session 参数。 */
       params: {
         /** 目标 session id。 */
-        sessionId: string;
+        session_id: string;
       };
     }
   | {
@@ -71,7 +68,7 @@ export type RpcRequest =
       /** 归档参数。 */
       params: {
         /** 目标 session id。 */
-        sessionId: string;
+        session_id: string;
       };
     }
   | {
@@ -96,7 +93,7 @@ export type RpcRequest =
       /** prompt 参数。 */
       params: {
         /** 目标 session id。 */
-        sessionId: string;
+        session_id: string;
         /** SDK prompt 输入。 */
         input: AgentSessionPromptInput;
       };
@@ -109,7 +106,7 @@ export type RpcRequest =
       /** 停止参数。 */
       params: {
         /** 目标 session id。 */
-        sessionId: string;
+        session_id: string;
       };
     }
   | {
@@ -120,7 +117,7 @@ export type RpcRequest =
       /** 目标 Session 参数。 */
       params: {
         /** 目标 session id。 */
-        sessionId: string;
+        session_id: string;
       };
     }
   | {
@@ -131,7 +128,7 @@ export type RpcRequest =
       /** messages 查询参数。 */
       params: {
         /** 目标 session id。 */
-        sessionId: string;
+        session_id: string;
         /** messages 分页参数。 */
         input?: ListSessionMessagesInput;
       };
@@ -139,34 +136,34 @@ export type RpcRequest =
   | {
       /** 请求 id，用于匹配响应。 */
       id: string;
-      /** 列出指定 Session 的 pending 工具审批。 */
-      method: "sdk.sessions.approvals";
+      /** 列出指定 Session 正在等待用户响应的 Interaction。 */
+      method: "sdk.sessions.interactions";
       /** 目标 Session 参数。 */
-      params: { sessionId: string };
+      params: { session_id: string };
     }
   | {
       /** 请求 id，用于匹配响应。 */
       id: string;
-      /** 读取指定 Session 的工具审批模式。 */
-      method: "sdk.sessions.approvalMode";
+      /** 读取指定 Session 的运行与安全状态。 */
+      method: "sdk.sessions.status";
       /** 目标 Session 参数。 */
-      params: { sessionId: string };
+      params: { session_id: string };
     }
   | {
       /** 请求 id，用于匹配响应。 */
       id: string;
-      /** 更新指定 Session 的工具审批模式。 */
-      method: "sdk.sessions.setApprovalMode";
-      /** Session 与审批模式参数。 */
-      params: { sessionId: string; input: SetSessionApprovalModeInput };
+      /** 更新指定 Session 的可序列化动态配置。 */
+      method: "sdk.sessions.set";
+      /** Session 与动态配置参数。 */
+      params: { session_id: string; input: RemoteSessionSetInput };
     }
   | {
       /** 请求 id，用于匹配响应。 */
       id: string;
-      /** 处理指定 Session 的 pending 工具审批。 */
-      method: "sdk.sessions.resolveApproval";
-      /** Session 与审批决策参数。 */
-      params: { sessionId: string; input: ResolveSessionApprovalInput };
+      /** 提交指定 Session 的 Interaction 用户响应。 */
+      method: "sdk.sessions.respond";
+      /** Session 与 Interaction 响应参数。 */
+      params: { session_id: string; input: RespondSessionInteractionInput };
     }
   | {
       /** 请求 id，用于匹配响应。 */
@@ -176,7 +173,7 @@ export type RpcRequest =
       /** 目标 session 参数。 */
       params: {
         /** 目标 session id。 */
-        sessionId: string;
+        session_id: string;
       };
     }
   | {
@@ -187,9 +184,9 @@ export type RpcRequest =
       /** 分叉参数。 */
       params: {
         /** 源 session id。 */
-        sessionId: string;
+        session_id: string;
         /** 可选源消息 id。 */
-        messageId?: string;
+        message_id?: string;
       };
     }
   | {
@@ -200,7 +197,7 @@ export type RpcRequest =
       /** 订阅参数。 */
       params: {
         /** 目标 session id。 */
-        sessionId: string;
+        session_id: string;
       };
     }
   | {
@@ -211,7 +208,7 @@ export type RpcRequest =
       /** 取消订阅参数。 */
       params: {
         /** 当前订阅 id。 */
-        subscriptionId: string;
+        subscription_id: string;
       };
     }
   | {
@@ -220,6 +217,12 @@ export type RpcRequest =
       /** 读取 Agent 内部状态。 */
       method: "internal.status.get";
     }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 让宿主从事实源重新加载 Workspace Env。 */
+      method: "internal.workspace.reload_env";
+    }
   | {
       /** 请求 id，用于匹配响应。 */
       id: string;
@@ -228,7 +231,7 @@ export type RpcRequest =
       /** 目标 session 参数。 */
       params: {
         /** 目标 session id。 */
-        sessionId: string;
+        session_id: string;
       };
     }
   | {
@@ -239,7 +242,7 @@ export type RpcRequest =
       /** 目标 session 参数。 */
       params: {
         /** 目标 session id。 */
-        sessionId: string;
+        session_id: string;
       };
     }
   | {
@@ -250,7 +253,7 @@ export type RpcRequest =
       /** 目标 session 参数。 */
       params: {
         /** 目标 session id。 */
-        sessionId: string;
+        session_id: string;
       };
     }
   | {
@@ -265,36 +268,6 @@ export type RpcRequest =
       /** 列出 plugin 状态。 */
       method: "internal.plugins.list";
     }
-  | {
-      /** 请求 id，用于匹配响应。 */
-      id: string;
-      /** 控制 plugin 生命周期。 */
-      method: "internal.plugins.control";
-      /** plugin 控制参数。 */
-      params: {
-        /** plugin 名称。 */
-        pluginName: string;
-        /** 控制动作。 */
-        action: PluginControlAction;
-      };
-    }
-  | {
-      /** 请求 id，用于匹配响应。 */
-      id: string;
-      /** 执行 plugin command。 */
-      method: "internal.plugins.command";
-      /** plugin command 参数。 */
-      params: {
-        /** plugin 名称。 */
-        pluginName: string;
-        /** command 名称。 */
-        command: string;
-        /** command payload。 */
-        payload?: JsonValue;
-        /** 可选调度 payload。 */
-        schedule?: JsonValue;
-      };
-    }
   | {
       /** 请求 id，用于匹配响应。 */
       id: string;
@@ -303,7 +276,7 @@ export type RpcRequest =
       /** plugin 参数。 */
       params: {
         /** plugin 名称。 */
-        pluginName: string;
+        plugin_name: string;
       };
     }
   | {
@@ -314,9 +287,9 @@ export type RpcRequest =
       /** plugin action 参数。 */
       params: {
         /** plugin 名称。 */
-        pluginName: string;
+        plugin_name: string;
         /** action 名称。 */
-        actionName: string;
+        action_name: string;
         /** action payload。 */
         payload?: JsonValue;
       };
@@ -358,7 +331,7 @@ export interface RpcReadyFrame {
   /** 帧类型。 */
   type: "ready";
   /** 当前订阅 id。 */
-  subscriptionId: string;
+  subscription_id: string;
 }
 
 /**
@@ -368,7 +341,7 @@ export interface RpcEventFrame {
   /** 帧类型。 */
   type: "event";
   /** 当前订阅 id。 */
-  subscriptionId: string;
+  subscription_id: string;
   /** session 事件。 */
   event: SessionMutation;
 }
@@ -399,10 +372,12 @@ export interface RpcInternalStatus {
   status: string;
   /** RPC 服务所属进程的操作系统 pid。 */
   pid: number;
-  /** 当前 Agent 项目的绝对路径。 */
-  projectRoot: string;
+  /** 当前 Agent 的稳定全局 ID。 */
+  agent_id: string;
+  /** 当前 Agent 绑定的 Workspace 绝对路径。 */
+  workspace_path: string;
   /** daemon 启动实例 ID；非 daemon 前台进程返回空字符串。 */
-  instanceId: string;
+  instance_id: string;
 }
 
 /**
@@ -444,11 +419,11 @@ export interface RpcSystemPromptPayload {
   /** 请求是否成功。 */
   success?: boolean;
   /** 当前 session id。 */
-  sessionId: string;
+  session_id: string;
   /** system message 总数。 */
-  totalMessages: number;
+  total_messages: number;
   /** system message 总字符数。 */
-  totalChars: number;
+  total_chars: number;
   /** system message 分段。 */
   sections: RpcSystemPromptSection[];
 }

package/src/types/sdk/AgentSessionCompact.ts

@@ -0,0 +1,36 @@
+/**
+ * Session 显式压缩句柄与结果类型。
+ *
+ * `session.compact()` 返回句柄表示请求已进入有序队列；压缩真正结束后由
+ * `finished` 兑现最终结果，调用方不需要从 Action Message 反推完成状态。
+ */
+
+/** Session 显式压缩的稳定结束原因。 */
+export type AgentSessionCompactReason =
+  | "compacted"
+  | "nothing_to_compact"
+  | "compact_failed";
+
+/** 一次显式 Session 压缩的最终结果。 */
+export interface AgentSessionCompactResult {
+  /** 当前压缩请求的稳定标识。 */
+  compact_id: string;
+  /** 压缩请求是否成功完成；没有可压缩内容同样视为成功。 */
+  success: boolean;
+  /** 是否实际生成并提交了压缩计划。 */
+  compacted: boolean;
+  /** 当前请求结束的稳定原因。 */
+  reason: AgentSessionCompactReason;
+  /** 压缩失败时的错误文本。 */
+  error?: string;
+}
+
+/** 一次显式 Session 压缩的等待句柄。 */
+export interface AgentSessionCompactHandle {
+  /** 当前句柄绑定的压缩请求标识。 */
+  id: string;
+  /** 已完成后的最终结果；`finished` 兑现前为 null。 */
+  result: AgentSessionCompactResult | null;
+  /** 等待压缩 Command 真正完成的 Promise。 */
+  finished: Promise<AgentSessionCompactResult>;
+}

package/src/types/sdk/AgentSessionPrompt.ts

@@ -41,7 +41,7 @@ export interface AgentSessionPromptInput {
  * - `string`：trim 后为空即视为空。
  * - `SessionUserMessagePart[]`：数组为空或仅包含空文本时视为空。
  */
-export function isAgentSessionPromptInputEmpty(input: AgentSessionPromptInput): boolean {
+export function is_agent_session_prompt_input_empty(input: AgentSessionPromptInput): boolean {
   const query = input.query;
   if (typeof query === "string") {
     return query.trim() === "";

package/src/types/sdk/AgentSessionStop.ts

@@ -22,7 +22,7 @@ export interface AgentSessionStopResult {
    * - 当前没有活跃 turn 时不会返回该字段。
    * - 如果只是清空尚未启动的队列，也不会返回该字段。
    */
-  turnId?: string;
+  turn_id?: string;
 
   /**
    * 本次 stop 取消的未绑定 prompt 数量。
@@ -30,7 +30,7 @@ export interface AgentSessionStopResult {
    * 说明（中文）
    * - 已经被当前 turn 吸收的 prompt 不计入这里，它们会随当前 turn 一起结束。
    */
-  cancelledQueuedPrompts: number;
+  cancelled_queued_prompts: number;
 
   /**
    * 本次 stop 的归因。

package/src/types/sdk/AgentSessionTurn.ts

@@ -7,8 +7,6 @@
  * - 增量过程继续通过 `session.subscribe()` 观察；turn handle 只负责等待最终完成结果。
  */
 
-import type { SessionMessageRecordV1 } from "@/executor/types/SessionRecords.js";
-
 /**
  * 单个 Session turn 的最终结果。
  */
@@ -16,7 +14,7 @@ export interface AgentSessionTurnResult {
   /**
    * 当前已完成 turn 的稳定标识。
    */
-  turnId: string;
+  turn_id: string;
 
   /**
    * 当前 turn 最终可见文本。
@@ -28,16 +26,6 @@ export interface AgentSessionTurnResult {
    */
   success: boolean;
 
-  /**
-   * 当前 turn 最终 assistant 消息。
-   *
-   * 说明（中文）
-   * - 仅在当前 turn 实际产生 assistant 内容时存在。
-   * - 失败状态由 `success` 与 `error` 表达，不会伪造成 assistant 正文。
-   * - transport / runtime service 若需要读取最终结构化输出，应优先消费这里。
-   */
-  assistantMessage?: SessionMessageRecordV1;
-
   /**
    * 当前 turn 失败时的错误文本。
    */
@@ -49,11 +37,11 @@ export interface AgentSessionTurnResult {
  */
 export interface AgentSessionTurnHandle {
   /**
-   * 当前句柄绑定到的 turnId。
+   * 当前句柄绑定到的 turn_id。
    *
    * 说明（中文）
    * - `prompt()` 只有在确定当前输入被并入哪个 turn 后才会返回。
-   * - 因此这里总是最终可用的 turnId，而不是临时 receipt id。
+   * - 因此这里总是最终可用的 turn_id，而不是临时 receipt id。
    */
   id: string;
 

package/src/types/session/SessionCommand.ts

@@ -0,0 +1,27 @@
+/**
+ * Session Command 构造类型。
+ *
+ * Command 只存在于 Session 运行进程内，不属于 Remote Transport 协议，也不持久化。
+ */
+
+/** Session Command 构造参数。 */
+export interface SessionCommandOptions {
+  /** Command 出队后执行的完整行为。 */
+  execute: () => Promise<void>;
+  /** Session stop 时取消该 Command 的可选行为；未提供时 Command 继续保留。 */
+  cancel?: () => void;
+  /** Command 成功执行后需要持久化的完成信息；未提供时静默完成。 */
+  completion?: SessionCommandCompletion;
+}
+
+/** Session Command 成功执行后的 canonical 持久化信息。 */
+export interface SessionCommandCompletion {
+  /** 完成信息固定持久化为 Action Message。 */
+  type: "action";
+  /** Action Message 使用的稳定业务标识。 */
+  id: string;
+  /** Action Message 展示的用户可读标题。 */
+  title: string;
+  /** Action Message 展示的可选结果说明。 */
+  description?: string;
+}

package/src/types/session/SessionComposer.ts

@@ -80,10 +80,14 @@ export interface SessionStepInput {
   tools: Record<string, Tool>;
 }
 
-/** 持久化上下文压缩的组装参数。 */
-export interface SessionCompactionInput extends SessionComposeInput {
-  /** 是否由调用方明确要求执行持久化压缩。 */
-  force: boolean;
+/** 持久化上下文压缩所需的最小只读输入。 */
+export interface SessionCompactionInput {
+  /** 当前 Session 的稳定身份快照。 */
+  session: SessionComposeIdentity;
+  /** 当前 Session 实际使用的模型；只读或未配置场景允许为空。 */
+  model?: LanguageModel;
+  /** 当前 Session 的累计 Summary 与 Active Message 快照。 */
+  history: Readonly<SessionContextSnapshot>;
 }
 
 /** Composer 生成、等待 SessionMessages 提交的压缩计划。 */

package/src/{executor/types/SessionRun.ts → types/session/SessionExecution.ts}

@@ -1,20 +1,20 @@
 /**
- * Session 运行结果与输入类型。
+ * Session Turn 执行结果与输入类型。
  *
  * 关键点（中文）
- * - `SessionRunInput` 表示上层会话入口输入（例如 context query）。
- * - `SessionExecuteInput` 表示 Executor 通过 Composer 装配后的中间运行态。
- * - 输出暴露可选 assistantMessage（UIMessage）。
+ * - `SessionTurnExecutionInput` 表示上层 Turn 执行入口输入。
+ * - `SessionStepExecutionInput` 表示 Executor 通过 Composer 装配后的 Step 输入。
+ * - 输出只返回执行结果；Assistant Message 通过显式输出端口写入唯一事实源。
  */
 
-import type { FileUIPart, Tool, UIMessageChunk } from "ai";
+import type { Tool, UIMessageChunk } from "ai";
 import type {
   SessionRecordV1,
   SessionMessageRecordV1,
   SessionUserMessageV1,
 } from "@/executor/types/SessionRecords.js";
 import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
-import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
+import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js";
 
 /**
  * Assistant step 可见性。
@@ -37,7 +37,7 @@ export interface SessionAssistantStepCallbackInput {
   /**
    * 当前 step 序号（从 1 开始）。
    */
-  stepIndex: number;
+  step_index: number;
 
   /**
    * 当前 step 的可见性。
@@ -55,7 +55,7 @@ export interface SessionAssistantStepCallbackInput {
    * - 由运行时直接透传，供持久化层提取 tool call / tool result 顺序事件。
    * - 外部调用方不应依赖其稳定结构，只能做 best-effort 读取。
    */
-  stepResult?: unknown;
+  step_result?: unknown;
 }
 
 /**
@@ -95,34 +95,20 @@ export type SessionUiMessageStepAbortCallback = () => Promise<void>;
 /**
  * Session 执行结果。
  */
-export interface SessionRunResult {
+export interface SessionTurnExecutionResult {
   /**
    * 本轮执行是否成功。
    */
   success: boolean;
 
+  /** 本轮最终用户可见文本，不承载 Assistant Message 快照。 */
+  text: string;
+
   /**
    * 失败时的错误信息（成功时为空）。
    */
   error?: string;
 
-  /**
-   * 最终 assistant 消息。
-   *
-   * 关键点（中文）
-   * - stop/abort 且没有任何 assistant 内容时可以为空。
-   * - turn 状态通过 `success` / `error` 表达，不应伪造成 assistant 正文。
-   */
-  assistantMessage?: SessionMessageRecordV1 | null;
-
-  /**
-   * 工具运行期显式生成、并在 Assistant 末尾持久化的文件 Parts。
-   *
-   * 关键点（中文）：该字段与聚合 `assistantMessage` 分离，Session 不需要从最终
-   * UIMessage 反推哪些文件来自工具通道。
-   */
-  assistant_file_parts?: FileUIPart[];
-
   /**
    * 本轮执行结束后待写入长期历史的 user 消息。
    *
@@ -130,7 +116,7 @@ export interface SessionRunResult {
    * - 这些消息通常由 tool 运行时在执行过程中动态注入。
    * - 为保证消息顺序稳定，统一在 assistant 结果落盘后再由外层 Session 持久化。
    */
-  deferredPersistedUserMessages?: SessionUserMessageV1[];
+  deferred_persisted_user_messages?: SessionUserMessageV1[];
 
   /**
    * 本轮结束后是否需要把已完成的 canonical 历史持久化压缩。
@@ -143,28 +129,28 @@ export interface SessionRunResult {
 }
 
 /**
- * Session 运行入口输入。
+ * Session Turn 执行入口输入。
  */
-export interface SessionRunInput {
+export interface SessionTurnExecutionInput {
   /**
    * 本轮用户输入查询文本。
    */
   query: string;
 
   /**
-   * 本轮显式运行上下文。
+   * 本轮唯一的显式 Turn 上下文。
    *
    * 关键点（中文）
-   * - 这里承载 step 合并、UI chunk 回调等跨组件运行期数据。
-   * - 若未传入，则由执行器按最小默认值兜底创建。
+   * - 这里承载 Step 合并、UI chunk 回调等跨组件运行期数据。
+   * - Context 由 Turn 生命周期所有者创建并在 Turn 收口后释放。
    */
-  runContext?: SessionRunContext;
+  turn_context: SessionTurnContext;
 }
 
 /**
  * Executor 通过 Composer 装配后的中间运行态。
  */
-export interface SessionExecuteInput {
+export interface SessionStepExecutionInput {
   /**
    * 当前轮用户查询文本。
    */
@@ -185,3 +171,24 @@ export interface SessionExecuteInput {
    */
   tools: Record<string, Tool>;
 }
+
+/** 单个 Session 的统一 Turn 执行协议。 */
+export interface SessionExecutor {
+  /** 执行一个已经由 SessionLoop 创建上下文的 Turn。 */
+  execute(
+    input: SessionTurnExecutionInput,
+  ): Promise<SessionTurnExecutionResult>;
+}
+
+/** Session 领域执行一次持久化历史压缩的统一回调。 */
+export type SessionCompactHistory = (input: {
+  /** 触发压缩的 Turn 标识；非 Turn 维护操作允许为空。 */
+  turn_id?: string;
+}) => Promise<{
+  /** 是否生成并成功提交了压缩计划。 */
+  compacted: boolean;
+  /** 没有压缩时的稳定原因。 */
+  reason?: string;
+  /** 压缩失败时的具体错误文本。 */
+  error?: string;
+}>;