@downcity/agent 1.1.43 → 1.1.51

package/src/index.ts

@@ -17,9 +17,8 @@ export type {
   AgentCreateSessionInput,
   AgentListSessionsInput,
   AgentOptions,
-  AgentHttpBinding,
-  AgentHttpStartOptions,
   AgentRpcBinding,
+  AgentRpcStartOptions,
   AgentStartOptions,
   AgentStartResult,
   AgentStopResult,
@@ -103,10 +102,11 @@ export {
   registerPluginActionCommandsForCli,
 } from "./plugin/core/PluginCommand.js";
 
-// Agent server 与 transport 集成
+// Agent RPC 集成
+export { startRpcServer } from "./rpc/Server.js";
+
+// 宿主 HTTP gateway 集成
 export { startServer } from "./runtime/server/http/Server.js";
-export { startLocalRpcServer } from "./runtime/server/rpc/Server.js";
-export { callAgentTransport } from "./runtime/transport/rpc/Transport.js";
 
 // Runtime plugin 运行集成
 export {
@@ -127,7 +127,7 @@ export { persistProjectPluginConfig } from "./plugin/core/ProjectConfigStore.js"
 export {
   initializeAgentProject,
   isAgentProjectInitialized,
-  normalizeDefaultAgentName,
+  normalizeDefaultAgentId,
 } from "./config/AgentInitializer.js";
 export { loadDowncityConfig } from "./config/Config.js";
 export {
@@ -193,7 +193,7 @@ export type {
   PlatformAgentShipStartConfig,
 } from "./types/runtime/platform/PlatformGateway.js";
 
-// Daemon / RPC 协议类型
+// Daemon 协议类型
 export {
   DAEMON_LOG_FILENAME,
   DAEMON_META_FILENAME,
@@ -203,10 +203,6 @@ export type {
   DaemonMeta,
   DaemonStaleReason,
 } from "./types/runtime/daemon/Daemon.js";
-export type {
-  LocalRpcRequest,
-  LocalRpcResponse,
-} from "./types/runtime/rpc/LocalRpc.js";
 
 // Inline instant 协议类型
 export type {
@@ -281,16 +277,13 @@ export type {
 
 // Platform store 类型
 export type {
-  StoredAgentEnvEntry,
   StoredChannelAccount,
   StoredChannelAccountChannel,
   StoredEnvEntry,
-  StoredEnvScope,
   StoredGlobalEnvEntry,
   StoredModel,
   StoredModelProvider,
   StoredProviderMeta,
-  UpsertAgentEnvEntryInput,
   UpsertChannelAccountInput,
   UpsertEnvEntryInput,
   UpsertGlobalEnvEntryInput,

package/src/plugin/core/PluginCommandRequest.ts

@@ -2,7 +2,7 @@
  * PluginCommandRequest：统一 plugin runtime command 请求解析模块。
  *
  * 关键点（中文）
- * - 统一收口 HTTP / RPC 两种入口的请求体解析。
+ * - 统一收口当前 HTTP 入口的请求体解析。
  * - plugin runtime 远程调用统一走 runtime command 协议，不再让 action 自带 HTTP route。
  * - ActionSchedule 参数（`schedule` / `delay` / `time`）也在这里一次性归一化。
  */

package/src/plugin/core/PluginLocalExecution.ts

@@ -9,7 +9,7 @@
 
 import path from "node:path";
 import { logger as defaultLogger } from "@/utils/logger/Logger.js";
-import { loadAgentEnvSnapshot, loadDowncityConfig } from "@/config/Config.js";
+import { loadDowncityConfig, resolveAgentEnv } from "@/config/Config.js";
 import { isPluginEnabled } from "@/plugin/core/Activation.js";
 import { findPluginByName } from "@/plugin/core/PluginCatalog.js";
 import {
@@ -30,12 +30,8 @@ import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
  */
 export function createLocalPluginCommandContext(projectRoot: string): PluginCommandContext {
   const rootPath = path.resolve(String(projectRoot || "").trim() || ".");
-  const env = loadAgentEnvSnapshot(rootPath);
-  const config = loadDowncityConfig(rootPath, {
-    projectEnv: env,
-    agentEnv: env,
-    globalEnv: {},
-  });
+  const env = resolveAgentEnv(rootPath);
+  const config = loadDowncityConfig(rootPath);
 
   defaultLogger.bindProjectRoot(rootPath);
 
@@ -47,7 +43,7 @@ export function createLocalPluginCommandContext(projectRoot: string): PluginComm
     env,
     paths: createAgentPathRuntime(
       rootPath,
-      String(config.name || "").trim() || path.basename(rootPath) || "agent",
+      String(config.id || "").trim() || path.basename(rootPath) || "agent",
     ),
     pluginConfig: createAgentPluginConfigRuntime(rootPath),
   };

package/src/plugin/types/PluginApi.ts

@@ -155,7 +155,7 @@ export interface PluginCliBaseOptions {
    */
   json?: boolean;
   /**
-   * agent 名称（从 managed agent registry 解析到项目路径）。
+   * agent id（从 managed agent registry 解析到项目路径）。
    */
   agent?: string;
 }

package/src/rpc/Client.ts

@@ -0,0 +1,467 @@
+/**
+ * Agent 本机 RPC Client。
+ *
+ * 职责说明（中文）
+ * - 为 `RemoteAgent(rpc://...)` 提供最小客户端实现。
+ * - 复用逐行 JSON（NDJSON）协议，与本机 RPC Server 对接。
+ * - 当前只承载 Session actor 所需方法。
+ */
+
+import net from "node:net";
+import type {
+  AgentCreateSessionInput,
+  AgentListSessionsInput,
+  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";
+
+type RpcClientRequest =
+  | {
+      id: string;
+      method: "sdk.sessions.list";
+      params?: AgentListSessionsInput;
+    }
+  | {
+      id: string;
+      method: "sdk.sessions.create";
+      params?: AgentCreateSessionInput;
+    }
+  | {
+      id: string;
+      method: "sdk.sessions.get";
+      params: {
+        sessionId: string;
+      };
+    }
+  | {
+      id: string;
+      method: "sdk.sessions.prompt";
+      params: {
+        sessionId: string;
+        input: AgentSessionPromptInput;
+      };
+    }
+  | {
+      id: string;
+      method: "sdk.sessions.history";
+      params: {
+        sessionId: string;
+        input?: AgentSessionHistoryInput;
+      };
+    }
+  | {
+      id: string;
+      method: "sdk.sessions.system";
+      params: {
+        sessionId: string;
+      };
+    }
+  | {
+      id: string;
+      method: "sdk.sessions.fork";
+      params: {
+        sessionId: string;
+        messageId?: string;
+      };
+    }
+  | {
+      id: string;
+      method: "sdk.sessions.subscribe";
+      params: {
+        sessionId: string;
+      };
+    }
+  | {
+      id: string;
+      method: "sdk.sessions.unsubscribe";
+      params: {
+        subscriptionId: string;
+      };
+    };
+
+type RpcResponseFrame = {
+  id: string;
+  success: boolean;
+  data?: unknown;
+  error?: string;
+};
+
+type RpcReadyFrame = {
+  type: "ready";
+  subscriptionId: string;
+};
+
+type RpcEventFrame = {
+  type: "event";
+  subscriptionId: string;
+  event: AgentSessionEvent;
+};
+
+type PendingRequest = {
+  resolve: (value: any) => void;
+  reject: (error: unknown) => void;
+};
+
+type RpcSubscription = {
+  on_ready: () => void;
+  on_event: (event: AgentSessionEvent) => void;
+};
+
+/**
+ * RPC endpoint。
+ */
+export interface RpcClientEndpoint {
+  /** RPC host。 */
+  host: string;
+  /** RPC port。 */
+  port: number;
+}
+
+/**
+ * RPC Session 订阅句柄。
+ */
+export interface RpcSessionSubscription {
+  /** 当前订阅 id。 */
+  subscription_id: string;
+  /** 取消订阅。 */
+  unsubscribe(): Promise<void>;
+}
+
+/**
+ * RPC Client。
+ */
+export class RpcClient {
+  private readonly endpoint: RpcClientEndpoint;
+  private socket: net.Socket | null = null;
+  private connect_promise: Promise<void> | null = null;
+  private buffered = "";
+  private readonly pending_requests = new Map<string, PendingRequest>();
+  private readonly subscriptions = new Map<string, RpcSubscription>();
+  private request_sequence = 0;
+
+  constructor(endpoint: RpcClientEndpoint) {
+    this.endpoint = endpoint;
+  }
+
+  /**
+   * 列出远程 session。
+   */
+  async list_sessions(
+    input?: AgentListSessionsInput,
+  ): Promise<AgentSessionSummaryPage> {
+    const data = await this.request<{ page: AgentSessionSummaryPage }>({
+      method: "sdk.sessions.list",
+      params: input,
+    });
+    return data.page;
+  }
+
+  /**
+   * 创建远程 session。
+   */
+  async create_session(
+    input?: AgentCreateSessionInput,
+  ): Promise<AgentSessionInfo> {
+    const data = await this.request<{ session: AgentSessionInfo }>({
+      method: "sdk.sessions.create",
+      params: input,
+    });
+    return data.session;
+  }
+
+  /**
+   * 获取远程 session 信息。
+   */
+  async get_session(session_id: string): Promise<AgentSessionInfo> {
+    const data = await this.request<{ session: AgentSessionInfo }>({
+      method: "sdk.sessions.get",
+      params: {
+        sessionId: session_id,
+      },
+    });
+    return data.session;
+  }
+
+  /**
+   * 发送 prompt。
+   */
+  async prompt_session(params: {
+    session_id: string;
+    input: AgentSessionPromptInput;
+  }): Promise<{ id: string }> {
+    const data = await this.request<{ turn: { id: string } }>({
+      method: "sdk.sessions.prompt",
+      params: {
+        sessionId: params.session_id,
+        input: params.input,
+      },
+    });
+    return data.turn;
+  }
+
+  /**
+   * 读取 history。
+   */
+  async get_session_history(params: {
+    session_id: string;
+    input?: AgentSessionHistoryInput;
+  }): Promise<AgentSessionHistoryPage> {
+    const data = await this.request<{ history: AgentSessionHistoryPage }>({
+      method: "sdk.sessions.history",
+      params: {
+        sessionId: params.session_id,
+        input: params.input,
+      },
+    });
+    return data.history;
+  }
+
+  /**
+   * 读取 system snapshot。
+   */
+  async get_session_system(session_id: string): Promise<AgentSessionSystemSnapshot> {
+    const data = await this.request<{ system: AgentSessionSystemSnapshot }>({
+      method: "sdk.sessions.system",
+      params: {
+        sessionId: session_id,
+      },
+    });
+    return data.system;
+  }
+
+  /**
+   * 分叉 session。
+   */
+  async fork_session(params: {
+    session_id: string;
+    message_id?: string;
+  }): Promise<AgentSessionInfo> {
+    const data = await this.request<{ session: AgentSessionInfo }>({
+      method: "sdk.sessions.fork",
+      params: {
+        sessionId: params.session_id,
+        ...(params.message_id ? { messageId: params.message_id } : {}),
+      },
+    });
+    return data.session;
+  }
+
+  /**
+   * 订阅 session 事件。
+   */
+  async subscribe_session(params: {
+    session_id: string;
+    on_ready: () => void;
+    on_event: (event: AgentSessionEvent) => void;
+  }): Promise<RpcSessionSubscription> {
+    const data = await this.request<{ subscriptionId: string }>({
+      method: "sdk.sessions.subscribe",
+      params: {
+        sessionId: params.session_id,
+      },
+    });
+    const subscription_id = String(data.subscriptionId || "").trim();
+    if (!subscription_id) {
+      throw new Error("RPC subscription did not return subscriptionId");
+    }
+    this.subscriptions.set(subscription_id, {
+      on_ready: params.on_ready,
+      on_event: params.on_event,
+    });
+    params.on_ready();
+    return {
+      subscription_id,
+      unsubscribe: async () => {
+        this.subscriptions.delete(subscription_id);
+        await this.request({
+          method: "sdk.sessions.unsubscribe",
+          params: {
+            subscriptionId: subscription_id,
+          },
+        });
+      },
+    };
+  }
+
+  /**
+   * 关闭底层连接。
+   */
+  async close(): Promise<void> {
+    const socket = this.socket;
+    this.socket = null;
+    this.connect_promise = null;
+    this.buffered = "";
+    for (const pending of this.pending_requests.values()) {
+      pending.reject(new Error("RPC client closed"));
+    }
+    this.pending_requests.clear();
+    this.fail_all_subscriptions("RPC client closed");
+    if (!socket) return;
+    await new Promise<void>((resolve) => {
+      socket.end(() => resolve());
+    });
+  }
+
+  private async request<TData = unknown>(input: {
+    method: RpcClientRequest["method"];
+    params?: unknown;
+  }): Promise<TData> {
+    await this.ensure_connected();
+    const socket = this.socket;
+    if (!socket) {
+      throw new Error("RPC socket is not connected");
+    }
+    const id = `rpc_${Date.now()}_${this.request_sequence += 1}`;
+    const request = (
+      input.params === undefined
+        ? {
+            id,
+            method: input.method,
+          }
+        : {
+            id,
+            method: input.method,
+            params: input.params as never,
+          }
+    ) as RpcClientRequest;
+    const result = await new Promise<TData>((resolve, reject) => {
+      this.pending_requests.set(id, { resolve, reject });
+      socket.write(`${JSON.stringify(request)}\n`, (error) => {
+        if (!error) return;
+        this.pending_requests.delete(id);
+        reject(error);
+      });
+    });
+    return result;
+  }
+
+  private async ensure_connected(): Promise<void> {
+    if (this.socket && !this.socket.destroyed) return;
+    if (this.connect_promise) {
+      await this.connect_promise;
+      return;
+    }
+
+    this.connect_promise = new Promise<void>((resolve, reject) => {
+      const socket = net.createConnection({
+        host: this.endpoint.host,
+        port: this.endpoint.port,
+      });
+
+      socket.setEncoding("utf8");
+
+      socket.on("connect", () => {
+        this.socket = socket;
+        resolve();
+      });
+
+      socket.on("data", (chunk: string) => {
+        this.consume_data(chunk);
+      });
+
+      socket.on("error", (error) => {
+        if (!this.socket) {
+          reject(error);
+          return;
+        }
+        this.fail_all_pending(error);
+        this.fail_all_subscriptions(
+          error instanceof Error ? error.message : String(error),
+        );
+      });
+
+      socket.on("close", () => {
+        this.socket = null;
+        this.connect_promise = null;
+        this.fail_all_pending(new Error("RPC socket closed"));
+        this.fail_all_subscriptions("RPC socket closed");
+      });
+    });
+
+    try {
+      await this.connect_promise;
+    } catch (error) {
+      this.connect_promise = null;
+      throw error;
+    }
+  }
+
+  private consume_data(chunk: string): void {
+    this.buffered += chunk;
+    let newline_index = this.buffered.indexOf("\n");
+    while (newline_index >= 0) {
+      const line = this.buffered.slice(0, newline_index).trim();
+      this.buffered = this.buffered.slice(newline_index + 1);
+      if (line) {
+        this.consume_line(line);
+      }
+      newline_index = this.buffered.indexOf("\n");
+    }
+  }
+
+  private consume_line(line: string): void {
+    const payload = JSON.parse(line) as RpcResponseFrame | RpcReadyFrame | RpcEventFrame;
+    if ("type" in payload && payload.type === "ready") {
+      const subscription = this.subscriptions.get(payload.subscriptionId);
+      subscription?.on_ready();
+      return;
+    }
+    if ("type" in payload && payload.type === "event") {
+      const subscription = this.subscriptions.get(payload.subscriptionId);
+      subscription?.on_event(payload.event);
+      return;
+    }
+    const pending = this.pending_requests.get(payload.id);
+    if (!pending) return;
+    this.pending_requests.delete(payload.id);
+    if (payload.success) {
+      pending.resolve(payload.data);
+      return;
+    }
+    pending.reject(new Error(String(payload.error || "RPC request failed")));
+  }
+
+  private fail_all_pending(error: unknown): void {
+    for (const pending of this.pending_requests.values()) {
+      pending.reject(error);
+    }
+    this.pending_requests.clear();
+  }
+
+  private fail_all_subscriptions(message: string): void {
+    for (const subscription of this.subscriptions.values()) {
+      subscription.on_event({
+        type: "error",
+        message,
+      });
+    }
+    this.subscriptions.clear();
+  }
+}
+
+/**
+ * 解析 rpc url。
+ */
+export function parse_rpc_url(url_input: string): RpcClientEndpoint {
+  const url = new URL(url_input);
+  if (url.protocol !== "rpc:") {
+    throw new Error(`Unsupported RPC protocol: ${url.protocol}`);
+  }
+  const host = String(url.hostname || "").trim();
+  const port = Number.parseInt(String(url.port || ""), 10);
+  if (!host) {
+    throw new Error("RPC url requires a host");
+  }
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    throw new Error("RPC url requires a valid port");
+  }
+  return {
+    host,
+    port,
+  };
+}