@downcity/agent 1.1.13 → 1.1.14

package/src/sdk/AgentSdkTypes.ts

@@ -13,6 +13,9 @@ 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/host/AgentHost.js";
+import type { LocalRpcServerHandle } from "@/types/rpc/LocalRpc.js";
+import type { ServerInstance } from "@/server/http/Server.js";
+import type { Session } from "@/sdk/Session.js";
 
 /**
  * 本地 Agent 构造参数。
@@ -61,6 +64,15 @@ export interface AgentOptions {
    */
   services?: BaseService[];
 
+  /**
+   * 是否自动装配全部内建 service。
+   *
+   * 关键点（中文）
+   * - 适合 city 这类宿主进程直接 `new Agent(...)` 的场景。
+   * - 未开启时，默认只使用显式传入的 `services`。
+   */
+  useBuiltinServices?: boolean;
+
   /**
    * 当前 agent 显式注册的 plugin 定义集合。
    *
@@ -71,6 +83,15 @@ export interface AgentOptions {
    */
   plugins?: Plugin[];
 
+  /**
+   * 是否自动装配全部内建 plugin。
+   *
+   * 关键点（中文）
+   * - 适合 city 这类宿主进程直接 `new Agent(...)` 的场景。
+   * - 未开启时，默认只使用显式传入的 `plugins`。
+   */
+  useBuiltinPlugins?: boolean;
+
   /**
    * 当前 agent 显式注入的平台能力集合。
    *
@@ -79,6 +100,143 @@ export interface AgentOptions {
    * - 推荐由宿主产品显式传入，避免 SDK 本地实例隐式依赖 city。
    */
   platform?: AgentPlatformRuntime;
+
+  /**
+   * 在 session 初始化后执行的宿主配置钩子。
+   *
+   * 关键点（中文）
+   * - SDK 不负责默认模型策略，宿主可在这里统一为 session 注入 model 等运行配置。
+   * - 该钩子只在 session 首次创建时触发一次，适合做实例级默认装配。
+   */
+  configureSession?: (session: Session) => Promise<void> | void;
+}
+
+/**
+ * Agent 启动参数。
+ */
+export interface AgentStartOptions {
+  /**
+   * 是否启动 HTTP 服务。
+   *
+   * 关键点（中文）
+   * - `false` 表示不启动。
+   * - 传对象时会按给定 host/port 启动。
+   * - 省略时默认不启动，避免 SDK 本地嵌入场景误开端口。
+   */
+  http?: false | AgentHttpStartOptions;
+
+  /**
+   * 是否启动本地 RPC 服务。
+   *
+   * 关键点（中文）
+   * - `true` 时启动主 local RPC server。
+   * - 省略或 `false` 时不启动。
+   */
+  rpc?: boolean;
+
+  /**
+   * 是否启动当前 agent 的 services。
+   *
+   * 关键点（中文）
+   * - 默认 `true`。
+   * - `false` 适合只需要 session 能力、不希望启动后台能力的嵌入场景。
+   */
+  services?: boolean;
+}
+
+/**
+ * Agent 停止结果快照。
+ */
+export interface AgentStopResult {
+  /**
+   * 本次是否实际停止了 HTTP 服务。
+   */
+  httpStopped: boolean;
+
+  /**
+   * 本次是否实际停止了本地 RPC 服务。
+   */
+  rpcStopped: boolean;
+
+  /**
+   * 本次是否实际停止了 services。
+   */
+  servicesStopped: boolean;
+}
+
+/**
+ * Agent 启动后的状态快照。
+ */
+export interface AgentStartResult {
+  /**
+   * 当前 agent 是否已启动 HTTP 服务。
+   */
+  http?: AgentHttpBinding;
+
+  /**
+   * 当前 agent 是否已启动本地 RPC 服务。
+   */
+  rpc?: AgentRpcBinding;
+
+  /**
+   * 当前 agent 是否已启动 services。
+   */
+  servicesStarted: boolean;
+}
+
+/**
+ * Agent HTTP 启动参数。
+ */
+export interface AgentHttpStartOptions {
+  /**
+   * HTTP 监听主机。
+   */
+  host?: string;
+
+  /**
+   * HTTP 监听端口。
+   */
+  port?: number;
+}
+
+/**
+ * Agent HTTP 绑定信息。
+ */
+export interface AgentHttpBinding {
+  /**
+   * 对外访问地址。
+   */
+  baseUrl: string;
+
+  /**
+   * 当前 host。
+   */
+  host: string;
+
+  /**
+   * 当前 port。
+   */
+  port: number;
+
+  /**
+   * HTTP server 句柄。
+   */
+  server: ServerInstance;
+}
+
+/**
+ * Agent RPC 绑定信息。
+ */
+export interface AgentRpcBinding {
+  /**
+   * 当前本地 RPC endpoint。
+   */
+  endpoint: string;
+
+  /**
+   * 本地 RPC server 句柄。
+   */
+  server: LocalRpcServerHandle;
 }
 
 /**

package/src/sdk/HttpServer.ts

@@ -2,34 +2,20 @@
  * SDK HTTP Server。
  *
  * 关键点（中文）
- * - 面向 `RemoteAgent` 暴露最小 session 能力集合。
- * - v1 先聚焦 session 创建、列表、history、run、stream、fork。
+ * - 这里承接单个 Agent 实例的主 HTTP server 生命周期。
+ * - 对外仍暴露 `RemoteAgent` 兼容的 SDK session API，同时保留完整 server 路由能力。
  */
 
-import http from "node:http";
-import { Hono } from "hono";
-import { cors } from "hono/cors";
 import type { Agent } from "@/sdk/Agent.js";
-
-type SdkHttpStartOptions = {
-  /**
-   * 监听主机。
-   */
-  host?: string;
-
-  /**
-   * 监听端口。
-   */
-  port?: number;
-};
+import type { AgentHttpBinding, AgentHttpStartOptions } from "@/sdk/AgentSdkTypes.js";
+import { startServer } from "@/server/http/Server.js";
 
 /**
  * SDK HTTP Server 管理器。
  */
 export class SdkAgentHttpServer {
   private readonly agent: Agent;
-  private server: http.Server | null = null;
-  private baseUrlValue: string | null = null;
+  private binding: AgentHttpBinding | null = null;
 
   constructor(agent: Agent) {
     this.agent = agent;
@@ -38,194 +24,43 @@ export class SdkAgentHttpServer {
   /**
    * 启动 HTTP Server。
    */
-  async start(options?: SdkHttpStartOptions): Promise<{ baseUrl: string }> {
-    if (this.server && this.baseUrlValue) {
-      return { baseUrl: this.baseUrlValue };
+  async start(options?: AgentHttpStartOptions): Promise<AgentHttpBinding> {
+    if (this.binding) {
+      return this.binding;
     }
-    await this.agent.ensureServicesStarted();
     const host = String(options?.host || "127.0.0.1").trim() || "127.0.0.1";
     const port =
       typeof options?.port === "number" && Number.isInteger(options.port)
         ? options.port
         : 15314;
-
-    const app = new Hono();
-    app.use(
-      "*",
-      cors({
-        origin: "*",
-        allowMethods: ["GET", "POST", "OPTIONS"],
-        allowHeaders: ["Content-Type"],
-      }),
-    );
-
-    app.get("/api/sdk/sessions", async (c) => {
-      return c.json({
-        success: true,
-        sessions: await this.agent.sessions(),
-      });
-    });
-
-    app.post("/api/sdk/sessions", async (c) => {
-      const body = await c.req.json().catch(() => ({}));
-      const session = await this.agent.session(
-        typeof body?.sessionId === "string" ? body.sessionId : undefined,
-      );
-      return c.json({
-        success: true,
-        session: await session.toMetadata(),
-      });
-    });
-
-    app.get("/api/sdk/sessions/:sessionId/messages", async (c) => {
-      const session = await this.agent.session(String(c.req.param("sessionId") || ""));
-      return c.json({
-        success: true,
-        sessionId: session.id,
-        messages: await session.history(),
-      });
-    });
-
-    app.get("/api/sdk/sessions/:sessionId/system", async (c) => {
-      const session = await this.agent.session(String(c.req.param("sessionId") || ""));
-      return c.json({
-        success: true,
-        sessionId: session.id,
-        system: await session.system(),
-      });
-    });
-
-    app.post("/api/sdk/sessions/:sessionId/run", async (c) => {
-      const session = await this.agent.session(String(c.req.param("sessionId") || ""));
-      const body = await c.req.json().catch(() => ({}));
-      const query = String(body?.query || "").trim();
-      if (!query) {
-        return c.json({ success: false, error: "query is required" }, 400);
-      }
-      const result = await session.run({ query });
-      return c.json({
-        success: true,
-        sessionId: session.id,
-        result,
-      });
+    const server = await startServer({
+      host,
+      port,
+      core: this.agent.core,
     });
-
-    app.post("/api/sdk/sessions/:sessionId/fork", async (c) => {
-      const session = await this.agent.session(String(c.req.param("sessionId") || ""));
-      const body = await c.req.json().catch(() => ({}));
-      const forked = await session.fork(
-        typeof body?.messageId === "string" ? body.messageId : undefined,
-      );
-      return c.json({
-        success: true,
-        session: await forked.toMetadata(),
-      });
-    });
-
-    app.post("/api/sdk/sessions/:sessionId/stream", async (c) => {
-      const session = await this.agent.session(String(c.req.param("sessionId") || ""));
-      const body = await c.req.json().catch(() => ({}));
-      const query = String(body?.query || "").trim();
-      if (!query) {
-        return c.json({ success: false, error: "query is required" }, 400);
-      }
-
-      const encoder = new TextEncoder();
-      const stream = new ReadableStream<Uint8Array>({
-        start: async (controller) => {
-          try {
-            for await (const event of session.stream({ query })) {
-              controller.enqueue(
-                encoder.encode(`${JSON.stringify(event)}\n`),
-              );
-            }
-            controller.close();
-          } catch (error) {
-            controller.enqueue(
-              encoder.encode(
-                `${JSON.stringify({
-                  type: "error",
-                  error: error instanceof Error ? error.message : String(error),
-                })}\n`,
-              ),
-            );
-            controller.close();
-          }
-        },
-      });
-
-      return new Response(stream, {
-        headers: {
-          "Content-Type": "application/x-ndjson; charset=utf-8",
-          "Cache-Control": "no-cache, no-transform",
-        },
-      });
-    });
-
-    const server = http.createServer(async (req, res) => {
-      try {
-        const url = new URL(req.url || "/", `http://${host}:${port}`);
-        const method = req.method || "GET";
-        const bodyBuffer = await this.readRequestBody(req);
-        const request = new Request(url.toString(), {
-          method,
-          headers: new Headers(req.headers as Record<string, string>),
-          body: bodyBuffer.length > 0 ? bodyBuffer : undefined,
-        });
-        const response = await app.fetch(request);
-        res.statusCode = response.status;
-        response.headers.forEach((value, key) => {
-          res.setHeader(key, value);
-        });
-        if (!response.body) {
-          res.end();
-          return;
-        }
-        const reader = response.body.getReader();
-        while (true) {
-          const { done, value } = await reader.read();
-          if (done) break;
-          if (value) res.write(Buffer.from(value));
-        }
-        res.end();
-      } catch (error) {
-        res.statusCode = 500;
-        res.end(String(error));
-      }
-    });
-
-    await new Promise<void>((resolve) => {
-      server.listen(port, host, () => resolve());
-    });
-
-    this.server = server;
-    this.baseUrlValue = `http://${host}:${port}`;
-    return {
-      baseUrl: this.baseUrlValue,
+    this.binding = {
+      baseUrl: `http://${host}:${port}`,
+      host,
+      port,
+      server,
     };
+    return this.binding;
   }
 
   /**
    * 停止 HTTP Server。
    */
   async stop(): Promise<void> {
-    if (!this.server) return;
-    const current = this.server;
-    this.server = null;
-    this.baseUrlValue = null;
-    await new Promise<void>((resolve) => {
-      current.close(() => resolve());
-    });
+    if (!this.binding) return;
+    const current = this.binding;
+    this.binding = null;
+    await current.server.stop();
   }
 
-  private async readRequestBody(
-    req: http.IncomingMessage,
-  ): Promise<Buffer> {
-    return await new Promise<Buffer>((resolve, reject) => {
-      const chunks: Buffer[] = [];
-      req.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
-      req.on("end", () => resolve(Buffer.concat(chunks)));
-      req.on("error", reject);
-    });
+  /**
+   * 返回当前是否已启动。
+   */
+  isStarted(): boolean {
+    return this.binding !== null;
   }
 }

package/src/sdk/RpcServer.ts

@@ -2,28 +2,20 @@
  * SDK 本地 RPC Server。
  *
  * 关键点（中文）
- * - 面向同机受信任进程提供最小 session JSON RPC 能力。
- * - v1 先支持 session 列表、加载、run、history、fork。
- * - stream 仍建议优先走 HTTP NDJSON。
+ * - 这里承接单个 Agent 实例的主 local RPC server 生命周期。
+ * - 启动后暴露的是完整本机受信任 IPC 能力，而不是仅 SDK session 子集。
  */
 
-import fs from "fs-extra";
-import net, { type Server } from "node:net";
-import path from "node:path";
 import type { Agent } from "@/sdk/Agent.js";
-import type {
-  LocalRpcRequest,
-  LocalRpcResponse,
-} from "@/types/rpc/LocalRpc.js";
-import { getSdkAgentRpcEndpointPath } from "@/sdk/Paths.js";
+import type { AgentRpcBinding } from "@/sdk/AgentSdkTypes.js";
+import { startLocalRpcServer } from "@/server/rpc/Server.js";
 
 /**
  * SDK RPC Server 管理器。
  */
 export class SdkAgentRpcServer {
   private readonly agent: Agent;
-  private server: Server | null = null;
-  private endpoint: string | null = null;
+  private binding: AgentRpcBinding | null = null;
 
   constructor(agent: Agent) {
     this.agent = agent;
@@ -32,213 +24,34 @@ export class SdkAgentRpcServer {
   /**
    * 启动本地 RPC server。
    */
-  async start(): Promise<{ endpoint: string }> {
-    if (this.server && this.endpoint) {
-      return { endpoint: this.endpoint };
+  async start(): Promise<AgentRpcBinding> {
+    if (this.binding) {
+      return this.binding;
     }
-    await this.agent.ensureServicesStarted();
-
-    const endpoint = getSdkAgentRpcEndpointPath(this.agent.path, this.agent.id);
-    await fs.ensureDir(path.dirname(endpoint));
-    await fs.remove(endpoint).catch(() => undefined);
-
-    const server = net.createServer((socket) => {
-      let buffered = "";
-      socket.setEncoding("utf8");
-      socket.on("data", (chunk) => {
-        buffered += String(chunk || "");
-        const newlineIndex = buffered.indexOf("\n");
-        if (newlineIndex < 0) return;
-        const raw = buffered.slice(0, newlineIndex).trim();
-        buffered = buffered.slice(newlineIndex + 1);
-        void this.respond(raw, socket);
-      });
+    const server = await startLocalRpcServer({
+      core: this.agent.core,
     });
-
-    await new Promise<void>((resolve, reject) => {
-      server.once("error", reject);
-      server.listen(endpoint, () => {
-        server.off("error", reject);
-        resolve();
-      });
-    });
-
-    this.server = server;
-    this.endpoint = endpoint;
-    return { endpoint };
+    this.binding = {
+      endpoint: server.endpoint,
+      server,
+    };
+    return this.binding;
   }
 
   /**
    * 停止本地 RPC server。
    */
   async stop(): Promise<void> {
-    if (!this.server) return;
-    const current = this.server;
-    const endpoint = this.endpoint;
-    this.server = null;
-    this.endpoint = null;
-    await new Promise<void>((resolve) => current.close(() => resolve()));
-    if (endpoint) {
-      await fs.remove(endpoint).catch(() => undefined);
-    }
-  }
-
-  private async respond(raw: string, socket: net.Socket): Promise<void> {
-    let request: LocalRpcRequest | null = null;
-    try {
-      request = JSON.parse(raw) as LocalRpcRequest;
-    } catch {
-      socket.write(
-        `${JSON.stringify({
-          requestId: "unknown",
-          status: 400,
-          success: false,
-          error: "Invalid RPC JSON payload",
-        } satisfies LocalRpcResponse)}\n`,
-      );
-      return;
-    }
-
-    const response = await this.dispatch(request);
-    socket.write(`${JSON.stringify(response)}\n`);
+    if (!this.binding) return;
+    const current = this.binding;
+    this.binding = null;
+    await current.server.stop();
   }
 
-  private async dispatch(request: LocalRpcRequest): Promise<LocalRpcResponse> {
-    const requestId = String(request.requestId || "").trim() || "unknown";
-    try {
-      if (request.method === "GET" && request.path === "/api/sdk/sessions") {
-        return {
-          requestId,
-          status: 200,
-          success: true,
-          data: {
-            success: true,
-            sessions: await this.agent.sessions(),
-          } as unknown as LocalRpcResponse["data"],
-        };
-      }
-
-      if (request.method === "POST" && request.path === "/api/sdk/sessions") {
-        const body =
-          request.body && typeof request.body === "object" && !Array.isArray(request.body)
-            ? request.body
-            : {};
-        const session = await this.agent.session(
-          typeof body.sessionId === "string" ? body.sessionId : undefined,
-        );
-        return {
-          requestId,
-          status: 200,
-          success: true,
-          data: {
-            success: true,
-            session: await session.toMetadata(),
-          } as unknown as LocalRpcResponse["data"],
-        };
-      }
-
-      const runMatch = /^\/api\/sdk\/sessions\/([^/]+)\/run$/.exec(request.path);
-      if (request.method === "POST" && runMatch) {
-        const session = await this.agent.session(
-          decodeURIComponent(runMatch[1] || ""),
-        );
-        const body =
-          request.body && typeof request.body === "object" && !Array.isArray(request.body)
-            ? request.body
-            : {};
-        const query = String(body.query || "").trim();
-        if (!query) {
-          return {
-            requestId,
-            status: 400,
-            success: false,
-            error: "query is required",
-          };
-        }
-        return {
-          requestId,
-          status: 200,
-          success: true,
-          data: {
-            success: true,
-            sessionId: session.id,
-            result: await session.run({ query }),
-          } as unknown as LocalRpcResponse["data"],
-        };
-      }
-
-      const forkMatch = /^\/api\/sdk\/sessions\/([^/]+)\/fork$/.exec(request.path);
-      if (request.method === "POST" && forkMatch) {
-        const session = await this.agent.session(
-          decodeURIComponent(forkMatch[1] || ""),
-        );
-        const body =
-          request.body && typeof request.body === "object" && !Array.isArray(request.body)
-            ? request.body
-            : {};
-        const forked = await session.fork(
-          typeof body.messageId === "string" ? body.messageId : undefined,
-        );
-        return {
-          requestId,
-          status: 200,
-          success: true,
-          data: {
-            success: true,
-            session: await forked.toMetadata(),
-          } as unknown as LocalRpcResponse["data"],
-        };
-      }
-
-      const messagesMatch =
-        /^\/api\/sdk\/sessions\/([^/]+)\/messages$/.exec(request.path);
-      if (request.method === "GET" && messagesMatch) {
-        const session = await this.agent.session(
-          decodeURIComponent(messagesMatch[1] || ""),
-        );
-        return {
-          requestId,
-          status: 200,
-          success: true,
-          data: {
-            success: true,
-            sessionId: session.id,
-            messages: await session.history(),
-          } as unknown as LocalRpcResponse["data"],
-        };
-      }
-
-      const systemMatch =
-        /^\/api\/sdk\/sessions\/([^/]+)\/system$/.exec(request.path);
-      if (request.method === "GET" && systemMatch) {
-        const session = await this.agent.session(
-          decodeURIComponent(systemMatch[1] || ""),
-        );
-        return {
-          requestId,
-          status: 200,
-          success: true,
-          data: {
-            success: true,
-            sessionId: session.id,
-            system: await session.system(),
-          } as unknown as LocalRpcResponse["data"],
-        };
-      }
-
-      return {
-        requestId,
-        status: 404,
-        success: false,
-        error: `Unknown RPC path: ${request.method} ${request.path}`,
-      };
-    } catch (error) {
-      return {
-        requestId,
-        status: 500,
-        success: false,
-        error: error instanceof Error ? error.message : String(error),
-      };
-    }
+  /**
+   * 返回当前是否已启动。
+   */
+  isStarted(): boolean {
+    return this.binding !== null;
   }
 }