@downcity/agent 1.1.32 → 1.1.35

package/src/sdk/Session.ts

@@ -9,25 +9,30 @@
 
 import { nanoid } from "nanoid";
 import type { Tool } from "ai";
-import { Executor } from "@session/Executor.js";
-import { JsonlSessionHistoryComposer } from "@session/composer/history/jsonl/JsonlSessionHistoryComposer.js";
-import { JsonlSessionHistoryStore } from "@/session/store/history/jsonl/JsonlSessionHistoryStore.js";
+import { Executor } from "@executor/Executor.js";
+import { JsonlSessionHistoryComposer } from "@executor/composer/history/jsonl/JsonlSessionHistoryComposer.js";
+import { JsonlSessionHistoryStore } from "@/executor/store/history/jsonl/JsonlSessionHistoryStore.js";
 import { extractTextFromUiMessage } from "@/plugin/builtins/chat/runtime/UIMessageTransformer.js";
 import type {
+  AgentSession,
+  AgentSessionHistoryInput,
+  AgentSessionHistoryPage,
   AgentSessionConfigSnapshot,
   AgentSessionForkInput,
-  AgentSessionMetadata,
+  AgentSessionInfo,
   AgentSessionSetInput,
   AgentSessionSystemBlock,
   AgentSessionSystemSnapshot,
 } from "@/sdk/AgentSdkTypes.js";
-import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
+import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
 import {
   buildSessionSystemBlocks,
   SessionSystemBuilder,
 } from "@/sdk/SessionSystemBuilder.js";
 import {
   inferModelLabel,
+  buildSessionHistoryPage,
+  buildSessionInfo,
   patchSessionModelLabel,
   readSessionMetadata,
   resolveSystemTimezone,
@@ -47,14 +52,14 @@ import {
   touchSessionMetadata,
 } from "@/sdk/session/index.js";
 import { createRuntimeSessionPort } from "@/sdk/session/index.js";
-import { drainDeferredPersistedUserMessages } from "@session/SessionRunScope.js";
+import { drainDeferredPersistedUserMessages } from "@executor/SessionRunScope.js";
 import type {
   AgentSessionSubscriber,
   AgentSessionUnsubscribe,
 } from "@/types/sdk/AgentSessionEvent.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
-import type { SessionUserMessageV1 } from "@/session/types/SessionMessages.js";
+import type { SessionUserMessageV1 } from "@/executor/types/SessionMessages.js";
 import { SessionEventHub } from "@/sdk/session/runtime/SessionEventHub.js";
 import { SessionPromptRuntime } from "@/sdk/session/runtime/SessionPromptRuntime.js";
 
@@ -93,9 +98,9 @@ type SessionOptions = {
   getInstructionSystemBlocks: () => AgentSessionSystemBlock[];
 
   /**
-   * 读取当前 agent 显式注入 runtime plugin 的 system blocks。
+   * 读取当前 agent 显式注入的受托管 plugin system blocks。
    */
-  getRuntimePluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
+  getManagedPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
 
   /**
    * 读取当前 agent 显式注册 plugin 的 system blocks。
@@ -107,7 +112,7 @@ type SessionOptions = {
    *
    * 关键点（中文）
    * - 这里通常由 `AgentCore` 注入，用于补齐默认 model、宿主覆写等一次性装配。
-   * - 所有执行入口都应通过这里兜底，避免只在 SDK `agent.session()` 链路上做配置。
+   * - 所有执行入口都应通过这里兜底，避免只在 SDK `agent.createSession()` / `agent.getSession()` 链路上做配置。
    */
   ensureConfigured?: (session: Session) => Promise<void>;
 };
@@ -115,7 +120,7 @@ type SessionOptions = {
 /**
  * SDK 本地 Session。
  */
-export class Session {
+export class Session implements AgentSession {
   readonly id: string;
   readonly agentId: string;
 
@@ -123,7 +128,7 @@ export class Session {
   private readonly tools: Record<string, Tool>;
   private readonly logger: SessionOptions["logger"];
   private readonly getInstructionSystemBlocks: SessionOptions["getInstructionSystemBlocks"];
-  private readonly getRuntimePluginSystemBlocks: SessionOptions["getRuntimePluginSystemBlocks"];
+  private readonly getManagedPluginSystemBlocks: SessionOptions["getManagedPluginSystemBlocks"];
   private readonly getPluginSystemBlocks: SessionOptions["getPluginSystemBlocks"];
   private readonly ensureConfiguredHook?: SessionOptions["ensureConfigured"];
   private readonly historyStore: JsonlSessionHistoryStore;
@@ -145,7 +150,7 @@ export class Session {
     this.tools = options.tools;
     this.logger = options.logger;
     this.getInstructionSystemBlocks = options.getInstructionSystemBlocks;
-    this.getRuntimePluginSystemBlocks = options.getRuntimePluginSystemBlocks;
+    this.getManagedPluginSystemBlocks = options.getManagedPluginSystemBlocks;
     this.getPluginSystemBlocks = options.getPluginSystemBlocks;
     this.ensureConfiguredHook = options.ensureConfigured;
     if (!this.id) {
@@ -196,7 +201,7 @@ export class Session {
         getSessionCreatedAt: () => this.createdAt,
         getSessionTimezone: () => this.timezone,
         getInstructionSystemBlocks: this.getInstructionSystemBlocks,
-        getRuntimePluginSystemBlocks: this.getRuntimePluginSystemBlocks,
+        getManagedPluginSystemBlocks: this.getManagedPluginSystemBlocks,
         getPluginSystemBlocks: this.getPluginSystemBlocks,
       }),
       getTools: () => this.tools,
@@ -347,10 +352,40 @@ export class Session {
   }
 
   /**
-   * 读取完整消息历史。
+   * 读取当前 session 详情。
    */
-  async history(): Promise<SessionMessageV1[]> {
-    return await this.historyStore.list();
+  async getInfo(): Promise<AgentSessionInfo> {
+    const [metadata, messages] = await Promise.all([
+      readSessionMetadata({
+        projectRoot: this.projectRoot,
+        agentId: this.agentId,
+        sessionId: this.id,
+      }),
+      this.historyStore.list(),
+    ]);
+    return buildSessionInfo({
+      projectRoot: this.projectRoot,
+      agentId: this.agentId,
+      sessionId: this.id,
+      metadata,
+      messages,
+      executing: this.isExecuting(),
+    });
+  }
+
+  /**
+   * 读取当前 session 历史分页。
+   */
+  async history(input?: AgentSessionHistoryInput): Promise<AgentSessionHistoryPage> {
+    const [session, messages] = await Promise.all([
+      this.getInfo(),
+      this.historyStore.list(),
+    ]);
+    return buildSessionHistoryPage({
+      session,
+      messages,
+      input,
+    });
   }
 
   /**
@@ -358,7 +393,7 @@ export class Session {
    *
    * 关键点（中文）
    * - 返回内容与实际 run 时使用的 SDK system composer 同源。
-   * - 包含 instruction/core、显式注入 runtime plugin system、显式注册 plugin system 与 session 上下文。
+   * - 包含 instruction/core、受托管 plugin system、显式注册 plugin system 与 session 上下文。
    * - 返回结构化快照，不把 system prompt 写入会话历史。
    */
   async system(): Promise<AgentSessionSystemSnapshot> {
@@ -369,7 +404,7 @@ export class Session {
       createdAt: this.createdAt,
       timezone: this.timezone,
       getInstructionSystemBlocks: this.getInstructionSystemBlocks,
-      getRuntimePluginSystemBlocks: this.getRuntimePluginSystemBlocks,
+      getManagedPluginSystemBlocks: this.getManagedPluginSystemBlocks,
       getPluginSystemBlocks: this.getPluginSystemBlocks,
     });
     return {
@@ -402,8 +437,11 @@ export class Session {
   /**
    * 从当前 session 创建一个分叉会话。
    */
-  async fork(input?: AgentSessionForkInput["messageId"]): Promise<Session> {
-    const messageId = String(input || "").trim() || undefined;
+  async fork(input?: AgentSessionForkInput | string): Promise<Session> {
+    const messageId =
+      typeof input === "string"
+        ? String(input || "").trim() || undefined
+        : String(input?.messageId || "").trim() || undefined;
     const messages = await this.historyStore.list();
     const forkMessages =
       !messageId
@@ -427,7 +465,7 @@ export class Session {
       tools: this.tools,
       logger: this.logger,
       getInstructionSystemBlocks: this.getInstructionSystemBlocks,
-      getRuntimePluginSystemBlocks: this.getRuntimePluginSystemBlocks,
+      getManagedPluginSystemBlocks: this.getManagedPluginSystemBlocks,
       getPluginSystemBlocks: this.getPluginSystemBlocks,
     });
     await forked.initialize();
@@ -444,27 +482,7 @@ export class Session {
   }
 
   /**
-   * 生成当前 session 的元数据快照。
-   */
-  async toMetadata(): Promise<AgentSessionMetadata> {
-    const meta = await readSessionMetadata({
-      projectRoot: this.projectRoot,
-      agentId: this.agentId,
-      sessionId: this.id,
-    });
-    const messageCount = await this.historyStore.size();
-    return {
-      agentId: this.agentId,
-      sessionId: this.id,
-      messageCount,
-      ...(typeof meta.createdAt === "number" ? { createdAt: meta.createdAt } : {}),
-      ...(typeof meta.updatedAt === "number" ? { updatedAt: meta.updatedAt } : {}),
-      ...(meta.sdkConfig?.modelLabel ? { modelLabel: meta.sdkConfig.modelLabel } : {}),
-    };
-  }
-
-  /**
-   * 返回供 runtime plugin 使用的 session 端口。
+   * 返回供受托管 plugin 使用的 session 端口。
    */
   getRuntimePort(): SessionPort {
     if (this.runtimePort) return this.runtimePort;

package/src/sdk/SessionSystemBuilder.ts

@@ -3,13 +3,13 @@
  *
  * 关键点（中文）
  * - 面向 `Agent` SDK 的本地会话执行场景。
- * - 注入调用方显式传入的静态 instruction、显式注入 runtime plugin system 与显式注册 plugin system。
+ * - 注入调用方显式传入的静态 instruction、受托管 plugin system 与显式注册 plugin system。
  * - SDK 不在 system 中注入动态变量；动态上下文应由调用方放入 user message。
  */
 
-import type { SessionSystemComposer } from "@session/composer/system/SessionSystemComposer.js";
-import { getSessionRunScope } from "@session/SessionRunScope.js";
-import type { SessionSystemMessage } from "@/session/types/SessionPrompts.js";
+import type { SessionSystemComposer } from "@executor/composer/system/SessionSystemComposer.js";
+import { getSessionRunScope } from "@executor/SessionRunScope.js";
+import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
 import type {
   AgentSessionSystemBlock,
   AgentSessionSystemSessionInfo,
@@ -50,9 +50,9 @@ export interface BuildSessionSystemBlocksParams {
   getInstructionSystemBlocks: () => AgentSessionSystemBlock[];
 
   /**
-   * 读取当前显式注入 runtime plugin 的 system blocks。
+   * 读取当前显式注入的受托管 plugin system blocks。
    */
-  getRuntimePluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
+  getManagedPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
 
   /**
    * 读取当前显式注册 plugin 的 system blocks。
@@ -92,9 +92,9 @@ type SessionSystemBuilderOptions = {
   getPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
 
   /**
-   * 读取当前显式注入 runtime plugin 的 system blocks。
+   * 读取当前显式注入的受托管 plugin system blocks。
    */
-  getRuntimePluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
+  getManagedPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
 };
 
 function normalizeSystemBlocks(
@@ -185,7 +185,7 @@ export async function buildSessionSystemBlocks(
   }
   return [
     ...normalizeSystemBlocks(params.getInstructionSystemBlocks()),
-    ...normalizeSystemBlocks(await params.getRuntimePluginSystemBlocks()),
+    ...normalizeSystemBlocks(await params.getManagedPluginSystemBlocks()),
     ...normalizeSystemBlocks(await params.getPluginSystemBlocks()),
     // session block 放在最后，尽量保留前缀 system blocks 的跨 session 缓存命中。
     createSessionSystemBlock(
@@ -218,7 +218,7 @@ export class SessionSystemBuilder implements SessionSystemComposer {
   private readonly getSessionCreatedAt: SessionSystemBuilderOptions["getSessionCreatedAt"];
   private readonly getSessionTimezone: SessionSystemBuilderOptions["getSessionTimezone"];
   private readonly getInstructionSystemBlocks: SessionSystemBuilderOptions["getInstructionSystemBlocks"];
-  private readonly getRuntimePluginSystemBlocks: SessionSystemBuilderOptions["getRuntimePluginSystemBlocks"];
+  private readonly getManagedPluginSystemBlocks: SessionSystemBuilderOptions["getManagedPluginSystemBlocks"];
   private readonly getPluginSystemBlocks: SessionSystemBuilderOptions["getPluginSystemBlocks"];
 
   constructor(options: SessionSystemBuilderOptions) {
@@ -227,7 +227,7 @@ export class SessionSystemBuilder implements SessionSystemComposer {
     this.getSessionCreatedAt = options.getSessionCreatedAt;
     this.getSessionTimezone = options.getSessionTimezone;
     this.getInstructionSystemBlocks = options.getInstructionSystemBlocks;
-    this.getRuntimePluginSystemBlocks = options.getRuntimePluginSystemBlocks;
+    this.getManagedPluginSystemBlocks = options.getManagedPluginSystemBlocks;
     this.getPluginSystemBlocks = options.getPluginSystemBlocks;
     if (!this.agentId) {
       throw new Error("SessionSystemBuilder requires a non-empty agentId");
@@ -252,7 +252,7 @@ export class SessionSystemBuilder implements SessionSystemComposer {
       createdAt: this.getSessionCreatedAt(),
       timezone: this.getSessionTimezone(),
       getInstructionSystemBlocks: this.getInstructionSystemBlocks,
-      getRuntimePluginSystemBlocks: this.getRuntimePluginSystemBlocks,
+      getManagedPluginSystemBlocks: this.getManagedPluginSystemBlocks,
       getPluginSystemBlocks: this.getPluginSystemBlocks,
     });
   }