@downcity/agent 1.1.8 → 1.1.11

package/src/sdk/SessionMetadata.ts

@@ -0,0 +1,178 @@
+/**
+ * SDK Session 元数据辅助。
+ *
+ * 关键点（中文）
+ * - 统一负责 `.downcity/agents/<agentId>/sessions/<sessionId>/messages/meta.json` 的 SDK 字段读写。
+ * - 仅处理轻量配置摘要与索引信息，不负责消息 JSONL 的读写。
+ */
+
+import fs from "fs-extra";
+import type { LanguageModel } from "ai";
+import type {
+  SessionHistoryMetaV1,
+  SessionHistorySdkConfigV1,
+} from "@/session/types/SessionHistoryMeta.js";
+import { getSdkAgentSessionMetaPath } from "@/sdk/Paths.js";
+
+type ReadSessionMetadataInput = {
+  /**
+   * 项目根目录。
+   */
+  projectRoot: string;
+
+  /**
+   * 当前 agentId。
+   */
+  agentId: string;
+
+  /**
+   * 当前 sessionId。
+   */
+  sessionId: string;
+};
+
+function normalizeModelLabel(input: unknown): string | undefined {
+  const label = typeof input === "string" ? input.trim() : "";
+  return label || undefined;
+}
+
+/**
+ * 从模型实例推导轻量可读标签。
+ */
+export function inferModelLabel(
+  model: LanguageModel | undefined,
+): string | undefined {
+  if (!model || typeof model !== "object") return undefined;
+  const record = model as Record<string, unknown>;
+  const candidates = [
+    record.modelId,
+    record.model,
+    record.id,
+    record.name,
+    record.label,
+  ];
+  for (const candidate of candidates) {
+    const text = normalizeModelLabel(candidate);
+    if (text) return text;
+  }
+  const constructorName =
+    model.constructor && typeof model.constructor.name === "string"
+      ? model.constructor.name.trim()
+      : "";
+  return constructorName || "configured-model";
+}
+
+/**
+ * 读取当前 session 的 meta.json。
+ */
+export async function readSdkSessionMetadata(
+  input: ReadSessionMetadataInput,
+): Promise<SessionHistoryMetaV1> {
+  const filePath = getSdkAgentSessionMetaPath(
+    input.projectRoot,
+    input.agentId,
+    input.sessionId,
+  );
+  try {
+    const raw = (await fs.readJson(filePath)) as Partial<SessionHistoryMetaV1>;
+    return {
+      v: 1,
+      sessionId: input.sessionId,
+      agentId: input.agentId,
+      createdAt:
+        typeof raw.createdAt === "number" && Number.isFinite(raw.createdAt)
+          ? raw.createdAt
+          : Date.now(),
+      updatedAt:
+        typeof raw.updatedAt === "number" && Number.isFinite(raw.updatedAt)
+          ? raw.updatedAt
+          : 0,
+      pinnedSkillIds: Array.isArray(raw.pinnedSkillIds)
+        ? raw.pinnedSkillIds
+            .map((item) => (typeof item === "string" ? item.trim() : ""))
+            .filter(Boolean)
+        : [],
+      ...(typeof raw.lastArchiveId === "string" && raw.lastArchiveId.trim()
+        ? { lastArchiveId: raw.lastArchiveId.trim() }
+        : {}),
+      ...(typeof raw.keepLastMessages === "number" &&
+      Number.isFinite(raw.keepLastMessages)
+        ? { keepLastMessages: raw.keepLastMessages }
+        : {}),
+      ...(typeof raw.maxInputTokensApprox === "number" &&
+      Number.isFinite(raw.maxInputTokensApprox)
+        ? { maxInputTokensApprox: raw.maxInputTokensApprox }
+        : {}),
+      ...(typeof raw.compactRatio === "number" && Number.isFinite(raw.compactRatio)
+        ? { compactRatio: raw.compactRatio }
+        : {}),
+      ...(raw.sdkConfig && typeof raw.sdkConfig === "object"
+        ? { sdkConfig: raw.sdkConfig as SessionHistorySdkConfigV1 }
+        : {}),
+    };
+  } catch {
+    return {
+      v: 1,
+      sessionId: input.sessionId,
+      agentId: input.agentId,
+      createdAt: Date.now(),
+      updatedAt: 0,
+      pinnedSkillIds: [],
+    };
+  }
+}
+
+/**
+ * 写回当前 session 的 meta.json。
+ */
+export async function writeSdkSessionMetadata(
+  input: ReadSessionMetadataInput & {
+    /**
+     * 下一份 meta 数据。
+     */
+    meta: SessionHistoryMetaV1;
+  },
+): Promise<void> {
+  const filePath = getSdkAgentSessionMetaPath(
+    input.projectRoot,
+    input.agentId,
+    input.sessionId,
+  );
+  await fs.ensureFile(filePath);
+  await fs.writeJson(filePath, input.meta, { spaces: 2 });
+}
+
+/**
+ * 更新当前 session 的 SDK 配置摘要。
+ */
+export async function patchSdkSessionModelLabel(
+  input: ReadSessionMetadataInput & {
+    /**
+     * 当前模型实例。
+     */
+    model?: LanguageModel;
+  },
+): Promise<SessionHistoryMetaV1> {
+  const current = await readSdkSessionMetadata(input);
+  const modelLabel = inferModelLabel(input.model);
+  const next: SessionHistoryMetaV1 = {
+    ...current,
+    agentId: input.agentId,
+    createdAt:
+      typeof current.createdAt === "number" ? current.createdAt : Date.now(),
+    updatedAt: Date.now(),
+    ...(modelLabel
+      ? {
+          sdkConfig: {
+            ...(current.sdkConfig || {}),
+            modelLabel,
+          },
+        }
+      : {}),
+  };
+  await writeSdkSessionMetadata({
+    ...input,
+    meta: next,
+  });
+  return next;
+}

package/src/sdk/SessionPersistence.ts

@@ -0,0 +1,113 @@
+/**
+ * SDK Session 持久化辅助。
+ *
+ * 关键点（中文）
+ * - 集中处理 session meta 更新时间、模型展示标签与 assistant 消息落盘。
+ * - `SdkSession` 只负责调用这些能力，不直接拼装 meta 结构。
+ */
+
+import { resolveAssistantMessageForPersistence } from "@/service/builtins/chat/runtime/UserVisibleText.js";
+import { extractTextFromUiMessage } from "@/service/builtins/chat/runtime/UIMessageTransformer.js";
+import type { SessionHistoryMetaV1 } from "@/session/types/SessionHistoryMeta.js";
+import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
+import type { AgentSessionConfigSnapshot } from "@/sdk/AgentSdkTypes.js";
+import {
+  readSdkSessionMetadata,
+  writeSdkSessionMetadata,
+} from "@/sdk/SessionMetadata.js";
+
+/**
+ * SDK Session 元数据写入参数。
+ */
+export interface TouchSdkSessionMetadataParams {
+  /**
+   * 当前项目根目录。
+   */
+  projectRoot: string;
+  /**
+   * 当前 agent 稳定标识。
+   */
+  agentId: string;
+  /**
+   * 当前 sessionId。
+   */
+  sessionId: string;
+  /**
+   * 当前 session 内存配置快照。
+   */
+  sessionConfig: AgentSessionConfigSnapshot;
+}
+
+/**
+ * Assistant 结果落盘参数。
+ */
+export interface PersistSdkAssistantResultParams
+  extends TouchSdkSessionMetadataParams {
+  /**
+   * 追加 assistant 消息的底层 session 端口。
+   */
+  coreSession: {
+    appendAssistantMessage(params: {
+      /**
+       * 已构造好的完整消息。
+       */
+      message?: SessionMessageV1 | null;
+      /**
+       * 兜底文本内容。
+       */
+      fallbackText?: string;
+    }): Promise<void>;
+  };
+  /**
+   * 本轮执行得到的 assistant 消息。
+   */
+  assistantMessage: SessionMessageV1;
+}
+
+/**
+ * 刷新 SDK session 元数据。
+ */
+export async function touchSdkSessionMetadata(
+  params: TouchSdkSessionMetadataParams,
+): Promise<void> {
+  const current = await readSdkSessionMetadata({
+    projectRoot: params.projectRoot,
+    agentId: params.agentId,
+    sessionId: params.sessionId,
+  });
+  const next: SessionHistoryMetaV1 = {
+    ...current,
+    agentId: params.agentId,
+    createdAt:
+      typeof current.createdAt === "number" ? current.createdAt : Date.now(),
+    updatedAt: Date.now(),
+    ...(params.sessionConfig.modelLabel
+      ? {
+          sdkConfig: {
+            ...(current.sdkConfig || {}),
+            modelLabel: params.sessionConfig.modelLabel,
+          },
+        }
+      : {}),
+  };
+  await writeSdkSessionMetadata({
+    projectRoot: params.projectRoot,
+    agentId: params.agentId,
+    sessionId: params.sessionId,
+    meta: next,
+  });
+}
+
+/**
+ * 持久化 assistant 结果并同步刷新 session meta。
+ */
+export async function persistSdkAssistantResult(
+  params: PersistSdkAssistantResultParams,
+): Promise<void> {
+  const persisted = resolveAssistantMessageForPersistence(params.assistantMessage);
+  await params.coreSession.appendAssistantMessage({
+    ...(persisted ? { message: persisted } : {}),
+    fallbackText: extractTextFromUiMessage(params.assistantMessage),
+  });
+  await touchSdkSessionMetadata(params);
+}

package/src/sdk/SessionServicePort.ts

@@ -0,0 +1,62 @@
+/**
+ * SDK Session service 端口构造器。
+ *
+ * 关键点（中文）
+ * - 把 SDK 本地 session 适配成 chat service 依赖的 `SessionPort`。
+ * - service 侧直接复用底层 `CoreSession` 协议，避免 SDK `run()` 包装层重复补写消息。
+ */
+
+import type { SessionPort } from "@/runtime/AgentContextTypes.js";
+
+/**
+ * 构造 SDK SessionPort 的参数。
+ */
+export interface CreateSdkSessionServicePortParams {
+  /**
+   * 当前 sessionId。
+   */
+  sessionId: string;
+  /**
+   * 底层 session 实例。
+   */
+  coreSession: Omit<SessionPort, "sessionId" | "getHistoryComposer">;
+  /**
+   * 当前 session 历史持久化端口。
+   */
+  historyComposer: ReturnType<SessionPort["getHistoryComposer"]>;
+  /**
+   * session 更新后需要同步执行的持久化回调。
+   */
+  touchMetadata: () => Promise<void>;
+}
+
+/**
+ * 创建供 service 使用的 session 端口。
+ */
+export function createSdkSessionServicePort(
+  params: CreateSdkSessionServicePortParams,
+): SessionPort {
+  return {
+    sessionId: params.sessionId,
+    getExecutor: () => params.coreSession.getExecutor(),
+    getHistoryComposer: () => params.historyComposer,
+    run: async (runParams) => {
+      return await params.coreSession.run(runParams);
+    },
+    clearExecutor: () => {
+      params.coreSession.clearExecutor();
+    },
+    afterSessionUpdatedAsync: async () => {
+      await params.coreSession.afterSessionUpdatedAsync();
+    },
+    appendUserMessage: async (messageParams) => {
+      await params.coreSession.appendUserMessage(messageParams);
+      await params.touchMetadata();
+    },
+    appendAssistantMessage: async (messageParams) => {
+      await params.coreSession.appendAssistantMessage(messageParams);
+      await params.touchMetadata();
+    },
+    isExecuting: () => params.coreSession.isExecuting(),
+  };
+}

package/src/sdk/StreamEvents.ts

@@ -0,0 +1,138 @@
+/**
+ * SDK Stream 事件映射辅助。
+ *
+ * 关键点（中文）
+ * - 把底层 AI SDK `UIMessageChunk` 归一到 `AgentSessionStreamEvent`。
+ * - 仅保留 SDK 当前需要的稳定事件，不把所有底层细节直接暴露出去。
+ */
+
+import type { UIMessageChunk } from "ai";
+import type { JsonValue } from "@/types/common/Json.js";
+import type { AgentSessionStreamEvent } from "@/sdk/AgentSdkTypes.js";
+import type { AsyncQueue } from "@/sdk/AsyncQueue.js";
+
+function toJsonValue(value: unknown): JsonValue {
+  if (value === undefined) return null;
+  if (value === null) return null;
+  if (
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  ) {
+    return value;
+  }
+  try {
+    return JSON.parse(JSON.stringify(value)) as JsonValue;
+  } catch {
+    return String(value);
+  }
+}
+
+/**
+ * 把单个 UI chunk 映射为 SDK stream 事件。
+ */
+export function mapUiMessageChunkToSdkEvent(
+  chunk: UIMessageChunk,
+): AgentSessionStreamEvent | null {
+  switch (chunk.type) {
+    case "text-delta":
+      return {
+        type: "text-delta",
+        text: chunk.delta,
+      };
+    case "reasoning-delta":
+      return {
+        type: "reasoning-delta",
+        text: chunk.delta,
+      };
+    case "tool-input-available":
+      return {
+        type: "tool-call",
+        toolCallId: chunk.toolCallId,
+        toolName: chunk.toolName,
+        args: toJsonValue(chunk.input),
+      };
+    case "tool-output-available":
+      return {
+        type: "tool-result",
+        toolCallId: chunk.toolCallId,
+        toolName: "unknown",
+        result: toJsonValue(chunk.output),
+      };
+    case "tool-output-error":
+      return {
+        type: "tool-error",
+        toolCallId: chunk.toolCallId,
+        toolName: "unknown",
+        error: chunk.errorText,
+      };
+    case "tool-input-error":
+      return {
+        type: "tool-error",
+        toolCallId: chunk.toolCallId,
+        toolName: chunk.toolName,
+        error: chunk.errorText,
+      };
+    case "finish":
+      return {
+        type: "finish",
+        ...(typeof chunk.finishReason === "string"
+          ? { finishReason: chunk.finishReason }
+          : {}),
+      };
+    case "error":
+      return {
+        type: "error",
+        error: chunk.errorText,
+      };
+    case "abort":
+      return {
+        type: "error",
+        error: String(chunk.reason || "stream aborted"),
+      };
+    default:
+      return null;
+  }
+}
+
+/**
+ * 把 UI chunk 推入 SDK stream 队列。
+ *
+ * 关键点（中文）
+ * - `tool-output-*` chunk 本身不总是携带 toolName。
+ * - 这里用调用 id 维护一次流式执行内的工具名称映射，避免上层重复关心底层 chunk 细节。
+ */
+export function pushUiMessageChunkAsSdkEvent(params: {
+  /**
+   * SDK stream 事件队列。
+   */
+  queue: AsyncQueue<AgentSessionStreamEvent>;
+  /**
+   * 底层 AI SDK UI chunk。
+   */
+  chunk: UIMessageChunk;
+  /**
+   * 当前 stream 生命周期内的 toolCallId 到 toolName 映射。
+   */
+  toolNameByCallId: Map<string, string>;
+}): void {
+  const { queue, chunk, toolNameByCallId } = params;
+  if (chunk.type === "tool-input-start") {
+    toolNameByCallId.set(chunk.toolCallId, chunk.toolName);
+    return;
+  }
+  const event = mapUiMessageChunkToSdkEvent(chunk);
+  if (!event) return;
+  if (event.type === "tool-call" || event.type === "tool-error") {
+    toolNameByCallId.set(event.toolCallId, event.toolName);
+  }
+  if (
+    (event.type === "tool-result" || event.type === "tool-error") &&
+    event.toolName === "unknown"
+  ) {
+    const toolName = toolNameByCallId.get(event.toolCallId);
+    queue.push(toolName ? { ...event, toolName } : event);
+    return;
+  }
+  queue.push(event);
+}

package/src/server/http/Server.ts

@@ -0,0 +1,157 @@
+/**
+ * Agent HTTP Server 装配模块。
+ *
+ * 职责说明：
+ * 1. 创建主 Hono 应用并挂载各路由模块。
+ * 2. 管理 Node HTTP Server 的启动与停止。
+ * 3. 保持 server 层只做协议装配，不混入具体路由实现。
+ */
+
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { logger } from "hono/logger";
+import http from "node:http";
+import { logger as serverLogger } from "@/utils/logger/Logger.js";
+import { executeRouter } from "@/server/http/execute/execute.js";
+import { healthRouter } from "@/server/http/health/health.js";
+import {
+  ensureServiceActionRoutesRegistered,
+  servicesRouter,
+} from "@/server/http/services/services.js";
+import { pluginsRouter } from "@/server/http/plugins/plugins.js";
+import { staticRouter } from "@/server/http/static/static.js";
+import { controlRouter } from "@/server/http/control/ControlRouter.js";
+import {
+  listBuiltinPluginRuntimeAuthPolicies,
+  registerBuiltinPluginHttpRoutes,
+} from "@/plugin/core/HttpRoutes.js";
+import { getAgentContext } from "@/runtime/AgentRuntime.js";
+
+/**
+ * Server 启动参数。
+ */
+export interface ServerStartOptions {
+  /** HTTP 服务监听端口。 */
+  port: number;
+  /** HTTP 服务监听主机。 */
+  host: string;
+}
+
+/**
+ * Server 运行实例。
+ */
+export interface ServerInstance {
+  /** Hono 应用实例。 */
+  app: Hono;
+  /** 原生 HTTP Server 实例。 */
+  server: http.Server;
+  /** 停止当前服务。 */
+  stop(): Promise<void>;
+}
+
+/**
+ * 创建主 Hono 应用。
+ */
+export function createServerApp(): Hono {
+  const app = new Hono();
+
+  app.use("*", logger());
+  app.use(
+    "*",
+    cors({
+      origin: "*",
+      allowMethods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
+      allowHeaders: ["Content-Type", "Authorization"],
+    }),
+  );
+
+  // 关键点（中文）：service action 路由在 runtime ready 后再注册，避免命令级 import 副作用。
+  ensureServiceActionRoutesRegistered();
+
+  // 关键点（中文）：按路由域挂载，server 模块只保留装配职责。
+  app.route("/", staticRouter);
+  app.route("/", healthRouter);
+  app.route("/", servicesRouter);
+  app.route("/", pluginsRouter);
+  app.route("/", executeRouter);
+  app.route("/", controlRouter);
+  registerBuiltinPluginHttpRoutes({
+    app,
+    getContext: getAgentContext,
+  });
+
+  return app;
+}
+
+/**
+ * 启动主 HTTP 服务。
+ */
+export async function startServer(
+  options: ServerStartOptions,
+): Promise<ServerInstance> {
+  const app = createServerApp();
+  const server = createNodeServer(app, options);
+
+  await new Promise<void>((resolve) => {
+    server.listen(options.port, options.host, () => {
+      serverLogger.info(
+        `🚀 Agent Server started: http://${options.host}:${options.port}`,
+      );
+      serverLogger.info("Available APIs:");
+      resolve();
+    });
+  });
+
+  return {
+    app,
+    server,
+    async stop(): Promise<void> {
+      await serverLogger.saveAllLogs();
+      await new Promise<void>((resolve) => {
+        server.close(() => resolve());
+      });
+      serverLogger.info("Agent Server stopped");
+    },
+  };
+}
+
+/**
+ * 创建 Node HTTP Server 适配层。
+ */
+function createNodeServer(app: Hono, options: ServerStartOptions): http.Server {
+  return http.createServer(async (req, res) => {
+    try {
+      const url = new URL(req.url || "/", `http://${options.host}:${options.port}`);
+      const method = req.method || "GET";
+      const bodyBuffer = await 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;
+      for (const [key, value] of response.headers.entries()) {
+        res.setHeader(key, value);
+      }
+      const body = await response.text();
+      res.end(body);
+    } catch {
+      res.statusCode = 500;
+      res.end("Internal Server Error");
+    }
+  });
+}
+
+/**
+ * 读取原生请求体。
+ */
+async function readRequestBody(req: http.IncomingMessage): Promise<Buffer> {
+  return new Promise<Buffer>((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk) => chunks.push(chunk));
+    req.on("end", () => resolve(Buffer.concat(chunks)));
+    req.on("error", reject);
+  });
+}