@downcity/agent 1.1.1 → 1.1.5

package/src/host/sdk/HttpServer.ts

@@ -0,0 +1,222 @@
+/**
+ * SDK HTTP Server。
+ *
+ * 关键点（中文）
+ * - 面向 `RemoteAgent` 暴露最小 session 能力集合。
+ * - v1 先聚焦 session 创建、列表、history、run、stream、fork。
+ */
+
+import http from "node:http";
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import type { Agent } from "@/host/sdk/Agent.js";
+
+type SdkHttpStartOptions = {
+  /**
+   * 监听主机。
+   */
+  host?: string;
+
+  /**
+   * 监听端口。
+   */
+  port?: number;
+};
+
+/**
+ * SDK HTTP Server 管理器。
+ */
+export class SdkAgentHttpServer {
+  private readonly agent: Agent;
+  private server: http.Server | null = null;
+  private baseUrlValue: string | null = null;
+
+  constructor(agent: Agent) {
+    this.agent = agent;
+  }
+
+  /**
+   * 启动 HTTP Server。
+   */
+  async start(options?: SdkHttpStartOptions): Promise<{ baseUrl: string }> {
+    if (this.server && this.baseUrlValue) {
+      return { baseUrl: this.baseUrlValue };
+    }
+    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.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,
+      });
+    });
+
+    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,
+    };
+  }
+
+  /**
+   * 停止 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());
+    });
+  }
+
+  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);
+    });
+  }
+}

package/src/host/sdk/Paths.ts

@@ -0,0 +1,126 @@
+/**
+ * SDK Session 落盘路径规则。
+ *
+ * 关键点（中文）
+ * - 与旧 `.downcity/session/<sessionId>` 路径分开，避免不同 agent 在同一项目目录下互相污染。
+ * - 新 SDK 统一落盘到 `.downcity/agents/<agentId>/sessions/<sessionId>/...`。
+ */
+
+import path from "node:path";
+
+/**
+ * `.downcity` 根目录路径。
+ */
+export function getSdkDowncityDirPath(projectRoot: string): string {
+  return path.join(projectRoot, ".downcity");
+}
+
+/**
+ * SDK agents 根目录路径。
+ */
+export function getSdkAgentsRootDirPath(projectRoot: string): string {
+  return path.join(getSdkDowncityDirPath(projectRoot), "agents");
+}
+
+/**
+ * 单个 agent 根目录路径。
+ */
+export function getSdkAgentDirPath(
+  projectRoot: string,
+  agentId: string,
+): string {
+  return path.join(
+    getSdkAgentsRootDirPath(projectRoot),
+    encodeURIComponent(String(agentId || "").trim()),
+  );
+}
+
+/**
+ * 单个 agent 的 sessions 根目录路径。
+ */
+export function getSdkAgentSessionsRootDirPath(
+  projectRoot: string,
+  agentId: string,
+): string {
+  return path.join(getSdkAgentDirPath(projectRoot, agentId), "sessions");
+}
+
+/**
+ * 单个 session 根目录路径。
+ */
+export function getSdkAgentSessionDirPath(
+  projectRoot: string,
+  agentId: string,
+  sessionId: string,
+): string {
+  return path.join(
+    getSdkAgentSessionsRootDirPath(projectRoot, agentId),
+    encodeURIComponent(String(sessionId || "").trim()),
+  );
+}
+
+/**
+ * 单个 session 的消息目录路径。
+ */
+export function getSdkAgentSessionMessagesDirPath(
+  projectRoot: string,
+  agentId: string,
+  sessionId: string,
+): string {
+  return path.join(
+    getSdkAgentSessionDirPath(projectRoot, agentId, sessionId),
+    "messages",
+  );
+}
+
+/**
+ * 单个 session 的消息 JSONL 文件路径。
+ */
+export function getSdkAgentSessionMessagesPath(
+  projectRoot: string,
+  agentId: string,
+  sessionId: string,
+): string {
+  return path.join(
+    getSdkAgentSessionMessagesDirPath(projectRoot, agentId, sessionId),
+    "messages.jsonl",
+  );
+}
+
+/**
+ * 单个 session 的 meta.json 路径。
+ */
+export function getSdkAgentSessionMetaPath(
+  projectRoot: string,
+  agentId: string,
+  sessionId: string,
+): string {
+  return path.join(
+    getSdkAgentSessionMessagesDirPath(projectRoot, agentId, sessionId),
+    "meta.json",
+  );
+}
+
+/**
+ * 单个 session 的 archive 目录路径。
+ */
+export function getSdkAgentSessionArchiveDirPath(
+  projectRoot: string,
+  agentId: string,
+  sessionId: string,
+): string {
+  return path.join(
+    getSdkAgentSessionMessagesDirPath(projectRoot, agentId, sessionId),
+    "archive",
+  );
+}
+
+/**
+ * 单个 agent 的本地 RPC socket 路径。
+ */
+export function getSdkAgentRpcEndpointPath(
+  projectRoot: string,
+  agentId: string,
+): string {
+  return path.join(getSdkAgentDirPath(projectRoot, agentId), "agent.rpc.sock");
+}

package/src/host/sdk/RemoteAgent.ts

@@ -0,0 +1,205 @@
+/**
+ * RemoteAgent：远程 SDK 客户端。
+ *
+ * 关键点（中文）
+ * - 面向已启动 `agent.http.start()` 的远程/本地 HTTP 服务。
+ * - 与本地 `Agent` 尽量保持同一套 session 使用面。
+ */
+
+import type {
+  AgentSessionMetadata,
+  AgentSessionRunInput,
+  AgentSessionRunResult,
+  AgentSessionSetInput,
+  AgentSessionStreamEvent,
+  RemoteAgentOptions,
+} from "@/host/sdk/AgentSdkTypes.js";
+import type { SessionMessageV1 } from "@/types/session/SessionMessages.js";
+
+/**
+ * 远程 Session 客户端。
+ */
+class RemoteSession {
+  readonly id: string;
+  private readonly baseUrl: string;
+
+  constructor(baseUrl: string, sessionId: string) {
+    this.baseUrl = baseUrl;
+    this.id = sessionId;
+  }
+
+  /**
+   * 远程 session 当前不支持直接注入本地模型实例。
+   */
+  async set(_input: AgentSessionSetInput): Promise<void> {
+    throw new Error(
+      "Remote session.set({ model }) is not supported in v1. Configure the model on the server-side local Agent session instead.",
+    );
+  }
+
+  /**
+   * 执行一轮非流式请求。
+   */
+  async run(input: AgentSessionRunInput): Promise<AgentSessionRunResult> {
+    const response = await fetch(`${this.baseUrl}/api/sdk/sessions/${encodeURIComponent(this.id)}/run`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(input),
+    });
+    const payload = (await response.json()) as {
+      success?: boolean;
+      error?: string;
+      result?: AgentSessionRunResult;
+    };
+    if (!response.ok || !payload.success || !payload.result) {
+      throw new Error(String(payload.error || "Remote session run failed"));
+    }
+    return payload.result;
+  }
+
+  /**
+   * 读取远程消息历史。
+   */
+  async history(): Promise<SessionMessageV1[]> {
+    const response = await fetch(
+      `${this.baseUrl}/api/sdk/sessions/${encodeURIComponent(this.id)}/messages`,
+    );
+    const payload = (await response.json()) as {
+      success?: boolean;
+      error?: string;
+      messages?: SessionMessageV1[];
+    };
+    if (!response.ok || !payload.success || !Array.isArray(payload.messages)) {
+      throw new Error(String(payload.error || "Remote session history failed"));
+    }
+    return payload.messages;
+  }
+
+  /**
+   * 分叉远程 session。
+   */
+  async fork(messageId?: string): Promise<RemoteSession> {
+    const response = await fetch(
+      `${this.baseUrl}/api/sdk/sessions/${encodeURIComponent(this.id)}/fork`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          ...(messageId ? { messageId } : {}),
+        }),
+      },
+    );
+    const payload = (await response.json()) as {
+      success?: boolean;
+      error?: string;
+      session?: AgentSessionMetadata;
+    };
+    if (!response.ok || !payload.success || !payload.session?.sessionId) {
+      throw new Error(String(payload.error || "Remote session fork failed"));
+    }
+    return new RemoteSession(this.baseUrl, payload.session.sessionId);
+  }
+
+  /**
+   * 执行一轮流式请求。
+   */
+  async *stream(
+    input: AgentSessionRunInput,
+  ): AsyncIterable<AgentSessionStreamEvent> {
+    const response = await fetch(
+      `${this.baseUrl}/api/sdk/sessions/${encodeURIComponent(this.id)}/stream`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(input),
+      },
+    );
+    if (!response.ok || !response.body) {
+      const text = await response.text().catch(() => "");
+      throw new Error(text || `Remote session stream failed (${response.status})`);
+    }
+
+    const decoder = new TextDecoder();
+    const reader = response.body.getReader();
+    let buffered = "";
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffered += decoder.decode(value, { stream: true });
+      let newlineIndex = buffered.indexOf("\n");
+      while (newlineIndex >= 0) {
+        const line = buffered.slice(0, newlineIndex).trim();
+        buffered = buffered.slice(newlineIndex + 1);
+        if (line) {
+          yield JSON.parse(line) as AgentSessionStreamEvent;
+        }
+        newlineIndex = buffered.indexOf("\n");
+      }
+    }
+    const tail = buffered.trim();
+    if (tail) {
+      yield JSON.parse(tail) as AgentSessionStreamEvent;
+    }
+  }
+}
+
+/**
+ * RemoteAgent：远程 Agent 客户端。
+ */
+export class RemoteAgent {
+  private readonly baseUrl: string;
+
+  constructor(options: RemoteAgentOptions) {
+    const baseUrl = String(options.baseUrl || "").trim().replace(/\/+$/, "");
+    if (!baseUrl) {
+      throw new Error("RemoteAgent requires a non-empty baseUrl");
+    }
+    this.baseUrl = baseUrl;
+  }
+
+  /**
+   * 获取或创建一个远程 session。
+   */
+  async session(sessionId?: string): Promise<RemoteSession> {
+    const response = await fetch(`${this.baseUrl}/api/sdk/sessions`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        ...(sessionId ? { sessionId } : {}),
+      }),
+    });
+    const payload = (await response.json()) as {
+      success?: boolean;
+      error?: string;
+      session?: AgentSessionMetadata;
+    };
+    if (!response.ok || !payload.success || !payload.session?.sessionId) {
+      throw new Error(String(payload.error || "Remote session load failed"));
+    }
+    return new RemoteSession(this.baseUrl, payload.session.sessionId);
+  }
+
+  /**
+   * 列出远程 agent 的全部 session 元数据。
+   */
+  async sessions(): Promise<AgentSessionMetadata[]> {
+    const response = await fetch(`${this.baseUrl}/api/sdk/sessions`);
+    const payload = (await response.json()) as {
+      success?: boolean;
+      error?: string;
+      sessions?: AgentSessionMetadata[];
+    };
+    if (!response.ok || !payload.success || !Array.isArray(payload.sessions)) {
+      throw new Error(String(payload.error || "Remote sessions list failed"));
+    }
+    return payload.sessions;
+  }
+}