@downcity/agent 1.1.25 → 1.1.32

package/src/sdk/Session.ts

@@ -12,7 +12,7 @@ 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 { extractTextFromUiMessage } from "@/service/builtins/chat/runtime/UIMessageTransformer.js";
+import { extractTextFromUiMessage } from "@/plugin/builtins/chat/runtime/UIMessageTransformer.js";
 import type {
   AgentSessionConfigSnapshot,
   AgentSessionForkInput,
@@ -46,7 +46,8 @@ import {
   persistSdkAssistantResult,
   touchSessionMetadata,
 } from "@/sdk/session/index.js";
-import { createSessionServicePort } from "@/sdk/session/index.js";
+import { createRuntimeSessionPort } from "@/sdk/session/index.js";
+import { drainDeferredPersistedUserMessages } from "@session/SessionRunScope.js";
 import type {
   AgentSessionSubscriber,
   AgentSessionUnsubscribe,
@@ -56,10 +57,6 @@ import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
 import type { SessionUserMessageV1 } from "@/session/types/SessionMessages.js";
 import { SessionEventHub } from "@/sdk/session/runtime/SessionEventHub.js";
 import { SessionPromptRuntime } from "@/sdk/session/runtime/SessionPromptRuntime.js";
-import type {
-  SessionAssistantStepCallback,
-  SessionUiMessageChunkCallback,
-} from "@/session/types/SessionRun.js";
 
 type SessionOptions = {
   /**
@@ -96,9 +93,9 @@ type SessionOptions = {
   getInstructionSystemBlocks: () => AgentSessionSystemBlock[];
 
   /**
-   * 读取当前 agent 显式注入 service 的 system blocks。
+   * 读取当前 agent 显式注入 runtime plugin 的 system blocks。
    */
-  getServiceSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
+  getRuntimePluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
 
   /**
    * 读取当前 agent 显式注册 plugin 的 system blocks。
@@ -126,7 +123,7 @@ export class Session {
   private readonly tools: Record<string, Tool>;
   private readonly logger: SessionOptions["logger"];
   private readonly getInstructionSystemBlocks: SessionOptions["getInstructionSystemBlocks"];
-  private readonly getServiceSystemBlocks: SessionOptions["getServiceSystemBlocks"];
+  private readonly getRuntimePluginSystemBlocks: SessionOptions["getRuntimePluginSystemBlocks"];
   private readonly getPluginSystemBlocks: SessionOptions["getPluginSystemBlocks"];
   private readonly ensureConfiguredHook?: SessionOptions["ensureConfigured"];
   private readonly historyStore: JsonlSessionHistoryStore;
@@ -139,8 +136,7 @@ export class Session {
   private timezone = resolveSystemTimezone();
   private initializePromise: Promise<this> | null = null;
   private ensureConfiguredPromise: Promise<void> | null = null;
-  private servicePort: SessionPort | null = null;
-  private directExecutionReserved = false;
+  private runtimePort: SessionPort | null = null;
 
   constructor(options: SessionOptions) {
     this.id = String(options.sessionId || "").trim();
@@ -149,7 +145,7 @@ export class Session {
     this.tools = options.tools;
     this.logger = options.logger;
     this.getInstructionSystemBlocks = options.getInstructionSystemBlocks;
-    this.getServiceSystemBlocks = options.getServiceSystemBlocks;
+    this.getRuntimePluginSystemBlocks = options.getRuntimePluginSystemBlocks;
     this.getPluginSystemBlocks = options.getPluginSystemBlocks;
     this.ensureConfiguredHook = options.ensureConfigured;
     if (!this.id) {
@@ -170,6 +166,7 @@ export class Session {
     const messagesDirPath = `${sessionDirPath}/messages`;
     this.historyStore = new JsonlSessionHistoryStore({
       rootPath: this.projectRoot,
+      agentId: this.agentId,
       sessionId: this.id,
       paths: {
         sessionDirPath,
@@ -199,7 +196,7 @@ export class Session {
         getSessionCreatedAt: () => this.createdAt,
         getSessionTimezone: () => this.timezone,
         getInstructionSystemBlocks: this.getInstructionSystemBlocks,
-        getServiceSystemBlocks: this.getServiceSystemBlocks,
+        getRuntimePluginSystemBlocks: this.getRuntimePluginSystemBlocks,
         getPluginSystemBlocks: this.getPluginSystemBlocks,
       }),
       getTools: () => this.tools,
@@ -209,13 +206,13 @@ export class Session {
       publish: (event) => {
         this.eventHub.publish(event);
       },
-      createAndPersistUserMessage: async (query) => {
-        return await this.createAndPersistUserPromptMessage(query);
+      createAndPersistUserMessage: async (input) => {
+        return await this.createAndPersistUserPromptMessage(input);
       },
-      executeTurn: async ({ turnId, query, onStepMerge }) => {
+      executeTurn: async ({ turnId, promptInput, onStepMerge }) => {
         return await this.executePromptTurn({
           turnId,
-          query,
+          promptInput,
           onStepMerge,
         });
       },
@@ -303,8 +300,9 @@ export class Session {
       throw new Error("session.prompt requires a non-empty query");
     }
     await this.ensureRunnable();
-    this.assertCanPrompt();
-    return await this.promptRuntime.prompt(query);
+    return await this.promptRuntime.prompt({
+      query,
+    });
   }
 
   /**
@@ -360,7 +358,7 @@ export class Session {
    *
    * 关键点（中文）
    * - 返回内容与实际 run 时使用的 SDK system composer 同源。
-   * - 包含 instruction/core、显式注入 service system、显式注册 plugin system 与 session 上下文。
+   * - 包含 instruction/core、显式注入 runtime plugin system、显式注册 plugin system 与 session 上下文。
    * - 返回结构化快照，不把 system prompt 写入会话历史。
    */
   async system(): Promise<AgentSessionSystemSnapshot> {
@@ -371,7 +369,7 @@ export class Session {
       createdAt: this.createdAt,
       timezone: this.timezone,
       getInstructionSystemBlocks: this.getInstructionSystemBlocks,
-      getServiceSystemBlocks: this.getServiceSystemBlocks,
+      getRuntimePluginSystemBlocks: this.getRuntimePluginSystemBlocks,
       getPluginSystemBlocks: this.getPluginSystemBlocks,
     });
     return {
@@ -391,11 +389,7 @@ export class Session {
    * 返回当前 session 是否正在执行。
    */
   isExecuting(): boolean {
-    return (
-      this.directExecutionReserved ||
-      this.promptRuntime.isActive() ||
-      this.executor.isExecuting()
-    );
+    return this.promptRuntime.isActive() || this.executor.isExecuting();
   }
 
   /**
@@ -433,7 +427,7 @@ export class Session {
       tools: this.tools,
       logger: this.logger,
       getInstructionSystemBlocks: this.getInstructionSystemBlocks,
-      getServiceSystemBlocks: this.getServiceSystemBlocks,
+      getRuntimePluginSystemBlocks: this.getRuntimePluginSystemBlocks,
       getPluginSystemBlocks: this.getPluginSystemBlocks,
     });
     await forked.initialize();
@@ -470,16 +464,13 @@ export class Session {
   }
 
   /**
-   * 返回供 chat service 使用的 session 端口。
+   * 返回供 runtime plugin 使用的 session 端口。
    */
-  getServicePort(): SessionPort {
-    if (this.servicePort) return this.servicePort;
-    this.servicePort = createSessionServicePort({
+  getRuntimePort(): SessionPort {
+    if (this.runtimePort) return this.runtimePort;
+    this.runtimePort = createRuntimeSessionPort({
       sessionId: this.id,
       getExecutor: () => this.executor.getExecutor(),
-      executeDirect: async (runParams) => {
-        return await this.executeDirect(runParams);
-      },
       prompt: async (input) => {
         return await this.prompt(input);
       },
@@ -507,7 +498,7 @@ export class Session {
         await this.touchMetadata();
       },
     });
-    return this.servicePort;
+    return this.runtimePort;
   }
 
   /**
@@ -540,34 +531,6 @@ export class Session {
     }
   }
 
-  private assertCanPrompt(): void {
-    if (!this.directExecutionReserved && !this.executor.isExecuting()) {
-      return;
-    }
-    if (this.promptRuntime.isActive()) {
-      return;
-    }
-    throw new Error(
-      "session.prompt cannot attach to an active direct session execution. Use prompt()/subscribe() as the public interactive API, or wait for the current execution to finish.",
-    );
-  }
-
-  private beginDirectExecution(): void {
-    if (this.promptRuntime.isActive()) {
-      throw new Error(
-        "Direct session execution cannot start while session.prompt() is active. Keep SDK-facing interactive sessions on prompt()/subscribe(), or wait for the actor turn to finish.",
-      );
-    }
-    if (this.directExecutionReserved || this.executor.isExecuting()) {
-      throw new Error("Direct session execution does not support concurrent execution on the same session.");
-    }
-    this.directExecutionReserved = true;
-  }
-
-  private endDirectExecution(): void {
-    this.directExecutionReserved = false;
-  }
-
   private async touchMetadata(): Promise<void> {
     await touchSessionMetadata({
       projectRoot: this.projectRoot,
@@ -591,10 +554,10 @@ export class Session {
   }
 
   private async createAndPersistUserPromptMessage(
-    query: string,
+    input: AgentSessionPromptInput,
   ): Promise<SessionUserMessageV1> {
     const message = this.historyStore.userText({
-      text: String(query || "").trim(),
+      text: String(input.query || "").trim(),
       metadata: {
         sessionId: this.id,
       },
@@ -608,17 +571,27 @@ export class Session {
 
   private async executePromptTurn(input: {
     turnId: string;
-    query: string;
+    promptInput: AgentSessionPromptInput;
     onStepMerge: () => Promise<SessionUserMessageV1[]>;
   }): Promise<{
     text: string;
     success: boolean;
+    assistantMessage: SessionMessageV1;
     error?: string;
   }> {
     const toolNameByCallId = new Map<string, string>();
     const result = await this.executor.run({
-      query: input.query,
+      query: input.promptInput.query,
       onStepCallback: input.onStepMerge,
+      onAssistantStepCallback: async (step) => {
+        this.eventHub.publish({
+          type: "assistant-step",
+          turnId: input.turnId,
+          text: step.text,
+          stepIndex: step.stepIndex,
+          ...(step.visibility ? { visibility: step.visibility } : {}),
+        });
+      },
       onUiMessageChunkCallback: async (chunk) => {
         if (chunk.type === "tool-input-start") {
           toolNameByCallId.set(chunk.toolCallId, chunk.toolName);
@@ -657,40 +630,24 @@ export class Session {
       },
     });
     await this.persistAssistantResult(result.assistantMessage);
+    await this.persistDeferredUserMessages();
     return {
       text: extractTextFromUiMessage(result.assistantMessage),
       success: result.success,
+      assistantMessage: result.assistantMessage,
       ...(result.error ? { error: result.error } : {}),
     };
   }
 
-  private async executeDirect(input: {
-    query: string;
-    onStepCallback?: () => Promise<SessionUserMessageV1[]>;
-    onAssistantStepCallback?: SessionAssistantStepCallback;
-    onUiMessageChunkCallback?: SessionUiMessageChunkCallback;
-  }) {
-    const query = String(input.query || "").trim();
-    if (!query) {
-      throw new Error("Session direct execution requires a non-empty query");
-    }
-    await this.ensureRunnable();
-    this.beginDirectExecution();
-    try {
-      return await this.executor.run({
-        query,
-        ...(typeof input.onStepCallback === "function"
-          ? { onStepCallback: input.onStepCallback }
-          : {}),
-        ...(typeof input.onAssistantStepCallback === "function"
-          ? { onAssistantStepCallback: input.onAssistantStepCallback }
-          : {}),
-        ...(typeof input.onUiMessageChunkCallback === "function"
-          ? { onUiMessageChunkCallback: input.onUiMessageChunkCallback }
-          : {}),
+  private async persistDeferredUserMessages(): Promise<void> {
+    const deferredMessages = drainDeferredPersistedUserMessages(this.id);
+    for (const message of deferredMessages) {
+      await this.executor.appendUserMessage({
+        message,
       });
-    } finally {
-      this.endDirectExecution();
+    }
+    if (deferredMessages.length > 0) {
+      await this.touchMetadata();
     }
   }
 }

package/src/sdk/SessionSystemBuilder.ts

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

package/src/sdk/session/Paths.ts

@@ -2,8 +2,8 @@
  * SDK Session 路径规则。
  *
  * 关键点（中文）
- * - 与旧 `.downcity/session/<sessionId>` 路径分开，避免不同 agent 在同一项目目录下互相污染。
- * - 新 SDK 统一落盘到 `.downcity/agents/<agentId>/sessions/<sessionId>/...`。
+ * - 所有 agent session 统一落盘到 `.downcity/agents/<agentId>/sessions/<sessionId>/...`。
+ * - `agentId` 是唯一隔离维度，不再保留第二套旧 session 根目录。
  */
 
 import path from "node:path";

package/src/sdk/session/Persistence.ts

@@ -6,10 +6,10 @@
  * - `Session` 只负责调用这些能力，不直接拼装 meta 结构。
  */
 
-import { resolveAssistantMessageForPersistence } from "@/service/builtins/chat/runtime/UserVisibleText.js";
-import { extractTextFromUiMessage } from "@/service/builtins/chat/runtime/UIMessageTransformer.js";
+import { extractTextFromUiMessage } from "@/plugin/builtins/chat/runtime/UIMessageTransformer.js";
 import type { SessionHistoryMetaV1 } from "@/session/types/SessionHistoryMeta.js";
 import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
+import { persistAssistantResult } from "@/session/messages/AssistantResultPersistence.js";
 import type { AgentSessionConfigSnapshot } from "@/sdk/AgentSdkTypes.js";
 import {
   readSessionMetadata,
@@ -104,9 +104,9 @@ export async function touchSessionMetadata(
 export async function persistSdkAssistantResult(
   params: PersistSdkAssistantResultParams,
 ): Promise<void> {
-  const persisted = resolveAssistantMessageForPersistence(params.assistantMessage);
-  await params.executor.appendAssistantMessage({
-    ...(persisted ? { message: persisted } : {}),
+  await persistAssistantResult({
+    writer: params.executor,
+    assistantMessage: params.assistantMessage,
     fallbackText: extractTextFromUiMessage(params.assistantMessage),
   });
   await touchSessionMetadata(params);

package/src/sdk/session/RuntimeSessionPort.ts

@@ -0,0 +1,107 @@
+/**
+ * SDK Session runtime plugin 端口构造器。
+ *
+ * 关键点（中文）
+ * - 把 SDK 本地 session 适配成 runtime / runtime plugin 依赖的 `SessionPort`。
+ * - SDK 公开面只保留 `prompt()` / `subscribe()`；runtime/service 若要 one-shot 等待结果，也统一委托给 `prompt()`。
+ */
+
+import type { SessionPort } from "@/core/AgentContextTypes.js";
+import type { SessionHistoryStore } from "@/session/store/history/SessionHistoryStore.js";
+import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
+import type {
+  AgentSessionSubscriber,
+  AgentSessionUnsubscribe,
+} from "@/types/sdk/AgentSessionEvent.js";
+import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
+
+/**
+ * 构造 SDK SessionPort 的参数。
+ */
+export interface CreateRuntimeSessionPortParams {
+  /**
+   * 当前 sessionId。
+   */
+  sessionId: string;
+  /**
+   * 读取当前 session 底层执行端口。
+   */
+  getExecutor: SessionPort["getExecutor"];
+  /**
+   * 追加一条新的 session prompt。
+   */
+  prompt: (input: AgentSessionPromptInput) => Promise<AgentSessionTurnHandle>;
+  /**
+   * 订阅当前 session 的 future 事件。
+   */
+  subscribe: (
+    subscriber: AgentSessionSubscriber,
+  ) => AgentSessionUnsubscribe;
+  /**
+   * 清理当前 session executor 状态。
+   */
+  clearExecutor: () => void;
+  /**
+   * session 更新后的异步通知回调。
+   */
+  afterSessionUpdatedAsync: () => Promise<void>;
+  /**
+   * 追加 user 消息到底层历史。
+   */
+  appendUserMessage: SessionPort["appendUserMessage"];
+  /**
+   * 追加 assistant 消息到底层历史。
+   */
+  appendAssistantMessage: SessionPort["appendAssistantMessage"];
+  /**
+   * 返回当前 session 是否正在执行。
+   */
+  isExecuting: () => boolean;
+  /**
+   * 当前 session 历史持久化端口。
+   */
+  historyStore: SessionHistoryStore;
+  /**
+   * 在执行前确保当前 session 已完成初始化与宿主级配置。
+   */
+  ensureReadyForExecution: () => Promise<void>;
+  /**
+   * session 更新后需要同步执行的持久化回调。
+   */
+  touchMetadata: () => Promise<void>;
+}
+
+/**
+ * 创建供 runtime plugin 使用的 session 端口。
+ */
+export function createRuntimeSessionPort(
+  params: CreateRuntimeSessionPortParams,
+): SessionPort {
+  return {
+    sessionId: params.sessionId,
+    getExecutor: () => params.getExecutor(),
+    getHistoryStore: () => params.historyStore,
+    prompt: async (input) => {
+      await params.ensureReadyForExecution();
+      return await params.prompt(input);
+    },
+    subscribe: (subscriber) => {
+      return params.subscribe(subscriber);
+    },
+    clearExecutor: () => {
+      params.clearExecutor();
+    },
+    afterSessionUpdatedAsync: async () => {
+      await params.afterSessionUpdatedAsync();
+    },
+    appendUserMessage: async (messageParams) => {
+      await params.appendUserMessage(messageParams);
+      await params.touchMetadata();
+    },
+    appendAssistantMessage: async (messageParams) => {
+      await params.appendAssistantMessage(messageParams);
+      await params.touchMetadata();
+    },
+    isExecuting: () => params.isExecuting(),
+  };
+}

package/src/sdk/session/index.ts

@@ -2,7 +2,7 @@
  * SDK Session 辅助模块聚合入口。
  *
  * 关键点（中文）
- * - 这里收口 `Session.ts` 依赖的路径、元数据、持久化与 service 端口适配能力。
+ * - 这里收口 `Session.ts` 依赖的路径、元数据、持久化与 runtime plugin 端口适配能力。
  * - 避免这些实现继续平铺在 `sdk/` 顶层，提升目录语义清晰度。
  */
 
@@ -30,5 +30,5 @@ export {
   touchSessionMetadata,
 } from "./Persistence.js";
 export {
-  createSessionServicePort,
-} from "./ServicePort.js";
+  createRuntimeSessionPort,
+} from "./RuntimeSessionPort.js";