@downcity/agent 1.1.17 → 1.1.19

package/src/runtime/server/http/control/StreamBySession.ts

@@ -0,0 +1,198 @@
+/**
+ * Control session 流式执行 helper。
+ *
+ * 关键点（中文）
+ * - 仅用于单 agent control API 的本地 session 流式返回。
+ * - chatKey 命中的平台 chat 队列仍保持原有入队语义，不在这里伪造“流式完成”。
+ * - 输出协议复用 SDK `AgentSessionStreamEvent` 的 NDJSON 事件行，便于 CLI 直接消费。
+ */
+
+import type { AgentContext, SessionPort } from "@/core/AgentContextTypes.js";
+import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
+import type {
+  ControlSessionExecuteAttachmentInput,
+} from "@/runtime/server/http/control/types/ControlSessionExecute.js";
+import { buildExecuteInputText } from "@/runtime/server/http/control/Helpers.js";
+import { drainDeferredPersistedUserMessages } from "@session/SessionRunScope.js";
+import { mapUiMessageChunkToSdkEvent } from "@/sdk/StreamEvents.js";
+import type { AgentSessionStreamEvent } from "@/sdk/AgentSdkTypes.js";
+import type {
+  SessionRunResult,
+  SessionUiMessageChunkCallback,
+} from "@/session/types/SessionRun.js";
+import { resolveDispatchTargetByChatKey } from "@/service/builtins/chat/runtime/ChatkeySend.js";
+import {
+  pickLastSuccessfulChatSendText,
+  resolveAssistantMessageForPersistence,
+} from "@/service/builtins/chat/runtime/UserVisibleText.js";
+
+type StreamableSessionPort = SessionPort & {
+  /**
+   * 流式执行当前 session。
+   *
+   * 说明（中文）
+   * - `SessionPort` 对外接口当前未显式暴露 `onUiMessageChunkCallback`，
+   *   但本地 executor 已支持该回调，这里按本地 control runtime 语义做窄化使用。
+   */
+  run(params: {
+    query: string;
+    onUiMessageChunkCallback?: SessionUiMessageChunkCallback;
+  }): Promise<SessionRunResult>;
+};
+
+const NDJSON_CONTENT_TYPE = "application/x-ndjson; charset=utf-8";
+
+function encodeNdjsonLine(
+  encoder: TextEncoder,
+  value: AgentSessionStreamEvent,
+): Uint8Array {
+  return encoder.encode(`${JSON.stringify(value)}\n`);
+}
+
+function resolveStreamEventFromUiChunk(params: {
+  chunk: Parameters<NonNullable<SessionUiMessageChunkCallback>>[0];
+  toolNameByCallId: Map<string, string>;
+}): AgentSessionStreamEvent | null {
+  const { chunk, toolNameByCallId } = params;
+  if (chunk.type === "tool-input-start") {
+    toolNameByCallId.set(chunk.toolCallId, chunk.toolName);
+    return null;
+  }
+
+  const event = mapUiMessageChunkToSdkEvent(chunk);
+  if (!event) return null;
+
+  if (event.type === "tool-call" || event.type === "tool-error") {
+    toolNameByCallId.set(event.toolCallId, event.toolName);
+  }
+
+  if (
+    (event.type === "tool-result" || event.type === "tool-error") &&
+    event.toolName === "unknown"
+  ) {
+    const toolName = toolNameByCallId.get(event.toolCallId);
+    return toolName ? { ...event, toolName } : event;
+  }
+
+  return event;
+}
+
+/**
+ * 为指定 session 创建流式执行响应。
+ */
+export async function createControlSessionStreamResponse(params: {
+  agentState: AgentRuntime;
+  executionContext: AgentContext;
+  sessionId: string;
+  instructions: string;
+  attachments?: ControlSessionExecuteAttachmentInput[];
+}): Promise<Response> {
+  const sessionId = String(params.sessionId || "").trim();
+  const instructions = String(params.instructions || "").trim();
+  if (!sessionId) {
+    return Response.json({ success: false, error: "Missing sessionId" }, { status: 400 });
+  }
+  if (!instructions) {
+    return Response.json({ success: false, error: "Missing instructions" }, { status: 400 });
+  }
+
+  const executeInput = await buildExecuteInputText({
+    projectRoot: params.agentState.rootPath,
+    sessionId,
+    instructions,
+    attachments: params.attachments,
+  });
+
+  const dispatchTarget = await resolveDispatchTargetByChatKey({
+    context: params.executionContext,
+    chatKey: sessionId,
+  });
+  if (dispatchTarget) {
+    return Response.json(
+      {
+        success: false,
+        error:
+          "Streaming execute does not support queued chat sessions. Use the non-stream execute API for chatKey routes.",
+      },
+      { status: 409 },
+    );
+  }
+
+  const session = params.agentState.getSession(sessionId) as StreamableSessionPort;
+  const encoder = new TextEncoder();
+
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      void (async () => {
+        const toolNameByCallId = new Map<string, string>();
+
+        const pushEvent = (event: AgentSessionStreamEvent): void => {
+          controller.enqueue(encodeNdjsonLine(encoder, event));
+        };
+
+        try {
+          await session.appendUserMessage({
+            text: executeInput,
+          });
+
+          const result = await session.run({
+            query: executeInput,
+            onUiMessageChunkCallback: async (chunk) => {
+              const event = resolveStreamEventFromUiChunk({
+                chunk,
+                toolNameByCallId,
+              });
+              if (!event) return;
+              pushEvent(event);
+            },
+          });
+
+          const userVisible = pickLastSuccessfulChatSendText(
+            result.assistantMessage,
+          ).trim();
+          try {
+            const messageForPersistence = resolveAssistantMessageForPersistence(
+              result.assistantMessage,
+            );
+            if (messageForPersistence) {
+              await session.appendAssistantMessage({
+                message: messageForPersistence,
+                fallbackText: userVisible,
+                extra: {
+                  via: "tui_session_stream",
+                  note: "assistant_message_missing",
+                },
+              });
+            }
+            const deferredInjectedMessages = drainDeferredPersistedUserMessages(
+              sessionId,
+            );
+            for (const message of deferredInjectedMessages) {
+              await session.appendUserMessage({
+                message,
+              });
+            }
+          } catch {
+            // ignore persistence follow-up errors after stream completion
+          }
+        } catch (error) {
+          pushEvent({
+            type: "error",
+            error: error instanceof Error ? error.message : String(error),
+          });
+        } finally {
+          controller.close();
+        }
+      })();
+    },
+  });
+
+  return new Response(stream, {
+    status: 200,
+    headers: {
+      "Content-Type": NDJSON_CONTENT_TYPE,
+      "Cache-Control": "no-cache, no-transform",
+      "X-Accel-Buffering": "no",
+    },
+  });
+}

package/src/sdk/AgentSdkTypes.ts

@@ -54,6 +54,16 @@ export interface AgentOptions {
    */
   instruction?: string | string[];
 
+  /**
+   * 当前 agent 为新建 session 提供的默认模型实例。
+   *
+   * 关键点（中文）
+   * - SDK 仍不负责“选择哪个模型”，这里只接收宿主已经创建好的 `LanguageModel`。
+   * - 该模型会作为 session 首次执行前的默认注入值。
+   * - 若同时提供 `configureSession`，则先应用这里的默认模型，再允许宿主继续覆写。
+   */
+  model?: LanguageModel;
+
   /**
    * 当前 agent 显式持有的 service 实例集合。
    *
@@ -106,7 +116,9 @@ export interface AgentOptions {
    *
    * 关键点（中文）
    * - SDK 不负责默认模型策略，宿主可在这里统一为 session 注入 model 等运行配置。
-   * - 该钩子只在 session 首次创建时触发一次，适合做实例级默认装配。
+   * - 若同时传入 `model`，则会先写入默认模型，再执行这里的宿主覆写逻辑。
+   * - 该钩子对每个 session 只触发一次，适合做实例级默认装配。
+   * - 触发时机可能来自显式 `agent.session()`，也可能来自该 session 的首次执行入口。
    */
   configureSession?: (session: Session) => Promise<void> | void;
 }

package/src/sdk/Session.ts

@@ -92,6 +92,15 @@ type SessionOptions = {
    * 读取当前 agent 显式注册 plugin 的 system blocks。
    */
   getPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
+
+  /**
+   * 在执行前确保当前 session 已完成宿主侧默认配置。
+   *
+   * 关键点（中文）
+   * - 这里通常由 `AgentCore` 注入，用于补齐默认 model、宿主覆写等一次性装配。
+   * - 所有执行入口都应通过这里兜底，避免只在 SDK `agent.session()` 链路上做配置。
+   */
+  ensureConfigured?: (session: Session) => Promise<void>;
 };
 
 /**
@@ -107,6 +116,7 @@ export class Session {
   private readonly getInstructionSystemBlocks: SessionOptions["getInstructionSystemBlocks"];
   private readonly getServiceSystemBlocks: SessionOptions["getServiceSystemBlocks"];
   private readonly getPluginSystemBlocks: SessionOptions["getPluginSystemBlocks"];
+  private readonly ensureConfiguredHook?: SessionOptions["ensureConfigured"];
   private readonly historyStore: JsonlSessionHistoryStore;
   private readonly historyComposer: JsonlSessionHistoryComposer;
   private readonly executor: Executor;
@@ -114,6 +124,7 @@ export class Session {
   private createdAt = Date.now();
   private timezone = resolveSystemTimezone();
   private initializePromise: Promise<this> | null = null;
+  private ensureConfiguredPromise: Promise<void> | null = null;
   private servicePort: SessionPort | null = null;
 
   constructor(options: SessionOptions) {
@@ -125,6 +136,7 @@ export class Session {
     this.getInstructionSystemBlocks = options.getInstructionSystemBlocks;
     this.getServiceSystemBlocks = options.getServiceSystemBlocks;
     this.getPluginSystemBlocks = options.getPluginSystemBlocks;
+    this.ensureConfiguredHook = options.ensureConfigured;
     if (!this.id) {
       throw new Error("Session requires a non-empty sessionId");
     }
@@ -338,9 +350,10 @@ export class Session {
     if (!query) {
       throw new Error("session.run requires a non-empty query");
     }
+    await this.ensureReadyForExecution();
     if (!this.sessionConfig.model) {
       throw new Error(
-        `Session "${this.id}" requires a configured model. Call session.set({ model }) first or let the host configure the session during creation.`,
+        `Session "${this.id}" requires a configured model. Pass model to new Agent({ model }), call session.set({ model }) first, or let the host configure the session during creation.`,
       );
     }
     await this.appendUserMessage({ text: query });
@@ -366,9 +379,10 @@ export class Session {
     if (!query) {
       throw new Error("session.stream requires a non-empty query");
     }
+    await this.ensureReadyForExecution();
     if (!this.sessionConfig.model) {
       throw new Error(
-        `Session "${this.id}" requires a configured model. Call session.set({ model }) first or let the host configure the session during creation.`,
+        `Session "${this.id}" requires a configured model. Pass model to new Agent({ model }), call session.set({ model }) first, or let the host configure the session during creation.`,
       );
     }
     const queue = new AsyncQueue<AgentSessionStreamEvent>();
@@ -478,6 +492,9 @@ export class Session {
       sessionId: this.id,
       executor: this.executor,
       historyStore: this.historyStore,
+      ensureReadyForExecution: async () => {
+        await this.ensureReadyForExecution();
+      },
       touchMetadata: async () => {
         await this.touchMetadata();
       },
@@ -485,6 +502,27 @@ export class Session {
     return this.servicePort;
   }
 
+  /**
+   * 在执行前确保 session 已完成初始化与宿主装配。
+   */
+  async ensureReadyForExecution(): Promise<void> {
+    await this.initialize();
+    if (this.ensureConfiguredPromise) {
+      await this.ensureConfiguredPromise;
+      return;
+    }
+    this.ensureConfiguredPromise = (async () => {
+      if (!this.ensureConfiguredHook) return;
+      await this.ensureConfiguredHook(this);
+    })();
+    try {
+      await this.ensureConfiguredPromise;
+    } catch (error) {
+      this.ensureConfiguredPromise = null;
+      throw error;
+    }
+  }
+
   private async touchMetadata(): Promise<void> {
     await touchSessionMetadata({
       projectRoot: this.projectRoot,

package/src/sdk/session/ServicePort.ts

@@ -25,6 +25,10 @@ export interface CreateSessionServicePortParams {
    * 当前 session 历史持久化端口。
    */
   historyStore: SessionHistoryStore;
+  /**
+   * 在执行前确保当前 session 已完成初始化与宿主级配置。
+   */
+  ensureReadyForExecution: () => Promise<void>;
   /**
    * session 更新后需要同步执行的持久化回调。
    */
@@ -42,6 +46,7 @@ export function createSessionServicePort(
     getExecutor: () => params.executor.getExecutor(),
     getHistoryStore: () => params.historyStore,
     run: async (runParams) => {
+      await params.ensureReadyForExecution();
       return await params.executor.run(runParams);
     },
     clearExecutor: () => {

package/src/session/Executor.ts

@@ -717,7 +717,7 @@ export class Executor implements SessionExecutor {
     const model = this.getModel();
     if (!model) {
       throw new Error(
-        `Executor for session "${this.sessionId}" requires a configured model`,
+        `Executor for session "${this.sessionId}" requires a configured model. Pass model to new Agent({ model }), call session.set({ model }), or let the host configure the session before execution.`,
       );
     }
     return model;