@downcity/agent 1.1.43 → 1.1.51

package/src/rpc/Server.ts

@@ -0,0 +1,302 @@
+/**
+ * Agent 本机 RPC Server。
+ *
+ * 职责说明（中文）
+ * - 为本机 `RemoteAgent(rpc://...)` 提供最小 SDK 会话访问面。
+ * - 当前只承载 Session actor 所需方法，不混入控制台 HTTP 语义。
+ * - 协议使用逐行 JSON（NDJSON），便于调试与事件流推送。
+ */
+
+import net from "node:net";
+import type {
+  AgentListSessionsInput,
+  AgentSessionCollection,
+} from "@/types/agent/AgentTypes.js";
+import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
+import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
+
+type RpcSessionRequest =
+  | {
+      id: string;
+      method: "sdk.sessions.list";
+      params?: AgentListSessionsInput;
+    }
+  | {
+      id: string;
+      method: "sdk.sessions.create";
+      params?: {
+        sessionId?: string;
+      };
+    }
+  | {
+      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?: {
+          limit?: number;
+          cursor?: string;
+          order?: "asc" | "desc";
+          view?: "message" | "timeline";
+        };
+      };
+    }
+  | {
+      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 RpcSuccessFrame = {
+  id: string;
+  success: true;
+  data?: unknown;
+};
+
+type RpcErrorFrame = {
+  id: string;
+  success: false;
+  error: string;
+};
+
+type RpcEventFrame = {
+  type: "event";
+  subscriptionId: string;
+  event: AgentSessionEvent;
+};
+
+type SocketSubscription = {
+  sessionId: string;
+  unsubscribe: () => void;
+};
+
+/**
+ * RPC Server 启动参数。
+ */
+export interface RpcServerStartOptions {
+  /** RPC 服务监听端口。 */
+  port: number;
+  /** RPC 服务监听主机。 */
+  host: string;
+  /** Session 集合访问口。 */
+  sessionCollection: AgentSessionCollection;
+}
+
+/**
+ * RPC Server 运行实例。
+ */
+export interface RpcServerInstance {
+  /** 当前监听 host。 */
+  host: string;
+  /** 当前监听 port。 */
+  port: number;
+  /** 当前访问 URL。 */
+  url: string;
+  /** 原生 net server。 */
+  server: net.Server;
+  /** 停止当前服务。 */
+  stop(): Promise<void>;
+}
+
+/**
+ * 启动 Agent 本机 RPC 服务。
+ */
+export async function startRpcServer(
+  options: RpcServerStartOptions,
+): Promise<RpcServerInstance> {
+  const server = net.createServer((socket) => {
+    const subscriptions = new Map<string, SocketSubscription>();
+    let buffered = "";
+
+    const cleanupSubscriptions = (): void => {
+      for (const subscription of subscriptions.values()) {
+        subscription.unsubscribe();
+      }
+      subscriptions.clear();
+    };
+
+    const writeFrame = (frame: RpcSuccessFrame | RpcErrorFrame | RpcEventFrame): void => {
+      socket.write(`${JSON.stringify(frame)}\n`);
+    };
+
+    const writeSuccess = (id: string, data?: unknown): void => {
+      writeFrame({
+        id,
+        success: true,
+        ...(data === undefined ? {} : { data }),
+      });
+    };
+
+    const writeError = (id: string, error: unknown): void => {
+      writeFrame({
+        id,
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    };
+
+    const handleRequest = async (request: RpcSessionRequest): Promise<void> => {
+      try {
+        switch (request.method) {
+          case "sdk.sessions.list": {
+            const page = await options.sessionCollection.listSessions(request.params);
+            writeSuccess(request.id, { page });
+            return;
+          }
+          case "sdk.sessions.create": {
+            const session = await options.sessionCollection.createSession(request.params);
+            writeSuccess(request.id, { session: await session.getInfo() });
+            return;
+          }
+          case "sdk.sessions.get": {
+            const session = await options.sessionCollection.getSession(request.params.sessionId);
+            writeSuccess(request.id, { session: await session.getInfo() });
+            return;
+          }
+          case "sdk.sessions.prompt": {
+            const session = await options.sessionCollection.getSession(request.params.sessionId);
+            const turn = await session.prompt(request.params.input);
+            writeSuccess(request.id, { turn: { id: turn.id } });
+            return;
+          }
+          case "sdk.sessions.history": {
+            const session = await options.sessionCollection.getSession(request.params.sessionId);
+            const history = await session.history(request.params.input);
+            writeSuccess(request.id, { history });
+            return;
+          }
+          case "sdk.sessions.system": {
+            const session = await options.sessionCollection.getSession(request.params.sessionId);
+            writeSuccess(request.id, { system: await session.system() });
+            return;
+          }
+          case "sdk.sessions.fork": {
+            const session = await options.sessionCollection.getSession(request.params.sessionId);
+            const forked = await session.fork(request.params.messageId);
+            writeSuccess(request.id, { session: await forked.getInfo() });
+            return;
+          }
+          case "sdk.sessions.subscribe": {
+            const session = await options.sessionCollection.getSession(request.params.sessionId);
+            const subscriptionId = `${request.params.sessionId}:${Date.now()}:${Math.random().toString(36).slice(2, 10)}`;
+            const unsubscribe = session.subscribe((event) => {
+              writeFrame({
+                type: "event",
+                subscriptionId,
+                event,
+              });
+            });
+            subscriptions.set(subscriptionId, {
+              sessionId: request.params.sessionId,
+              unsubscribe,
+            });
+            writeSuccess(request.id, { subscriptionId });
+            return;
+          }
+          case "sdk.sessions.unsubscribe": {
+            const subscription = subscriptions.get(request.params.subscriptionId);
+            if (subscription) {
+              subscription.unsubscribe();
+              subscriptions.delete(request.params.subscriptionId);
+            }
+            writeSuccess(request.id, { unsubscribed: true });
+            return;
+          }
+        }
+      } catch (error) {
+        writeError(request.id, error);
+      }
+    };
+
+    socket.on("data", (chunk) => {
+      buffered += chunk.toString("utf8");
+      let newlineIndex = buffered.indexOf("\n");
+      while (newlineIndex >= 0) {
+        const line = buffered.slice(0, newlineIndex).trim();
+        buffered = buffered.slice(newlineIndex + 1);
+        if (line) {
+          try {
+            const parsed = JSON.parse(line) as RpcSessionRequest;
+            void handleRequest(parsed);
+          } catch (error) {
+            writeFrame({
+              id: "parse",
+              success: false,
+              error: error instanceof Error ? error.message : String(error),
+            });
+          }
+        }
+        newlineIndex = buffered.indexOf("\n");
+      }
+    });
+
+    socket.on("error", () => {
+      cleanupSubscriptions();
+    });
+    socket.on("close", () => {
+      cleanupSubscriptions();
+    });
+    socket.on("end", () => {
+      cleanupSubscriptions();
+    });
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(options.port, options.host, () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+
+  return {
+    host: options.host,
+    port: options.port,
+    url: `rpc://${options.host}:${options.port}`,
+    server,
+    async stop(): Promise<void> {
+      await new Promise<void>((resolve) => {
+        server.close(() => resolve());
+      });
+    },
+  };
+}

package/src/runtime/host/daemon/Api.ts

@@ -39,7 +39,7 @@ export type DaemonJsonApiCallParams = {
    * 单次调用超时（毫秒）。
    *
    * 说明（中文）
-   * - 仅本地 IPC transport 当前会消费该参数。
+   * - HTTP daemon client 可消费该参数。
    * - 用于 `session execute`、`plugin command` 这类可能持续几十秒的请求，
    *   避免被默认短超时误判成“Agent server 未启动”。
    */

package/src/runtime/host/daemon/Client.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 业务模块统一通过 daemon API 与运行时通信。
- * - 地址解析优先级：CLI 参数 > 环境变量 > daemon meta > 默认值。
+ * - HTTP gateway 与本机 RPC 的地址解析分开，避免端口语义混淆。
  */
 
 import fs from "fs-extra";
@@ -62,29 +62,27 @@ function pickArgValue(args: string[], key: string): string | undefined {
   return next || undefined;
 }
 
-/**
- * 解析 daemon endpoint。
- *
- * 优先级（中文）
- * 1) 显式入参 `host/port`
- * 2) 环境变量 `DC_SERVER_*` / `DC_CTX_SERVER_*`
- * 3) daemon meta args（`downcity.daemon.json`）
- * 4) 默认 `127.0.0.1:5314`
- */
-function resolveDaemonEndpoint(params: {
+type ResolveDaemonEndpointParams = {
   projectRoot: string;
   host?: string;
   port?: number;
+};
+
+function resolveDaemonEndpointFromSources(params: {
+  projectRoot: string;
+  explicit_host?: string;
+  explicit_port?: number;
+  env_host_name: string;
+  env_port_name: string;
+  arg_port_name: string;
+  default_host: string;
+  default_port: number;
 }): DaemonEndpoint {
-  const explicitHost = normalizeHost(params.host);
-  const explicitPort = parsePortLike(params.port);
+  const explicitHost = normalizeHost(params.explicit_host);
+  const explicitPort = parsePortLike(params.explicit_port);
 
-  const envHost =
-    normalizeHost(process.env.DC_SERVER_HOST) ||
-    normalizeHost(process.env.DC_CTX_SERVER_HOST);
-  const envPort =
-    parsePortLike(process.env.DC_SERVER_PORT) ||
-    parsePortLike(process.env.DC_CTX_SERVER_PORT);
+  const envHost = normalizeHost(process.env[params.env_host_name]);
+  const envPort = parsePortLike(process.env[params.env_port_name]);
 
   let daemonArgHost: string | undefined;
   let daemonArgPort: number | undefined;
@@ -96,14 +94,14 @@ function resolveDaemonEndpoint(params: {
         ? raw.args.map((item) => String(item))
         : [];
       daemonArgHost = normalizeHost(pickArgValue(args, "--host"));
-      daemonArgPort = parsePortLike(pickArgValue(args, "--port"));
+      daemonArgPort = parsePortLike(pickArgValue(args, params.arg_port_name));
     }
   } catch {
     // ignore daemon meta errors, fallback to other sources
   }
 
-  const host = explicitHost || envHost || daemonArgHost || "127.0.0.1";
-  const port = explicitPort || envPort || daemonArgPort || 5314;
+  const host = explicitHost || envHost || daemonArgHost || params.default_host;
+  const port = explicitPort || envPort || daemonArgPort || params.default_port;
 
   return {
     host,
@@ -112,6 +110,30 @@ function resolveDaemonEndpoint(params: {
   };
 }
 
+/**
+ * 解析 daemon endpoint。
+ *
+ * 优先级（中文）
+ * 1) 显式入参 `host/port`
+ * 2) 环境变量 `DC_CITY_HOST/DC_CITY_PORT`
+ * 3) daemon meta args（`downcity.daemon.json`）
+ * 4) 默认 `127.0.0.1:5314`
+ */
+function resolveDaemonEndpoint(
+  params: ResolveDaemonEndpointParams,
+): DaemonEndpoint {
+  return resolveDaemonEndpointFromSources({
+    projectRoot: params.projectRoot,
+    explicit_host: params.host,
+    explicit_port: params.port,
+    env_host_name: "DC_CITY_HOST",
+    env_port_name: "DC_CITY_PORT",
+    arg_port_name: "--port",
+    default_host: "127.0.0.1",
+    default_port: 5314,
+  });
+}
+
 /**
  * 调用 daemon JSON API。
  *

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

@@ -82,7 +82,7 @@ export function registerControlOverviewRoutes(
           cityVersion: DC_VERSION,
           now: new Date().toISOString(),
           agent: {
-            name: runtime.config.name,
+            id: runtime.config.id,
             status: "running",
           },
           sessions: {

package/src/session/index.ts

@@ -10,7 +10,6 @@ export { Session } from "./Session.js";
 
 export {
   getSdkAgentDirPath,
-  getSdkAgentRpcEndpointPath,
   getSdkAgentSessionArchiveDirPath,
   getSdkAgentSessionDirPath,
   getSdkAgentSessionMessagesDirPath,

package/src/session/storage/Paths.ts

@@ -114,13 +114,3 @@ export function getSdkAgentSessionArchiveDirPath(
     "archive",
   );
 }
-
-/**
- * 单个 agent 的本地 RPC socket 路径。
- */
-export function getSdkAgentRpcEndpointPath(
-  projectRoot: string,
-  agentId: string,
-): string {
-  return path.join(getSdkAgentDirPath(projectRoot, agentId), "agent.rpc.sock");
-}

package/src/types/agent/AgentTypes.ts

@@ -9,8 +9,7 @@
 
 import type { LanguageModel, Tool } from "ai";
 import type { BasePlugin } from "@/plugin/core/BasePlugin.js";
-import type { LocalRpcServerHandle } from "@/types/runtime/rpc/LocalRpc.js";
-import type { ServerInstance } from "@/runtime/server/http/Server.js";
+import type { RpcServerInstance } from "@/rpc/Server.js";
 import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
 import type {
   AgentSessionSubscriber,
@@ -77,12 +76,12 @@ export interface AgentOptions {
   plugins?: BasePlugin[];
 
   /**
-   * 当前 agent 实例可见的环境变量快照。
+   * 当前 agent 的显式环境变量覆盖项。
    *
    * 关键点（中文）
-   * - 这里传入的是已经在宿主侧完成合并的最终环境变量集合。
-   * - SDK 不再区分 global env 与 agent env；如需区分，应由更上层在传入前自行处理。
-   * - 该快照会参与配置解析与运行时上下文装配，但不会回写到宿主环境。
+   * - 这里表示宿主显式注入给 agent 的基础 env。
+   * - `Agent` 会在这份基础 env 之上继续叠加项目 `.env`。
+   * - 覆盖后的最终 env 会参与配置解析与运行时上下文装配，但不会回写到宿主环境。
    */
   env?: Record<string, string>;
 
@@ -93,23 +92,14 @@ export interface AgentOptions {
  */
 export interface AgentStartOptions {
   /**
-   * 是否启动 HTTP 服务。
+   * 是否启动本机 RPC 服务。
    *
    * 关键点（中文）
    * - `false` 表示不启动。
    * - 传对象时会按给定 host/port 启动。
    * - 省略时默认不启动，避免 SDK 本地嵌入场景误开端口。
    */
-  http?: false | AgentHttpStartOptions;
-
-  /**
-   * 是否启动本地 RPC 服务。
-   *
-   * 关键点（中文）
-   * - `true` 时启动主 local RPC server。
-   * - 省略或 `false` 时不启动。
-   */
-  rpc?: boolean;
+  rpc?: false | AgentRpcStartOptions;
 
   /**
    * 是否启动当前 agent 的 plugins。
@@ -126,12 +116,7 @@ export interface AgentStartOptions {
  */
 export interface AgentStopResult {
   /**
-   * 本次是否实际停止了 HTTP 服务。
-   */
-  httpStopped: boolean;
-
-  /**
-   * 本次是否实际停止了本地 RPC 服务。
+   * 本次是否实际停止了本机 RPC 服务。
    */
   rpcStopped: boolean;
 
@@ -146,12 +131,7 @@ export interface AgentStopResult {
  */
 export interface AgentStartResult {
   /**
-   * 当前 agent 是否已启动 HTTP 服务。
-   */
-  http?: AgentHttpBinding;
-
-  /**
-   * 当前 agent 是否已启动本地 RPC 服务。
+   * 当前 agent 是否已启动本机 RPC 服务。
    */
   rpc?: AgentRpcBinding;
 
@@ -162,28 +142,28 @@ export interface AgentStartResult {
 }
 
 /**
- * Agent HTTP 启动参数。
+ * Agent RPC 启动参数。
  */
-export interface AgentHttpStartOptions {
+export interface AgentRpcStartOptions {
   /**
-   * HTTP 监听主机。
+   * RPC 监听主机。
    */
   host?: string;
 
   /**
-   * HTTP 监听端口。
+   * RPC 监听端口。
    */
   port?: number;
 }
 
 /**
- * Agent HTTP 绑定信息。
+ * Agent RPC 绑定信息。
  */
-export interface AgentHttpBinding {
+export interface AgentRpcBinding {
   /**
-   * 对外访问地址。
+   * 远程访问地址。
    */
-  baseUrl: string;
+  url: string;
 
   /**
    * 当前 host。
@@ -196,24 +176,9 @@ export interface AgentHttpBinding {
   port: number;
 
   /**
-   * HTTP server 句柄。
-   */
-  server: ServerInstance;
-}
-
-/**
- * Agent RPC 绑定信息。
- */
-export interface AgentRpcBinding {
-  /**
-   * 当前本地 RPC endpoint。
-   */
-  endpoint: string;
-
-  /**
-   * 本地 RPC server 句柄。
+   * RPC server 句柄。
    */
-  server: LocalRpcServerHandle;
+  server: RpcServerInstance;
 }
 
 /**
@@ -221,11 +186,12 @@ export interface AgentRpcBinding {
  */
 export interface RemoteAgentOptions {
   /**
-   * 远程 SDK HTTP 基础地址。
+   * 远程 agent 访问地址。
    *
-   * 例如：`http://127.0.0.1:15314`
+   * 例如：`https://city.example.com`、`http://127.0.0.1:15314`
+   * 或 `rpc://127.0.0.1:5314`
    */
-  baseUrl: string;
+  url: string;
 }
 
 /**

package/src/types/config/AgentProject.ts

@@ -24,12 +24,13 @@ export interface AgentProjectInitializationInput {
   projectRoot: string;
 
   /**
-   * agent 展示名。
+   * agent 唯一标识。
    *
    * 关键点（中文）
-   * - 为空时会自动回退到目录名推导出的默认名称。
+   * - 为空时会自动回退到目录名推导出的默认 id。
+   * - 该字段会直接写入 `downcity.json.id`。
    */
-  agentName?: string;
+  id?: string;
 
   /**
    * 项目执行绑定配置。
@@ -71,9 +72,9 @@ export interface AgentProjectInitializationResult {
   projectRoot: string;
 
   /**
-   * 最终写入的 agent 名称。
+   * 最终写入的 agent id。
    */
-  agentName: string;
+  id: string;
 
   /**
    * 最终启用的 chat channels。