@downcity/agent 1.1.199 → 1.1.202

package/src/agent/local/services/{AgentSessionManager.ts → AgentSessions.ts}

@@ -1,8 +1,8 @@
 /**
- * AgentSessionManager：本地 Agent session 管理服务。
+ * AgentSessions：本地 Agent session 集合入口。
  *
  * 关键点（中文）
- * - 统一管理 session 缓存、创建、恢复、默认配置注入与 session collection。
+ * - 统一管理 session 缓存、创建、恢复、默认配置注入与列表查询。
  * - 该服务只负责 session 生命周期与查询，不负责 plugin / RPC 启停。
  * - Session 对象创建细节集中在这里，避免 facade 和 lifecycle 重复依赖 Session 构造逻辑。
  */
@@ -22,7 +22,7 @@ import type {
   AgentManagedSession,
   AgentModel,
   AgentSession,
-  AgentSessionCollection,
+  AgentSessions as AgentSessionsApi,
   AgentSessionConstructor,
   AgentSessionSummaryPage,
   AgentSessionSystemBlock,
@@ -48,7 +48,7 @@ function decodeMaybe(input: string): string {
   }
 }
 
-type AgentSessionManagerOptions = {
+type AgentSessionsOptions = {
   /**
    * 当前 agent 稳定标识。
    */
@@ -106,22 +106,21 @@ type AgentSessionManagerOptions = {
 /**
  * 本地 Agent session 管理服务。
  */
-export class AgentSessionManager {
+export class AgentSessions implements AgentSessionsApi<AgentSession> {
   private readonly agent_id: string;
   private readonly project_root: string;
   private readonly tools: Record<string, Tool>;
   private readonly logger: Logger;
-  private readonly get_agent_context: AgentSessionManagerOptions["get_agent_context"];
-  private readonly get_instruction: AgentSessionManagerOptions["get_instruction"];
+  private readonly get_agent_context: AgentSessionsOptions["get_agent_context"];
+  private readonly get_instruction: AgentSessionsOptions["get_instruction"];
   private readonly plugin_instances: Map<string, Plugin>;
-  private readonly ensure_agent_ready: AgentSessionManagerOptions["ensure_agent_ready"];
+  private readonly ensure_agent_ready: AgentSessionsOptions["ensure_agent_ready"];
   private readonly default_model?: AgentModel;
   private readonly SessionClass: AgentSessionConstructor;
   private readonly sessions_by_id = new Map<string, AgentManagedSession>();
   private readonly configured_session_ids = new Set<string>();
-  private readonly session_collection: AgentSessionCollection;
 
-  constructor(options: AgentSessionManagerOptions) {
+  constructor(options: AgentSessionsOptions) {
     this.agent_id = options.agent_id;
     this.project_root = options.project_root;
     this.tools = options.tools;
@@ -132,14 +131,6 @@ export class AgentSessionManager {
     this.ensure_agent_ready = options.ensure_agent_ready;
     this.default_model = options.default_model;
     this.SessionClass = options.SessionClass || Session;
-    this.session_collection = {
-      create_session: async (input) => await this.create_session(input),
-      get_session: async (session_id) => await this.get_session(session_id),
-      list_sessions: async (input) => await this.list_sessions(input),
-      archive_session: async (input) => await this.archive_session(input),
-      archive_sessions: async (input) => await this.archive_sessions(input),
-      clean_archive: async () => await this.clean_archive(),
-    };
   }
 
   /**
@@ -149,13 +140,6 @@ export class AgentSessionManager {
     return [...this.sessions_by_id.values()];
   }
 
-  /**
-   * 返回对外暴露的 session collection。
-   */
-  get_session_collection(): AgentSessionCollection {
-    return this.session_collection;
-  }
-
   /**
    * 获取或创建一个 session runtime port。
    */
@@ -168,7 +152,7 @@ export class AgentSessionManager {
   /**
    * 新建一个 session。
    */
-  async create_session(
+  async create(
     input?: AgentCreateSessionInput,
   ): Promise<AgentSession> {
     const explicit_session_id =
@@ -197,10 +181,10 @@ export class AgentSessionManager {
   /**
    * 获取一个已存在的 session。
    */
-  async get_session(session_id: string): Promise<AgentSession> {
+  async get(session_id: string): Promise<AgentSession> {
     const resolved_session_id = String(session_id || "").trim();
     if (!resolved_session_id) {
-      throw new Error("get_session requires a non-empty sessionId");
+      throw new Error("sessions.get requires a non-empty sessionId");
     }
     const session_dir_path = getSdkAgentSessionDirPath(
       this.project_root,
@@ -224,7 +208,7 @@ export class AgentSessionManager {
   /**
    * 列出当前 agent 的 session 摘要页。
    */
-  async list_sessions(
+  async list(
     input?: AgentListSessionsInput,
   ): Promise<AgentSessionSummaryPage> {
     return await listAgentSessionSummaryPage({
@@ -238,12 +222,12 @@ export class AgentSessionManager {
   /**
    * 归档单个 session。
    */
-  async archive_session(
+  async archive(
     input: AgentArchiveSessionInput,
   ): Promise<AgentArchiveSessionResult> {
     const session_id = String(input?.id || "").trim();
     if (!session_id) {
-      throw new Error("archive_session requires a non-empty id");
+      throw new Error("sessions.archive requires a non-empty id");
     }
 
     const executing_session_ids = new Set(
@@ -290,7 +274,7 @@ export class AgentSessionManager {
   /**
    * 列出当前 agent 的已归档 session 摘要页。
    */
-  async archive_sessions(
+  async archived(
     input?: AgentArchiveSessionsInput,
   ): Promise<AgentArchiveSessionsResult> {
     return await listArchivedAgentSessionSummaryPage({

package/src/agent/remote/RemoteAgent.ts

@@ -8,7 +8,15 @@
  */
 
 import type {
-  AgentSessionCollection,
+  AgentArchiveSessionInput,
+  AgentArchiveSessionsInput,
+  AgentArchiveSessionResult,
+  AgentArchiveSessionsResult,
+  AgentCleanArchiveResult,
+  AgentCreateSessionInput,
+  AgentListSessionsInput,
+  AgentSessionSummaryPage,
+  AgentSessions,
   RemoteAgentPluginActionInput,
   RemoteAgentPluginActionResult,
   RemoteAgentOptions,
@@ -30,6 +38,8 @@ import { create_remote_agent_transport } from "@/agent/remote/TransportFactory.j
  * RemoteAgent：远程 Agent 客户端。
  */
 export class RemoteAgent {
+  readonly sessions: AgentSessions<RemoteAgentSession>;
+
   private readonly transport: RemoteAgentTransport;
 
   constructor(options: RemoteAgentOptions) {
@@ -38,6 +48,7 @@ export class RemoteAgent {
       throw new Error("RemoteAgent requires a non-empty url");
     }
     this.transport = create_remote_agent_transport(url, options.token);
+    this.sessions = new RemoteAgentSessions(this.transport);
   }
 
   /**
@@ -121,27 +132,51 @@ export class RemoteAgent {
     await this.transport.close?.();
   }
 
-  /**
-   * 返回当前远程 session collection 入口。
-   *
-   * 关键点（中文）
-   * - `RemoteAgentTransport` 只负责协议传输，不直接等价于 `AgentSessionCollection`。
-   * - 这里把 transport 包装为 `AgentSessionCollection`，`create_session` / `get_session` 返回 `RemoteSession` 实例。
-   */
-  session_collection(): AgentSessionCollection {
-    return {
-     create_session: async (input) => {
-       const info = await this.transport.create_session(input);
-        return new RemoteSession(this.transport, info);
-      },
-      get_session: async (session_id) => {
-        const info = await this.transport.get_info(session_id);
-        return new RemoteSession(this.transport, info);
-      },
-      list_sessions: async (input) => await this.transport.list_sessions(input),
-      archive_session: async (input) => await this.transport.archive_session(input),
-      archive_sessions: async (input) => await this.transport.archive_sessions(input),
-      clean_archive: async () => await this.transport.clean_archive(),
-    };
+}
+
+/**
+ * 远程 Agent session 集合入口。
+ *
+ * 关键点（中文）
+ * - `RemoteAgentTransport` 只负责协议传输，不直接暴露为用户 SDK API。
+ * - 这里把远程传输包装成和本地 `agent.sessions` 一致的方法命名。
+ */
+class RemoteAgentSessions implements AgentSessions<RemoteAgentSession> {
+  private readonly transport: RemoteAgentTransport;
+
+  constructor(transport: RemoteAgentTransport) {
+    this.transport = transport;
+  }
+
+  /** 新建一个远程 session。 */
+  async create(input?: AgentCreateSessionInput): Promise<RemoteAgentSession> {
+    const info = await this.transport.create_session(input);
+    return new RemoteSession(this.transport, info);
+  }
+
+  /** 获取一个远程 session。 */
+  async get(session_id: string): Promise<RemoteAgentSession> {
+    const info = await this.transport.get_info(session_id);
+    return new RemoteSession(this.transport, info);
+  }
+
+  /** 列出远程 session 摘要页。 */
+  async list(input?: AgentListSessionsInput): Promise<AgentSessionSummaryPage> {
+    return await this.transport.list_sessions(input);
+  }
+
+  /** 归档一个远程 session。 */
+  async archive(input: AgentArchiveSessionInput): Promise<AgentArchiveSessionResult> {
+    return await this.transport.archive_session(input);
+  }
+
+  /** 列出远程已归档 session。 */
+  async archived(input?: AgentArchiveSessionsInput): Promise<AgentArchiveSessionsResult> {
+    return await this.transport.archive_sessions(input);
+  }
+
+  /** 永久清空远程已归档 session。 */
+  async clean_archive(): Promise<AgentCleanArchiveResult> {
+    return await this.transport.clean_archive();
   }
 }

package/src/agent/remote/RemoteSession.ts

@@ -7,14 +7,14 @@
  */
 
 import type {
-  AgentSession,
   AgentSessionConfigSnapshot,
   AgentSessionForkInput,
-  AgentSessionHistoryInput,
-  AgentSessionHistoryPage,
+  AgentSessionRecordsInput,
+  AgentSessionRecordsPage,
   AgentSessionInfo,
   AgentSessionSetInput,
   AgentSessionSystemSnapshot,
+  RemoteAgentSession,
 } from "@/types/agent/AgentTypes.js";
 import { isAgentSessionPromptInputEmpty } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
@@ -53,7 +53,7 @@ type RemoteTurnLifecycle = {
 /**
  * 远程 Session 客户端。
  */
-export class RemoteSession implements AgentSession {
+export class RemoteSession implements RemoteAgentSession {
   readonly id: string;
   readonly agentId: string;
   readonly config: AgentSessionConfigSnapshot;
@@ -87,7 +87,7 @@ export class RemoteSession implements AgentSession {
   /**
    * 读取当前远程 session 详情。
    */
-  async getInfo(): Promise<AgentSessionInfo> {
+  async get_info(): Promise<AgentSessionInfo> {
     return await this.transport.get_info(this.id);
   }
 
@@ -135,8 +135,8 @@ export class RemoteSession implements AgentSession {
   /**
    * 读取远程消息历史。
    */
-  async history(input?: AgentSessionHistoryInput): Promise<AgentSessionHistoryPage> {
-    return await this.transport.history(this.id, input);
+  async records(input?: AgentSessionRecordsInput): Promise<AgentSessionRecordsPage> {
+    return await this.transport.records(this.id, input);
   }
 
   /**
@@ -149,7 +149,7 @@ export class RemoteSession implements AgentSession {
   /**
    * 分叉远程 session。
    */
-  async fork(input?: AgentSessionForkInput | string): Promise<AgentSession> {
+  async fork(input?: AgentSessionForkInput | string): Promise<RemoteAgentSession> {
     const info = await this.transport.fork(this.id, input);
     return new RemoteSession(this.transport, info);
   }
@@ -296,6 +296,8 @@ function extract_turn_id(event: AgentSessionEvent): string | null {
     case "assistant-step":
     case "turn-finish":
       return event.turnId;
+    case "action":
+      return event.metadata.turnId || null;
     default:
       return null;
   }

package/src/agent/remote/RemoteTransport.ts

@@ -15,8 +15,8 @@ import type {
   AgentArchiveSessionsResult,
   AgentCleanArchiveResult,
   AgentSessionForkInput,
-  AgentSessionHistoryInput,
-  AgentSessionHistoryPage,
+  AgentSessionRecordsInput,
+  AgentSessionRecordsPage,
   AgentSessionInfo,
   AgentSessionSummaryPage,
   AgentSessionSystemSnapshot,
@@ -63,10 +63,10 @@ export type RemoteSessionTransport = {
     on_event: (event: AgentSessionEvent) => void;
   }): Promise<TransportSubscription>;
   /** 读取 history。 */
-  history(
+  records(
     session_id: string,
-    input?: AgentSessionHistoryInput,
-  ): Promise<AgentSessionHistoryPage>;
+    input?: AgentSessionRecordsInput,
+  ): Promise<AgentSessionRecordsPage>;
   /** 读取 system snapshot。 */
   system(session_id: string): Promise<AgentSessionSystemSnapshot>;
   /** 分叉 session。 */

package/src/agent/remote/transports/HttpRemoteAgentTransport.ts

@@ -15,8 +15,8 @@ import type {
   AgentArchiveSessionsResult,
   AgentCleanArchiveResult,
   AgentSessionForkInput,
-  AgentSessionHistoryInput,
-  AgentSessionHistoryPage,
+  AgentSessionRecordsInput,
+  AgentSessionRecordsPage,
   AgentSessionInfo,
   AgentSessionSummaryPage,
   AgentSessionSystemSnapshot,
@@ -184,10 +184,10 @@ export class HttpRemoteAgentTransport implements RemoteAgentTransport {
     };
   }
 
-  async history(
+  async records(
     session_id: string,
-    input?: AgentSessionHistoryInput,
-  ): Promise<AgentSessionHistoryPage> {
+    input?: AgentSessionRecordsInput,
+  ): Promise<AgentSessionRecordsPage> {
     const query = new URLSearchParams();
     if (input?.limit !== undefined) query.set("limit", String(input.limit));
     if (input?.cursor) query.set("cursor", input.cursor);
@@ -197,19 +197,19 @@ export class HttpRemoteAgentTransport implements RemoteAgentTransport {
     const payload = await read_http_json<{
       success?: boolean;
       error?: string;
-      history?: AgentSessionHistoryPage;
+      records?: AgentSessionRecordsPage;
     }>(
-      `${this.base_url}/api/sdk/sessions/${encodeURIComponent(session_id)}/history${
+      `${this.base_url}/api/sdk/sessions/${encodeURIComponent(session_id)}/records${
         query.size > 0 ? `?${query.toString()}` : ""
       }`,
       {
         headers: this.headers(),
       },
     );
-    if (!payload.success || !payload.history || !Array.isArray(payload.history.items)) {
-      throw new Error(String(payload.error || "Remote session history failed"));
+    if (!payload.success || !payload.records || !Array.isArray(payload.records.items)) {
+      throw new Error(String(payload.error || "Remote session records failed"));
     }
-    return payload.history;
+    return payload.records;
   }
 
   async system(session_id: string): Promise<AgentSessionSystemSnapshot> {

package/src/agent/remote/transports/RpcRemoteAgentTransport.ts

@@ -15,8 +15,8 @@ import type {
   AgentArchiveSessionsResult,
   AgentCleanArchiveResult,
   AgentSessionForkInput,
-  AgentSessionHistoryInput,
-  AgentSessionHistoryPage,
+  AgentSessionRecordsInput,
+  AgentSessionRecordsPage,
   AgentSessionInfo,
   AgentSessionSummaryPage,
   AgentSessionSystemSnapshot,
@@ -89,11 +89,11 @@ export class RpcRemoteAgentTransport implements RemoteAgentTransport {
     };
   }
 
-  async history(
+  async records(
     session_id: string,
-    input?: AgentSessionHistoryInput,
-  ): Promise<AgentSessionHistoryPage> {
-    return await this.client.get_session_history({
+    input?: AgentSessionRecordsInput,
+  ): Promise<AgentSessionRecordsPage> {
+    return await this.client.get_session_records({
       session_id,
       input,
     });

package/src/executor/Executor.ts

@@ -25,10 +25,13 @@ import { ExecutorRecoveryPolicy } from "@executor/services/ExecutorRecoveryPolic
 import { generateId } from "@/utils/Id.js";
 import type { Logger } from "@/utils/logger/Logger.js";
 import type { JsonObject } from "@/types/common/Json.js";
-import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+import type {
+  SessionActionRecordV1,
+  SessionRecordV1,
+} from "@/executor/types/SessionRecords.js";
+import { to_session_action_record } from "@/executor/types/SessionRecords.js";
 import type { SessionExecutor } from "@/executor/types/SessionExecutor.js";
 import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
-import type { AgentSessionOperationRecord } from "@/types/sdk/AgentSessionOperation.js";
 import type {
   SessionExecuteInput,
   SessionRunResult,
@@ -212,23 +215,23 @@ export class Executor implements SessionExecutor {
   /**
    * 追加一条 user 消息。
    */
-  async appendUserMessage(params: {
-    message?: SessionMessageV1 | null;
+  async append_user_message(params: {
+    message?: SessionRecordV1 | null;
     text?: string;
     extra?: JsonObject;
   }): Promise<void> {
-    await this.historyWriter.appendUserMessage(params);
+    await this.historyWriter.append_user_message(params);
   }
 
   /**
    * 追加一条 assistant 消息。
    */
-  async appendAssistantMessage(params: {
-    message?: SessionMessageV1 | null;
+  async append_assistant_message(params: {
+    message?: SessionRecordV1 | null;
     fallbackText?: string;
     extra?: JsonObject;
   }): Promise<void> {
-    await this.historyWriter.appendAssistantMessage(params);
+    await this.historyWriter.append_assistant_message(params);
   }
 
   /**
@@ -362,7 +365,7 @@ export class Executor implements SessionExecutor {
     const composed_context = await this.contextComposer.compose(run_context);
     const tools = this.bind_run_scope_to_tools(composed_context.tools, run_context);
     const system = await this.systemComposer.resolve(run_context);
-    let compaction_operation_id = "";
+    let compaction_action_id = "";
 
     try {
       if (retry_count > 0) {
@@ -371,13 +374,13 @@ export class Executor implements SessionExecutor {
         });
       }
 
-      const emit_compaction_operation = async (
-        operation: AgentSessionOperationRecord,
+      const emit_compaction_action = async (
+        action: SessionActionRecordV1,
       ): Promise<void> => {
-        if (operation.status === "started") {
-          compaction_operation_id = operation.operationId;
+        if (action.state === "running") {
+          compaction_action_id = action.id;
         }
-        await this.emitOperation(run_context, operation);
+        await this.emitAction(run_context, action);
       };
 
       await this.compactionComposer.run({
@@ -385,18 +388,22 @@ export class Executor implements SessionExecutor {
         model,
         system,
         retryCount: retry_count,
-        onOperation: emit_compaction_operation,
+        onAction: emit_compaction_action,
       });
     } catch (error) {
-      await this.emitOperation(run_context, {
-        operationId:
-          compaction_operation_id ||
+      await this.emitAction(run_context, {
+        type: "action",
+        id:
+          compaction_action_id ||
           `compacting:${this.sessionId}:failed:${Date.now()}:${generateId()}`,
-        name: "compacting",
-        status: "failed",
-        label: "Session history compact failed",
-        error: error instanceof Error ? error.message : String(error),
-        visible: false,
+        title: "Session records compact failed",
+        description: error instanceof Error ? error.message : String(error),
+        state: "failed",
+        metadata: {
+          v: 1,
+          ts: Date.now(),
+          sessionId: this.sessionId,
+        },
       });
       // 压缩失败不阻断主流程，继续使用当前历史消息执行。
     }
@@ -492,8 +499,8 @@ export class Executor implements SessionExecutor {
       ...(typeof input?.onUiMessageChunkCallback === "function"
         ? { onUiMessageChunkCallback: input.onUiMessageChunkCallback }
         : {}),
-      ...(typeof input?.onOperationCallback === "function"
-        ? { onOperationCallback: input.onOperationCallback }
+      ...(typeof input?.onActionCallback === "function"
+        ? { onActionCallback: input.onActionCallback }
         : {}),
       ...(input?.abortSignal ? { abortSignal: input.abortSignal } : {}),
       injectedUserMessages: Array.isArray(input?.injectedUserMessages)
@@ -511,25 +518,28 @@ export class Executor implements SessionExecutor {
   }
 
   /**
-   * 发布一次 session operation。
+   * 发布一次 session action。
    */
-  private async emitOperation(
+  private async emitAction(
     run_context: SessionRunContext,
-    operation: AgentSessionOperationRecord,
+    action: SessionActionRecordV1,
   ): Promise<void> {
-    if (typeof run_context.onOperationCallback !== "function") return;
-    const operation_id =
-      String(operation.operationId || "").trim() ||
-      `operation:${this.sessionId}:${Date.now()}:${generateId()}`;
-    await run_context.onOperationCallback({
-      type: "operation",
-      sessionId: run_context.sessionId || this.sessionId,
-      ...operation,
-      operationId: operation_id,
-      ...(run_context.turnId && !operation.turnId
-        ? { turnId: run_context.turnId }
-        : {}),
-    });
+    if (typeof run_context.onActionCallback !== "function") return;
+    const action_id =
+      String(action.id || "").trim() ||
+      `action:${this.sessionId}:${Date.now()}:${generateId()}`;
+    const event = to_session_action_record({
+      ...action,
+      id: action_id,
+      metadata: {
+        ...action.metadata,
+        sessionId: run_context.sessionId || this.sessionId,
+        ...(run_context.turnId && !action.metadata.turnId
+          ? { turnId: run_context.turnId }
+          : {}),
+      },
+    }, run_context.sessionId || this.sessionId);
+    await run_context.onActionCallback(event);
   }
 
   /**

package/src/executor/SessionRunScope.ts

@@ -1,6 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { FileUIPart } from "ai";
-import type { SessionUserMessageV1 } from "@/executor/types/SessionMessages.js";
+import type { SessionUserMessageV1 } from "@/executor/types/SessionRecords.js";
 import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
 
 /**

package/src/executor/composer/compaction/SessionCompactionComposer.ts

@@ -8,7 +8,7 @@
 
 import type { LanguageModel, SystemModelMessage } from "ai";
 import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
-import type { AgentSessionOperationRecord } from "@/types/sdk/AgentSessionOperation.js";
+import type { SessionActionRecordV1 } from "@/executor/types/SessionRecords.js";
 
 /**
  * compaction Composer 执行输入。
@@ -35,13 +35,13 @@ export type SessionCompactionInput = {
   retryCount: number;
 
   /**
-   * 可选 operation 发布回调。
+   * 可选 action 发布回调。
    *
    * 说明（中文）
-   * - 默认 compaction Composer 可在真正开始压缩时发布 `compacting`。
-   * - 回调由上层 Session 负责转成订阅事件与 operation message。
+   * - 默认 compaction Composer 可在真正开始压缩时发布 action。
+   * - 回调由上层 Session 负责转成订阅事件与 action record。
    */
-  onOperation?: (operation: AgentSessionOperationRecord) => Promise<void>;
+  onAction?: (action: SessionActionRecordV1) => Promise<void>;
 };
 
 /**

package/src/executor/composer/compaction/jsonl/JsonlSessionCompactionComposer.ts

@@ -79,7 +79,7 @@ export class JsonlSessionCompactionComposer implements SessionCompactionComposer
       maxInputTokensApprox: policy.maxInputTokensApprox,
       archiveOnCompact: policy.archiveOnCompact,
       compactRatio: policy.compactRatio,
-      ...(input.onOperation ? { onOperation: input.onOperation } : {}),
+      ...(input.onAction ? { onAction: input.onAction } : {}),
     });
   }