@downcity/agent 1.1.74 → 1.1.79

package/src/agent/remote/transports/HttpRemoteAgentTransport.ts

@@ -0,0 +1,347 @@
+/**
+ * RemoteAgent HTTP transport。
+ *
+ * 关键点（中文）
+ * - 只适配 Town Agent HTTP gateway 的 SDK routes。
+ * - 不处理 RemoteSession 的 turn lifecycle，避免 transport 与 actor 逻辑混在一起。
+ */
+
+import type {
+  AgentCreateSessionInput,
+  AgentListSessionsInput,
+  AgentSessionForkInput,
+  AgentSessionHistoryInput,
+  AgentSessionHistoryPage,
+  AgentSessionInfo,
+  AgentSessionSummaryPage,
+  AgentSessionSystemSnapshot,
+} from "@/types/agent/AgentTypes.js";
+import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
+import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
+import type {
+  RemoteAgentTransport,
+  TransportSubscription,
+} from "@/agent/remote/RemoteTransport.js";
+
+type SdkEventsReadyFrame = {
+  /** SDK HTTP events 连接内部 ready 标记。 */
+  type: "sdk-events-ready";
+};
+
+/**
+ * Town HTTP gateway transport。
+ */
+export class HttpRemoteAgentTransport implements RemoteAgentTransport {
+  private readonly base_url: string;
+  private readonly token: string;
+
+  constructor(url: string, token?: string) {
+    this.base_url = url.replace(/\/+$/, "");
+    this.token = String(token || "").trim();
+  }
+
+  private headers(input?: Record<string, string>): Headers {
+    const headers = new Headers(input);
+    if (this.token) {
+      headers.set("Authorization", `Bearer ${this.token}`);
+    }
+    return headers;
+  }
+
+  async create_session(input?: AgentCreateSessionInput): Promise<AgentSessionInfo> {
+    const payload = await read_http_json<{
+      success?: boolean;
+      error?: string;
+      session?: AgentSessionInfo;
+    }>(`${this.base_url}/api/sdk/sessions`, {
+      method: "POST",
+      headers: this.headers({
+        "Content-Type": "application/json",
+      }),
+      body: JSON.stringify({
+        ...(input?.sessionId ? { sessionId: input.sessionId } : {}),
+      }),
+    });
+    if (!payload.success || !payload.session?.sessionId) {
+      throw new Error(String(payload.error || "Remote session create failed"));
+    }
+    return payload.session;
+  }
+
+  async get_info(session_id: string): Promise<AgentSessionInfo> {
+    const payload = await read_http_json<{
+      success?: boolean;
+      error?: string;
+      session?: AgentSessionInfo;
+    }>(`${this.base_url}/api/sdk/sessions/${encodeURIComponent(session_id)}`, {
+      headers: this.headers(),
+    });
+    if (!payload.success || !payload.session?.sessionId) {
+      throw new Error(String(payload.error || "Remote session info failed"));
+    }
+    return payload.session;
+  }
+
+  async prompt(
+    session_id: string,
+    input: AgentSessionPromptInput,
+  ): Promise<{ id: string }> {
+    const payload = await read_http_json<{
+      success?: boolean;
+      error?: string;
+      turn?: {
+        id?: string;
+      };
+    }>(`${this.base_url}/api/sdk/sessions/${encodeURIComponent(session_id)}/prompt`, {
+      method: "POST",
+      headers: this.headers({
+        "Content-Type": "application/json",
+      }),
+      body: JSON.stringify({
+        query: input.query,
+      }),
+    });
+    const id = String(payload.turn?.id || "").trim();
+    if (!payload.success || !id) {
+      throw new Error(String(payload.error || "Remote session prompt failed"));
+    }
+    return { id };
+  }
+
+  async subscribe(params: {
+    session_id: string;
+    on_ready: () => void;
+    on_event: (event: AgentSessionEvent) => void;
+  }): Promise<TransportSubscription> {
+    const abort_controller = new AbortController();
+    let resolve_ready!: () => void;
+    let reject_ready!: (error: unknown) => void;
+    const ready_promise = new Promise<void>((resolve, reject) => {
+      resolve_ready = resolve;
+      reject_ready = reject;
+    });
+    const response = await fetch(
+      `${this.base_url}/api/sdk/sessions/${encodeURIComponent(params.session_id)}/events`,
+      {
+        headers: this.headers(),
+        signal: abort_controller.signal,
+      },
+    );
+    if (!response.ok || !response.body) {
+      const text = await response.text().catch(() => "");
+      throw new Error(text || `Remote session events failed (${response.status})`);
+    }
+    void consume_http_event_stream({
+      body: response.body,
+      abort_controller,
+      on_ready: () => {
+        params.on_ready();
+        resolve_ready();
+      },
+      on_ready_error: (error) => {
+        reject_ready(error);
+      },
+      on_event: params.on_event,
+    });
+    await ready_promise;
+    return {
+      close: async () => {
+        abort_controller.abort();
+      },
+    };
+  }
+
+  async history(
+    session_id: string,
+    input?: AgentSessionHistoryInput,
+  ): Promise<AgentSessionHistoryPage> {
+    const query = new URLSearchParams();
+    if (input?.limit !== undefined) query.set("limit", String(input.limit));
+    if (input?.cursor) query.set("cursor", input.cursor);
+    if (input?.order) query.set("order", input.order);
+    if (input?.view) query.set("view", input.view);
+    const payload = await read_http_json<{
+      success?: boolean;
+      error?: string;
+      history?: AgentSessionHistoryPage;
+    }>(
+      `${this.base_url}/api/sdk/sessions/${encodeURIComponent(session_id)}/history${
+        query.size > 0 ? `?${query.toString()}` : ""
+      }`,
+      {
+        headers: this.headers(),
+      },
+    );
+    if (!payload.success || !payload.history || !Array.isArray(payload.history.items)) {
+      throw new Error(String(payload.error || "Remote session history failed"));
+    }
+    return payload.history;
+  }
+
+  async system(session_id: string): Promise<AgentSessionSystemSnapshot> {
+    const payload = await read_http_json<{
+      success?: boolean;
+      error?: string;
+      system?: AgentSessionSystemSnapshot;
+    }>(`${this.base_url}/api/sdk/sessions/${encodeURIComponent(session_id)}/system`, {
+      headers: this.headers(),
+    });
+    if (!payload.success || !payload.system || !Array.isArray(payload.system.blocks)) {
+      throw new Error(String(payload.error || "Remote session system failed"));
+    }
+    return payload.system;
+  }
+
+  async fork(
+    session_id: string,
+    input?: AgentSessionForkInput | string,
+  ): Promise<AgentSessionInfo> {
+    const message_id =
+      typeof input === "string"
+        ? String(input || "").trim() || undefined
+        : String(input?.messageId || "").trim() || undefined;
+    const payload = await read_http_json<{
+      success?: boolean;
+      error?: string;
+      session?: AgentSessionInfo;
+    }>(`${this.base_url}/api/sdk/sessions/${encodeURIComponent(session_id)}/fork`, {
+      method: "POST",
+      headers: this.headers({
+        "Content-Type": "application/json",
+      }),
+      body: JSON.stringify({
+        ...(message_id ? { messageId: message_id } : {}),
+      }),
+    });
+    if (!payload.success || !payload.session?.sessionId) {
+      throw new Error(String(payload.error || "Remote session fork failed"));
+    }
+    return payload.session;
+  }
+
+  async list_sessions(input?: AgentListSessionsInput): Promise<AgentSessionSummaryPage> {
+    const query = new URLSearchParams();
+    if (input?.limit !== undefined) query.set("limit", String(input.limit));
+    if (input?.cursor) query.set("cursor", input.cursor);
+    if (input?.query) query.set("query", input.query);
+    const payload = await read_http_json<{
+      success?: boolean;
+      error?: string;
+      page?: AgentSessionSummaryPage;
+    }>(
+      `${this.base_url}/api/sdk/sessions${query.size > 0 ? `?${query.toString()}` : ""}`,
+      {
+        headers: this.headers(),
+      },
+    );
+    if (!payload.success || !payload.page) {
+      throw new Error(String(payload.error || "Remote sessions list failed"));
+    }
+    return payload.page;
+  }
+}
+
+async function read_http_json<T>(input: string, init?: RequestInit): Promise<T> {
+  const response = await fetch(input, init);
+  const payload = (await response.json().catch(() => ({}))) as T;
+  if (!response.ok) {
+    const message = extract_error_message(payload);
+    throw new Error(message || `HTTP ${response.status}`);
+  }
+  return payload;
+}
+
+async function consume_http_event_stream(params: {
+  body: ReadableStream<Uint8Array>;
+  abort_controller: AbortController;
+  on_ready: () => void;
+  on_ready_error: (error: unknown) => void;
+  on_event: (event: AgentSessionEvent) => void;
+}): Promise<void> {
+  const decoder = new TextDecoder();
+  const reader = params.body.getReader();
+  let buffered = "";
+  let ready_resolved = false;
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffered += decoder.decode(value, { stream: true });
+      let newline_index = buffered.indexOf("\n");
+      while (newline_index >= 0) {
+        const line = buffered.slice(0, newline_index).trim();
+        buffered = buffered.slice(newline_index + 1);
+        if (line) {
+          const value = JSON.parse(line) as unknown;
+          if (is_sdk_events_ready_frame(value)) {
+            ready_resolved = true;
+            params.on_ready();
+          } else {
+            params.on_event(value as AgentSessionEvent);
+          }
+        }
+        newline_index = buffered.indexOf("\n");
+      }
+    }
+
+    const tail = buffered.trim();
+    if (tail) {
+      const value = JSON.parse(tail) as unknown;
+      if (is_sdk_events_ready_frame(value)) {
+        ready_resolved = true;
+        params.on_ready();
+      } else {
+        params.on_event(value as AgentSessionEvent);
+      }
+    }
+
+    if (!params.abort_controller.signal.aborted) {
+      if (!ready_resolved) {
+        const error = new Error("Remote session events connection closed before ready");
+        params.on_ready_error(error);
+        throw error;
+      }
+      params.on_event({
+        type: "error",
+        message: "Remote session events connection closed",
+      });
+    }
+  } catch (error) {
+    if (!params.abort_controller.signal.aborted) {
+      if (!ready_resolved) {
+        params.on_ready_error(error);
+      }
+      params.on_event({
+        type: "error",
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+  } finally {
+    try {
+      reader.releaseLock();
+    } catch {
+      // ignore
+    }
+  }
+}
+
+function extract_error_message(payload: unknown): string {
+  if (!payload || typeof payload !== "object") return "";
+  if ("error" in payload && typeof payload.error === "string") {
+    return payload.error;
+  }
+  if ("message" in payload && typeof payload.message === "string") {
+    return payload.message;
+  }
+  return "";
+}
+
+function is_sdk_events_ready_frame(value: unknown): value is SdkEventsReadyFrame {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "type" in value &&
+    (value as { type?: unknown }).type === "sdk-events-ready"
+  );
+}

package/src/agent/remote/transports/RpcRemoteAgentTransport.ts

@@ -0,0 +1,107 @@
+/**
+ * RemoteAgent RPC transport。
+ *
+ * 关键点（中文）
+ * - 只把 RemoteAgent 的 session actor 方法映射到 RpcClient。
+ * - 长连接生命周期由 RpcClient 管理。
+ */
+
+import type {
+  AgentCreateSessionInput,
+  AgentListSessionsInput,
+  AgentSessionForkInput,
+  AgentSessionHistoryInput,
+  AgentSessionHistoryPage,
+  AgentSessionInfo,
+  AgentSessionSummaryPage,
+  AgentSessionSystemSnapshot,
+} from "@/types/agent/AgentTypes.js";
+import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
+import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
+import { RpcClient, parse_rpc_url } from "@/rpc/Client.js";
+import type {
+  RemoteAgentTransport,
+  TransportSubscription,
+} from "@/agent/remote/RemoteTransport.js";
+
+/**
+ * 本机 RPC transport。
+ */
+export class RpcRemoteAgentTransport implements RemoteAgentTransport {
+  private readonly client: RpcClient;
+
+  constructor(url: string) {
+    this.client = new RpcClient(parse_rpc_url(url));
+  }
+
+  async create_session(input?: AgentCreateSessionInput): Promise<AgentSessionInfo> {
+    return await this.client.create_session(input);
+  }
+
+  async get_info(session_id: string): Promise<AgentSessionInfo> {
+    return await this.client.get_session(session_id);
+  }
+
+  async prompt(
+    session_id: string,
+    input: AgentSessionPromptInput,
+  ): Promise<{ id: string }> {
+    return await this.client.prompt_session({
+      session_id,
+      input,
+    });
+  }
+
+  async subscribe(params: {
+    session_id: string;
+    on_ready: () => void;
+    on_event: (event: AgentSessionEvent) => void;
+  }): Promise<TransportSubscription> {
+    const subscription = await this.client.subscribe_session({
+      session_id: params.session_id,
+      on_ready: params.on_ready,
+      on_event: params.on_event,
+    });
+    return {
+      close: async () => {
+        await subscription.unsubscribe();
+      },
+    };
+  }
+
+  async history(
+    session_id: string,
+    input?: AgentSessionHistoryInput,
+  ): Promise<AgentSessionHistoryPage> {
+    return await this.client.get_session_history({
+      session_id,
+      input,
+    });
+  }
+
+  async system(session_id: string): Promise<AgentSessionSystemSnapshot> {
+    return await this.client.get_session_system(session_id);
+  }
+
+  async fork(
+    session_id: string,
+    input?: AgentSessionForkInput | string,
+  ): Promise<AgentSessionInfo> {
+    const message_id =
+      typeof input === "string"
+        ? String(input || "").trim() || undefined
+        : String(input?.messageId || "").trim() || undefined;
+    return await this.client.fork_session({
+      session_id,
+      ...(message_id ? { message_id } : {}),
+    });
+  }
+
+  async list_sessions(input?: AgentListSessionsInput): Promise<AgentSessionSummaryPage> {
+    return await this.client.list_sessions(input);
+  }
+
+  async close(): Promise<void> {
+    await this.client.close();
+  }
+}

package/src/executor/Executor.ts

@@ -13,7 +13,7 @@ import type { SessionHistoryComposer } from "@executor/composer/history/SessionH
 import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
 import { withSessionRunScope } from "@executor/SessionRunScope.js";
 import type { SessionRunScope } from "@executor/SessionRunScope.js";
-import { buildSessionStepEventMessages } from "@executor/messages/SessionStepEventMapper.js";
+import { buildSessionStepParts } from "@executor/messages/SessionStepEventMapper.js";
 import { JsonlSessionCompactionComposer } from "@executor/composer/compaction/jsonl/JsonlSessionCompactionComposer.js";
 import { LocalSessionContextComposer } from "@executor/composer/context/LocalSessionContextComposer.js";
 import type { SessionCompactionComposer } from "@executor/composer/compaction/SessionCompactionComposer.js";
@@ -55,6 +55,7 @@ import type {
   SessionRunInput,
   SessionRunResult,
 } from "@/executor/types/SessionRun.js";
+import { generateId } from "@/utils/Id.js";
 
 /**
  * 可压缩错误的最大重试次数。
@@ -226,6 +227,56 @@ export class Executor implements SessionExecutor {
     await this.historyWriter.appendAssistantMessage(params);
   }
 
+  /**
+   * 把 step/tool 过程增量写入当前运行中的 assistant 快照。
+   */
+  private async appendAssistantStepPartsToInflight(
+    parts: SessionMessageV1["parts"],
+  ): Promise<void> {
+    const normalized_parts = Array.isArray(parts)
+      ? parts.filter((part) => part && typeof part === "object")
+      : [];
+    if (normalized_parts.length === 0) return;
+
+    const current_inflight = await this.historyStore.readInflight();
+    const next_message: SessionMessageV1 = current_inflight
+      ? {
+          ...current_inflight,
+          metadata: {
+            ...(current_inflight.metadata || {
+              v: 1 as const,
+              ts: Date.now(),
+              sessionId: this.sessionId,
+            }),
+            ts: Date.now(),
+            sessionId: this.sessionId,
+            source: "egress",
+            kind: "normal",
+          },
+          parts: [
+            ...(Array.isArray(current_inflight.parts)
+              ? current_inflight.parts
+              : []),
+            ...normalized_parts,
+          ],
+        }
+      : {
+          id: `a:${this.sessionId}:${generateId()}`,
+          role: "assistant",
+          metadata: {
+            v: 1,
+            ts: Date.now(),
+            sessionId: this.sessionId,
+            source: "egress",
+            kind: "normal",
+          },
+          parts: normalized_parts,
+        };
+
+    await this.historyStore.writeInflight(next_message);
+    await this.afterSessionUpdatedAsync();
+  }
+
   /**
    * 运行当前 session 的一次请求。
    *
@@ -256,7 +307,6 @@ export class Executor implements SessionExecutor {
         ? { onUiMessageChunkCallback: params.onUiMessageChunkCallback }
         : {}),
     };
-    let persistedAssistantStepCount = 0;
     const providedOnAssistantStepCallback =
       sessionRunScope.onAssistantStepCallback;
 
@@ -266,20 +316,14 @@ export class Executor implements SessionExecutor {
       visibility?: "visible" | "internal";
       stepResult?: unknown;
     }): Promise<void> => {
-      const stepMessages = buildSessionStepEventMessages({
-        sessionId: this.sessionId,
+      const step_parts = buildSessionStepParts({
         stepIndex: step.stepIndex,
         stepResult: step.stepResult,
         text: step.text,
         visibility: step.visibility,
       });
-      if (stepMessages.length > 0) {
-        for (const stepMessage of stepMessages) {
-          await this.appendAssistantMessage({
-            message: stepMessage,
-          });
-          persistedAssistantStepCount += 1;
-        }
+      if (step_parts.length > 0) {
+        await this.appendAssistantStepPartsToInflight(step_parts);
       }
 
       if (typeof providedOnAssistantStepCallback === "function") {
@@ -298,32 +342,7 @@ export class Executor implements SessionExecutor {
         },
         () => this.runWithRetry({ query }),
       );
-      if (persistedAssistantStepCount <= 0) return result;
-
-      return {
-        ...result,
-        assistantMessage: {
-          ...result.assistantMessage,
-          metadata: {
-            ...(result.assistantMessage.metadata || {
-              v: 1 as const,
-              ts: Date.now(),
-              sessionId: this.sessionId,
-            }),
-            extra: {
-              ...(
-                result.assistantMessage.metadata?.extra &&
-                  typeof result.assistantMessage.metadata.extra === "object" &&
-                  !Array.isArray(result.assistantMessage.metadata.extra)
-                  ? result.assistantMessage.metadata.extra
-                  : {}
-              ),
-              assistantStepMessagesPersisted: true,
-              assistantStepCount: persistedAssistantStepCount,
-            },
-          },
-        },
-      };
+      return result;
     } finally {
       this.resetRunState();
       this.executing = false;

package/src/executor/composer/history/SessionHistoryWriter.ts

@@ -104,7 +104,7 @@ export class SessionHistoryWriter {
     try {
       const historyStore = this.getHistoryStore();
       if (params.message && typeof params.message === "object") {
-        await historyStore.append(params.message);
+        await historyStore.finalizeInflight(params.message);
         void this.afterSessionUpdatedAsync();
         return;
       }
@@ -112,7 +112,7 @@ export class SessionHistoryWriter {
       const fallbackText = String(params.fallbackText || "").trim();
       if (!fallbackText) return;
 
-      await historyStore.append(
+      await historyStore.finalizeInflight(
         historyStore.assistantText({
           text: fallbackText,
           metadata: {

package/src/executor/messages/AssistantResultPersistence.ts

@@ -4,14 +4,11 @@
  * 关键点（中文）
  * - 负责收敛“写完整 assistant message / 写 fallback 文本 / 完全跳过”三种分支。
  * - 避免 SDK、HTTP execute、control execute、chat queue 各自复制一套判断。
- * - 一旦 step 消息已经单独持久化，最终 merged assistant 必须跳过，不能再补一条 fallback。
+ * - 运行中 step/tool 的持久化由 inflight 快照承担；run 结束时只关心最终 assistant 如何收口。
  */
 
 import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
-import {
-  hasPersistedAssistantSteps,
-  resolveAssistantMessageForPersistence,
-} from "@/executor/messages/UserVisibleText.js";
+import { resolveAssistantMessageForPersistence } from "@/executor/messages/UserVisibleText.js";
 
 /**
  * assistant 写入端口。
@@ -48,8 +45,8 @@ export interface PersistAssistantResultParams {
    * 可选兜底文本。
    *
    * 关键点（中文）
-   * - 仅在没有完整 assistant message 且未发生 step 持久化时才允许写入。
-   * - 若 step 已单独落盘，这里必须被忽略，避免重复 assistant。
+   * - 仅在没有完整 assistant message 时才允许写入。
+   * - inflight 快照的正式收口由 history store 负责，这里不再处理旧的 step 独立落盘分支。
    */
   fallbackText?: string;
 }
@@ -83,11 +80,6 @@ export function buildAssistantResultPersistencePayload(
     };
   }
 
-  // 关键点（中文）：step 已经单独落盘时，最终 merged assistant 必须完全跳过。
-  if (hasPersistedAssistantSteps(params.assistantMessage)) {
-    return null;
-  }
-
   const fallbackText = normalizeFallbackText(params.fallbackText);
   if (!fallbackText) return null;
   return {