@downcity/agent 1.1.8 → 1.1.11

package/src/server/http/control/AuthControlService.ts

@@ -0,0 +1,161 @@
+/**
+ * Control Authorization Service。
+ *
+ * 关键点（中文）
+ * - 这是 control 侧的 auth 管理面 facade。
+ * - 它通过 auth plugin action 读取与写入授权数据，但自身不属于 plugin 内核。
+ * - 这样调用方不需要知道 plugin action 名称，也不需要依赖 `plugin/builtins/auth/*` 目录。
+ */
+
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
+import type { JsonObject } from "@/types/common/Json.js";
+import type { AuthControlPayload } from "@/server/http/control/types/AuthControl.js";
+import type {
+  AuthSetUserRolePayload,
+  AuthWriteConfigPayload,
+  ChatAuthorizationConfig,
+  ChatAuthorizationSnapshot,
+} from "@/plugin/builtins/auth/types/AuthPlugin.js";
+import {
+  AUTH_ACTIONS,
+  AUTH_PLUGIN_NAME,
+  CHAT_AUTHORIZATION_CATALOG,
+} from "@/plugin/builtins/auth/types/AuthPlugin.js";
+
+function toRecord(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  return value as Record<string, unknown>;
+}
+
+function readSnapshot(value: unknown): ChatAuthorizationSnapshot {
+  const record = toRecord(value);
+  return {
+    config: toRecord(record.config) as unknown as ChatAuthorizationConfig,
+    users: (Array.isArray(record.users) ? record.users : []) as ChatAuthorizationSnapshot["users"],
+    chats: (Array.isArray(record.chats) ? record.chats : []) as ChatAuthorizationSnapshot["chats"],
+  };
+}
+
+/**
+ * 读取 auth plugin 快照。
+ */
+async function readAuthorizationSnapshotViaPlugin(
+  context: AgentContext,
+): Promise<ChatAuthorizationSnapshot> {
+  const result = await context.plugins.runAction({
+    plugin: AUTH_PLUGIN_NAME,
+    action: AUTH_ACTIONS.snapshot,
+  });
+  if (!result.success) {
+    throw new Error(result.error || result.message || "auth snapshot failed");
+  }
+  return readSnapshot(result.data);
+}
+
+/**
+ * 读取 auth plugin 配置。
+ */
+async function readAuthorizationConfigViaPlugin(
+  context: AgentContext,
+): Promise<ChatAuthorizationConfig> {
+  const result = await context.plugins.runAction({
+    plugin: AUTH_PLUGIN_NAME,
+    action: AUTH_ACTIONS.readConfig,
+  });
+  if (!result.success) {
+    throw new Error(result.error || result.message || "auth read-config failed");
+  }
+  return toRecord(result.data) as unknown as ChatAuthorizationConfig;
+}
+
+/**
+ * 通过 auth plugin 覆盖写入授权配置。
+ */
+async function writeAuthorizationConfigViaPlugin(params: {
+  context: AgentContext;
+  config: ChatAuthorizationConfig;
+}): Promise<ChatAuthorizationConfig> {
+  const result = await params.context.plugins.runAction({
+    plugin: AUTH_PLUGIN_NAME,
+    action: AUTH_ACTIONS.writeConfig,
+    payload: {
+      config: params.config,
+    } as AuthWriteConfigPayload as unknown as JsonObject,
+  });
+  if (!result.success) {
+    throw new Error(result.error || result.message || "auth write-config failed");
+  }
+  return toRecord(result.data) as unknown as ChatAuthorizationConfig;
+}
+
+/**
+ * 通过 auth plugin 设置用户角色。
+ */
+async function setAuthorizationUserRoleViaPlugin(params: {
+  context: AgentContext;
+  channel: string;
+  userId: string;
+  roleId: string;
+}): Promise<ChatAuthorizationConfig> {
+  const result = await params.context.plugins.runAction({
+    plugin: AUTH_PLUGIN_NAME,
+    action: AUTH_ACTIONS.setUserRole,
+    payload: {
+      channel: params.channel,
+      userId: params.userId,
+      roleId: params.roleId,
+    } as AuthSetUserRolePayload as unknown as JsonObject,
+  });
+  if (!result.success) {
+    throw new Error(result.error || result.message || "auth set-user-role failed");
+  }
+  return toRecord(result.data) as unknown as ChatAuthorizationConfig;
+}
+
+/**
+ * 读取 authorization 页面所需的完整数据。
+ */
+export async function readAuthControlPayload(
+  context: AgentContext,
+): Promise<AuthControlPayload> {
+  const [config, snapshot] = await Promise.all([
+    readAuthorizationConfigViaPlugin(context),
+    readAuthorizationSnapshotViaPlugin(context),
+  ]);
+  return {
+    catalog: CHAT_AUTHORIZATION_CATALOG,
+    config,
+    users: snapshot.users,
+    chats: snapshot.chats,
+  };
+}
+
+/**
+ * 覆盖写入授权配置，并返回最新 control payload。
+ */
+export async function writeAuthControlConfig(params: {
+  context: AgentContext;
+  config: ChatAuthorizationConfig;
+}): Promise<AuthControlPayload> {
+  await writeAuthorizationConfigViaPlugin({
+    context: params.context,
+    config: params.config,
+  });
+  return readAuthControlPayload(params.context);
+}
+
+/**
+ * 设置用户角色，并返回最新 control payload。
+ */
+export async function setAuthControlUserRole(params: {
+  context: AgentContext;
+  input: AuthSetUserRolePayload;
+}): Promise<AuthControlPayload> {
+  await setAuthorizationUserRoleViaPlugin({
+    context: params.context,
+    channel: params.input.channel,
+    userId: params.input.userId,
+    roleId: params.input.roleId,
+  });
+  return readAuthControlPayload(params.context);
+}

package/src/server/http/control/ControlApiRoutes.ts

@@ -0,0 +1,31 @@
+/**
+ * Agent Control API 路由聚合入口。
+ *
+ * 关键点（中文）
+ * - 本文件只做模块装配，不再承载具体业务逻辑。
+ * - 单 agent control API 子路由按 overview/session/model/task/auth 五类拆分，便于继续维护。
+ * - 单 agent control API 统一暴露在 `/api/control/*` 下。
+ */
+
+import type { ControlRouteRegistrationParams } from "@/server/http/control/types/ControlRoutes.js";
+import { registerControlAuthorizationRoutes } from "@/server/http/control/ControlAuthorizationRoutes.js";
+import { registerControlSessionRoutes } from "@/server/http/control/SessionRoutes.js";
+import { registerControlModelRoutes } from "@/server/http/control/ModelRoutes.js";
+import { registerControlOverviewRoutes } from "@/server/http/control/OverviewRoutes.js";
+import { registerControlTaskRoutes } from "@/server/http/control/TaskRoutes.js";
+
+/**
+ * 注册单 agent control API 路由。
+ */
+export function registerControlApiRoutes(
+  params: ControlRouteRegistrationParams,
+): void {
+  registerControlAuthorizationRoutes({
+    app: params.app,
+    getAgentContext: params.getAgentContext,
+  });
+  registerControlOverviewRoutes(params);
+  registerControlSessionRoutes(params);
+  registerControlModelRoutes(params);
+  registerControlTaskRoutes(params);
+}

package/src/server/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 "@/runtime/AgentContextTypes.js";
+import {
+  readAuthControlPayload,
+  setAuthControlUserRole,
+  writeAuthControlConfig,
+} from "@/server/http/control/AuthControlService.js";
+import {
+  isChatAuthorizationChannel,
+  type AuthSetUserRolePayload,
+  type ChatAuthorizationConfig,
+} from "@/plugin/builtins/auth/types/AuthPlugin.js";
+import type { ChatAuthorizationChannel } from "@/plugin/builtins/auth/types/AuthPlugin.js";
+import { buildControlRouteAliases } from "@/server/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/server/http/control/ControlRouter.ts

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

package/src/server/http/control/ExecuteBySession.ts

@@ -0,0 +1,151 @@
+/**
+ * Control execute by session helper。
+ *
+ * 关键点（中文）
+ * - chatKey session 优先复用 chat 平台队列链路（与平台入站执行一致）。
+ * - 非 chat session 保留原有直接执行语义。
+ */
+
+import type { AgentRuntime } from "@/runtime/AgentRuntime.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
+import type { JsonObject } from "@/types/common/Json.js";
+import type { ControlSessionExecuteAttachmentInput } from "@/server/http/control/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,
+  };
+}