@downcity/agent 1.1.337 → 1.1.399

package/src/city/transport/rpc/CityRPC.ts

@@ -0,0 +1,138 @@
+/**
+ * CityRPC：在一个原生 TCP RPC Server 上暴露 City 持有的全部 Agent。
+ *
+ * 请求必须携带 `agent_id` 与 `workspace_id`。`RemoteAgent` 会从
+ * `rpc://host:port/<agent_id>/<workspace_id>` 自动解析并附加字段。
+ */
+
+import type { AgentSessions } from "@/index.js";
+import type { AgentSessionCollection } from "@/types/agent/AgentSessionCollection.js";
+import type { City } from "@/city/runtime/City.js";
+import { start_rpc_server, type RpcServerInstance } from "@/city/transport/rpc/RpcServer.js";
+import type {
+  AgentRpcBinding,
+  AgentRpcListenOptions,
+} from "@/city/transport/types/AgentRpcBinding.js";
+import type { CityRpcRuntimeOptions } from "@/city/transport/types/CityRpcRuntime.js";
+import { SerializedTransport } from "@/city/transport/SerializedTransport.js";
+
+const DEFAULT_RPC_HOST = "127.0.0.1";
+const DEFAULT_RPC_PORT = 15314;
+
+/** 在单一 RPC 端口暴露 City 的多 Agent transport。 */
+export class CityRPC {
+  private readonly city: City;
+  private readonly runtime_options: CityRpcRuntimeOptions;
+  /** 当前 City RPC Server 的唯一串行生命周期。 */
+  private readonly lifecycle: SerializedTransport<
+    AgentRpcListenOptions | undefined,
+    RpcServerInstance,
+    AgentRpcBinding
+  >;
+
+  constructor(city: City, runtime_options: CityRpcRuntimeOptions = {}) {
+    this.city = city;
+    this.runtime_options = runtime_options;
+    this.lifecycle = new SerializedTransport({
+      start: async (options) => await this.start_server(options),
+      stop: async (instance) => await instance.stop(),
+    });
+  }
+
+  /** 监听 City 级 RPC 端口。 */
+  async listen(options?: AgentRpcListenOptions): Promise<AgentRpcBinding> {
+    return await this.lifecycle.listen(options);
+  }
+
+  /** 创建并启动 City RPC Server。 */
+  private async start_server(options?: AgentRpcListenOptions): Promise<{
+    /** 已启动的底层 RPC Server。 */
+    resource: RpcServerInstance;
+    /** 当前 RPC 监听地址。 */
+    binding: AgentRpcBinding;
+  }> {
+      const host = String(options?.host || DEFAULT_RPC_HOST).trim() || DEFAULT_RPC_HOST;
+      const port = Number.isInteger(options?.port) ? Number(options?.port) : DEFAULT_RPC_PORT;
+      const unavailable_sessions = create_unavailable_sessions() as unknown as AgentSessionCollection;
+      const instance = await start_rpc_server({
+        host,
+        port,
+        sessions: unavailable_sessions,
+        resolve_request_options: async (request) => {
+          if (
+            request.method === "internal.city.status"
+            || request.method === "internal.city.shutdown"
+          ) {
+            return {
+              sessions: unavailable_sessions,
+              get_city_status: () => ({
+                agent_ids: this.city.agents.list().map((agent) => agent.id),
+              }),
+              shutdown_city: this.runtime_options.shutdown,
+            };
+          }
+          const agent_id = String(request.agent_id || "").trim();
+          if (!agent_id) throw new Error("CityRPC request requires agent_id");
+          const workspace_id = String(request.workspace_id || "").trim();
+          if (!workspace_id) throw new Error("CityRPC request requires workspace_id");
+          const workspace_entry = await this.city.enter_workspace(agent_id, workspace_id);
+          const agent = this.city.agents.get(agent_id);
+          if (!agent) throw new Error(`Agent not found: ${agent_id}`);
+          const sessions = workspace_entry.sessions;
+          const resolve_session_model = this.runtime_options.resolve_session_model;
+          const reload_workspace_env = this.runtime_options.reload_workspace_env;
+          return {
+            sessions,
+            get_agent_context: () => ({
+              agent,
+              workspace: workspace_entry.workspace,
+              sessions,
+              plugins: workspace_entry.plugins,
+              list_plugin_states: () => workspace_entry.list_plugin_states(),
+              resolve_system_messages: async (input) => await workspace_entry.resolve_system_messages(input),
+            }),
+            resolve_session_model: resolve_session_model
+              ? async (model_id) => await resolve_session_model(
+                  agent_id,
+                  workspace_id,
+                  model_id,
+                )
+              : undefined,
+            reload_workspace_env: reload_workspace_env
+              ? async () => await reload_workspace_env(agent_id, workspace_id)
+              : undefined,
+            shutdown_city: this.runtime_options.shutdown,
+          };
+        },
+      });
+    return {
+      resource: instance,
+      binding: { url: instance.url, host: instance.host, port: instance.port },
+    };
+  }
+
+  /** 幂等关闭 RPC Server 与全部长连接。 */
+  async close(): Promise<void> {
+    await this.lifecycle.close();
+  }
+
+  /** 返回当前绑定；尚未监听时返回 null。 */
+  binding(): AgentRpcBinding | null {
+    return this.lifecycle.binding();
+  }
+}
+
+/** 空 City 中拒绝 Agent SDK 请求的 Session 集合。 */
+function create_unavailable_sessions(): AgentSessions {
+  const unavailable = async (): Promise<never> => {
+    throw new Error("City has no Agents");
+  };
+  return {
+    create: unavailable,
+    get: unavailable,
+    list: unavailable,
+    archive: unavailable,
+    archived: unavailable,
+    clean_archive: unavailable,
+  };
+}

package/src/city/transport/rpc/RpcServer.ts

@@ -0,0 +1,158 @@
+/**
+ * Agent 本机 RPC server 网络层。
+ *
+ * 职责说明（中文）
+ * - 为本机 `RemoteAgent(rpc://...)` 与 downcity runtime 提供 Agent RPC 入口。
+ * - 只负责 TCP/NDJSON framing、socket 生命周期与订阅清理。
+ * - 具体 `sdk.*` / `internal.*` 方法由 server handlers 承接。
+ */
+
+import net from "node:net";
+import type {
+  RpcRequest,
+  RpcServerFrame,
+} from "@/city/transport/types/RpcProtocol.js";
+import type {
+  RpcServerStartOptions,
+  RpcSocketSubscription,
+} from "@/city/transport/rpc/server/ServerTypes.js";
+import { dispatch_rpc_request } from "@/city/transport/rpc/server/RequestDispatcher.js";
+
+/**
+ * RPC server 运行实例。
+ */
+export interface RpcServerInstance {
+  /** 当前监听 host。 */
+  host: string;
+  /** 当前监听 port。 */
+  port: number;
+  /** 当前访问 URL。 */
+  url: string;
+  /** 原生 net server。 */
+  server: net.Server;
+  /** 停止当前服务。 */
+  stop(): Promise<void>;
+}
+
+/**
+ * 启动 Agent 本机 RPC server。
+ */
+export async function start_rpc_server(
+  options: RpcServerStartOptions,
+): Promise<RpcServerInstance> {
+  const sockets = new Set<net.Socket>();
+  const server = net.createServer((socket) => {
+    sockets.add(socket);
+    const subscriptions = new Map<string, RpcSocketSubscription>();
+    let buffered = "";
+
+    const cleanup_subscriptions = (): void => {
+      for (const subscription of subscriptions.values()) {
+        subscription.unsubscribe();
+      }
+      subscriptions.clear();
+    };
+
+    const write_frame = (frame: RpcServerFrame): void => {
+      socket.write(`${JSON.stringify(frame)}\n`);
+    };
+
+    const write_success = (id: string, data?: unknown): void => {
+      write_frame({
+        id,
+        success: true,
+        ...(data === undefined ? {} : { data }),
+      });
+    };
+
+    const write_error = (id: string, error: unknown): void => {
+      write_frame({
+        id,
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    };
+
+    const handle_line = async (line: string): Promise<void> => {
+      let request: RpcRequest;
+      try {
+        request = JSON.parse(line) as RpcRequest;
+      } catch (error) {
+        write_error("parse", error);
+        return;
+      }
+      try {
+        const request_options = await options.resolve_request_options?.(request) ?? options;
+        await dispatch_rpc_request({
+          request,
+          options: request_options,
+          subscriptions,
+          write_success,
+          write_error,
+          write_event: write_frame,
+        });
+      } catch (error) {
+        write_error(request.id, error);
+      }
+    };
+
+    socket.on("data", (chunk) => {
+      buffered += chunk.toString("utf8");
+      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) {
+          void handle_line(line);
+        }
+        newline_index = buffered.indexOf("\n");
+      }
+    });
+
+    socket.on("error", () => {
+      cleanup_subscriptions();
+    });
+    socket.on("close", () => {
+      sockets.delete(socket);
+      cleanup_subscriptions();
+    });
+    socket.on("end", () => {
+      cleanup_subscriptions();
+    });
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    const on_error = (error: Error): void => {
+      server.off("error", on_error);
+      // 启动失败的 Server 不会交给 RpcServerInstance，必须在这里收口。
+      try {
+        server.close();
+      } catch {
+        // 未进入监听态时 close 可能抛出 ERR_SERVER_NOT_RUNNING，可安全忽略。
+      }
+      reject(error);
+    };
+    server.once("error", on_error);
+    server.listen(options.port, options.host, () => {
+      server.off("error", on_error);
+      resolve();
+    });
+  });
+
+  return {
+    host: options.host,
+    port: options.port,
+    url: `rpc://${options.host}:${options.port}`,
+    server,
+    async stop(): Promise<void> {
+      // 关键点（中文）：RPC 是长连接；停止 server 时必须主动关闭现有 socket。
+      for (const socket of sockets) {
+        socket.destroy();
+      }
+      sockets.clear();
+      await new Promise<void>((resolve) => {
+        server.close(() => resolve());
+      });
+    },
+  };
+}

package/src/city/transport/rpc/server/InternalHandlers.ts

@@ -0,0 +1,223 @@
+/**
+ * RPC internal handlers。
+ *
+ * 关键点（中文）
+ * - 只处理 `internal.*` 方法。
+ * - 这些方法服务 downcity 本机管理通道，不属于 RemoteAgent 的用户 SDK 面。
+ * - Session 与 Plugin 数据通过 Agent 能力操作，不读取领域内部路径。
+ */
+
+import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
+import type { RpcRequest } from "@/city/transport/types/RpcProtocol.js";
+import type {
+  RpcRequestHandlerOptions,
+  RpcAgentContext,
+  RpcWriteSuccess,
+} from "@/city/transport/rpc/server/ServerTypes.js";
+
+/**
+ * 处理 internal RPC 请求。
+ */
+export async function handle_internal_rpc_request(params: {
+  /** 当前 RPC 请求。 */
+  request: RpcRequest;
+  /** handler 依赖。 */
+  options: RpcRequestHandlerOptions;
+  /** 成功帧写入函数。 */
+  write_success: RpcWriteSuccess;
+}): Promise<boolean> {
+  const { request, options, write_success } = params;
+
+  switch (request.method) {
+    case "internal.city.status": {
+      if (!options.get_city_status) {
+        throw new Error("RPC host does not provide City status");
+      }
+      write_success(request.id, {
+        status: "ok",
+        pid: process.pid,
+        agent_ids: options.get_city_status().agent_ids,
+        instance_id: String(process.env.DOWNCITY_DAEMON_INSTANCE_ID || "").trim(),
+      });
+      return true;
+    }
+    case "internal.city.shutdown": {
+      if (!options.shutdown_city) throw new Error("RPC host does not provide City shutdown");
+      write_success(request.id, { accepted: true });
+      setImmediate(() => void options.shutdown_city?.());
+      return true;
+    }
+    case "internal.status.get": {
+      const context = requireAgent(options);
+      write_success(request.id, {
+        status: "ok",
+        pid: process.pid,
+        agent_id: context.agent.id,
+        workspace_id: context.workspace.id,
+        workspace_path: context.workspace.path,
+        instance_id: String(process.env.DOWNCITY_DAEMON_INSTANCE_ID || "").trim(),
+      });
+      return true;
+    }
+    case "internal.workspace.reload_env": {
+      if (!options.reload_workspace_env) {
+        throw new Error("Agent RPC host does not provide Workspace Env reload");
+      }
+      const env = await options.reload_workspace_env();
+      write_success(request.id, {
+        reloaded: true,
+        key_count: Object.keys(env).length,
+      });
+      return true;
+    }
+    case "internal.sessions.clear_messages": {
+      const context = requireAgent(options);
+      const session_id = String(request.params.session_id || "").trim();
+      if (!session_id) throw new Error("Missing session_id");
+      await context.sessions.clear_messages(session_id);
+      write_success(request.id, {
+        session_id: session_id,
+        cleared: true,
+      });
+      return true;
+    }
+    case "internal.sessions.clear_chat_history": {
+      const context = requireAgent(options);
+      const session_id = String(request.params.session_id || "").trim();
+      if (!session_id) throw new Error("Missing session_id");
+      const result = await context.plugins.run_action({
+        plugin: "chat",
+        action: "history_clear",
+        payload: { session_id: session_id },
+      });
+      if (!result.success) {
+        throw new Error(result.error || result.message || "Chat history clear failed");
+      }
+      const data = result.data && typeof result.data === "object"
+        ? result.data as { cleared?: unknown }
+        : {};
+      write_success(request.id, {
+        session_id: session_id,
+        cleared: data.cleared === true,
+      });
+      return true;
+    }
+    case "internal.sessions.resolve_system_prompt": {
+      const context = requireAgent(options);
+      const session_id =
+        String(request.params.session_id || "").trim() || "consoleui-chat-main";
+      const system_messages = await context.resolve_system_messages({
+        session_id,
+        profile: "chat",
+      });
+      write_success(request.id, {
+        session_id: session_id,
+        ...toSystemPromptPayload(system_messages),
+      });
+      return true;
+    }
+    case "internal.plugins.catalog": {
+      const context = requireAgent(options);
+      write_success(request.id, {
+        plugins: context.plugins.list(),
+      });
+      return true;
+    }
+    case "internal.plugins.list": {
+      const context = requireAgent(options);
+      write_success(request.id, {
+        plugins: context.list_plugin_states(),
+      });
+      return true;
+    }
+    case "internal.plugins.availability": {
+      const context = requireAgent(options);
+      const availability = await context.plugins.availability(
+        request.params.plugin_name,
+      );
+      write_success(request.id, {
+        plugin_name: request.params.plugin_name,
+        availability,
+      });
+      return true;
+    }
+    case "internal.plugins.action": {
+      const context = requireAgent(options);
+      const result = await context.plugins.run_action({
+        plugin: request.params.plugin_name,
+        action: request.params.action_name,
+        payload: request.params.payload,
+      });
+      write_success(request.id, {
+        ...result,
+        plugin_name: request.params.plugin_name,
+        action_name: request.params.action_name,
+      });
+      return true;
+    }
+    default:
+      return false;
+  }
+}
+
+function requireAgent(options: RpcRequestHandlerOptions): RpcAgentContext {
+  const context = options.get_agent_context?.();
+  if (!context) {
+    throw new Error("Agent RPC server was started without Agent");
+  }
+  return context;
+}
+
+function normalizeSystemText(input: string | null | undefined): string {
+  return String(input || "").trim();
+}
+
+function toSystemMessageText(message: SessionSystemMessage): string {
+  const content = message.content as unknown;
+  if (typeof content === "string") return normalizeSystemText(content);
+  if (!Array.isArray(content)) return "";
+  const parts = content as Array<{ text?: unknown }>;
+  const texts: string[] = [];
+  for (const part of parts) {
+    if (!part || typeof part !== "object") continue;
+    const text = normalizeSystemText(String(part.text || ""));
+    if (!text) continue;
+    texts.push(text);
+  }
+  return texts.join("\n").trim();
+}
+
+/**
+ * 把 system messages 转成 Console/downcity 可直接渲染的结构。
+ */
+function toSystemPromptPayload(messages: SessionSystemMessage[]): {
+  sections: Array<{
+    key: string;
+    title: string;
+    items: Array<{ index: number; content: string }>;
+  }>;
+  total_messages: number;
+  total_chars: number;
+} {
+  const items = messages
+    .map((message, index) => ({
+      index: index + 1,
+      content: toSystemMessageText(message),
+    }))
+    .filter((item) => item.content);
+  const total_chars = items.reduce(
+    (acc, item) => acc + String(item.content || "").length,
+    0,
+  );
+  return {
+    sections: [
+      {
+        key: "resolved",
+        title: "Resolved System Messages",
+        items,
+      },
+    ],
+    total_messages: items.length,
+    total_chars,
+  };
+}

package/src/city/transport/rpc/server/RequestDispatcher.ts

@@ -0,0 +1,67 @@
+/**
+ * RPC request dispatcher。
+ *
+ * 关键点（中文）
+ * - server.ts 不直接包含业务 switch，只负责把已解析请求交给这里。
+ * - dispatcher 按命名空间分发，避免 SDK 与 downcity internal 方法混在一起。
+ */
+
+import type { RpcRequest } from "@/city/transport/types/RpcProtocol.js";
+import type {
+  RpcRequestHandlerOptions,
+  RpcSocketSubscription,
+  RpcWriteError,
+  RpcWriteEvent,
+  RpcWriteSuccess,
+} from "@/city/transport/rpc/server/ServerTypes.js";
+import { handle_sdk_session_rpc_request } from "@/city/transport/rpc/server/SdkSessionHandlers.js";
+import { handle_internal_rpc_request } from "@/city/transport/rpc/server/InternalHandlers.js";
+
+/**
+ * 分发并执行单个 RPC 请求。
+ */
+export async function dispatch_rpc_request(params: {
+  /** 当前 RPC 请求。 */
+  request: RpcRequest;
+  /** handler 依赖。 */
+  options: RpcRequestHandlerOptions;
+  /** 当前 socket 的订阅表。 */
+  subscriptions: Map<string, RpcSocketSubscription>;
+  /** 成功帧写入函数。 */
+  write_success: RpcWriteSuccess;
+  /** 失败帧写入函数。 */
+  write_error: RpcWriteError;
+  /** 事件帧写入函数。 */
+  write_event: RpcWriteEvent;
+}): Promise<void> {
+  const {
+    request,
+    options,
+    subscriptions,
+    write_success,
+    write_error,
+    write_event,
+  } = params;
+
+  try {
+    const handled_by_sdk = await handle_sdk_session_rpc_request({
+      request,
+      options,
+      subscriptions,
+      write_success,
+      write_event,
+    });
+    if (handled_by_sdk) return;
+
+    const handled_by_internal = await handle_internal_rpc_request({
+      request,
+      options,
+      write_success,
+    });
+    if (handled_by_internal) return;
+
+    throw new Error(`Unsupported RPC method: ${request.method}`);
+  } catch (error) {
+    write_error(request.id, error);
+  }
+}