@downcity/agent 1.1.32 → 1.1.43

package/src/plugin/core/ProjectConfigStore.ts

@@ -10,6 +10,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
+import type { AgentPluginConfigRuntime } from "@/types/runtime/host/AgentHost.js";
 
 type PersistableSections = {
   /**
@@ -18,6 +19,17 @@ type PersistableSections = {
   plugins?: DowncityConfig["plugins"];
 };
 
+type ProjectPluginConfigCarrier = {
+  /**
+   * 当前项目配置对象。
+   */
+  config: DowncityConfig;
+  /**
+   * plugin 配置持久化能力。
+   */
+  pluginConfig: AgentPluginConfigRuntime;
+};
+
 function getProjectDowncityJsonPath(projectRoot: string): string {
   return path.join(path.resolve(projectRoot), "downcity.json");
 }
@@ -32,6 +44,91 @@ async function readProjectDowncityConfig(projectRoot: string): Promise<DowncityC
   return parsed as DowncityConfig;
 }
 
+function readProjectPluginRecordFromConfig(
+  config: Pick<DowncityConfig, "plugins"> | null | undefined,
+  pluginName: string,
+): Record<string, unknown> {
+  const normalizedPluginName = String(pluginName || "").trim();
+  if (!normalizedPluginName) return {};
+  const current = config?.plugins?.[normalizedPluginName];
+  if (!current || typeof current !== "object" || Array.isArray(current)) {
+    return {};
+  }
+  return current as Record<string, unknown>;
+}
+
+/**
+ * 从项目配置读取单个 plugin 的原始配置块。
+ */
+export function readProjectPluginRecord(
+  config: Pick<DowncityConfig, "plugins"> | null | undefined,
+  pluginName: string,
+): Record<string, unknown> {
+  return readProjectPluginRecordFromConfig(config, pluginName);
+}
+
+/**
+ * 从项目配置读取单个 plugin 的启用态。
+ *
+ * 关键点（中文）
+ * - 除 `auth` 外，未显式配置 `enabled: false` 时默认视为启用。
+ * - 这样可以保持“零配置即可使用”的内建 plugin 体验。
+ */
+export function readProjectPluginEnabled(params: {
+  /**
+   * 项目配置对象（可选）。
+   */
+  config?: Pick<DowncityConfig, "plugins"> | null;
+  /**
+   * plugin 名称。
+   */
+  pluginName: string;
+}): boolean {
+  const normalizedPluginName = String(params.pluginName || "").trim();
+  if (!normalizedPluginName) return false;
+  if (normalizedPluginName === "auth") return true;
+  const current = readProjectPluginRecordFromConfig(params.config, normalizedPluginName);
+  return current.enabled !== false;
+}
+
+/**
+ * 将单个 plugin 的启用态写回项目配置。
+ *
+ * 关键点（中文）
+ * - 这里只维护 `plugins.<name>.enabled`，不理解插件私有字段语义。
+ * - 其余配置字段会原样保留，避免开关动作覆盖插件已有设置。
+ */
+export async function writeProjectPluginEnabled(params: {
+  /**
+   * 目标 plugin 名称。
+   */
+  pluginName: string;
+  /**
+   * 目标启用态。
+   */
+  enabled: boolean;
+  /**
+   * 当前项目配置与持久化能力。
+   */
+  context: ProjectPluginConfigCarrier;
+}): Promise<void> {
+  const normalizedPluginName = String(params.pluginName || "").trim();
+  if (!normalizedPluginName || normalizedPluginName === "auth") return;
+  if (!params.context.config.plugins) {
+    params.context.config.plugins = {};
+  }
+  params.context.config.plugins[normalizedPluginName] = {
+    ...readProjectPluginRecordFromConfig(
+      params.context.config,
+      normalizedPluginName,
+    ),
+    enabled: params.enabled,
+  };
+  await params.context.pluginConfig.persistProjectPlugins(
+    params.context.config.plugins,
+  );
+}
+
 /**
  * 将 plugins 配置块写回项目 `downcity.json`。
  */

package/src/plugin/types/ActionSchedule.ts

@@ -0,0 +1,94 @@
+/**
+ * ActionSchedule：plugin action 延迟执行能力的共享类型。
+ *
+ * 关键点（中文）
+ * - 这里描述的是“某个 plugin action 在未来某个时间执行”的通用记录。
+ * - 它不是独立 plugin，也不表达业务语义，只服务于 plugin command/action 协议。
+ * - 外部请求字段仍可叫 `schedule`，但内部类型统一归入 ActionSchedule 模块。
+ */
+
+import type { JsonValue } from "@/types/common/Json.js";
+
+/**
+ * ActionSchedule 任务状态。
+ */
+export type ActionScheduleJobStatus =
+  | "pending"
+  | "running"
+  | "succeeded"
+  | "failed"
+  | "cancelled";
+
+/**
+ * ActionSchedule 任务完整记录。
+ */
+export interface ActionScheduleJobRecord {
+  /**
+   * ActionSchedule 任务唯一 ID。
+   */
+  id: string;
+  /**
+   * 目标 plugin 名称。
+   */
+  pluginName: string;
+  /**
+   * 目标 action 名称。
+   */
+  actionName: string;
+  /**
+   * 原始 action payload。
+   */
+  payload: JsonValue;
+  /**
+   * 计划执行时间（毫秒时间戳）。
+   */
+  runAtMs: number;
+  /**
+   * 当前任务状态。
+   */
+  status: ActionScheduleJobStatus;
+  /**
+   * 最近一次错误文本。
+   */
+  error?: string;
+  /**
+   * 创建时间（毫秒时间戳）。
+   */
+  createdAt: number;
+  /**
+   * 最近更新时间（毫秒时间戳）。
+   */
+  updatedAt: number;
+}
+
+/**
+ * 创建 ActionSchedule 任务所需输入。
+ */
+export interface CreateActionScheduleJobInput {
+  /**
+   * 目标 plugin 名称。
+   */
+  pluginName: string;
+  /**
+   * 目标 action 名称。
+   */
+  actionName: string;
+  /**
+   * 目标 action payload。
+   */
+  payload: JsonValue;
+  /**
+   * 计划执行时间（毫秒时间戳）。
+   */
+  runAtMs: number;
+}
+
+/**
+ * 统一 plugin action 延迟执行输入。
+ */
+export interface PluginActionScheduleInput {
+  /**
+   * 计划执行时间（毫秒时间戳）。
+   */
+  runAtMs: number;
+}

package/src/plugin/types/Plugin.ts

@@ -11,13 +11,12 @@ import type { Command } from "commander";
 import type { Context as HonoContext, Hono } from "hono";
 import type {
   AgentPathRuntime,
-  AgentPlatformRuntime,
   AgentPluginConfigRuntime,
 } from "@/types/runtime/host/AgentHost.js";
 import type {
   AgentContext,
   StructuredConfig,
-} from "@/core/AgentContextTypes.js";
+} from "@/types/runtime/agent/AgentContext.js";
 import type { Logger } from "@/utils/logger/Logger.js";
 import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
 import type { JsonObject, JsonValue } from "@/types/common/Json.js";
@@ -137,7 +136,7 @@ export interface PluginStateControlResult {
  *
  * 关键点（中文）
  * - 这里表达的是“CLI 命令执行 plugin 时真正需要的最小上下文”。
- * - plugin 命令不应依赖 session、service invoke、agent runtime 等长期宿主对象。
+ * - plugin 命令不应依赖 session、plugin invoke、agent runtime 等长期宿主对象。
  * - agent runtime 在需要复用 action 时，直接传入自身更完整的 AgentContext 即可。
  */
 export interface PluginCommandContext {
@@ -159,12 +158,12 @@ export interface PluginCommandContext {
   config: DowncityConfig;
   /**
    * 当前项目环境变量快照。
+   *
+   * 关键点（中文）
+   * - 这里约定为宿主已经整理好的最终可见 env 视图。
+   * - plugin 不再区分 global env 与 agent env，避免上下文语义膨胀。
    */
   env: Record<string, string>;
-  /**
-   * 当前平台级全局环境变量快照。
-   */
-  globalEnv: Record<string, string>;
   /**
    * 当前可见的路径能力集合。
    */
@@ -173,20 +172,16 @@ export interface PluginCommandContext {
    * 当前可见的 plugin 配置持久化能力集合。
    */
   pluginConfig: AgentPluginConfigRuntime;
-  /**
-   * 当前可见的平台能力集合。
-   */
-  platform: AgentPlatformRuntime;
 }
 
 /**
- * Service 调用参数。
+ * Plugin action 调用参数。
  */
-export interface PluginServiceInvokeParams {
+export interface PluginActionInvokeParams {
   /**
-   * 目标 service 名称。
+   * 目标 plugin 名称。
    */
-  service: string;
+  plugin: string;
   /**
    * 目标 action 名称。
    */
@@ -198,9 +193,9 @@ export interface PluginServiceInvokeParams {
 }
 
 /**
- * Service 调用结果。
+ * Plugin action 调用结果。
  */
-export interface PluginServiceInvokeResult {
+export interface PluginActionInvokeResult {
   /**
    * 调用是否成功。
    */
@@ -216,15 +211,15 @@ export interface PluginServiceInvokeResult {
 }
 
 /**
- * Service 调用端口。
+ * Plugin action 调用端口。
  */
-export interface PluginServiceInvokePort {
+export interface PluginActionInvokePort {
   /**
-   * 调用指定 service action。
+   * 调用指定 plugin action。
    */
   invoke(
-    params: PluginServiceInvokeParams,
-  ): Promise<PluginServiceInvokeResult>;
+    params: PluginActionInvokeParams,
+  ): Promise<PluginActionInvokeResult>;
 }
 
 /**
@@ -267,7 +262,7 @@ export interface PluginCommandResult {
  * Plugin 生命周期兼容定义。
  *
  * 关键点（中文）
- * - 这是从旧 service lifecycle 过渡过来的兼容层。
+ * - 这是从旧运行生命周期过渡过来的兼容层。
  * - 新代码优先直接实现 `start/stop/command`。
  */
 export interface PluginLifecycle {
@@ -608,10 +603,6 @@ export interface PluginAction<
      * 当前插件名称。
      */
     pluginName: string;
-    /**
-     * 兼容旧 service action 参数名。
-     */
-    serviceName?: string;
     /**
      * 当前 Action 名称。
      */
@@ -816,13 +807,13 @@ export interface PluginUsageDefinition {
 }
 
 /**
- * Plugin runtime HTTP 注入参数。
+ * Plugin HTTP 注入参数。
  *
  * 关键点（中文）
  * - plugin 只声明自己的路由与鉴权策略，不感知 server 装配细节。
  * - console 会复用相同路径策略保护代理请求，但不会重复注册路由本身。
  */
-export interface PluginRuntimeHttpRegistration {
+export interface PluginHttpRegistration {
   /**
    * 该组路由对应的鉴权策略列表。
    */
@@ -851,9 +842,9 @@ export interface PluginRuntimeHttpRegistration {
  */
 export interface PluginHttpDefinition {
   /**
-   * runtime HTTP 路由注入（可选）。
+   * server HTTP 路由注入（可选）。
    */
-  runtime?: PluginRuntimeHttpRegistration;
+  server?: PluginHttpRegistration;
 }
 
 /**
@@ -909,7 +900,7 @@ export interface Plugin {
    */
   system?: (context: AgentContext) => string | Promise<string>;
   /**
-   * 旧 service lifecycle 兼容定义（可选）。
+   * 旧生命周期兼容定义（可选）。
    */
   lifecycle?: PluginLifecycle;
   /**

package/src/plugin/types/PluginApi.ts

@@ -1,5 +1,5 @@
 /**
- * plugin 管理命令与 API 类型。
+ * plugin catalog / availability / action API 类型。
  *
  * 关键点（中文）
  * - 统一描述 CLI -> daemon 的 plugin 管理协议。
@@ -73,9 +73,9 @@ export interface PluginAvailabilityView {
 }
 
 /**
- * plugin list 响应。
+ * plugin catalog 响应。
  */
-export interface PluginListResponse {
+export interface PluginCatalogResponse {
   /**
    * 请求是否成功。
    */

package/src/plugin/types/PluginState.ts

@@ -8,9 +8,4 @@ export type {
   PluginStateControlResult,
   PluginStateRecord,
   PluginStateSnapshot,
-  PluginState as ServiceState,
-  PluginStateControlAction as ServiceStateControlAction,
-  PluginStateControlResult as ServiceStateControlResult,
-  PluginStateRecord as ServiceStateRecord,
-  PluginStateSnapshot as ServiceStateSnapshot,
 } from "@/plugin/types/Plugin.js";

package/src/plugin/types/Plugins.ts

@@ -29,9 +29,9 @@ export type PluginStateView = {
 };
 
 /**
- * plugin 列表响应。
+ * plugin 状态列表响应。
  */
-export type PluginListResponse = {
+export type PluginStateListResponse = {
   success: boolean;
   plugins?: PluginStateView[];
   error?: string;

package/src/runtime/host/AgentHostRuntime.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - agent runtime 负责创建这些宿主能力对象，再注入到 AgentRuntime。
- * - service / session / plugin 只消费这些对象，不直接依赖具体宿主实现。
+ * - plugin runtime / session / plugin 作者 API 只消费这些对象，不直接依赖具体宿主实现。
  * - 当前先收敛路径与 plugin 配置持久化两类宿主能力。
  */
 import {

package/src/runtime/host/daemon/Api.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 这里描述的是 CLI 与 agent daemon 之间的远程访问契约，不包含具体 HTTP 实现。
- * - service 等上层模块只依赖这些协议类型，不需要感知 city/daemon 的内部实现细节。
+ * - plugin runtime 等上层模块只依赖这些协议类型，不需要感知 city/daemon 的内部实现细节。
  * - 该文件属于 agent daemon 访问协议边界，而不是通用 HTTP 类型目录。
  */
 
@@ -40,7 +40,7 @@ export type DaemonJsonApiCallParams = {
    *
    * 说明（中文）
    * - 仅本地 IPC transport 当前会消费该参数。
-   * - 用于 `session execute`、`service command` 这类可能持续几十秒的请求，
+   * - 用于 `session execute`、`plugin command` 这类可能持续几十秒的请求，
    *   避免被默认短超时误判成“Agent server 未启动”。
    */
   timeoutMs?: number;

package/src/runtime/host/daemon/ProjectSetup.ts

@@ -8,11 +8,6 @@
 
 import fs from "fs-extra";
 import path from "node:path";
-import { loadDowncityConfig } from "@/config/Config.js";
-import {
-  readProjectPrimaryModelId,
-} from "@/config/ExecutionBinding.js";
-import type { AgentPlatformRuntime } from "@/types/runtime/host/AgentHost.js";
 import {
   getCacheDirPath,
   getDowncityAgentsRootDirPath,
@@ -73,51 +68,3 @@ export function ensureRuntimeProjectReady(projectRoot: string): void {
   ensureContextFiles(projectRoot);
   ensureShipDirectories(projectRoot);
 }
-
-/**
- * 校验项目执行绑定是否可用于启动。
- *
- * 关键点（中文）
- * - `downcity.json.execution` 必须存在且合法。
- * - 若走 API 模式，则 `execution.modelId` 必须在 console 模型池中可解析。
- * - 若走 local 模式，则 `lmp` plugin 必须启用且本地模型文件必须存在。
- * - 若模型被 pause，也要在启动前直接拒绝，避免进程拉起后秒退。
- */
-export function ensureRuntimeExecutionBindingReady(
-  projectRoot: string,
-  platform?: Pick<AgentPlatformRuntime, "getModel">,
-): void {
-  let primaryModelId = "";
-  try {
-    const config = loadDowncityConfig(projectRoot);
-    primaryModelId = readProjectPrimaryModelId(config);
-  } catch (error) {
-    console.error("❌ Invalid downcity.json execution binding");
-    console.error(`   project: ${projectRoot}`);
-    console.error(`   error: ${error instanceof Error ? error.message : String(error)}`);
-    process.exit(1);
-  }
-
-  if (!primaryModelId) {
-    console.error("❌ Invalid downcity.json execution binding");
-    console.error(`   project: ${projectRoot}`);
-    console.error('   error: "execution" must be { "type": "api", "modelId": "..." }');
-    process.exit(1);
-  }
-
-  const model = platform?.getModel(primaryModelId);
-  if (!model) {
-    console.error("❌ Model not found in platform model pool");
-    console.error(`   project: ${projectRoot}`);
-    console.error(`   execution.modelId: ${primaryModelId}`);
-    console.error("   fix: run `city model create` or `city model list`");
-    process.exit(1);
-  }
-  if (model.isPaused === true) {
-    console.error("❌ Model is paused");
-    console.error(`   project: ${projectRoot}`);
-    console.error(`   execution.modelId: ${primaryModelId}`);
-    console.error(`   fix: run \`city model pause ${primaryModelId} --enabled false\``);
-    process.exit(1);
-  }
-}

package/src/runtime/sandbox/SandboxConfigResolver.ts

@@ -8,7 +8,7 @@
  */
 
 import path from "node:path";
-import type { AgentContext } from "@/core/AgentContextTypes.js";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
 import type { ResolvedSandboxConfig } from "@/runtime/sandbox/types/SandboxRuntime.js";
 
 const DEFAULT_ENV_ALLOWLIST = [

package/src/runtime/sandbox/SandboxRunner.ts

@@ -7,7 +7,7 @@
  * - shell 命令不再允许回退到宿主机普通子进程执行。
  */
 
-import type { AgentContext } from "@/core/AgentContextTypes.js";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
 import type { SandboxSpawnResult } from "@/runtime/sandbox/types/SandboxRuntime.js";
 import { resolveSandboxConfig, resolveSandboxCwd } from "@/runtime/sandbox/SandboxConfigResolver.js";
 import { spawnMacOsSeatbeltSandbox } from "@/runtime/sandbox/MacOsSeatbeltSandbox.js";

package/src/runtime/sandbox/types/SandboxRuntime.ts

@@ -4,7 +4,7 @@
  * 关键点（中文）
  * - 这里放的是 agent 执行层内部使用的最小 sandbox 运行时类型。
  * - 当前只围绕 `SandboxRunner` 设计，不引入复杂 provider / policy / binding 对象。
- * - 目标是让 `ShellService` 可以直接把命令交给 `SandboxRunner` 执行。
+ * - 目标是让 shell plugin runtime 可以直接把命令交给 `SandboxRunner` 执行。
  */
 
 import type { ChildProcessWithoutNullStreams } from "node:child_process";

package/src/runtime/server/http/Server.ts

@@ -16,19 +16,13 @@ import { finished } from "node:stream/promises";
 import { logger as serverLogger } from "@/utils/logger/Logger.js";
 import { createExecuteRouter } from "@/runtime/server/http/execute/execute.js";
 import { healthRouter } from "@/runtime/server/http/health/health.js";
-import {
-  createServicesRouter,
-} from "@/runtime/server/http/services/services.js";
 import { createPluginsRouter } from "@/runtime/server/http/plugins/plugins.js";
 import { createStaticRouter } from "@/runtime/server/http/static/static.js";
 import { createControlRouter } from "@/runtime/server/http/control/ControlRouter.js";
 import { createSdkRouter } from "@/runtime/server/http/sdk/Router.js";
-import {
-  registerBuiltinPluginHttpRoutes,
-} from "@/plugin/core/HttpRoutes.js";
-import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
-import type { AgentContext } from "@/core/AgentContextTypes.js";
-import type { AgentCore } from "@/core/AgentCore.js";
+import type { AgentRuntime } from "@/types/runtime/agent/AgentRuntime.js";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type { AgentSessionCollection } from "@/types/agent/AgentTypes.js";
 
 /**
  * Server 启动参数。
@@ -38,12 +32,12 @@ export interface ServerStartOptions {
   port: number;
   /** HTTP 服务监听主机。 */
   host: string;
-  /** 可选实例级 agent core。 */
-  core?: Pick<AgentCore, "getContext" | "getRuntime" | "session" | "sessions">;
-  /** 可选实例级 runtime 读取函数。 */
-  getAgentRuntime?: () => AgentRuntime;
-  /** 可选实例级 context 读取函数。 */
-  getAgentContext?: () => AgentContext;
+  /** 当前 agent runtime 读取函数。 */
+  getAgentRuntime: () => AgentRuntime;
+  /** 当前 agent context 读取函数。 */
+  getAgentContext: () => AgentContext;
+  /** 可选 SDK Session 集合绑定。 */
+  sessionCollection?: AgentSessionCollection;
 }
 
 /**
@@ -58,41 +52,16 @@ export interface ServerInstance {
   stop(): Promise<void>;
 }
 
-type AgentServerBindings = {
-  getAgentRuntime: () => AgentRuntime;
-  getAgentContext: () => AgentContext;
-};
-
-function resolveServerBindings(options: Pick<
-  ServerStartOptions,
-  "core" | "getAgentRuntime" | "getAgentContext"
->): AgentServerBindings {
-  const core = options.core;
-  if (core) {
-    return {
-      getAgentRuntime: () => core.getRuntime(),
-      getAgentContext: () => core.getContext(),
-    };
-  }
-  if (options.getAgentRuntime && options.getAgentContext) {
-    return {
-      getAgentRuntime: options.getAgentRuntime,
-      getAgentContext: options.getAgentContext,
-    };
-  }
-  throw new Error(
-    "createServerApp/startServer requires either core or both getAgentRuntime/getAgentContext",
-  );
-}
-
 /**
  * 创建主 Hono 应用。
  */
 export function createServerApp(
-  options: Pick<ServerStartOptions, "core" | "getAgentRuntime" | "getAgentContext">,
+  options: Pick<
+    ServerStartOptions,
+    "getAgentRuntime" | "getAgentContext" | "sessionCollection"
+  >,
 ): Hono {
   const app = new Hono();
-  const bindings = resolveServerBindings(options);
 
   app.use("*", logger());
   app.use(
@@ -106,30 +75,29 @@ export function createServerApp(
 
   // 关键点（中文）：按路由域挂载，server 模块只保留装配职责。
   app.route("/", createStaticRouter({
-    getAgentRuntime: bindings.getAgentRuntime,
+    getAgentRuntime: options.getAgentRuntime,
   }));
   app.route("/", healthRouter);
-  const servicesRouter = createServicesRouter({
-    getAgentContext: bindings.getAgentContext,
-  });
-  app.route("/", servicesRouter);
   app.route("/", createPluginsRouter({
-    getAgentContext: bindings.getAgentContext,
+    getAgentContext: options.getAgentContext,
   }));
   app.route("/", createExecuteRouter({
-    getAgentRuntime: bindings.getAgentRuntime,
+    getAgentRuntime: options.getAgentRuntime,
   }));
   app.route("/", createControlRouter({
-    getAgentRuntime: bindings.getAgentRuntime,
-    getAgentContext: bindings.getAgentContext,
+    getAgentRuntime: options.getAgentRuntime,
+    getAgentContext: options.getAgentContext,
   }));
-  if (options.core) {
-    app.route("/", createSdkRouter(options.core));
+  if (options.sessionCollection) {
+    app.route("/", createSdkRouter(options.sessionCollection));
+  }
+  for (const plugin of options.getAgentContext().agent.pluginInstances.values()) {
+    plugin.http?.server?.register({
+      app,
+      getContext: options.getAgentContext,
+      pluginName: plugin.name,
+    });
   }
-  registerBuiltinPluginHttpRoutes({
-    app,
-    getContext: bindings.getAgentContext,
-  });
 
   return app;
 }