@downcity/agent 1.1.1 → 1.1.5

package/src/http/control/ControlAuthorizationRoutes.ts

@@ -0,0 +1,108 @@
+/**
+ * Agent Control Authorization 路由。
+ *
+ * 关键点（中文）
+ * - 单独承接 `/api/control/authorization*`。
+ * - 授权页面的数据统一通过 auth plugin API 读取与写入。
+ */
+
+import type { Hono } from "hono";
+import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import {
+  readAuthControlPayload,
+  setAuthControlUserRole,
+  writeAuthControlConfig,
+} from "@/http/control/AuthControlService.js";
+import {
+  isChatAuthorizationChannel,
+  type AuthSetUserRolePayload,
+  type ChatAuthorizationConfig,
+} from "@/shared/types/AuthPlugin.js";
+import type { ChatAuthorizationChannel } from "@/shared/types/AuthPlugin.js";
+import { buildControlRouteAliases } from "@/http/control/CommonHelpers.js";
+
+function normalizeChatChannel(value: unknown): ChatAuthorizationChannel | null {
+  const text = String(value || "").trim().toLowerCase();
+  if (isChatAuthorizationChannel(text)) return text;
+  return null;
+}
+
+/**
+ * 注册 authorization 相关路由。
+ */
+export function registerControlAuthorizationRoutes(params: {
+  app: Hono;
+  getAgentContext: () => AgentContext;
+}): void {
+  const { app, getAgentContext } = params;
+
+  for (const routePath of buildControlRouteAliases("/authorization")) {
+    app.get(routePath, async (c) => {
+      try {
+        const payload = await readAuthControlPayload(getAgentContext());
+        return c.json({
+          success: true,
+          ...payload,
+        });
+      } catch (error) {
+        return c.json({ success: false, error: String(error) }, 500);
+      }
+    });
+  }
+
+  for (const routePath of buildControlRouteAliases("/authorization/config")) {
+    app.post(routePath, async (c) => {
+      try {
+        const body = (await c.req.json().catch(() => ({}))) as {
+          config?: ChatAuthorizationConfig;
+        };
+        const payload = await writeAuthControlConfig({
+          context: getAgentContext(),
+          config: body.config && typeof body.config === "object" ? body.config : {},
+        });
+        return c.json({
+          success: true,
+          ...payload,
+        });
+      } catch (error) {
+        return c.json({ success: false, error: String(error) }, 500);
+      }
+    });
+  }
+
+  for (const routePath of buildControlRouteAliases("/authorization/action")) {
+    app.post(routePath, async (c) => {
+      try {
+        const body = (await c.req.json().catch(() => ({}))) as {
+          action?: string;
+          channel?: string;
+          userId?: string;
+          roleId?: string;
+        };
+        const action = String(body.action || "").trim();
+        const channel = normalizeChatChannel(body.channel);
+        if (!action || !channel) {
+          return c.json({ success: false, error: "Missing action/channel" }, 400);
+        }
+        if (action !== "setUserRole") {
+          return c.json({ success: false, error: `Unsupported action: ${action}` }, 400);
+        }
+
+        const payload = await setAuthControlUserRole({
+          context: getAgentContext(),
+          input: {
+            channel,
+            userId: String(body.userId || "").trim(),
+            roleId: String(body.roleId || "").trim(),
+          } as AuthSetUserRolePayload,
+        });
+        return c.json({
+          success: true,
+          ...payload,
+        });
+      } catch (error) {
+        return c.json({ success: false, error: String(error) }, 500);
+      }
+    });
+  }
+}

package/src/http/control/ControlRouter.ts

@@ -0,0 +1,31 @@
+/**
+ * Agent Control API 路由入口模块。
+ *
+ * 职责说明：
+ * 1. 为单 agent control API 暴露独立 router。
+ * 2. 将控制域的 API 装配收敛在 `http/control/` 下。
+ * 3. server 只负责挂载该 router，不再持有控制面细节。
+ *
+ * 命名说明（中文）
+ * - 这里的 control 指“单 agent 控制域”。
+ * - 它不是 city 的 gateway / control plane。
+ * - 当前公开路径统一使用 `/api/control/*`。
+ */
+
+import { Hono } from "hono";
+import {
+  getAgentRuntime,
+  getAgentContext,
+} from "@/agent/AgentRuntime.js";
+import { registerControlApiRoutes } from "@/http/control/ControlApiRoutes.js";
+
+/**
+ * 单 agent control API 专用路由。
+ */
+export const controlRouter = new Hono();
+
+registerControlApiRoutes({
+  app: controlRouter,
+  getAgentRuntime: getAgentRuntime,
+  getAgentContext: getAgentContext,
+});

package/src/http/control/ExecuteBySession.ts

@@ -0,0 +1,151 @@
+/**
+ * Control execute by session helper。
+ *
+ * 关键点（中文）
+ * - chatKey session 优先复用 chat 平台队列链路（与平台入站执行一致）。
+ * - 非 chat session 保留原有直接执行语义。
+ */
+
+import type { AgentRuntime } from "@/agent/AgentRuntime.js";
+import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { JsonObject } from "@/shared/types/Json.js";
+import type { ControlSessionExecuteAttachmentInput } from "@/shared/types/ControlSessionExecute.js";
+import { drainDeferredPersistedUserMessages } from "@session/SessionRunScope.js";
+import { resolveChatQueueStore } from "@/service/builtins/chat/runtime/ChatQueue.js";
+import { resolveDispatchTargetByChatKey } from "@/service/builtins/chat/runtime/ChatkeySend.js";
+import { appendExecIngress } from "@/service/builtins/chat/runtime/ChatIngressStore.js";
+import { buildQueuedUserMessageWithInfo } from "@/service/builtins/chat/runtime/QueuedUserMessage.js";
+import {
+  pickLastSuccessfulChatSendText,
+  resolveAssistantMessageForPersistence,
+} from "@/service/builtins/chat/runtime/UserVisibleText.js";
+import { buildExecuteInputText } from "./Helpers.js";
+
+/**
+ * 在指定 session 中执行一轮请求。
+ *
+ * 说明（中文）
+ * - 若 `sessionId` 能解析为 chat 分发目标，则改为入 chat queue。
+ * - 否则按普通 session 同步执行。
+ */
+export async function executeBySessionId(params: {
+  agentState: AgentRuntime;
+  executionContext: AgentContext;
+  sessionId: string;
+  instructions: string;
+  attachments?: ControlSessionExecuteAttachmentInput[];
+}) {
+  const sessionId = String(params.sessionId || "").trim();
+  const instructions = String(params.instructions || "").trim();
+  if (!sessionId) throw new Error("Missing sessionId");
+  if (!instructions) throw new Error("Missing instructions");
+
+  const executeInput = await buildExecuteInputText({
+    projectRoot: params.agentState.rootPath,
+    sessionId,
+    instructions,
+    attachments: params.attachments,
+  });
+
+  const dispatchTarget = await resolveDispatchTargetByChatKey({
+    context: params.executionContext,
+    chatKey: sessionId,
+  });
+  if (dispatchTarget) {
+    const queuedText = buildQueuedUserMessageWithInfo({
+      messageId: dispatchTarget.messageId,
+      text: executeInput,
+    });
+    const ingressExtra: JsonObject = {
+      source: "tui_session_execute",
+      ingressKind: "exec",
+      trigger: "api_execute",
+    };
+
+    try {
+      await appendExecIngress({
+        context: params.executionContext,
+        sessionId,
+        channel: dispatchTarget.channel,
+        chatId: dispatchTarget.chatId,
+        text: queuedText,
+        ...(dispatchTarget.chatType ? { targetType: dispatchTarget.chatType } : {}),
+        ...(typeof dispatchTarget.messageThreadId === "number"
+          ? { threadId: dispatchTarget.messageThreadId }
+          : {}),
+        ...(dispatchTarget.messageId ? { messageId: dispatchTarget.messageId } : {}),
+        extra: ingressExtra,
+      });
+    } catch (error) {
+      params.agentState.logger.warn("Control execute ingress append failed", {
+        sessionId,
+        error: String(error),
+      });
+    }
+
+    const enqueueResult = resolveChatQueueStore(params.executionContext).enqueue({
+      kind: "exec",
+      channel: dispatchTarget.channel,
+      targetId: dispatchTarget.chatId,
+      sessionId,
+      text: queuedText,
+      ...(dispatchTarget.chatType ? { targetType: dispatchTarget.chatType } : {}),
+      ...(typeof dispatchTarget.messageThreadId === "number"
+        ? { threadId: dispatchTarget.messageThreadId }
+        : {}),
+      ...(dispatchTarget.messageId ? { messageId: dispatchTarget.messageId } : {}),
+      sessionPersisted: true,
+      extra: ingressExtra,
+    });
+
+    return {
+      success: true,
+      queued: true,
+      queueItemId: enqueueResult.itemId,
+      queuePosition: enqueueResult.lanePosition,
+      userVisible: "",
+    };
+  }
+
+  const session = params.agentState.getSession(sessionId);
+  await session.appendUserMessage({
+    text: executeInput,
+  });
+
+  const result = await session.run({
+    query: executeInput,
+  });
+
+  const userVisible = pickLastSuccessfulChatSendText(result.assistantMessage).trim();
+  try {
+    const messageForPersistence = resolveAssistantMessageForPersistence(
+      result.assistantMessage,
+    );
+    if (messageForPersistence) {
+      await session.appendAssistantMessage({
+        message: messageForPersistence,
+        fallbackText: userVisible,
+        extra: {
+          via: "tui_session_execute",
+          note: "assistant_message_missing",
+        },
+      });
+    }
+    const deferredInjectedMessages = drainDeferredPersistedUserMessages(
+      sessionId,
+    );
+    for (const message of deferredInjectedMessages) {
+      await session.appendUserMessage({
+        message,
+      });
+    }
+  } catch {
+    // ignore
+  }
+
+  return {
+    ...result,
+    userVisible,
+    queued: false,
+  };
+}

package/src/http/control/ExecuteInput.ts

@@ -0,0 +1,236 @@
+/**
+ * Control execute 输入拼装 helper。
+ *
+ * 关键点（中文）
+ * - 负责把 API 传入的附件规范化并落盘。
+ * - 最终统一转成 `<file>` 标签注入到 user message。
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import { getCacheDirPath } from "@/config/Paths.js";
+import { renderChatMessageFileTag } from "@/service/builtins/chat/runtime/ChatMessageMarkup.js";
+import type {
+  ControlSessionExecuteAttachmentInput,
+  ControlSessionExecuteAttachmentType,
+} from "@/shared/types/ControlSessionExecute.js";
+
+const EXECUTE_ATTACHMENT_MAX_COUNT = 8;
+const EXECUTE_ATTACHMENT_MAX_BYTES = 2 * 1024 * 1024;
+const EXECUTE_ATTACHMENT_CONTENT_MAX_CHARS = 1_500_000;
+const EXECUTE_ATTACHMENT_FALLBACK_TEXT = "请查看以上附件并按用户要求处理。";
+
+function normalizeExecuteAttachmentType(
+  value: unknown,
+): ControlSessionExecuteAttachmentType {
+  const raw = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (
+    raw === "photo" ||
+    raw === "voice" ||
+    raw === "audio" ||
+    raw === "video"
+  ) {
+    return raw;
+  }
+  return "document";
+}
+
+function normalizeAttachmentCaption(value: unknown): string | undefined {
+  const text = String(value || "")
+    .replace(/\r?\n+/g, " ")
+    .replace(/\s+/g, " ")
+    .replace(/\|/g, "/")
+    .trim();
+  if (!text) return undefined;
+  return text.slice(0, 180);
+}
+
+function toProjectRelativePath(projectRoot: string, absPath: string): string | null {
+  const relative = path.relative(projectRoot, absPath);
+  if (!relative) return null;
+  if (relative.startsWith("..")) return null;
+  if (path.isAbsolute(relative)) return null;
+  return relative.split(path.sep).join("/");
+}
+
+function normalizeAttachmentFileName(params: {
+  fileName?: string;
+  fallbackExt: string;
+}): string {
+  const raw = String(params.fileName || "").trim();
+  const base = (raw || "attachment")
+    .replace(/[\\/:*?"<>|]/g, "-")
+    .replace(/\s+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^\.+/, "")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 72);
+  const safeBase = base || "attachment";
+  const fallbackExt = params.fallbackExt.startsWith(".")
+    ? params.fallbackExt
+    : `.${params.fallbackExt}`;
+  const hasExt = /\.[A-Za-z0-9]+$/.test(safeBase);
+  return hasExt ? safeBase : `${safeBase}${fallbackExt}`;
+}
+
+function inferAttachmentExt(params: {
+  type: ControlSessionExecuteAttachmentType;
+  fileName?: string;
+  contentType?: string;
+}): string {
+  const fromFileName = path.extname(String(params.fileName || "").trim())
+    .toLowerCase()
+    .trim();
+  if (fromFileName) return fromFileName;
+  const contentType = String(params.contentType || "").toLowerCase();
+  if (contentType.includes("markdown")) return ".md";
+  if (contentType.includes("json")) return ".json";
+  if (contentType.includes("html")) return ".html";
+  if (contentType.includes("plain")) return ".txt";
+  if (params.type === "photo") return ".jpg";
+  if (params.type === "voice" || params.type === "audio") return ".mp3";
+  if (params.type === "video") return ".mp4";
+  return ".md";
+}
+
+async function resolveAttachmentPathFromInput(params: {
+  projectRoot: string;
+  attachment: ControlSessionExecuteAttachmentInput;
+}): Promise<string | null> {
+  const rawPath = String(params.attachment.path || "").trim();
+  if (!rawPath) return null;
+  const abs = path.isAbsolute(rawPath)
+    ? path.normalize(rawPath)
+    : path.resolve(params.projectRoot, rawPath);
+  const relative = toProjectRelativePath(params.projectRoot, abs);
+  if (!relative) return null;
+  const stat = await fs
+    .stat(abs)
+    .then((value) => value)
+    .catch(() => null);
+  if (!stat?.isFile()) return null;
+  return relative;
+}
+
+function resolveAttachmentBytes(
+  attachment: ControlSessionExecuteAttachmentInput,
+): Buffer | null {
+  const textContent =
+    typeof attachment.content === "string" ? attachment.content : "";
+  if (textContent) {
+    const clipped = textContent.slice(0, EXECUTE_ATTACHMENT_CONTENT_MAX_CHARS);
+    return Buffer.from(clipped, "utf8");
+  }
+
+  const base64 = String(attachment.contentBase64 || "").trim();
+  if (!base64) return null;
+  try {
+    return Buffer.from(base64, "base64");
+  } catch {
+    return null;
+  }
+}
+
+async function materializeAttachmentContent(params: {
+  projectRoot: string;
+  sessionId: string;
+  attachment: ControlSessionExecuteAttachmentInput;
+  index: number;
+}): Promise<string | null> {
+  const bytes = resolveAttachmentBytes(params.attachment);
+  if (!bytes || bytes.length <= 0) return null;
+  if (bytes.length > EXECUTE_ATTACHMENT_MAX_BYTES) {
+    throw new Error(
+      `Attachment too large (>${EXECUTE_ATTACHMENT_MAX_BYTES} bytes)`,
+    );
+  }
+
+  const type = normalizeExecuteAttachmentType(params.attachment.type);
+  const ext = inferAttachmentExt({
+    type,
+    fileName: params.attachment.fileName,
+    contentType: params.attachment.contentType,
+  });
+  const safeName = normalizeAttachmentFileName({
+    fileName: params.attachment.fileName,
+    fallbackExt: ext,
+  });
+  const safeContext = String(params.sessionId || "session")
+    .replace(/[^A-Za-z0-9_-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 32);
+  const prefix = safeContext || "context";
+  const fileName = `${Date.now()}-${prefix}-${String(params.index + 1).padStart(2, "0")}-${safeName}`;
+  const cacheDir = path.join(getCacheDirPath(params.projectRoot), "chrome-extension");
+  await fs.ensureDir(cacheDir);
+  const absPath = path.join(cacheDir, fileName);
+  await fs.writeFile(absPath, bytes);
+  return toProjectRelativePath(params.projectRoot, absPath);
+}
+
+function toAttachmentLine(params: {
+  type: ControlSessionExecuteAttachmentType;
+  relativePath: string;
+  caption?: string;
+}): string {
+  return renderChatMessageFileTag({
+    type: params.type,
+    path: params.relativePath,
+    ...(params.caption ? { caption: params.caption } : {}),
+  });
+}
+
+/**
+ * 构造 execute 入站文本。
+ */
+export async function buildExecuteInputText(params: {
+  projectRoot: string;
+  sessionId: string;
+  instructions: string;
+  attachments?: ControlSessionExecuteAttachmentInput[];
+}): Promise<string> {
+  const instructions = String(params.instructions || "").trim();
+  const inputAttachments = Array.isArray(params.attachments)
+    ? params.attachments.slice(0, EXECUTE_ATTACHMENT_MAX_COUNT)
+    : [];
+  if (inputAttachments.length === 0) return instructions;
+
+  const lines: string[] = [];
+  for (let index = 0; index < inputAttachments.length; index += 1) {
+    const attachment = inputAttachments[index];
+    if (!attachment || typeof attachment !== "object") continue;
+    const type = normalizeExecuteAttachmentType(attachment.type);
+    const caption = normalizeAttachmentCaption(attachment.caption);
+
+    const reusePath = await resolveAttachmentPathFromInput({
+      projectRoot: params.projectRoot,
+      attachment,
+    });
+    const relativePath =
+      reusePath ||
+      (await materializeAttachmentContent({
+        projectRoot: params.projectRoot,
+        sessionId: params.sessionId,
+        attachment,
+        index,
+      }));
+    if (!relativePath) continue;
+
+    lines.push(
+      toAttachmentLine({
+        type,
+        relativePath,
+        ...(caption ? { caption } : {}),
+      }),
+    );
+  }
+
+  if (lines.length === 0) return instructions;
+  return [lines.join("\n"), instructions || EXECUTE_ATTACHMENT_FALLBACK_TEXT]
+    .filter(Boolean)
+    .join("\n\n")
+    .trim();
+}

package/src/http/control/Helpers.ts

@@ -0,0 +1,22 @@
+/**
+ * Control helper 聚合出口。
+ *
+ * 关键点（中文）
+ * - 兼容控制面路由层的统一 import 路径。
+ * - 具体实现已拆分到独立子模块，避免单文件继续膨胀。
+ */
+
+export { toLimit, toOptionalString, decodeMaybe } from "./CommonHelpers.js";
+export { buildExecuteInputText } from "./ExecuteInput.js";
+export {
+  loadSessionMessagesFromFile,
+  resolveUiMessagePreview,
+  toUiMessageTimeline,
+} from "./MessageTimeline.js";
+export { listControlSessionSummaries } from "./SessionSummaryStore.js";
+export {
+  TASK_RUN_DIR_REGEX,
+  listTaskRuns,
+  readRecentLogs,
+  readTaskRunDetail,
+} from "./TaskStore.js";