@downcity/agent 1.1.79 → 1.1.81

package/src/executor/README.md

@@ -6,7 +6,7 @@
 
 - `Session`：用户/SDK 面向的完整会话对象，负责模型配置、历史入口、prompt 入口和分叉能力。
 - `Executor`：单个 session 的内部单轮执行引擎，负责并发锁、执行 scope、Composer 编排、压缩重试、assistant step 持久化和 tool-loop 调用。
-- `Composer`：执行前的材料组装协议，只负责把原材料组装成某一阶段输入，不直接执行模型，也没有公共运行时基类。
+- `Composer`：Session 执行阶段的可替换策略协议。调用方可以通过 custom composer 定义 system、history、runtime context 与 compaction 等阶段逻辑。
 - `HistoryStore`：历史事实源，负责 JSONL 读写、meta、archive、lock、compact 与消息工厂。
 - `HistoryComposer`：历史组装策略，只负责把 `HistoryStore` 中的历史组装成本轮模型输入。
 - `CoreEngine`：Executor 内部的模型/tool-loop 核心机制，负责模型流、tool calls、续写和最终 assistant message 合并。
@@ -38,7 +38,7 @@ sdk/Session.prompt({ query })
 
 ## Composer 的代码实现方式
 
-Composer 在代码里是 TypeScript `interface`，不是抽象基类。每个 Composer 只声明当前阶段需要的最小协议，实现类用 `implements` 接上。
+Composer 在代码里是 TypeScript `interface`，不是抽象基类。每个 Composer 声明当前阶段的策略协议，实现类用 `implements` 接上；如果需要自定义 Composer，应在自定义 `Session` 类中传给 `super({ composers })`。
 
 ```ts
 export interface SessionSystemComposer {
@@ -76,9 +76,9 @@ Executor.prepareExecuteInput()
 边界规则：
 
 - Composer 不调用模型，模型调用只发生在 `Executor.runCoreEngine()`。
-- Composer 不持有历史事实，历史事实由 `HistoryStore` 负责。
+- Composer 可以绑定或读取当前 session 的上下文，但历史事实源仍由 `HistoryStore` 负责。
 - Composer 不管理 session 生命周期，生命周期由 `Session` / `Executor` 管理。
-- Composer 可以读取上下文并做策略判断，但输出应该是“本轮执行材料”。
+- Composer 可以读取上下文并做策略判断，输出或执行结果应该服务于当前阶段的本轮 session 执行。
 
 ## 当前目录结构
 

package/src/executor/SessionRunScope.ts

@@ -1,54 +1,20 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import type { FileUIPart } from "ai";
 import type { SessionUserMessageV1 } from "@/executor/types/SessionMessages.js";
-import type {
-  SessionAssistantStepCallback,
-  SessionUiMessageChunkCallback,
-} from "@/executor/types/SessionRun.js";
+import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
 
 /**
  * SessionRunScope（单次请求作用域）。
  *
  * 关键点（中文）
  * - 这是 session run 层请求作用域上下文，不属于具体 plugin 业务模块。
- * - 统一承载请求链需要透传的字段（如 `sessionId`）。
+ * - 当前阶段仅作为深层工具回调读取 `runContext` 的薄包装。
  */
 export type SessionRunScope = {
-  sessionId?: string;
   /**
-   * step 边界合并回调（可选）。
-   *
-   * 关键点（中文）
-   * - 由调用侧（如 chat queue）注入。
-   * - Orchestrator 从 SessionRunScope 读取并编排到本轮运行上下文。
+   * 当前显式运行上下文。
    */
-  onStepCallback?: () => Promise<SessionUserMessageV1[]>;
-
-  /**
-   * assistant step 完成回调（可选）。
-   *
-   * 关键点（中文）
-   * - 在每个 LLM step 结束时触发。
-   * - 用于把中间文本增量派发到外部通道（如 direct 模式分步发送）。
-   */
-  onAssistantStepCallback?: SessionAssistantStepCallback;
-
-  /**
-   * UI stream chunk 回调（可选）。
-   *
-   * 关键点（中文）
-   * - 用于把底层模型 UI stream 事件向上层 SDK / transport 旁路输出。
-   * - 不影响最终 assistantMessage 的收敛与落盘。
-   */
-  onUiMessageChunkCallback?: SessionUiMessageChunkCallback;
-
-  /**
-   * 运行时注入的 user 消息队列（可选）。
-   *
-   * 关键点（中文）
-   * - 用于在 tool 执行后向下一 step 注入结构化 user 消息。
-   * - 队列内容由上层 plugin runtime 通过统一协议下发，main 不感知业务语义。
-   */
-  injectedUserMessages?: SessionUserMessageV1[];
+  runContext: SessionRunContext;
 };
 
 /**
@@ -56,23 +22,10 @@ export type SessionRunScope = {
  *
  * 关键点（中文）
  * - 同一条异步调用链内可读取一致的 SessionRunScope。
- * - 用于把 `sessionId` 从入口透传到 plugin runtime 与工具层。
+ * - 当前主要用于 tool 深层桥接层读取活跃 runContext。
  */
 export const sessionRunScopeStorage = new AsyncLocalStorage<SessionRunScope>();
 
-/**
- * 待持久化的运行时注入 user 消息队列（按 sessionId）。
- *
- * 关键点（中文）
- * - sessionRunScopeStorage 中的 injectedUserMessages 只负责“下一 step 临时可见”。
- * - 为了让时间线顺序稳定，这里把“真正写入历史”的动作延后到
- *   assistant message 落盘之后再统一执行。
- */
-const deferredPersistedUserMessagesBySession = new Map<
-  string,
-  SessionUserMessageV1[]
->();
-
 /**
  * 在当前异步调用链内绑定 session run 作用域。
  */
@@ -87,6 +40,13 @@ export function getSessionRunScope(): SessionRunScope | undefined {
   return sessionRunScopeStorage.getStore();
 }
 
+/**
+ * 读取当前异步链路上的显式 runContext。
+ */
+export function getSessionRunContext(): SessionRunContext | undefined {
+  return sessionRunScopeStorage.getStore()?.runContext;
+}
+
 /**
  * 入队一条“待注入 user 消息”。
  *
@@ -96,12 +56,9 @@ export function getSessionRunScope(): SessionRunScope | undefined {
 export function enqueueInjectedUserMessage(
   message: SessionUserMessageV1,
 ): void {
-  const store = sessionRunScopeStorage.getStore();
-  if (!store || !message) return;
-  if (!Array.isArray(store.injectedUserMessages)) {
-    store.injectedUserMessages = [];
-  }
-  store.injectedUserMessages.push(message);
+  const run_context = getSessionRunContext();
+  if (!run_context || !message) return;
+  run_context.injectedUserMessages.push(message);
 }
 
 /**
@@ -111,10 +68,10 @@ export function enqueueInjectedUserMessage(
  * - 采用 drain 语义，确保每条注入消息只在下一 step 使用一次。
  */
 export function drainInjectedUserMessages(): SessionUserMessageV1[] {
-  const store = sessionRunScopeStorage.getStore();
-  if (!store || !Array.isArray(store.injectedUserMessages)) return [];
-  const out = [...store.injectedUserMessages];
-  store.injectedUserMessages = [];
+  const run_context = getSessionRunContext();
+  if (!run_context) return [];
+  const out = [...run_context.injectedUserMessages];
+  run_context.injectedUserMessages = [];
   return out;
 }
 
@@ -125,11 +82,11 @@ export function enqueueDeferredPersistedUserMessage(
   sessionId: string,
   message: SessionUserMessageV1,
 ): void {
+  const run_context = getSessionRunContext();
   const key = String(sessionId || "").trim();
-  if (!key || !message) return;
-  const current = deferredPersistedUserMessagesBySession.get(key) || [];
-  current.push(message);
-  deferredPersistedUserMessagesBySession.set(key, current);
+  if (!run_context || !key || !message) return;
+  if (run_context.sessionId !== key) return;
+  run_context.deferredPersistedUserMessages.push(message);
 }
 
 /**
@@ -138,9 +95,28 @@ export function enqueueDeferredPersistedUserMessage(
 export function drainDeferredPersistedUserMessages(
   sessionId: string,
 ): SessionUserMessageV1[] {
+  const run_context = getSessionRunContext();
   const key = String(sessionId || "").trim();
-  if (!key) return [];
-  const current = deferredPersistedUserMessagesBySession.get(key) || [];
-  deferredPersistedUserMessagesBySession.delete(key);
-  return [...current];
+  if (!run_context || !key || run_context.sessionId !== key) return [];
+  const current = [...run_context.deferredPersistedUserMessages];
+  run_context.deferredPersistedUserMessages = [];
+  return current;
+}
+
+/**
+ * 入队一组“待并入 assistant 消息的 file parts”。
+ */
+export function enqueueAssistantFileParts(parts: FileUIPart[]): void {
+  const run_context = getSessionRunContext();
+  if (!run_context || !Array.isArray(parts) || parts.length === 0) return;
+  run_context.pendingAssistantFileParts.push(...parts);
+}
+
+/**
+ * 读取当前 run 内待并入 assistant 消息的 file parts。
+ */
+export function readPendingAssistantFileParts(): FileUIPart[] {
+  const run_context = getSessionRunContext();
+  if (!run_context) return [];
+  return [...run_context.pendingAssistantFileParts];
 }

package/src/executor/composer/context/LocalSessionContextComposer.ts

@@ -8,10 +8,6 @@
 
 import type { ModelMessage } from "ai";
 import { generateId } from "@/utils/Id.js";
-import {
-  drainInjectedUserMessages,
-  getSessionRunScope,
-} from "@executor/SessionRunScope.js";
 import type {
   SessionContextComposer,
   SessionContextComposeResult,
@@ -19,6 +15,7 @@ import type {
 import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
 import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
 import type { Tool } from "ai";
+import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
 
 type LocalSessionContextComposerOptions = {
   /**
@@ -45,19 +42,18 @@ export class LocalSessionContextComposer implements SessionContextComposer {
     this.getTools = options.getTools;
   }
 
-  async compose(): Promise<SessionContextComposeResult> {
+  async compose(
+    run_context: SessionRunContext,
+  ): Promise<SessionContextComposeResult> {
     const tools = this.getTools();
-    const ctx = getSessionRunScope();
-    const sessionId = String(ctx?.sessionId || this.sessionId || "").trim();
+    const sessionId = String(
+      run_context.sessionId || this.sessionId || "",
+    ).trim();
     if (!sessionId) {
       throw new Error(
-        "LocalSessionContextComposer.compose requires a sessionId from sessionRunScope or options.sessionId",
+        "LocalSessionContextComposer.compose requires a non-empty sessionId",
       );
     }
-    // 关键点（中文）：sessionId 统一回填到请求上下文，后续组件直接读取。
-    if (ctx && typeof ctx === "object") {
-      if (!ctx.sessionId) ctx.sessionId = sessionId;
-    }
     return {
       tools,
     };
@@ -69,6 +65,7 @@ export class LocalSessionContextComposer implements SessionContextComposer {
       appendMergedUserMessages: (
         messages: SessionMessageV1[],
       ) => Promise<ModelMessage[]>;
+      runContext: SessionRunContext;
     },
   ): (input: { messages?: ModelMessage[] }) => Promise<{
     system: SessionSystemMessage[];
@@ -82,8 +79,9 @@ export class LocalSessionContextComposer implements SessionContextComposer {
       system: SessionSystemMessage[];
       messages?: ModelMessage[];
     }> => {
-      const injectedMessages = drainInjectedUserMessages();
-      const onStepCallback = getSessionRunScope()?.onStepCallback;
+      const injectedMessages = [...input.runContext.injectedUserMessages];
+      input.runContext.injectedUserMessages = [];
+      const onStepCallback = input.runContext.onStepCallback;
       if (
         typeof onStepCallback !== "function" &&
         injectedMessages.length === 0
@@ -120,8 +118,10 @@ export class LocalSessionContextComposer implements SessionContextComposer {
     };
   }
 
-  createOnStepFinishHandler(): (stepResult: unknown) => Promise<void> {
-    const onAssistantStepCallback = getSessionRunScope()?.onAssistantStepCallback;
+  createOnStepFinishHandler(
+    run_context: SessionRunContext,
+  ): (stepResult: unknown) => Promise<void> {
+    const onAssistantStepCallback = run_context.onAssistantStepCallback;
     let assistantStepIndex = 0;
     return async (stepResult: unknown): Promise<void> => {
       const step = stepResult as { text?: unknown };
@@ -144,12 +144,16 @@ export class LocalSessionContextComposer implements SessionContextComposer {
   /**
    * 构造 fallback assistant 消息。
    */
-  buildFallbackAssistantMessage(text: string): SessionMessageV1 {
-    const ctx = getSessionRunScope();
-    const sessionId = String(ctx?.sessionId || this.sessionId || "").trim();
+  buildFallbackAssistantMessage(
+    text: string,
+    run_context: SessionRunContext,
+  ): SessionMessageV1 {
+    const sessionId = String(
+      run_context.sessionId || this.sessionId || "",
+    ).trim();
     if (!sessionId) {
       throw new Error(
-        "LocalSessionContextComposer.buildFallbackAssistantMessage requires a sessionId from sessionRunScope or options.sessionId",
+        "LocalSessionContextComposer.buildFallbackAssistantMessage requires a non-empty sessionId",
       );
     }
     return {

package/src/executor/composer/context/SessionContextComposer.ts

@@ -9,6 +9,7 @@
 import type { ModelMessage, Tool } from "ai";
 import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
 import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
+import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
 
 /**
  * 本轮运行上下文组装输出。
@@ -32,7 +33,7 @@ export interface SessionContextComposer {
   /**
    * 组装一次 run 所需上下文。
    */
-  compose(): Promise<SessionContextComposeResult>;
+  compose(run_context: SessionRunContext): Promise<SessionContextComposeResult>;
 
   /**
    * 构造 prepareStep 回调。
@@ -49,6 +50,10 @@ export interface SessionContextComposer {
       appendMergedUserMessages: (
         messages: SessionMessageV1[],
       ) => Promise<ModelMessage[]>;
+      /**
+       * 当前显式运行上下文。
+       */
+      runContext: SessionRunContext;
     },
   ): (input: { messages?: ModelMessage[] }) => Promise<{
     system: SessionSystemMessage[];
@@ -58,7 +63,9 @@ export interface SessionContextComposer {
   /**
    * 构造 onStepFinish 回调。
    */
-  createOnStepFinishHandler(): (stepResult: unknown) => Promise<void>;
+  createOnStepFinishHandler(
+    run_context: SessionRunContext,
+  ): (stepResult: unknown) => Promise<void>;
 
   /**
    * 构造 fallback assistant 消息。
@@ -66,5 +73,8 @@ export interface SessionContextComposer {
    * 关键点（中文）
    * - fallback 消息构造由 ContextComposer 内部实现，Executor 不直接依赖 history Composer。
    */
-  buildFallbackAssistantMessage(text: string): SessionMessageV1;
+  buildFallbackAssistantMessage(
+    text: string,
+    run_context: SessionRunContext,
+  ): SessionMessageV1;
 }

package/src/executor/composer/system/SessionSystemComposer.ts

@@ -7,6 +7,7 @@
  */
 
 import type { SystemModelMessage } from "ai";
+import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
 
 /**
  * Session system Composer 协议。
@@ -20,5 +21,5 @@ export interface SessionSystemComposer {
   /**
    * 解析本轮 system messages。
    */
-  resolve(): Promise<SystemModelMessage[]>;
+  resolve(run_context: SessionRunContext): Promise<SystemModelMessage[]>;
 }

package/src/executor/composer/system/default/DefaultSessionSystemComposer.ts

@@ -9,8 +9,8 @@
 import type {
   SessionSystemComposer,
 } from "@executor/composer/system/SessionSystemComposer.js";
-import { getSessionRunScope } from "@executor/SessionRunScope.js";
 import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
 import {
   resolveSessionSystemMessages,
   type SystemProfile,
@@ -60,9 +60,8 @@ export class DefaultSessionSystemComposer implements SessionSystemComposer {
     this.profile = options.profile === "task" ? "task" : "chat";
   }
 
-  async resolve() {
-    const ctx = getSessionRunScope();
-    const sessionId = String(ctx?.sessionId || "").trim();
+  async resolve(run_context: SessionRunContext) {
+    const sessionId = String(run_context.sessionId || "").trim();
     if (!sessionId) {
       throw new Error("DefaultSessionSystemComposer.resolve requires a non-empty sessionId");
     }