@downcity/agent 1.1.108 → 1.1.113

package/src/types/agent/RemoteAgentPluginAction.ts

@@ -0,0 +1,52 @@
+/**
+ * RemoteAgent plugin action 类型。
+ *
+ * 关键点（中文）
+ * - RemoteAgent 是远程 runtime 的瘦客户端，因此这里只描述远程调用协议。
+ * - 业务 action 的具体 payload 与 data 由目标 plugin 自己定义。
+ */
+
+import type { JsonValue } from "@/types/common/Json.js";
+import type { PluginActionResult } from "@/types/plugin/PluginAction.js";
+
+/**
+ * RemoteAgent 远程 plugin action 调用输入。
+ */
+export interface RemoteAgentPluginActionInput {
+  /**
+   * 目标 plugin 名称。
+   *
+   * 示例：`shell`、`chat`、`task`。
+   */
+  plugin: string;
+
+  /**
+   * 目标 action 名称。
+   *
+   * 示例：`approve`、`deny`、`send`。
+   */
+  action: string;
+
+  /**
+   * 传给目标 action 的 JSON payload。
+   *
+   * shell approval 示例：`{ "approvalId": "ap_xxx" }`。
+   */
+  payload?: JsonValue;
+}
+
+/**
+ * RemoteAgent 远程 plugin action 调用结果。
+ */
+export type RemoteAgentPluginActionResult =
+  PluginActionResult<JsonValue> & {
+    /**
+     * Runtime 回传的 plugin 名称。
+     */
+    pluginName?: string;
+
+    /**
+     * Runtime 回传的 action 名称。
+     */
+    actionName?: string;
+  };

package/src/types/executor/SessionRunContext.ts

@@ -18,6 +18,15 @@ import type { FileUIPart } from "ai";
  * 单次 session run 的运行上下文。
  */
 export interface SessionRunContext {
+  /**
+   * 当前执行所属的 turn 标识。
+   *
+   * 关键点（中文）
+   * - session 是长期对话容器，turn 是单次用户输入触发的执行轮次。
+   * - 工具运行时发布 session event 时应优先使用该字段，避免把 sessionId 误当 turnId。
+   */
+  turnId?: string;
+
   /**
    * 当前执行所属的 session 标识。
    */

package/src/types/runtime/agent/AgentContext.ts

@@ -31,6 +31,7 @@ import type {
 import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type {
+  AgentSessionEvent,
   AgentSessionSubscriber,
   AgentSessionUnsubscribe,
 } from "@/types/sdk/AgentSessionEvent.js";
@@ -132,6 +133,14 @@ export interface SessionPort {
    * - 历史消息仍通过 `getHistoryStore()` / SDK `history()` 读取。
    */
   subscribe(subscriber: AgentSessionSubscriber): AgentSessionUnsubscribe;
+  /**
+   * 发布一条 session runtime 事件。
+   *
+   * 关键点（中文）
+   * - plugin runtime 用它把审批、外部进度等非模型 chunk 事件推送给订阅方。
+   * - 历史消息持久化仍由 appendUserMessage / appendAssistantMessage 负责。
+   */
+  publishEvent(event: AgentSessionEvent): void;
   /**
    * 清理当前 session 的 executor 缓存。
    */

package/src/types/sdk/AgentSessionEvent.ts

@@ -90,7 +90,7 @@ export interface AgentSessionToolCallEvent {
   /**
    * 当前工具名称。
    */
-  toolName: string;
+  toolName: "shell_exec" | "shell_start" | "shell_write" | string;
 
   /**
    * 当前工具输入参数。
@@ -120,7 +120,7 @@ export interface AgentSessionToolResultEvent {
   /**
    * 当前工具名称。
    */
-  toolName: string;
+  toolName: "shell_exec" | "shell_start" | "shell_write" | string;
 
   /**
    * 当前工具输出结果。
@@ -128,6 +128,120 @@ export interface AgentSessionToolResultEvent {
   result: JsonValue;
 }
 
+/**
+ * 工具审批请求事件。
+ */
+export interface AgentSessionToolApprovalRequestEvent {
+  /**
+   * 当前事件类型。
+   */
+  type: "tool-approval-request";
+
+  /**
+   * 当前审批所属 turn。
+   */
+  turnId: string;
+
+  /**
+   * 当前工具调用唯一标识。
+   */
+  toolCallId: string;
+
+  /**
+   * 当前工具名称。
+   */
+  toolName: "shell_exec" | "shell_start" | "shell_write" | string;
+
+  /**
+   * 当前审批请求唯一标识。
+   */
+  approvalId: string;
+
+  /**
+   * 请求执行的 sandbox 模式。
+   */
+  sandbox: "unrestricted";
+
+  /**
+   * 请求执行的命令文本。
+   *
+   * 说明（中文）
+   * - `shell_exec` / `shell_start` 中是命令文本。
+   * - `shell_write` 中是 stdin 写入内容，用于兼容旧 UI 展示。
+   */
+  cmd: string;
+
+  /**
+   * 当前审批动作类型。
+   */
+  operation?: "exec" | "start" | "write";
+
+  /**
+   * 关联 shell_id；`shell_write` 审批时用于标识目标会话。
+   */
+  shellId?: string;
+
+  /**
+   * stdin 写入内容预览；仅 `shell_write` 审批存在。
+   */
+  inputPreview?: string;
+
+  /**
+   * stdin 写入字符数；仅 `shell_write` 审批存在。
+   */
+  inputChars?: number;
+
+  /**
+   * 命令执行目录。
+   */
+  cwd: string;
+
+  /**
+   * Agent 给用户展示的申请原因。
+   */
+  reason: string;
+
+  /**
+   * 当前审批状态。
+   */
+  status: "pending";
+}
+
+/**
+ * 工具审批结果事件。
+ */
+export interface AgentSessionToolApprovalResultEvent {
+  /**
+   * 当前事件类型。
+   */
+  type: "tool-approval-result";
+
+  /**
+   * 当前审批所属 turn。
+   */
+  turnId: string;
+
+  /**
+   * 当前工具调用唯一标识。
+   */
+  toolCallId: string;
+
+  /**
+   * 当前工具名称。
+   */
+  toolName: "shell_exec" | "shell_start" | "shell_write" | string;
+
+  /**
+   * 当前审批请求唯一标识。
+   */
+  approvalId: string;
+
+  /**
+   * 用户最终决策。
+   */
+  decision: "approved" | "denied" | "expired";
+}
+
 /**
  * assistant step 完成事件。
  */
@@ -236,6 +350,8 @@ export type AgentSessionEvent =
   | AgentSessionReasoningDeltaEvent
   | AgentSessionToolCallEvent
   | AgentSessionToolResultEvent
+  | AgentSessionToolApprovalRequestEvent
+  | AgentSessionToolApprovalResultEvent
   | AgentSessionAssistantStepEvent
   | AgentSessionTitleEvent
   | AgentSessionTurnFinishEvent