@downcity/agent 1.1.217 → 1.1.224

package/src/rpc/Client.ts

@@ -16,13 +16,15 @@ import type {
   AgentArchiveSessionResult,
   AgentArchiveSessionsResult,
   AgentCleanArchiveResult,
-  AgentSessionRecordsInput,
-  AgentSessionRecordsPage,
   AgentSessionInfo,
   AgentSessionSummaryPage,
   AgentSessionSystemSnapshot,
   AgentSessionSetInput,
 } from "@/types/agent/SessionTypes.js";
+import type {
+  ListSessionMessagesInput,
+  SessionMessagePage,
+} from "@/types/session/SessionMessage.js";
 import type { JsonValue } from "@/types/common/Json.js";
 import type { JsonObject } from "@/types/common/Json.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
@@ -36,7 +38,14 @@ import type {
   PluginControlResult,
   PluginSnapshot,
 } from "@/types/plugin/PluginState.js";
-import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
+import type { SessionMutation } from "@/types/session/SessionMutation.js";
+import type {
+  ResolveSessionApprovalInput,
+  SessionApproval,
+  SessionApprovalModeSnapshot,
+  SessionApprovalResult,
+  SetSessionApprovalModeInput,
+} from "@/types/session/SessionApproval.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type {
   RpcClientEndpoint,
@@ -45,14 +54,6 @@ import type {
   RpcSessionSubscription,
   RpcSystemPromptPayload,
 } from "@/types/rpc/RpcProtocol.js";
-import type {
-  ShellApprovalMode,
-  ShellApprovalDecisionResult,
-  ShellApprovalModeUpdateResult,
-  ShellApprovalModeOption,
-  ShellSessionApprovalModeView,
-  ShellApprovalView,
-} from "@downcity/shell";
 
 export type {
   RpcClientEndpoint,
@@ -67,7 +68,7 @@ type PendingRequest = {
 
 type RpcSubscription = {
   on_ready: () => void;
-  on_event: (event: AgentSessionEvent) => void;
+  on_event: (event: SessionMutation) => void;
   /** 底层 RPC 连接结束后的通知。 */
   on_close: (error?: unknown) => void;
 };
@@ -219,18 +220,18 @@ export class RpcClient {
   /**
    * 读取 session records。
    */
-  async get_session_records(params: {
+  async get_session_messages(params: {
     session_id: string;
-    input?: AgentSessionRecordsInput;
-  }): Promise<AgentSessionRecordsPage> {
-    const data = await this.request<{ records: AgentSessionRecordsPage }>({
-      method: "sdk.sessions.records",
+    input?: ListSessionMessagesInput;
+  }): Promise<SessionMessagePage> {
+    const data = await this.request<{ messages: SessionMessagePage }>({
+      method: "sdk.sessions.messages",
       params: {
         sessionId: params.session_id,
         input: params.input,
       },
     });
-    return data.records;
+    return data.messages;
   }
 
   /**
@@ -246,6 +247,44 @@ export class RpcClient {
     return data.system;
   }
 
+  async get_session_approvals(session_id: string): Promise<SessionApproval[]> {
+    const data = await this.request<{ approvals: SessionApproval[] }>({
+      method: "sdk.sessions.approvals",
+      params: { sessionId: session_id },
+    });
+    return data.approvals;
+  }
+
+  async get_session_approval_mode(session_id: string): Promise<SessionApprovalModeSnapshot> {
+    const data = await this.request<{ approval_mode: SessionApprovalModeSnapshot }>({
+      method: "sdk.sessions.approvalMode",
+      params: { sessionId: session_id },
+    });
+    return data.approval_mode;
+  }
+
+  async set_session_approval_mode(
+    session_id: string,
+    input: SetSessionApprovalModeInput,
+  ): Promise<SessionApprovalModeSnapshot> {
+    const data = await this.request<{ approval_mode: SessionApprovalModeSnapshot }>({
+      method: "sdk.sessions.setApprovalMode",
+      params: { sessionId: session_id, input },
+    });
+    return data.approval_mode;
+  }
+
+  async resolve_session_approval(
+    session_id: string,
+    input: ResolveSessionApprovalInput,
+  ): Promise<SessionApprovalResult> {
+    const data = await this.request<{ result: SessionApprovalResult }>({
+      method: "sdk.sessions.resolveApproval",
+      params: { sessionId: session_id, input },
+    });
+    return data.result;
+  }
+
   /**
    * 分叉 session。
    */
@@ -269,7 +308,7 @@ export class RpcClient {
   async subscribe_session(params: {
     session_id: string;
     on_ready: () => void;
-    on_event: (event: AgentSessionEvent) => void;
+    on_event: (event: SessionMutation) => void;
     on_close: (error?: unknown) => void;
   }): Promise<RpcSessionSubscription> {
     const data = await this.request<{ subscriptionId: string }>({
@@ -450,78 +489,6 @@ export class RpcClient {
     });
   }
 
-  /**
-   * 列出 shell approvals。
-   */
-  async list_shell_approvals(): Promise<ShellApprovalView[]> {
-    const data = await this.request<{ approvals: ShellApprovalView[] }>({
-      method: "internal.shell.approvals",
-    });
-    return Array.isArray(data.approvals) ? data.approvals : [];
-  }
-
-  /**
-   * 列出 shell approval 模式。
-   */
-  async list_shell_approval_modes(): Promise<ShellApprovalModeOption[]> {
-    const data = await this.request<{ modes: ShellApprovalModeOption[] }>({
-      method: "internal.shell.approvalModes",
-    });
-    return Array.isArray(data.modes) ? data.modes : [];
-  }
-
-  /**
-   * 读取 shell approval 模式。
-   */
-  async get_shell_approval_mode(session_id: string): Promise<ShellSessionApprovalModeView> {
-    return await this.request<ShellSessionApprovalModeView>({
-      method: "internal.shell.approvalMode",
-      params: {
-        sessionId: session_id,
-      },
-    });
-  }
-
-  /**
-   * 设置 shell approval 模式。
-   */
-  async set_shell_approval_mode(input: {
-    session_id: string;
-    mode: ShellApprovalMode;
-  }): Promise<ShellApprovalModeUpdateResult> {
-    return await this.request<ShellApprovalModeUpdateResult>({
-      method: "internal.shell.setApprovalMode",
-      params: {
-        sessionId: input.session_id,
-        mode: input.mode,
-      },
-    });
-  }
-
-  /**
-   * 批准 shell approval。
-   */
-  async approve_shell_approval(approval_id: string): Promise<ShellApprovalDecisionResult> {
-    return await this.request<ShellApprovalDecisionResult>({
-      method: "internal.shell.approve",
-      params: {
-        approvalId: approval_id,
-      },
-    });
-  }
-
-  /**
-   * 拒绝 shell approval。
-   */
-  async deny_shell_approval(approval_id: string): Promise<ShellApprovalDecisionResult> {
-    return await this.request<ShellApprovalDecisionResult>({
-      method: "internal.shell.deny",
-      params: {
-        approvalId: approval_id,
-      },
-    });
-  }
-
   /**
    * 关闭底层连接。
    */
@@ -669,10 +636,6 @@ export class RpcClient {
 
   private fail_all_subscriptions(message: string): void {
     for (const subscription of this.subscriptions.values()) {
-      subscription.on_event({
-        type: "error",
-        message,
-      });
       subscription.on_close(new Error(message));
     }
     this.subscriptions.clear();

package/src/session/Session.ts

@@ -10,12 +10,12 @@
 import { Executor } from "@executor/Executor.js";
 import type { Tool } from "ai";
 import { JsonlSessionHistoryComposer } from "@executor/composer/history/jsonl/JsonlSessionHistoryComposer.js";
-import { JsonlSessionHistoryStore } from "@/executor/store/history/jsonl/JsonlSessionHistoryStore.js";
+import { SessionRecorderHistoryStore } from "@/session/recorder/SessionRecorderHistoryStore.js";
+import { JsonlSessionMessageStore } from "@/session/recorder/JsonlSessionMessageStore.js";
+import { SessionRecorder } from "@/session/recorder/SessionRecorder.js";
 import type {
   AgentSessionConfigSnapshot,
   AgentSessionForkInput,
-  AgentSessionRecordsInput,
-  AgentSessionRecordsPage,
   AgentSessionInfo,
   AgentSessionSetInput,
   AgentSessionSystemBlock,
@@ -23,18 +23,30 @@ import type {
 } from "@/types/agent/SessionTypes.js";
 import type { AgentSession } from "@/types/agent/SessionActor.js";
 import {
-  getSdkAgentSessionArchiveDirPath,
+  getSdkAgentSessionAssistantMessagePath,
   getSdkAgentSessionDirPath,
-  getSdkAgentSessionInflightPath,
 } from "@/session/storage/Paths.js";
 import { resolveSystemTimezone } from "@/session/storage/Metadata.js";
 import { createRuntimeSessionPort } from "@/session/storage/RuntimeSessionPort.js";
 import { SessionSystemBuilder } from "@/session/SessionSystemBuilder.js";
 import type { SessionPort } from "@/types/runtime/agent/AgentContext.js";
 import type {
-  AgentSessionSubscriber,
-  AgentSessionUnsubscribe,
-} from "@/types/sdk/AgentSessionEvent.js";
+  SessionMutation,
+  SessionMutationSubscriber,
+  SessionMutationUnsubscribe,
+} from "@/types/session/SessionMutation.js";
+import type {
+  ResolveSessionApprovalInput,
+  SessionApproval,
+  SessionApprovalModeSnapshot,
+  SessionApprovalResult,
+  SetSessionApprovalModeInput,
+  SessionApprovalRuntimeEvent,
+} from "@/types/session/SessionApproval.js";
+import type {
+  ListSessionMessagesInput,
+  SessionMessagePage,
+} from "@/types/session/SessionMessage.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
@@ -69,10 +81,16 @@ export class Session implements AgentSession {
   private readonly getPluginSystemBlocks: SessionOptions["getPluginSystemBlocks"];
   private readonly ensureConfiguredHook?: SessionOptions["ensureConfigured"];
   private readonly composers?: SessionComposerOptions;
-  private readonly historyStore: JsonlSessionHistoryStore;
+  private readonly historyStore: SessionRecorderHistoryStore;
+  private readonly messageStore: JsonlSessionMessageStore;
+  private readonly recorder: SessionRecorder;
   private readonly historyComposer: SessionHistoryComposer;
   private readonly executor: Executor;
-  private readonly eventHub = new SessionEventHub();
+  private readonly eventHub: SessionEventHub;
+  private readonly list_approvals: SessionOptions["list_approvals"];
+  private readonly get_approval_mode: SessionOptions["get_approval_mode"];
+  private readonly set_approval_mode_hook: SessionOptions["set_approval_mode"];
+  private readonly resolve_approval_hook: SessionOptions["resolve_approval"];
   private readonly localState: SessionLocalState;
   private readonly stateService: SessionStateService;
   private readonly turnService: SessionTurnService;
@@ -90,6 +108,10 @@ export class Session implements AgentSession {
     this.getPluginSystemBlocks = options.getPluginSystemBlocks;
     this.ensureConfiguredHook = options.ensureConfigured;
     this.composers = options.composers;
+    this.list_approvals = options.list_approvals;
+    this.get_approval_mode = options.get_approval_mode;
+    this.set_approval_mode_hook = options.set_approval_mode;
+    this.resolve_approval_hook = options.resolve_approval;
     if (!this.id) {
       throw new Error("Session requires a non-empty sessionId");
     }
@@ -100,6 +122,22 @@ export class Session implements AgentSession {
       throw new Error("Session requires a non-empty projectRoot");
     }
 
+    this.eventHub = new SessionEventHub({
+      create_reply: (mutation) => ({
+        approval: async ({ decision }) => {
+          const approval_id = require_approval_id(mutation);
+          return await this.resolve_approval({ approval_id, decision });
+        },
+      }),
+    });
+    this.messageStore = this.create_message_store();
+    this.recorder = new SessionRecorder({
+      session_id: this.id,
+      store: this.messageStore,
+      publish: (mutation) => {
+        this.eventHub.publish(mutation);
+      },
+    });
     this.historyStore = this.create_history_store();
     this.localState = this.create_local_state();
     const composer_context = this.create_composer_context();
@@ -118,6 +156,7 @@ export class Session implements AgentSession {
       project_root: this.projectRoot,
       session_id: this.id,
       history_store: this.historyStore,
+      recorder: this.recorder,
       executor: this.executor,
       state: this.localState,
       logger: this.logger,
@@ -137,12 +176,14 @@ export class Session implements AgentSession {
       executor: this.executor,
       state_service: this.stateService,
       event_hub: this.eventHub,
+      recorder: this.recorder,
     });
     this.viewService = new SessionViewService<this>({
       agent_id: this.agentId,
       project_root: this.projectRoot,
       session_id: this.id,
       history_store: this.historyStore,
+      recorder: this.recorder,
       state_service: this.stateService,
       logger: this.logger,
       is_executing: () => this.isExecuting(),
@@ -158,6 +199,7 @@ export class Session implements AgentSession {
         return {
           session,
           history_store: session.historyStore,
+          recorder: session.recorder,
           state_service: session.stateService,
         };
       },
@@ -168,6 +210,7 @@ export class Session implements AgentSession {
    * 初始化当前 session。
    */
   async initialize(): Promise<this> {
+    await this.recorder.initialize();
     await this.stateService.initialize();
     return this;
   }
@@ -203,8 +246,45 @@ export class Session implements AgentSession {
   /**
    * 订阅当前 Session 的未来事件。
    */
-  subscribe(subscriber: AgentSessionSubscriber): AgentSessionUnsubscribe {
-    return this.turnService.subscribe(subscriber);
+  subscribe(
+    subscriber: SessionMutationSubscriber,
+  ): SessionMutationUnsubscribe {
+    return this.eventHub.subscribe(subscriber);
+  }
+
+  /** 列出当前 Session 的 pending 工具审批。 */
+  async approvals(): Promise<SessionApproval[]> {
+    return await this.list_approvals(this.id);
+  }
+
+  /** 读取当前 Session 的工具审批模式。 */
+  async approval_mode(): Promise<SessionApprovalModeSnapshot> {
+    return await this.get_approval_mode(this.id);
+  }
+
+  /** 更新当前 Session 的工具审批模式。 */
+  async set_approval_mode(input: SetSessionApprovalModeInput): Promise<SessionApprovalModeSnapshot> {
+    return await this.set_approval_mode_hook(this.id, input);
+  }
+
+  /** 处理当前 Session 的 pending 工具审批。 */
+  async resolve_approval(input: ResolveSessionApprovalInput): Promise<SessionApprovalResult> {
+    return await this.resolve_approval_hook(this.id, input);
+  }
+
+  private async apply_runtime_event(event: SessionApprovalRuntimeEvent): Promise<void> {
+    if (event.type === "tool-approval-request") {
+      await this.recorder.require_tool_approval({
+        tool_call_id: event.tool_call_id,
+        approval_id: event.approval_id,
+      });
+      return;
+    }
+    await this.recorder.resolve_tool_approval({
+      tool_call_id: event.tool_call_id,
+      approval_id: event.approval_id,
+      decision: event.decision,
+    });
   }
 
   /**
@@ -239,8 +319,8 @@ export class Session implements AgentSession {
   /**
    * 读取当前 session records 分页。
    */
-  async records(input?: AgentSessionRecordsInput): Promise<AgentSessionRecordsPage> {
-    return await this.viewService.records(input);
+  async messages(input?: ListSessionMessagesInput): Promise<SessionMessagePage> {
+    return await this.recorder.list_messages(input);
   }
 
   /**
@@ -275,8 +355,8 @@ export class Session implements AgentSession {
       prompt: async (input) => await this.prompt(input),
       stop: async () => await this.stop(),
       subscribe: (subscriber) => this.subscribe(subscriber),
-      publishEvent: (event) => {
-        this.eventHub.publish(event);
+      publishEvent: async (event) => {
+        await this.apply_runtime_event(event);
       },
       append_user_message: async (message_params) => {
         await this.stateService.append_user_message(message_params);
@@ -312,6 +392,10 @@ export class Session implements AgentSession {
       getPluginSystemBlocks: this.getPluginSystemBlocks,
       ensureConfigured: this.ensureConfiguredHook,
       composers: this.composers,
+      list_approvals: this.list_approvals,
+      get_approval_mode: this.get_approval_mode,
+      set_approval_mode: this.set_approval_mode_hook,
+      resolve_approval: this.resolve_approval_hook,
     });
   }
 
@@ -329,33 +413,28 @@ export class Session implements AgentSession {
     return new SessionClass(options) as this;
   }
 
-  private create_history_store(): JsonlSessionHistoryStore {
+  private create_message_store(): JsonlSessionMessageStore {
     const session_dir_path = getSdkAgentSessionDirPath(
       this.projectRoot,
       this.agentId,
       this.id,
     );
     const messages_dir_path = `${session_dir_path}/messages`;
-    return new JsonlSessionHistoryStore({
-      rootPath: this.projectRoot,
-      agentId: this.agentId,
-      sessionId: this.id,
-      paths: {
-        sessionDirPath: session_dir_path,
-        messagesDirPath: messages_dir_path,
-        messagesFilePath: `${messages_dir_path}/messages.jsonl`,
-        metaFilePath: `${messages_dir_path}/meta.json`,
-        archiveDirPath: getSdkAgentSessionArchiveDirPath(
-          this.projectRoot,
-          this.agentId,
-          this.id,
-        ),
-        inflightFilePath: getSdkAgentSessionInflightPath(
-          this.projectRoot,
-          this.agentId,
-          this.id,
-        ),
-      },
+    return new JsonlSessionMessageStore({
+      session_id: this.id,
+      file_path: `${messages_dir_path}/messages.jsonl`,
+      assistant_message_file_path: getSdkAgentSessionAssistantMessagePath(
+        this.projectRoot,
+        this.agentId,
+        this.id,
+      ),
+    });
+  }
+
+  private create_history_store(): SessionRecorderHistoryStore {
+    return new SessionRecorderHistoryStore({
+      session_id: this.id,
+      recorder: this.recorder,
     });
   }
 
@@ -471,3 +550,15 @@ export class Session implements AgentSession {
     return input;
   }
 }
+
+function require_approval_id(mutation: SessionMutation): string {
+  if (
+    mutation.variant === "part" &&
+    mutation.type === "tool" &&
+    mutation.part.state === "approval-required" &&
+    mutation.part.approval_id
+  ) {
+    return mutation.part.approval_id;
+  }
+  throw new Error("Current Session Mutation is not an approval-required Tool Part");
+}

package/src/session/browse/Browse.ts

@@ -45,6 +45,8 @@ import { getSdkAgentArchivedSessionsDirPath } from "@/session/storage/Paths.js";
 import { getSdkAgentArchivedSessionMessagesPath } from "@/session/storage/Paths.js";
 import { getSdkAgentArchivedSessionMetaPath } from "@/session/storage/Paths.js";
 import { readSessionMetadataFromPath } from "@/session/storage/Metadata.js";
+import { to_executor_ui_message } from "@/session/recorder/SessionMessageCodec.js";
+import type { SessionMessage } from "@/types/session/SessionMessage.js";
 
 type AnyUiPart = UIMessagePart<Record<string, never>, Record<string, never>>;
 
@@ -324,46 +326,73 @@ export function toSessionTimelineEvents(
 export async function loadSessionMessagesFromPath(
   filePath: string,
 ): Promise<SessionRecordV1[]> {
-  const messages: SessionRecordV1[] = [];
+  const messages_by_id = new Map<string, SessionMessage>();
   if (await fs.pathExists(filePath)) {
     const raw = await fs.readFile(filePath, "utf-8");
     const lines = raw.split("\n").filter(Boolean);
     for (const line of lines) {
       try {
-        const parsed = JSON.parse(line) as SessionRecordV1;
-        if (!parsed || typeof parsed !== "object") continue;
-        const candidate = parsed as { type?: unknown; role?: unknown };
-        if (
-          candidate.type !== "action" &&
-          candidate.role !== "user" &&
-          candidate.role !== "assistant"
-        ) {
-          continue;
+        const message = JSON.parse(line) as SessionMessage;
+        if (!is_canonical_session_message(message)) continue;
+        const previous = messages_by_id.get(message.message_id);
+        if (!previous || message.revision > previous.revision) {
+          messages_by_id.set(message.message_id, message);
         }
-        messages.push(parsed);
       } catch {
         // 关键点（中文）：单行损坏不影响整个 session 的可读性。
       }
     }
   }
 
-  const inflight_path = filePath.replace(/messages\.jsonl$/, "inflight.json");
+  const inflight_path = filePath.replace(/messages\.jsonl$/, "assistant_message.json");
   if (await fs.pathExists(inflight_path)) {
     try {
-      const parsed = (await fs.readJson(inflight_path)) as SessionRecordV1;
-      if (
-        is_session_message_record(parsed) &&
-        parsed.role === "assistant" &&
-        Array.isArray(parsed.parts)
-      ) {
-        messages.push(parsed);
+      const message = (await fs.readJson(inflight_path)) as SessionMessage;
+      if (is_canonical_session_message(message) && message.type === "assistant") {
+        messages_by_id.set(message.message_id, message);
       }
     } catch {
-      // ignore invalid inflight snapshot
+      // 运行中快照损坏时仍返回已经完成的历史。
     }
   }
 
-  return messages;
+  return [...messages_by_id.values()]
+    .sort((left, right) => left.sequence - right.sequence)
+    .flatMap(project_canonical_message_record);
+}
+
+function is_canonical_session_message(input: unknown): input is SessionMessage {
+  if (!input || typeof input !== "object") return false;
+  const candidate = input as Partial<SessionMessage>;
+  return (
+    typeof candidate.message_id === "string" &&
+    typeof candidate.session_id === "string" &&
+    typeof candidate.sequence === "number" &&
+    typeof candidate.revision === "number" &&
+    (candidate.type === "user" ||
+      candidate.type === "assistant" ||
+      candidate.type === "action" ||
+      candidate.type === "error")
+  );
+}
+
+function project_canonical_message_record(message: SessionMessage): SessionRecordV1[] {
+  const projected = to_executor_ui_message(message);
+  if (projected) return [projected];
+  if (message.type !== "action") return [];
+  return [{
+    type: "action",
+    id: message.message_id,
+    title: message.title,
+    ...(message.description ? { description: message.description } : {}),
+    state: message.status,
+    metadata: {
+      v: 1,
+      ts: message.updated_at,
+      sessionId: message.session_id,
+      ...(message.turn_id ? { turnId: message.turn_id } : {}),
+    },
+  }];
 }
 
 /**
@@ -481,7 +510,7 @@ async function resolve_session_summary_metadata(input: {
   const history_bytes = await fs.stat(input.messagesPath)
     .then((file_stat) => file_stat.size)
     .catch(() => 0);
-  const inflight_path = `${input.messagesPath.slice(0, -"messages.jsonl".length)}inflight.json`;
+  const inflight_path = `${input.messagesPath.slice(0, -"messages.jsonl".length)}assistant_message.json`;
   const has_inflight = await fs.pathExists(inflight_path);
   if (
     !input.refresh &&