@downcity/agent 1.1.222 → 1.1.226

package/src/session/runtime/SessionEventHub.ts

@@ -1,5 +1,5 @@
 /**
- * SessionEventHub：Session 级事件分发器。
+ * SessionEventHub：统一 Session Mutation 分发器。
  *
  * 关键点（中文）
  * - 收口 `Session.subscribe()` 的订阅/取消订阅能力。
@@ -7,24 +7,36 @@
  */
 
 import type {
-  AgentSessionEvent,
-  AgentSessionSubscriber,
-  AgentSessionUnsubscribe,
-} from "@/types/sdk/AgentSessionEvent.js";
+  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, AgentSessionSubscriber>();
-  private nextSubscriberId = 1;
+  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 事件订阅者。
    */
-  subscribe(subscriber: AgentSessionSubscriber): AgentSessionUnsubscribe {
-    const id = this.nextSubscriberId;
-    this.nextSubscriberId += 1;
+  subscribe(subscriber: SessionMutationSubscriber): SessionMutationUnsubscribe {
+    const id = this.next_subscriber_id;
+    this.next_subscriber_id += 1;
     this.subscribers.set(id, subscriber);
 
     return () => {
@@ -35,10 +47,11 @@ export class SessionEventHub {
   /**
    * 广播一条 Session 事件。
    */
-  publish(event: AgentSessionEvent): void {
+  publish(mutation: SessionMutation): void {
+    const reply = this.create_reply(mutation);
     for (const subscriber of this.subscribers.values()) {
       try {
-        subscriber(event);
+        Promise.resolve(subscriber(mutation, reply)).catch(() => undefined);
       } catch {
         // ignore single subscriber failures
       }

package/src/session/runtime/SessionPromptRuntime.ts

@@ -13,7 +13,7 @@ import type {
   SessionRecordV1,
   SessionMessageRecordV1,
 } from "@/executor/types/SessionRecords.js";
-import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
+import type { SessionMutation } from "@/types/session/SessionMutation.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type {
@@ -89,7 +89,7 @@ export interface SessionPromptRuntimeOptions {
   /**
    * 广播 session 事件。
    */
-  publish: (event: AgentSessionEvent) => void;
+  publish: (mutation: SessionMutation) => void;
 
   /**
    * 构造并持久化一条 user 消息。
@@ -226,8 +226,13 @@ export class SessionPromptRuntime {
       const activeTurn = createActiveTurnState(turnId);
       this.activeTurn = activeTurn;
       this.publish({
-        type: "turn-start",
-        turnId,
+        mutation_id: nanoid(),
+        variant: "turn",
+        type: "start",
+        session_id: this.sessionId,
+        turn_id: turnId,
+        status: "running",
+        created_at: Date.now(),
       });
       current.deferredHandle.resolve(createTurnHandle(activeTurn));
 
@@ -255,10 +260,14 @@ export class SessionPromptRuntime {
         };
         activeTurn.result = finalResult;
         this.publish({
-          type: "turn-finish",
-          turnId,
+          mutation_id: nanoid(),
+          variant: "turn",
+          type: "finish",
+          session_id: this.sessionId,
+          turn_id: turnId,
+          status: stopped ? "stopped" : finalResult.success ? "completed" : "failed",
+          created_at: Date.now(),
           text: finalResult.text,
-          success: finalResult.success,
           ...(finalResult.error ? { error: finalResult.error } : {}),
         });
         activeTurn.deferredFinished.resolve(finalResult);
@@ -286,16 +295,16 @@ export class SessionPromptRuntime {
           } catch {
             // Error Message 写入失败不能阻止 turn handle 收口。
           }
-          this.publish({
-            type: "error",
-            message,
-          });
         }
         this.publish({
-          type: "turn-finish",
-          turnId,
+          mutation_id: nanoid(),
+          variant: "turn",
+          type: "finish",
+          session_id: this.sessionId,
+          turn_id: turnId,
+          status: activeTurn.abortController.signal.aborted ? "stopped" : "failed",
+          created_at: Date.now(),
           text: "",
-          success: false,
           error: message,
         });
         activeTurn.deferredFinished.resolve(finalResult);
@@ -326,14 +335,23 @@ export class SessionPromptRuntime {
       cancelledTurn.result = finalResult;
       cancelledTurn.deferredFinished.resolve(finalResult);
       this.publish({
-        type: "turn-start",
-        turnId,
+        mutation_id: nanoid(),
+        variant: "turn",
+        type: "start",
+        session_id: this.sessionId,
+        turn_id: turnId,
+        status: "running",
+        created_at: Date.now(),
       });
       this.publish({
-        type: "turn-finish",
-        turnId,
+        mutation_id: nanoid(),
+        variant: "turn",
+        type: "finish",
+        session_id: this.sessionId,
+        turn_id: turnId,
+        status: "failed",
+        created_at: Date.now(),
         text: "",
-        success: false,
         error: QUEUED_PROMPT_CANCELLED_MESSAGE,
       });
       item.deferredHandle.resolve(createTurnHandle(cancelledTurn));

package/src/session/services/SessionStateService.ts

@@ -26,9 +26,7 @@ import type {
   AgentSessionConfigSnapshot,
   AgentSessionSetInput,
 } from "@/types/agent/SessionTypes.js";
-import type {
-  AgentSessionEvent,
-} from "@/types/sdk/AgentSessionEvent.js";
+import type { SessionMutation } from "@/types/session/SessionMutation.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type {
   SessionActionRecordInputV1,
@@ -102,7 +100,7 @@ type SessionStateServiceOptions = {
   /**
    * 发布 session 事件。
    */
-  publish_event: (event: AgentSessionEvent) => void;
+  publish_event: (mutation: SessionMutation) => void;
 };
 
 type SessionSetOptions = {
@@ -372,6 +370,7 @@ export class SessionStateService {
       ? from_ui_assistant_parts(params.message.parts)
       : [{
           part_id: `external-assistant-text:${Date.now()}`,
+          sequence: 1,
           type: "text" as const,
           text: String(params.fallbackText || "").trim(),
           state: "done" as const,
@@ -442,8 +441,11 @@ export class SessionStateService {
     const next_title = String(next_metadata.title || "").trim();
     if (!next_title || next_title === before_title) return;
     this.publish_event({
-      type: "session-title",
-      sessionId: this.session_id,
+      mutation_id: generateId(),
+      variant: "session",
+      type: "title",
+      session_id: this.session_id,
+      created_at: Date.now(),
       title: next_title,
     });
   }

package/src/session/services/SessionTurnService.ts

@@ -9,11 +9,7 @@
 
 import { extractTextFromParts, extractTextFromUiMessage } from "@/executor/messages/UIMessageTransformer.js";
 import type { Executor } from "@executor/Executor.js";
-import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
-import type {
-  AgentSessionSubscriber,
-  AgentSessionUnsubscribe,
-} from "@/types/sdk/AgentSessionEvent.js";
+import type { SessionMutation } from "@/types/session/SessionMutation.js";
 import { isAgentSessionPromptInputEmpty } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
@@ -118,15 +114,8 @@ export class SessionTurnService {
   /**
    * 发布一条 session 事件。
    */
-  publish_event(event: AgentSessionEvent): void {
-    this.event_hub.publish(event);
-  }
-
-  /**
-   * 订阅当前 session 的未来事件。
-   */
-  subscribe(subscriber: AgentSessionSubscriber): AgentSessionUnsubscribe {
-    return this.event_hub.subscribe(subscriber);
+  publish_event(mutation: SessionMutation): void {
+    this.event_hub.publish(mutation);
   }
 
   /**

package/src/session/storage/Paths.ts

@@ -212,13 +212,13 @@ export function getSdkAgentSessionArchiveFilePath(
  * - step / tool 过程会持续重写这个文件，避免中途中断后过程完全丢失。
  * - 完成后再把最终 assistant 合并进 `messages.jsonl`，并清理该文件。
  */
-export function getSdkAgentSessionInflightPath(
+export function getSdkAgentSessionAssistantMessagePath(
   projectRoot: string,
   agentId: string,
   sessionId: string,
 ): string {
   return path.join(
     getSdkAgentSessionMessagesDirPath(projectRoot, agentId, sessionId),
-    "inflight.json",
+    "assistant_message.json",
   );
 }

package/src/session/storage/RuntimeSessionPort.ts

@@ -11,12 +11,9 @@ import type { SessionHistoryStore } from "@/executor/store/history/SessionHistor
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type {
-  AgentSessionEvent,
-} from "@/types/sdk/AgentSessionEvent.js";
-import type {
-  SessionMessageMutationSubscriber,
-  SessionMessageMutationUnsubscribe,
-} from "@/types/session/SessionMessageMutation.js";
+  SessionMutationSubscriber,
+  SessionMutationUnsubscribe,
+} from "@/types/session/SessionMutation.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
 
 /**
@@ -43,12 +40,12 @@ export interface CreateRuntimeSessionPortParams {
    * 订阅当前 session 的 future 事件。
    */
   subscribe: (
-    subscriber: SessionMessageMutationSubscriber,
-  ) => SessionMessageMutationUnsubscribe;
+    subscriber: SessionMutationSubscriber,
+  ) => SessionMutationUnsubscribe;
   /**
    * 发布一条 session runtime 事件。
    */
-  publishEvent: (event: AgentSessionEvent) => void;
+  publishEvent: SessionPort["publishEvent"];
   /**
    * 追加 user 消息到底层历史。
    */
@@ -92,8 +89,8 @@ export function createRuntimeSessionPort(
     subscribe: (subscriber) => {
       return params.subscribe(subscriber);
     },
-    publishEvent: (event) => {
-      params.publishEvent(event);
+    publishEvent: async (event) => {
+      await params.publishEvent(event);
     },
     append_user_message: async (messageParams) => {
       await params.append_user_message(messageParams);

package/src/types/agent/SessionActor.ts

@@ -22,15 +22,16 @@ import type {
   AgentSessionSystemSnapshot,
 } from "@/types/agent/SessionTypes.js";
 import type {
-  AgentSessionSubscriber,
-  AgentSessionUnsubscribe,
-} from "@/types/sdk/AgentSessionEvent.js";
+  SessionMutationSubscriber,
+  SessionMutationUnsubscribe,
+} from "@/types/session/SessionMutation.js";
 import type {
-  ListSessionMessageChangesInput,
-  SessionMessageMutationPage,
-  SessionMessageMutationSubscriber,
-  SessionMessageMutationUnsubscribe,
-} from "@/types/session/SessionMessageMutation.js";
+  ResolveSessionApprovalInput,
+  SessionApproval,
+  SessionApprovalModeSnapshot,
+  SessionApprovalResult,
+  SetSessionApprovalModeInput,
+} from "@/types/session/SessionApproval.js";
 import type {
   ListSessionMessagesInput,
   SessionMessagePage,
@@ -80,24 +81,26 @@ export interface AgentSessionActor {
 
   /** 订阅当前 session 的未来事件。 */
   subscribe(
-    subscriber: SessionMessageMutationSubscriber,
-  ): SessionMessageMutationUnsubscribe;
-
-  /** 订阅远程 transport 使用的 Message 与 turn lifecycle 事件。 */
-  subscribe_transport(
-    subscriber: AgentSessionSubscriber,
-  ): AgentSessionUnsubscribe;
+    subscriber: SessionMutationSubscriber,
+  ): SessionMutationUnsubscribe;
 
   /** 读取当前 session messages 分页。 */
   messages(input?: ListSessionMessagesInput): Promise<SessionMessagePage>;
 
-  /** 读取指定 cursor 后的 Message Mutation。 */
-  message_changes(
-    input: ListSessionMessageChangesInput,
-  ): Promise<SessionMessageMutationPage>;
-
   /** 读取当前 session 生效的 system 快照。 */
   system(): Promise<AgentSessionSystemSnapshot>;
+
+  /** 列出当前 Session 的 pending 工具审批。 */
+  approvals(): Promise<SessionApproval[]>;
+
+  /** 读取当前 Session 的工具审批模式。 */
+  approval_mode(): Promise<SessionApprovalModeSnapshot>;
+
+  /** 更新当前 Session 的工具审批模式。 */
+  set_approval_mode(input: SetSessionApprovalModeInput): Promise<SessionApprovalModeSnapshot>;
+
+  /** 处理当前 Session 的 pending 工具审批。 */
+  resolve_approval(input: ResolveSessionApprovalInput): Promise<SessionApprovalResult>;
 }
 
 /**

package/src/types/rpc/RpcProtocol.ts

@@ -18,14 +18,16 @@ import type {
   AgentSessionSystemSnapshot,
   AgentSessionSetInput,
 } from "@/types/agent/SessionTypes.js";
-import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
+import type { SessionMutation } from "@/types/session/SessionMutation.js";
+import type {
+  ResolveSessionApprovalInput,
+  SetSessionApprovalModeInput,
+} from "@/types/session/SessionApproval.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 { ListSessionMessageChangesInput } from "@/types/session/SessionMessageMutation.js";
 import type { JsonObject, JsonValue } from "@/types/common/Json.js";
 import type { PluginControlAction } from "@/types/plugin/PluginState.js";
-import type { ShellApprovalMode } from "@downcity/shell";
 
 /**
  * RPC 请求。
@@ -140,15 +142,34 @@ export type RpcRequest =
   | {
       /** 请求 id，用于匹配响应。 */
       id: string;
-      /** 读取 session message mutations。 */
-      method: "sdk.sessions.message_changes";
-      /** changes 查询参数。 */
-      params: {
-        /** 目标 session id。 */
-        sessionId: string;
-        /** Mutation 增量参数。 */
-        input: ListSessionMessageChangesInput;
-      };
+      /** 列出指定 Session 的 pending 工具审批。 */
+      method: "sdk.sessions.approvals";
+      /** 目标 Session 参数。 */
+      params: { sessionId: string };
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 读取指定 Session 的工具审批模式。 */
+      method: "sdk.sessions.approvalMode";
+      /** 目标 Session 参数。 */
+      params: { sessionId: string };
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 更新指定 Session 的工具审批模式。 */
+      method: "sdk.sessions.setApprovalMode";
+      /** Session 与审批模式参数。 */
+      params: { sessionId: string; input: SetSessionApprovalModeInput };
+    }
+  | {
+      /** 请求 id，用于匹配响应。 */
+      id: string;
+      /** 处理指定 Session 的 pending 工具审批。 */
+      method: "sdk.sessions.resolveApproval";
+      /** Session 与审批决策参数。 */
+      params: { sessionId: string; input: ResolveSessionApprovalInput };
     }
   | {
       /** 请求 id，用于匹配响应。 */
@@ -302,64 +323,6 @@ export type RpcRequest =
         /** action payload。 */
         payload?: JsonValue;
       };
-    }
-  | {
-      /** 请求 id，用于匹配响应。 */
-      id: string;
-      /** 列出 shell approvals。 */
-      method: "internal.shell.approvals";
-    }
-  | {
-      /** 请求 id，用于匹配响应。 */
-      id: string;
-      /** 列出 shell approval 模式。 */
-      method: "internal.shell.approvalModes";
-    }
-  | {
-      /** 请求 id，用于匹配响应。 */
-      id: string;
-      /** 读取 shell approval 模式。 */
-      method: "internal.shell.approvalMode";
-      /** session 参数。 */
-      params: {
-        /** session id。 */
-        sessionId: string;
-      };
-    }
-  | {
-      /** 请求 id，用于匹配响应。 */
-      id: string;
-      /** 设置 shell approval 模式。 */
-      method: "internal.shell.setApprovalMode";
-      /** session 模式参数。 */
-      params: {
-        /** session id。 */
-        sessionId: string;
-        /** approval 模式。 */
-        mode: ShellApprovalMode;
-      };
-    }
-  | {
-      /** 请求 id，用于匹配响应。 */
-      id: string;
-      /** 批准 shell approval。 */
-      method: "internal.shell.approve";
-      /** approval 参数。 */
-      params: {
-        /** approval id。 */
-        approvalId: string;
-      };
-    }
-  | {
-      /** 请求 id，用于匹配响应。 */
-      id: string;
-      /** 拒绝 shell approval。 */
-      method: "internal.shell.deny";
-      /** approval 参数。 */
-      params: {
-        /** approval id。 */
-        approvalId: string;
-      };
     };
 
 /**
@@ -410,7 +373,7 @@ export interface RpcEventFrame {
   /** 当前订阅 id。 */
   subscriptionId: string;
   /** session 事件。 */
-  event: AgentSessionEvent;
+  event: SessionMutation;
 }
 
 /**

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

@@ -29,14 +29,10 @@ import type { SessionHistoryStore } from "@/executor/store/history/SessionHistor
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type {
-  AgentSessionEvent,
-  AgentSessionSubscriber,
-  AgentSessionUnsubscribe,
-} from "@/types/sdk/AgentSessionEvent.js";
-import type {
-  SessionMessageMutationSubscriber,
-  SessionMessageMutationUnsubscribe,
-} from "@/types/session/SessionMessageMutation.js";
+  SessionMutationSubscriber,
+  SessionMutationUnsubscribe,
+} from "@/types/session/SessionMutation.js";
+import type { SessionApprovalRuntimeEvent } from "@/types/session/SessionApproval.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
 
 /**
@@ -140,8 +136,8 @@ export interface SessionPort {
    * - 当前 Message snapshot 通过公开 SDK `session.messages()` 读取。
    */
   subscribe(
-    subscriber: SessionMessageMutationSubscriber,
-  ): SessionMessageMutationUnsubscribe;
+    subscriber: SessionMutationSubscriber,
+  ): SessionMutationUnsubscribe;
   /**
    * 发布一条 session runtime 事件。
    *
@@ -149,7 +145,7 @@ export interface SessionPort {
    * - plugin runtime 用它把审批、外部进度等非模型 chunk 事件推送给订阅方。
    * - 历史消息持久化仍由 append_user_message / append_assistant_message 负责。
    */
-  publishEvent(event: AgentSessionEvent): void;
+  publishEvent(event: SessionApprovalRuntimeEvent): Promise<void>;
   /**
    * 追加一条 user 消息。
    */

package/src/types/session/SessionApproval.ts

@@ -0,0 +1,108 @@
+/**
+ * Session 级工具审批类型。
+ *
+ * 审批由具体工具运行时执行，但归属、查询和决策能力统一通过 Session 暴露。
+ */
+
+/** Session 工具审批的最终人工决策。 */
+export type SessionApprovalDecision = "approved" | "denied";
+
+/** Session 工具审批模式。 */
+export type SessionApprovalMode = "ask" | "always-allow";
+
+/** 当前 Session 的待审批工具请求。 */
+export interface SessionApproval {
+  /** 当前审批请求的稳定唯一标识。 */
+  approval_id: string;
+  /** 当前审批所属 Session 标识。 */
+  session_id: string;
+  /** 当前审批所属 Turn 标识。 */
+  turn_id?: string;
+  /** 当前审批对应的工具调用标识。 */
+  tool_call_id?: string;
+  /** 当前审批对应的工具注册名称。 */
+  tool_name: string;
+  /** 请求执行的命令或输入文本。 */
+  command: string;
+  /** 当前工具执行工作目录。 */
+  cwd: string;
+  /** 工具申请 unrestricted 权限的原因。 */
+  reason: string;
+  /** 当前审批对应的工具操作类型。 */
+  operation: "exec" | "start" | "write";
+  /** 当前审批创建时间戳（ms）。 */
+  created_at: number;
+}
+
+/** 提交 Session 工具审批决策的参数。 */
+export interface ResolveSessionApprovalInput {
+  /** 需要处理的审批请求标识。 */
+  approval_id: string;
+  /** 对当前审批请求作出的最终决定。 */
+  decision: SessionApprovalDecision;
+}
+
+/** Session 工具审批决策结果。 */
+export interface SessionApprovalResult {
+  /** 是否成功命中并处理 pending 审批。 */
+  success: boolean;
+  /** 已尝试处理的审批请求标识。 */
+  approval_id: string;
+  /** 已提交的最终审批决定。 */
+  decision: SessionApprovalDecision;
+}
+
+/** 当前 Session 的审批模式快照。 */
+export interface SessionApprovalModeSnapshot {
+  /** 当前审批模式所属 Session 标识。 */
+  session_id: string;
+  /** 当前 Session 生效的审批模式。 */
+  mode: SessionApprovalMode;
+}
+
+/** 更新当前 Session 审批模式的参数。 */
+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;