@downcity/agent 1.1.21 → 1.1.23

package/src/sdk/AgentSdkTypes.ts

@@ -9,9 +9,7 @@
 
 import type { LanguageModel, Tool } from "ai";
 import type { BaseService } from "@/service/builtins/BaseService.js";
-import type { JsonValue } from "@/types/common/Json.js";
 import type { Plugin } from "@/plugin/types/Plugin.js";
-import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
 import type { AgentPlatformRuntime } from "@/types/runtime/host/AgentHost.js";
 import type { LocalRpcServerHandle } from "@/types/runtime/rpc/LocalRpc.js";
 import type { ServerInstance } from "@/runtime/server/http/Server.js";
@@ -292,140 +290,6 @@ export interface AgentSessionConfigSnapshot {
   modelLabel?: string;
 }
 
-/**
- * Session 运行输入。
- */
-export interface AgentSessionRunInput {
-  /**
-   * 当前轮用户查询文本。
-   */
-  query: string;
-}
-
-/**
- * Session 运行结果。
- */
-export interface AgentSessionRunResult {
-  /**
-   * 本轮执行是否成功。
-   */
-  success: boolean;
-
-  /**
-   * 失败时的错误文本。
-   */
-  error?: string;
-
-  /**
-   * 最终 assistant 文本。
-   */
-  text: string;
-
-  /**
-   * 最终 assistant 原始 UIMessage。
-   */
-  assistantMessage: SessionMessageV1;
-}
-
-/**
- * SDK 对外的流式事件。
- */
-export type AgentSessionStreamEvent =
-  | {
-      /**
-       * 文本增量事件。
-       */
-      type: "text-delta";
-      /**
-       * 当前追加的文本片段。
-       */
-      text: string;
-    }
-  | {
-      /**
-       * reasoning 增量事件。
-       */
-      type: "reasoning-delta";
-      /**
-       * 当前追加的 reasoning 文本片段。
-       */
-      text: string;
-    }
-  | {
-      /**
-       * 工具调用可用事件。
-       */
-      type: "tool-call";
-      /**
-       * 当前工具调用唯一标识。
-       */
-      toolCallId: string;
-      /**
-       * 工具名称。
-       */
-      toolName: string;
-      /**
-       * 工具输入参数。
-       */
-      args: JsonValue;
-    }
-  | {
-      /**
-       * 工具调用结果事件。
-       */
-      type: "tool-result";
-      /**
-       * 当前工具调用唯一标识。
-       */
-      toolCallId: string;
-      /**
-       * 工具名称。
-       */
-      toolName: string;
-      /**
-       * 工具输出结果。
-       */
-      result: JsonValue;
-    }
-  | {
-      /**
-       * 工具调用失败事件。
-       */
-      type: "tool-error";
-      /**
-       * 当前工具调用唯一标识。
-       */
-      toolCallId: string;
-      /**
-       * 工具名称。
-       */
-      toolName: string;
-      /**
-       * 错误文本。
-       */
-      error: string;
-    }
-  | {
-      /**
-       * 运行结束事件。
-       */
-      type: "finish";
-      /**
-       * 最终完成原因（若底层可提供）。
-       */
-      finishReason?: string;
-    }
-  | {
-      /**
-       * 运行错误事件。
-       */
-      type: "error";
-      /**
-       * 错误文本。
-       */
-      error: string;
-    };
-
 /**
  * Session system block 来源类型。
  */
@@ -490,7 +354,7 @@ export interface AgentSessionSystemSessionInfo {
    *
    * 关键点（中文）
    * - 这是 session 初始化时落盘的稳定参考时间，按 Date/ISO 字符串对外展示。
-   * - 它不是每轮运行的当前时间，不会随着 `run()` / `stream()` 改变。
+   * - 它不是每轮运行的当前时间，不会随着后续 turn 执行而改变。
    */
   createdAt: string;
 

package/src/sdk/RemoteAgent.ts

@@ -3,19 +3,76 @@
  *
  * 关键点（中文）
  * - 面向已通过 `agent.start({ http: { ... } })` 暴露出来的远程/本地 HTTP 服务。
- * - 与本地 `Agent` 尽量保持同一套 session 使用面。
+ * - 与本地 `Session` 保持同一套 Session actor 使用面：`prompt()` + `subscribe()`。
+ * - `RemoteAgent` 只负责 transport 与本地 turn handle 合成，不重复实现第二套会话编排器。
  */
 
 import type {
   AgentSessionMetadata,
-  AgentSessionRunInput,
-  AgentSessionRunResult,
   AgentSessionSetInput,
-  AgentSessionStreamEvent,
   AgentSessionSystemSnapshot,
   RemoteAgentOptions,
 } from "@/sdk/AgentSdkTypes.js";
 import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
+import type {
+  AgentSessionEvent,
+  AgentSessionSubscriber,
+  AgentSessionUnsubscribe,
+} from "@/types/sdk/AgentSessionEvent.js";
+import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
+import type {
+  AgentSessionTurnHandle,
+  AgentSessionTurnResult,
+} from "@/types/sdk/AgentSessionTurn.js";
+import { SessionEventHub } from "@/sdk/session/runtime/SessionEventHub.js";
+
+type Deferred<T> = {
+  /**
+   * 当前延迟 Promise。
+   */
+  promise: Promise<T>;
+  /**
+   * 兑现 Promise。
+   */
+  resolve: (value: T) => void;
+};
+
+type RemoteTurnLifecycle = {
+  /**
+   * 当前 turnId。
+   */
+  turnId: string;
+  /**
+   * 当前 turn 的最终结果快照。
+   */
+  result: AgentSessionTurnResult | null;
+  /**
+   * 当前 turn 完成 Promise 控制器。
+   */
+  deferredFinished: Deferred<AgentSessionTurnResult>;
+};
+
+type EventConnectionReady = {
+  /**
+   * 当前 ready promise 是否已经完成。
+   */
+  settled: boolean;
+  /**
+   * 标记事件连接已经在服务端完成订阅。
+   */
+  resolve: () => void;
+  /**
+   * 标记事件连接在 ready 前失败。
+   */
+  reject: (error: unknown) => void;
+};
+
+type SdkEventsReadyFrame = {
+  /**
+   * SDK HTTP events 连接内部 ready 标记。
+   */
+  type: "sdk-events-ready";
+};
 
 /**
  * 远程 Session 客户端。
@@ -23,6 +80,13 @@ import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
 class RemoteSession {
   readonly id: string;
   private readonly baseUrl: string;
+  private readonly eventHub = new SessionEventHub();
+  private readonly turnsById = new Map<string, RemoteTurnLifecycle>();
+  private readonly completedTurnIds: string[] = [];
+  private eventPumpConnectPromise: Promise<void> | null = null;
+  private eventPumpAbortController: AbortController | null = null;
+  private eventPumpRunning = false;
+  private eventSubscriberCount = 0;
 
   constructor(baseUrl: string, sessionId: string) {
     this.baseUrl = baseUrl;
@@ -39,25 +103,60 @@ class RemoteSession {
   }
 
   /**
-   * 执行一轮非流式请求。
+   * 向当前远程 session 追加一条新的 prompt。
    */
-  async run(input: AgentSessionRunInput): Promise<AgentSessionRunResult> {
-    const response = await fetch(`${this.baseUrl}/api/sdk/sessions/${encodeURIComponent(this.id)}/run`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
+  async prompt(input: AgentSessionPromptInput): Promise<AgentSessionTurnHandle> {
+    const query = String(input.query || "").trim();
+    if (!query) {
+      throw new Error("remote session.prompt requires a non-empty query");
+    }
+
+    await this.ensureEventPump();
+
+    const response = await fetch(
+      `${this.baseUrl}/api/sdk/sessions/${encodeURIComponent(this.id)}/prompt`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          query,
+        }),
       },
-      body: JSON.stringify(input),
-    });
+    );
     const payload = (await response.json()) as {
       success?: boolean;
       error?: string;
-      result?: AgentSessionRunResult;
+      turn?: {
+        id?: string;
+      };
     };
-    if (!response.ok || !payload.success || !payload.result) {
-      throw new Error(String(payload.error || "Remote session run failed"));
+    if (!response.ok || !payload.success || !payload.turn?.id) {
+      throw new Error(String(payload.error || "Remote session prompt failed"));
     }
-    return payload.result;
+
+    const lifecycle = this.ensureTurnLifecycle(payload.turn.id);
+    return createTurnHandle(lifecycle);
+  }
+
+  /**
+   * 订阅当前远程 session 的 future 事件。
+   */
+  subscribe(subscriber: AgentSessionSubscriber): AgentSessionUnsubscribe {
+    this.eventSubscriberCount += 1;
+    void this.ensureEventPump().catch((error) => {
+      this.eventHub.publish({
+        type: "error",
+        message: error instanceof Error ? error.message : String(error),
+      });
+    });
+    const unsubscribe = this.eventHub.subscribe(subscriber);
+    return () => {
+      unsubscribe();
+      this.eventSubscriberCount = Math.max(0, this.eventSubscriberCount - 1);
+      this.maybeStopEventPump();
+    };
   }
 
   /**
@@ -128,48 +227,187 @@ class RemoteSession {
     return new RemoteSession(this.baseUrl, payload.session.sessionId);
   }
 
-  /**
-   * 执行一轮流式请求。
-   */
-  async *stream(
-    input: AgentSessionRunInput,
-  ): AsyncIterable<AgentSessionStreamEvent> {
-    const response = await fetch(
-      `${this.baseUrl}/api/sdk/sessions/${encodeURIComponent(this.id)}/stream`,
-      {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
+  private async ensureEventPump(): Promise<void> {
+    if (this.eventPumpConnectPromise) {
+      await this.eventPumpConnectPromise;
+      return;
+    }
+    if (this.eventPumpRunning) return;
+
+    this.eventPumpConnectPromise = (async () => {
+      const abortController = new AbortController();
+      this.eventPumpAbortController = abortController;
+      const response = await fetch(
+        `${this.baseUrl}/api/sdk/sessions/${encodeURIComponent(this.id)}/events`,
+        {
+          signal: abortController.signal,
         },
-        body: JSON.stringify(input),
-      },
-    );
-    if (!response.ok || !response.body) {
-      const text = await response.text().catch(() => "");
-      throw new Error(text || `Remote session stream failed (${response.status})`);
+      );
+      if (!response.ok || !response.body) {
+        const text = await response.text().catch(() => "");
+        throw new Error(
+          text || `Remote session events failed (${response.status})`,
+        );
+      }
+      this.eventPumpRunning = true;
+      const ready = createEventConnectionReady();
+      void this.consumeEventConnection(response.body, abortController, ready)
+        .finally(() => {
+          const wasAborted = abortController.signal.aborted;
+          this.eventPumpRunning = false;
+          if (this.eventPumpAbortController === abortController) {
+            this.eventPumpAbortController = null;
+          }
+          if (!wasAborted) {
+            this.failPendingTurns("Remote session events connection closed");
+            this.eventHub.publish({
+              type: "error",
+              message: "Remote session events connection closed",
+            });
+          }
+        });
+      await ready.promise;
+    })();
+
+    try {
+      await this.eventPumpConnectPromise;
+    } catch (error) {
+      this.eventPumpAbortController = null;
+      throw error;
+    } finally {
+      this.eventPumpConnectPromise = null;
     }
+  }
 
+  private async consumeEventConnection(
+    body: ReadableStream<Uint8Array>,
+    abortController: AbortController,
+    ready: EventConnectionReady,
+  ): Promise<void> {
     const decoder = new TextDecoder();
-    const reader = response.body.getReader();
+    const reader = body.getReader();
     let buffered = "";
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      buffered += decoder.decode(value, { stream: true });
-      let newlineIndex = buffered.indexOf("\n");
-      while (newlineIndex >= 0) {
-        const line = buffered.slice(0, newlineIndex).trim();
-        buffered = buffered.slice(newlineIndex + 1);
-        if (line) {
-          yield JSON.parse(line) as AgentSessionStreamEvent;
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffered += decoder.decode(value, { stream: true });
+        let newlineIndex = buffered.indexOf("\n");
+        while (newlineIndex >= 0) {
+          const line = buffered.slice(0, newlineIndex).trim();
+          buffered = buffered.slice(newlineIndex + 1);
+          if (line) {
+            this.handleEventLine(JSON.parse(line) as unknown, ready);
+          }
+          newlineIndex = buffered.indexOf("\n");
         }
-        newlineIndex = buffered.indexOf("\n");
+      }
+      const tail = buffered.trim();
+      if (tail) {
+        this.handleEventLine(JSON.parse(tail) as unknown, ready);
+      }
+      rejectEventConnectionReady(
+        ready,
+        "Remote session events connection closed before ready",
+      );
+    } catch (error) {
+      if (!abortController.signal.aborted) {
+        const message = error instanceof Error ? error.message : String(error);
+        rejectEventConnectionReady(ready, message);
+        this.failPendingTurns(message);
+        this.eventHub.publish({
+          type: "error",
+          message,
+        });
+      }
+    } finally {
+      try {
+        reader.releaseLock();
+      } catch {
+        // ignore
       }
     }
-    const tail = buffered.trim();
-    if (tail) {
-      yield JSON.parse(tail) as AgentSessionStreamEvent;
+  }
+
+  private handleEventLine(
+    value: unknown,
+    ready: EventConnectionReady,
+  ): void {
+    if (isSdkEventsReadyFrame(value)) {
+      resolveEventConnectionReady(ready);
+      return;
     }
+    this.handleEvent(value as AgentSessionEvent);
+  }
+
+  private handleEvent(event: AgentSessionEvent): void {
+    const turnId = extractTurnId(event);
+    if (turnId) {
+      this.ensureTurnLifecycle(turnId);
+    }
+
+    if (event.type === "turn-finish") {
+      const lifecycle = this.ensureTurnLifecycle(event.turnId);
+      const result: AgentSessionTurnResult = {
+        turnId: event.turnId,
+        text: event.text,
+        success: event.success,
+        ...(event.error ? { error: event.error } : {}),
+      };
+      lifecycle.result = result;
+      lifecycle.deferredFinished.resolve(result);
+      this.rememberCompletedTurn(event.turnId);
+      this.maybeStopEventPump();
+    }
+
+    this.eventHub.publish(event);
+  }
+
+  private ensureTurnLifecycle(turnId: string): RemoteTurnLifecycle {
+    const cached = this.turnsById.get(turnId);
+    if (cached) return cached;
+    const created: RemoteTurnLifecycle = {
+      turnId,
+      result: null,
+      deferredFinished: createDeferred<AgentSessionTurnResult>(),
+    };
+    this.turnsById.set(turnId, created);
+    return created;
+  }
+
+  private failPendingTurns(message: string): void {
+    for (const lifecycle of this.turnsById.values()) {
+      if (lifecycle.result) continue;
+      const result: AgentSessionTurnResult = {
+        turnId: lifecycle.turnId,
+        text: "",
+        success: false,
+        error: message,
+      };
+      lifecycle.result = result;
+      lifecycle.deferredFinished.resolve(result);
+      this.rememberCompletedTurn(lifecycle.turnId);
+    }
+    this.maybeStopEventPump();
+  }
+
+  private rememberCompletedTurn(turnId: string): void {
+    this.completedTurnIds.push(turnId);
+    while (this.completedTurnIds.length > 200) {
+      const oldestTurnId = this.completedTurnIds.shift();
+      if (oldestTurnId) {
+        this.turnsById.delete(oldestTurnId);
+      }
+    }
+  }
+
+  private maybeStopEventPump(): void {
+    if (this.eventSubscriberCount > 0) return;
+    if ([...this.turnsById.values()].some((item) => item.result === null)) return;
+    if (!this.eventPumpAbortController) return;
+    this.eventPumpAbortController.abort();
+    this.eventPumpAbortController = null;
   }
 }
 
@@ -227,3 +465,84 @@ export class RemoteAgent {
     return payload.sessions;
   }
 }
+
+function createDeferred<T>(): Deferred<T> {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((innerResolve) => {
+    resolve = innerResolve;
+  });
+  return {
+    promise,
+    resolve,
+  };
+}
+
+function createEventConnectionReady(): EventConnectionReady & {
+  /**
+   * 等待事件连接 ready 的 Promise。
+   */
+  promise: Promise<void>;
+} {
+  let resolve!: () => void;
+  let reject!: (error: unknown) => void;
+  const promise = new Promise<void>((innerResolve, innerReject) => {
+    resolve = innerResolve;
+    reject = innerReject;
+  });
+  return {
+    promise,
+    settled: false,
+    resolve,
+    reject,
+  };
+}
+
+function resolveEventConnectionReady(ready: EventConnectionReady): void {
+  if (ready.settled) return;
+  ready.settled = true;
+  ready.resolve();
+}
+
+function rejectEventConnectionReady(
+  ready: EventConnectionReady,
+  error: unknown,
+): void {
+  if (ready.settled) return;
+  ready.settled = true;
+  ready.reject(error);
+}
+
+function isSdkEventsReadyFrame(value: unknown): value is SdkEventsReadyFrame {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "type" in value &&
+    (value as { type?: unknown }).type === "sdk-events-ready"
+  );
+}
+
+function createTurnHandle(
+  lifecycle: RemoteTurnLifecycle,
+): AgentSessionTurnHandle {
+  return {
+    id: lifecycle.turnId,
+    get result() {
+      return lifecycle.result;
+    },
+    finished: lifecycle.deferredFinished.promise,
+  };
+}
+
+function extractTurnId(event: AgentSessionEvent): string | null {
+  switch (event.type) {
+    case "turn-start":
+    case "text-delta":
+    case "reasoning-delta":
+    case "tool-call":
+    case "tool-result":
+    case "turn-finish":
+      return event.turnId;
+    default:
+      return null;
+  }
+}