@downcity/city 1.1.1 → 1.1.5

package/src/control/gateway/GatewaySupport.ts

@@ -0,0 +1,59 @@
+/**
+ * 平台控制面网关共享辅助函数。
+ *
+ * 关键点（中文）
+ * - 提供与路由层正交的纯文本/纯 payload 组装能力。
+ * - 让 `ControlGateway` 与 route 注册模块不再重复拼接阻塞文案。
+ */
+
+/**
+ * 平台工作负载安全检查结果。
+ */
+export interface PlatformWorkloadSafetyCheck {
+  /**
+   * 当前仍在运行的上下文列表。
+   */
+  activeContexts: string[];
+  /**
+   * 当前仍在运行的任务列表。
+   */
+  activeTasks: string[];
+}
+
+/**
+ * 生成 workload 阻塞详情文本。
+ */
+export function buildPlatformWorkloadBlockDetail(
+  checks: PlatformWorkloadSafetyCheck,
+): string {
+  const contextLabel =
+    checks.activeContexts.length > 0
+      ? `contexts: ${checks.activeContexts.join(", ")}`
+      : "";
+  const taskLabel =
+    checks.activeTasks.length > 0 ? `tasks: ${checks.activeTasks.join(", ")}` : "";
+  return [contextLabel, taskLabel].filter(Boolean).join(" | ");
+}
+
+/**
+ * 生成 stop/restart 被阻塞时的统一响应 payload。
+ */
+export function buildPlatformWorkloadBlockPayload(
+  action: "stop" | "restart",
+  checks: PlatformWorkloadSafetyCheck,
+): {
+  success: false;
+  error: string;
+  activeContexts: string[];
+  activeTasks: string[];
+} {
+  const detail = buildPlatformWorkloadBlockDetail(checks);
+  return {
+    success: false,
+    error: detail
+      ? `Agent has running workload, ${action} blocked (${detail})`
+      : `Agent has running workload, ${action} blocked`,
+    activeContexts: checks.activeContexts,
+    activeTasks: checks.activeTasks,
+  };
+}

package/src/control/gateway/Proxy.ts

@@ -0,0 +1,62 @@
+/**
+ * 平台控制面代理转发辅助。
+ *
+ * 关键点（中文）
+ * - 负责把 `/api/*` 请求转发到选中 agent。
+ * - 保持最小职责，不参与 agent 选择逻辑。
+ */
+
+/**
+ * 构造上游请求地址。
+ */
+export function buildPlatformUpstreamUrl(
+  requestUrl: URL,
+  baseUrl: string,
+): string {
+  const upstreamPath = new URL(requestUrl.pathname + requestUrl.search, baseUrl);
+  upstreamPath.searchParams.delete("agent");
+  return upstreamPath.toString();
+}
+
+/**
+ * 转发请求到目标 runtime。
+ */
+export async function forwardPlatformRequest(
+  request: Request,
+  upstreamUrl: string,
+): Promise<Response> {
+  const method = request.method || "GET";
+  const headers = new Headers();
+  for (const [key, value] of request.headers.entries()) {
+    const lower = key.toLowerCase();
+    if (
+      lower === "host" ||
+      lower === "content-length" ||
+      lower === "x-city-agent"
+    ) {
+      continue;
+    }
+    headers.set(key, value);
+  }
+
+  const body =
+    method === "GET" || method === "HEAD"
+      ? undefined
+      : Buffer.from(await request.arrayBuffer());
+
+  const response = await fetch(upstreamUrl, {
+    method,
+    headers,
+    body,
+  });
+  const buffer = Buffer.from(await response.arrayBuffer());
+  const outHeaders = new Headers();
+  outHeaders.set(
+    "content-type",
+    response.headers.get("content-type") || "application/octet-stream",
+  );
+  return new Response(buffer, {
+    status: response.status,
+    headers: outHeaders,
+  });
+}

package/src/control/instant/InstantApiRoutes.ts

@@ -0,0 +1,74 @@
+/**
+ * InstantApiRoutes：Inline Composer 即时模式路由。
+ *
+ * 关键点（中文）
+ * - 统一暴露 `/api/ui/inline/instant-run`，避免扩展直接区分 model/acp 两套后端路径。
+ * - 接口层只做轻量参数校验，具体临时 session 执行逻辑下沉到 service。
+ */
+
+import type { Hono } from "hono";
+import type { PlatformAgentOption } from "@downcity/agent";
+import type {
+  PlatformInlineInstantRunInput,
+  PlatformInlineInstantService,
+  InlineInstantExecutorType,
+} from "@downcity/agent";
+import { InstantSessionService } from "@/control/instant/InstantSessionService.js";
+
+function normalizeExecutorType(input: unknown): InlineInstantExecutorType | "" {
+  const value = String(input || "").trim();
+  if (value === "model" || value === "acp") return value;
+  return "";
+}
+
+/**
+ * 注册 Inline Composer 即时模式路由。
+ */
+export function registerPlatformInstantRoutes(params: {
+  app: Hono;
+  resolveAgentById: (requestedAgentId: string) => Promise<PlatformAgentOption | null>;
+  instantSessionService?: PlatformInlineInstantService;
+}): void {
+  const service =
+    params.instantSessionService ||
+    new InstantSessionService({
+      resolveAgentById: (agentId) => params.resolveAgentById(agentId),
+    });
+
+  params.app.post("/api/ui/inline/instant-run", async (c) => {
+    try {
+      const body = (await c.req.json().catch(() => ({}))) as Partial<PlatformInlineInstantRunInput>;
+      const executorType = normalizeExecutorType(body.executorType);
+      if (!executorType) {
+        return c.json({ success: false, error: "Missing or invalid executorType" }, 400);
+      }
+
+      const prompt = String(body.prompt || "").trim();
+      if (!prompt) {
+        return c.json({ success: false, error: "Missing prompt" }, 400);
+      }
+
+      if (executorType === "model" && !String(body.modelId || "").trim()) {
+        return c.json({ success: false, error: "Missing modelId" }, 400);
+      }
+      if (executorType === "acp" && !String(body.agentId || "").trim()) {
+        return c.json({ success: false, error: "Missing agentId" }, 400);
+      }
+
+      const payload = await service.run({
+        executorType,
+        prompt,
+        system: String(body.system || "").trim(),
+        pageContext: String(body.pageContext || "").trim(),
+        modelId: String(body.modelId || "").trim(),
+        agentId: String(body.agentId || "").trim(),
+      });
+      return c.json({
+        success: true,
+        ...payload,
+      });
+    } catch (error) {
+      return c.json({ success: false, error: String(error) }, 500);
+    }
+  });
+}

package/src/control/instant/InstantSessionService.ts

@@ -0,0 +1,278 @@
+/**
+ * InstantSessionService：Inline Composer 即时模式执行服务。
+ *
+ * 关键点（中文）
+ * - 统一承接 model 即时 executor。
+ * - 每次请求都创建独立临时 session，执行结束后立即清理临时目录与 executor。
+ * - 不复用长期 runtime session，也不进入 channel/chat 的普通投递链路。
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import os from "node:os";
+import { mkdtemp } from "node:fs/promises";
+import { generateId } from "@/utils/Id.js";
+import {
+  createModel,
+  drainDeferredPersistedUserMessages,
+  getLogger,
+  JsonlSessionCompactionComposer,
+  JsonlSessionHistoryComposer,
+  loadStaticSystemPrompts,
+  LocalSessionExecutor,
+  pickLastSuccessfulChatSendText,
+  resolveAssistantMessageForPersistence,
+  Session,
+} from "@downcity/agent";
+import type { Logger } from "@downcity/agent";
+import type { PlatformAgentOption } from "@downcity/agent";
+import type {
+  PlatformInlineInstantRunInput,
+  PlatformInlineInstantRunResult,
+  PlatformInlineInstantService,
+} from "@downcity/agent";
+import { InstantSystemComposer } from "@/control/instant/InstantSystemComposer.js";
+import type { Logger as AgentLogger } from "@downcity/agent";
+
+type InstantSessionServiceOptions = {
+  /**
+   * 根据 agentId 解析项目配置。
+   */
+  resolveAgentById?: (agentId: string) => Promise<PlatformAgentOption | null>;
+
+  /**
+   * 可选统一日志器。
+   */
+  logger?: Logger;
+};
+
+type TempSessionRuntime = {
+  /**
+   * 本次即时执行使用的临时 sessionId。
+   */
+  sessionId: string;
+
+  /**
+   * 临时 session 落盘目录。
+   */
+  tempDirPath: string;
+
+  /**
+   * 当前临时 session 实例。
+   */
+  session: Session;
+};
+
+function buildInstantPrompt(input: {
+  prompt: string;
+  pageContext?: string;
+}): string {
+  const prompt = String(input.prompt || "").trim();
+  const pageContext = String(input.pageContext || "").trim();
+  if (!pageContext) return prompt;
+  return [
+    prompt,
+    "",
+    "以下是补充页面上下文（Markdown）：",
+    "",
+    "```markdown",
+    pageContext,
+    "```",
+  ].join("\n").trim();
+}
+
+
+function readAssistantFallbackText(text: string, resultText: string): string {
+  const picked = String(text || "").trim();
+  if (picked) return picked;
+  return String(resultText || "").trim();
+}
+
+function readAssistantMessageText(result: {
+  assistantMessage?: {
+    parts?: Array<{
+      type?: unknown;
+      text?: unknown;
+    }>;
+  };
+} | null | undefined): string {
+  const parts = Array.isArray(result?.assistantMessage?.parts)
+    ? result.assistantMessage.parts
+    : [];
+  return parts
+    .map((part) =>
+      part?.type === "text" ? String(part.text || "").trim() : "",
+    )
+    .filter(Boolean)
+    .join("\n")
+    .trim();
+}
+
+/**
+ * 即时模式服务默认实现。
+ */
+export class InstantSessionService implements PlatformInlineInstantService {
+  private readonly resolveAgentById: InstantSessionServiceOptions["resolveAgentById"];
+  private readonly logger: Logger;
+
+  constructor(options?: InstantSessionServiceOptions) {
+    this.resolveAgentById = options?.resolveAgentById;
+    this.logger = options?.logger || getLogger();
+  }
+
+  async run(
+    input: PlatformInlineInstantRunInput,
+  ): Promise<PlatformInlineInstantRunResult> {
+    const executorType = String(input.executorType || "").trim();
+    if (executorType === "model") {
+      return await this.runModelInstant({
+        ...input,
+        executorType: "model",
+      });
+    }
+
+    throw new Error(`Unsupported inline instant executor: ${String(input.executorType || "")}`);
+  }
+
+  private async createTempHistoryComposer(params: {
+    rootPath: string;
+    sessionId: string;
+  }): Promise<{
+    tempDirPath: string;
+    historyComposer: JsonlSessionHistoryComposer;
+  }> {
+    const tempDirPath = await mkdtemp(
+      path.join(os.tmpdir(), "downcity-inline-instant-"),
+    );
+    const historyComposer = new JsonlSessionHistoryComposer({
+      rootPath: params.rootPath,
+      sessionId: params.sessionId,
+      paths: {
+        sessionDirPath: tempDirPath,
+        messagesDirPath: tempDirPath,
+        messagesFilePath: path.join(tempDirPath, "messages.jsonl"),
+        metaFilePath: path.join(tempDirPath, "meta.json"),
+        archiveDirPath: path.join(tempDirPath, "archive"),
+      },
+    });
+    return {
+      tempDirPath,
+      historyComposer,
+    };
+  }
+
+  private async executeTempSession(params: {
+    sessionRuntime: TempSessionRuntime;
+    query: string;
+  }): Promise<{ sessionId: string; text: string }> {
+    const query = String(params.query || "").trim();
+    if (!query) throw new Error("instant prompt cannot be empty");
+
+    const { sessionRuntime } = params;
+    try {
+      await sessionRuntime.session.appendUserMessage({
+        text: query,
+      });
+
+      const result = await sessionRuntime.session.run({
+        query,
+      });
+      const userVisible = pickLastSuccessfulChatSendText(result.assistantMessage).trim();
+      const assistantText = readAssistantMessageText(result);
+      const messageForPersistence = resolveAssistantMessageForPersistence(
+        result.assistantMessage,
+      );
+      if (messageForPersistence) {
+        await sessionRuntime.session.appendAssistantMessage({
+          message: messageForPersistence,
+          fallbackText: readAssistantFallbackText(userVisible, assistantText),
+          extra: {
+            via: "control_plane_instant",
+          },
+        });
+      }
+      const deferredInjectedMessages = drainDeferredPersistedUserMessages(
+        sessionRuntime.sessionId,
+      );
+      for (const message of deferredInjectedMessages) {
+        await sessionRuntime.session.appendUserMessage({
+          message,
+        });
+      }
+      return {
+        sessionId: sessionRuntime.sessionId,
+        text: readAssistantFallbackText(userVisible, assistantText),
+      };
+    } finally {
+      sessionRuntime.session.clearExecutor();
+      await fs.remove(sessionRuntime.tempDirPath).catch(() => undefined);
+    }
+  }
+
+  private buildSessionId(): string {
+    return `inline-instant-model`;
+  }
+
+  private async runModelInstant(
+    input: PlatformInlineInstantRunInput & { executorType: "model" },
+  ): Promise<PlatformInlineInstantRunResult> {
+    const modelId = String(input.modelId || "").trim();
+    if (!modelId) throw new Error("modelId is required for inline model executor");
+
+    const sessionId = this.buildSessionId();
+    const rootPath = process.cwd();
+    const { tempDirPath, historyComposer } = await this.createTempHistoryComposer({
+      rootPath,
+      sessionId,
+    });
+    const model = await createModel({
+      config: {
+        name: "console-inline-instant-model",
+        version: "1.0.0",
+        execution: {
+          type: "api",
+          modelId,
+        },
+      },
+    });
+    const compactionComposer = new JsonlSessionCompactionComposer();
+    const systemComposer = new InstantSystemComposer({
+      prompts: [String(input.system || "").trim()].filter(Boolean),
+      projectRoot: rootPath,
+    });
+
+    const session = new Session({
+      sessionId,
+      historyComposer,
+      createExecutor: (sessionHistoryComposer) =>
+        new LocalSessionExecutor({
+          model,
+          logger: this.logger as unknown as AgentLogger,
+          historyComposer: sessionHistoryComposer,
+          compactionComposer,
+          systemComposer,
+          getTools: () => ({}),
+        }),
+    });
+
+    const text = await this.executeTempSession({
+      sessionRuntime: {
+        sessionId,
+        tempDirPath,
+        session,
+      },
+      query: buildInstantPrompt({
+        prompt: String(input.prompt || "").trim(),
+        pageContext: input.pageContext,
+      }),
+    });
+
+    return {
+      sessionId: text.sessionId,
+      executorType: "model",
+      modelId,
+      text: text.text,
+    };
+  }
+
+}

package/src/control/instant/InstantSystemComposer.ts

@@ -0,0 +1,60 @@
+/**
+ * InstantSystemComposer：即时模式临时 session 的 system composer。
+ *
+ * 关键点（中文）
+ * - 只负责把传入的静态 prompt 文本转为 system messages。
+ * - 不依赖完整 AgentContext，避免为了即时模式拉起正式 runtime。
+ * - 支持项目路径与 sessionId 变量替换，保留 PROFILE/SOUL 等静态提示的可用性。
+ */
+
+import {
+  getSessionRunScope,
+  SessionSystemComposer,
+  transformPromptsIntoSystemMessages,
+} from "@downcity/agent";
+
+type InstantSystemComposerOptions = {
+  /**
+   * 当前要注入的静态 prompt 文本集合。
+   */
+  prompts: string[];
+
+  /**
+   * 可选项目根目录。
+   *
+   * 说明（中文）
+   * - 用于替换 system prompt 里的项目路径变量。
+   */
+  projectRoot?: string;
+};
+
+/**
+ * 即时模式 system composer 默认实现。
+ */
+export class InstantSystemComposer extends SessionSystemComposer {
+  readonly name = "inline_instant_system";
+
+  private readonly prompts: string[];
+  private readonly projectRoot: string;
+
+  constructor(options: InstantSystemComposerOptions) {
+    super();
+    this.prompts = Array.isArray(options.prompts)
+      ? options.prompts
+          .map((item) => String(item || "").trim())
+          .filter(Boolean)
+      : [];
+    this.projectRoot = String(options.projectRoot || "").trim();
+  }
+
+  async resolve() {
+    if (this.prompts.length < 1) return [];
+    const scope = getSessionRunScope();
+    return await transformPromptsIntoSystemMessages(this.prompts, {
+      ...(this.projectRoot ? { projectPath: this.projectRoot } : {}),
+      ...(String(scope?.sessionId || "").trim()
+        ? { sessionId: String(scope?.sessionId || "").trim() }
+        : {}),
+    });
+  }
+}

package/src/http/auth/AuthMiddleware.ts

@@ -7,7 +7,7 @@
  */
 
 import type { Context, MiddlewareHandler } from "hono";
-import type { AuthPrincipal } from "@/shared/types/auth/AuthTypes.js";
+import type { AuthPrincipal } from "@downcity/agent";
 import { isAuthError } from "./AuthError.js";
 import type { AuthService } from "./AuthService.js";
 

package/src/http/auth/AuthService.ts

@@ -6,9 +6,9 @@
  * - 路由层只调用这里，不直接碰数据库与密码哈希细节。
  */
 
-import type { AuthIssuedToken, AuthTokenSummary } from "@/shared/types/auth/AuthToken.js";
-import type { AuthPrincipal, AuthTokenRecord, AuthUser } from "@/shared/types/auth/AuthTypes.js";
-import { optionalTrimmedText } from "@/shared/utils/store/StoreShared.js";
+import type { AuthIssuedToken, AuthTokenSummary } from "@downcity/agent";
+import type { AuthPrincipal, AuthTokenRecord, AuthUser } from "@downcity/agent";
+import { optionalTrimmedText } from "@downcity/agent";
 import { AuthError } from "./AuthError.js";
 import { AuthStore, type AuthStoreOptions } from "./AuthStore.js";
 import { extractBearerToken, generateAccessToken, hashAccessToken } from "./TokenService.js";

package/src/http/auth/AuthStore.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 该模块只负责 `auth_*` 表的读写，不处理密码校验与 HTTP 语义。
- * - 数据仍落在 console 的 SQLite 中，与现有控制面共享底层存储。
+ * - 数据仍落在控制面全局 SQLite 中，与现有平台配置共享底层存储。
  */
 
 import fs from "fs-extra";
@@ -11,29 +11,29 @@ import path from "node:path";
 import Database from "better-sqlite3";
 import { drizzle } from "drizzle-orm/better-sqlite3";
 import { nanoid } from "nanoid";
-import { getConsoleShipDbPath } from "@/runtime/CityPaths.js";
-import type { AuthIssuedToken, AuthTokenSummary } from "@/shared/types/auth/AuthToken.js";
+import { getPlatformStoreDbPath } from "@/process/registry/CityPaths.js";
+import type { AuthIssuedToken, AuthTokenSummary } from "@downcity/agent";
 import {
   AUTH_DEFAULT_ROLES,
   AUTH_PERMISSION_DESCRIPTIONS,
   AUTH_PERMISSION_KEYS,
   type AuthDefaultRoleName,
   type AuthPermissionKey,
-} from "@/shared/types/auth/AuthPermission.js";
+} from "@downcity/agent";
 import type {
   AuthAuditLog,
   AuthPermission,
   AuthRole,
   AuthTokenRecord,
   AuthUser,
-} from "@/shared/types/auth/AuthTypes.js";
-import { ensureConsoleStoreSchema } from "@/shared/utils/store/StoreSchema.js";
+} from "@downcity/agent";
+import { ensurePlatformStoreSchema } from "@downcity/agent";
 import {
   nowIso,
   normalizeNonEmptyText,
   optionalTrimmedText,
-  type ConsoleStoreContext,
-} from "@/shared/utils/store/StoreShared.js";
+  type PlatformStoreContext,
+} from "@downcity/agent";
 
 /**
  * AuthStore 构造参数。
@@ -52,10 +52,10 @@ type SqliteRow = Record<string, unknown>;
  */
 export class AuthStore {
   private readonly sqlite: Database.Database;
-  private readonly context: ConsoleStoreContext;
+  private readonly context: PlatformStoreContext;
 
   constructor(options: AuthStoreOptions = {}) {
-    const dbPath = path.resolve(options.dbPath || getConsoleShipDbPath());
+    const dbPath = path.resolve(options.dbPath || getPlatformStoreDbPath());
     fs.ensureDirSync(path.dirname(dbPath));
     this.sqlite = new Database(dbPath);
     this.sqlite.pragma("journal_mode = WAL");
@@ -63,7 +63,7 @@ export class AuthStore {
       sqlite: this.sqlite,
       db: drizzle(this.sqlite),
     };
-    ensureConsoleStoreSchema(this.context);
+    ensurePlatformStoreSchema(this.context);
   }
 
   /**

package/src/http/auth/RoutePolicy.ts

@@ -7,8 +7,8 @@
  */
 
 import type { MiddlewareHandler } from "hono";
-import type { AuthRoutePolicy } from "@/shared/types/auth/AuthRoute.js";
-import type { AuthPermissionKey } from "@/shared/types/auth/AuthPermission.js";
+import type { AuthRoutePolicy } from "@downcity/agent";
+import type { AuthPermissionKey } from "@downcity/agent";
 import { isAuthError as isAuthDomainError } from "./AuthError.js";
 import type { AuthService } from "./AuthService.js";
 import { AUTH_PRINCIPAL_CONTEXT_KEY, type AuthMiddlewareVariables } from "./AuthMiddleware.js";
@@ -62,34 +62,34 @@ export const SERVER_AUTH_ROUTE_POLICIES: AuthRoutePolicy[] = [
     anyPermissions: ["plugin.write"],
   },
   {
-    path: "/api/dashboard/authorization",
+    path: "/api/control/authorization",
     method: "GET",
     requireAuth: true,
     anyPermissions: ["auth.read"],
   },
   {
-    path: "/api/dashboard/authorization/config",
+    path: "/api/control/authorization/config",
     method: "POST",
     requireAuth: true,
     anyPermissions: ["auth.write"],
   },
   {
-    path: "/api/dashboard/authorization/action",
+    path: "/api/control/authorization/action",
     method: "POST",
     requireAuth: true,
     anyPermissions: ["auth.write"],
   },
   {
-    path: "/api/dashboard/*",
+    path: "/api/control/*",
     method: "*",
     requireAuth: true,
   },
 ];
 
 /**
- * Console 网关侧路由权限矩阵。
+ * 控制面网关侧路由权限矩阵。
  */
-export const CONSOLE_AUTH_ROUTE_POLICIES: AuthRoutePolicy[] = [
+export const CONTROL_PLANE_AUTH_ROUTE_POLICIES: AuthRoutePolicy[] = [
   { path: "/api/auth/*", method: "*", requireAuth: false },
   { path: "/health", method: "GET", requireAuth: false },
   {