@downcity/agent 1.1.25 → 1.1.35

package/src/plugin/builtins/task/runtime/TaskRunnerTypes.ts

@@ -0,0 +1,199 @@
+/**
+ * TaskRunner 类型定义。
+ *
+ * 关键点（中文）
+ * - 这里集中声明 task runner 在拆分后跨模块共享的内部类型。
+ * - 这些类型服务于 task 运行链路，统一归档到 `src/types/task/`。
+ */
+
+import type { JsonlSessionHistoryStore } from "@/executor/store/history/jsonl/JsonlSessionHistoryStore.js";
+import type { SessionExecutor } from "@/executor/types/SessionExecutor.js";
+import type {
+  ShipTaskRunExecutionStatusV1,
+  ShipTaskRunProgressPhaseV1,
+  ShipTaskRunProgressStatusV1,
+  ShipTaskRunResultStatusV1,
+  ShipTaskRunStatusV1,
+} from "@/plugin/builtins/task/types/Task.js";
+
+/**
+ * run-progress.json 的当前快照状态。
+ */
+export type RunProgressSnapshot = {
+  /**
+   * 当前进度状态。
+   */
+  status: ShipTaskRunProgressStatusV1;
+  /**
+   * 当前进度阶段。
+   */
+  phase: ShipTaskRunProgressPhaseV1;
+  /**
+   * 当前阶段对人类可读的说明文本。
+   */
+  message: string;
+  /**
+   * 当前对话轮次。
+   */
+  round?: number;
+  /**
+   * 最大允许轮次。
+   */
+  maxRounds?: number;
+  /**
+   * 运行结束时间（毫秒时间戳）。
+   */
+  endedAt?: number;
+  /**
+   * 任务总体运行状态。
+   */
+  runStatus?: ShipTaskRunStatusV1;
+  /**
+   * 执行阶段状态。
+   */
+  executionStatus?: ShipTaskRunExecutionStatusV1;
+  /**
+   * 结果校验状态。
+   */
+  resultStatus?: ShipTaskRunResultStatusV1;
+};
+
+/**
+ * 任务结果校验结果。
+ */
+export type TaskResultValidation = {
+  /**
+   * 结果校验后的状态。
+   */
+  resultStatus: ShipTaskRunResultStatusV1;
+  /**
+   * 校验失败时的错误列表。
+   */
+  errors: string[];
+};
+
+/**
+ * 模拟用户的判定结果。
+ */
+export type UserSimulatorDecision = {
+  /**
+   * 模拟用户是否认为当前结果已满足要求。
+   */
+  satisfied: boolean;
+  /**
+   * 模拟用户给出的回复文本。
+   */
+  reply: string;
+  /**
+   * 判定理由。
+   */
+  reason: string;
+  /**
+   * 可选评分，范围通常为 0-10。
+   */
+  score?: number;
+  /**
+   * 原始输出文本快照。
+   */
+  raw: string;
+};
+
+/**
+ * 单轮对话的落盘记录。
+ */
+export type DialogueRoundRecord = {
+  /**
+   * 当前任务是否启用了 review 多轮模式。
+   */
+  reviewEnabled: boolean;
+  /**
+   * 当前轮次编号。
+   */
+  round: number;
+  /**
+   * 本轮执行器收到的 query。
+   */
+  executorQuery: string;
+  /**
+   * 本轮执行器输出文本。
+   */
+  executorOutput: string;
+  /**
+   * 本轮执行器是否通过 `chat_send` 等方式实际送达文本。
+   */
+  executorDelivered: boolean;
+  /**
+   * 执行器 assistantMessage 的调试快照。
+   */
+  executorAssistantMessageSnapshot?: string;
+  /**
+   * 本轮结果校验状态。
+   */
+  validationResultStatus: ShipTaskRunResultStatusV1;
+  /**
+   * 本轮规则校验失败项。
+   */
+  ruleErrors: string[];
+  /**
+   * 模拟用户收到的 query。
+   */
+  userSimulatorQuery?: string;
+  /**
+   * 模拟用户输出文本。
+   */
+  userSimulatorOutput?: string;
+  /**
+   * 模拟用户 assistantMessage 的调试快照。
+   */
+  userSimulatorAssistantMessageSnapshot?: string;
+  /**
+   * 模拟用户最终判定结果。
+   */
+  userSimulator: UserSimulatorDecision;
+  /**
+   * 传递给下一轮执行器的反馈文本。
+   */
+  feedbackForNextRound?: string;
+};
+
+/**
+ * script 类型任务的执行结果。
+ */
+export type ScriptExecutionResult = {
+  /**
+   * script 标准输出与标准错误合并后的文本。
+   */
+  outputText: string;
+};
+
+/**
+ * task 运行专用的 session runtime 端口。
+ *
+ * 关键点（中文）
+ * - task runner 不直接依赖具体 SDK `Session` 实现。
+ * - 这里暴露的是 task 场景最小可用端口：执行器 + history Store。
+ */
+export type TaskSessionRuntimePort = {
+  /**
+   * 获取指定 sessionId 对应的 Session 执行端口。
+   */
+  getExecutor(sessionId: string): SessionExecutor;
+  /**
+   * 获取指定 sessionId 对应的 JsonlSessionHistoryStore。
+   */
+  getHistoryStore(sessionId: string): JsonlSessionHistoryStore;
+};
+
+/**
+ * 从 assistant 输出中提取的文本结果。
+ */
+export type ChatSendOutputPick = {
+  /**
+   * 最终提取到的文本内容。
+   */
+  text: string;
+  /**
+   * 该文本是否已经通过 chat_send 等方式送达。
+   */
+  delivered: boolean;
+};

package/src/plugin/builtins/task/types/Cron.ts

@@ -0,0 +1,16 @@
+/**
+ * cron 触发定义。
+ */
+export type TaskCronTriggerDefinition = {
+  id: string;
+  expression: string;
+  timezone?: string;
+  execute: () => Promise<void> | void;
+};
+
+/**
+ * cron 引擎端口。
+ */
+export type TaskCronEngine = {
+  register(definition: TaskCronTriggerDefinition): void;
+};

package/src/plugin/builtins/task/types/TaskPluginTypes.ts

@@ -0,0 +1,55 @@
+/**
+ * Task plugin runtime 类型定义。
+ *
+ * 关键点（中文）
+ * - 这里集中声明 task plugin runtime 在类化拆分后共享的 action payload 与调度结果类型。
+ * - 跨模块复用的 task plugin runtime 类型统一收敛在 `plugin/builtins/task/types/`。
+ */
+
+import type { ShipTaskStatus } from "@/plugin/builtins/task/types/Task.js";
+
+/**
+ * `task.list` action 的输入载荷。
+ */
+export type TaskListActionPayload = {
+  /**
+   * 按任务状态过滤；省略时返回全部状态。
+   */
+  status?: ShipTaskStatus;
+};
+
+/**
+ * task cron runtime 启动或重载后的统计结果。
+ */
+export type TaskCronRegisterResult = {
+  /**
+   * 本次扫描到的任务定义数量。
+   */
+  tasksFound: number;
+  /**
+   * 本次成功注册到 cron engine 的作业数量。
+   */
+  jobsScheduled: number;
+};
+
+/**
+ * 任务定义变更后 scheduler 重载结果。
+ */
+export type TaskSchedulerReloadResult = {
+  /**
+   * scheduler 是否成功完成重载。
+   */
+  reloaded: boolean;
+  /**
+   * 成功重载时扫描到的任务数量。
+   */
+  tasksFound?: number;
+  /**
+   * 成功重载时注册成功的 cron 作业数量。
+   */
+  jobsScheduled?: number;
+  /**
+   * 重载失败时的错误文本。
+   */
+  error?: string;
+};

package/src/plugin/builtins/tts/Plugin.ts

@@ -6,6 +6,8 @@
  * - Console 只通过 setup / action 与插件交互，保持极简统一。
  */
 
+import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
+import { BasePlugin } from "@/plugin/core/BasePlugin.js";
 import type { Plugin } from "@/plugin/types/Plugin.js";
 import type {
   TtsInstallInput,
@@ -29,11 +31,9 @@ import {
   toJsonObject,
 } from "@/plugin/builtins/tts/PluginSupport.js";
 
-/**
- * ttsPlugin：文本转语音插件定义。
- */
-export const ttsPlugin: Plugin = {
-  name: "tts",
+function createTtsPluginDefinition(plugin: Plugin): Plugin {
+  return {
+    name: "tts",
   title: "Text To Speech",
   description:
     "Generates local speech audio files from plain text through an installed TTS model, then returns a reusable audio file tag for downstream sending.",
@@ -118,7 +118,7 @@ export const ttsPlugin: Plugin = {
     statusAction: "status",
   },
   async availability(context) {
-    if (!isPluginEnabled({ plugin: ttsPlugin, context })) {
+    if (!isPluginEnabled({ plugin, context })) {
       return {
         enabled: false,
         available: false,
@@ -143,7 +143,7 @@ export const ttsPlugin: Plugin = {
       },
       execute: async ({ context }) => {
         const config = readTtsPluginConfig(context);
-        const availability = await ttsPlugin.availability!(context);
+        const availability = await plugin.availability!(context);
         const synthesizer = await checkTtsSynthesizer(context);
         return {
           success: true,
@@ -446,7 +446,7 @@ export const ttsPlugin: Plugin = {
         },
       },
       execute: async ({ context, payload }) => {
-        const pluginStatus = await ttsPlugin.availability!(context);
+        const pluginStatus = await plugin.availability!(context);
         if (!pluginStatus.enabled || !pluginStatus.available) {
           return {
             success: false,
@@ -477,7 +477,7 @@ export const ttsPlugin: Plugin = {
     },
   },
   system(context) {
-    if (!isPluginEnabled({ plugin: ttsPlugin, context })) {
+    if (!isPluginEnabled({ plugin, context })) {
       return "";
     }
     return [
@@ -493,4 +493,17 @@ export const ttsPlugin: Plugin = {
       "Example: `city tts synthesize \"你好，欢迎来到 Downcity\" --format wav`",
     ].join("\n");
   },
-};
+  };
+}
+
+/**
+ * TtsPlugin：文本转语音插件。
+ */
+export class TtsPlugin extends BasePlugin {
+  readonly name = "tts";
+
+  constructor(agent: AgentRuntime | null = null) {
+    super(agent);
+    Object.assign(this, createTtsPluginDefinition(this));
+  }
+}

package/src/plugin/builtins/tts/runtime/Synthesizer.ts

@@ -13,7 +13,7 @@ import fs from "fs-extra";
 import type { TtsPluginConfig, TtsSynthesizeInput } from "@/plugin/builtins/tts/types/TtsPlugin.js";
 import type { TtsAudioFormat, TtsModelId } from "@/plugin/builtins/tts/types/Tts.js";
 import type { PluginCommandContext } from "@/plugin/types/Plugin.js";
-import { renderChatMessageFileTag } from "@/service/builtins/chat/runtime/ChatMessageMarkup.js";
+import { renderChatMessageFileTag } from "@/plugin/builtins/chat/runtime/ChatMessageMarkup.js";
 import { getTtsModelCatalogItem, resolveTtsModelId } from "@/plugin/builtins/tts/runtime/Catalog.js";
 import { resolveTtsModelsRootDir } from "@/plugin/builtins/tts/runtime/Paths.js";
 

package/src/plugin/builtins/voice/InboundAugment.ts

@@ -7,7 +7,7 @@
  */
 
 import type { AgentContext } from "@/core/AgentContextTypes.js";
-import type { ChatInboundAugmentInput } from "@/service/builtins/chat/types/ChatPlugin.js";
+import type { ChatInboundAugmentInput } from "@/plugin/builtins/chat/types/ChatPlugin.js";
 import type { JsonValue } from "@/types/common/Json.js";
 import { transcribeWithVoiceDependency } from "@/plugin/builtins/voice/Dependency.js";
 

package/src/plugin/builtins/web/Plugin.ts

@@ -5,6 +5,8 @@
  * - `web` plugin 不再自实现联网与浏览器能力，只负责 provider 选择、状态检查与提示词注入。
  * - 真正的联网逻辑直接交给外部实现：`web-access` 或 `agent-browser`。
  */
+import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
+import { BasePlugin } from "@/plugin/core/BasePlugin.js";
 import type { Plugin } from "@/plugin/types/Plugin.js";
 import type { JsonObject, JsonValue } from "@/types/common/Json.js";
 import type { WebPluginConfig, WebPluginInstallInput } from "@/plugin/builtins/web/types/WebPlugin.js";
@@ -82,11 +84,9 @@ function getInstallScopeOpt(
   return undefined;
 }
 
-/**
- * webPlugin：provider 选择器与提示词适配层。
- */
-export const webPlugin: Plugin = {
-  name: "web",
+function createWebPluginDefinition(plugin: Plugin): Plugin {
+  return {
+    name: "web",
   title: "Web Access",
   description:
     "Connects the agent to either web-access or agent-browser, checks provider readiness, and injects the matching guidance into the runtime prompt.",
@@ -164,7 +164,7 @@ export const webPlugin: Plugin = {
     statusAction: "status",
   },
   async availability(context) {
-    if (!isPluginEnabled({ plugin: webPlugin, context })) {
+    if (!isPluginEnabled({ plugin, context })) {
       return {
         enabled: false,
         available: false,
@@ -189,7 +189,7 @@ export const webPlugin: Plugin = {
       },
       execute: async ({ context }) => {
         const config = readWebPluginConfig(context);
-        const availability = await webPlugin.availability!(context);
+        const availability = await plugin.availability!(context);
         const source = await inspectWebPluginDependency(context);
         return {
           success: true,
@@ -461,7 +461,7 @@ export const webPlugin: Plugin = {
         },
       },
       execute: async ({ context }) => {
-        const availability = await webPlugin.availability!(context);
+        const availability = await plugin.availability!(context);
         const dependency = await doctorWebPluginDependency(context);
         return {
           success: true,
@@ -482,7 +482,7 @@ export const webPlugin: Plugin = {
   },
   system(context) {
     const config = readWebPluginConfig(context);
-    if (!isPluginEnabled({ plugin: webPlugin, context }) || !config.injectPrompt) {
+    if (!isPluginEnabled({ plugin, context }) || !config.injectPrompt) {
       return "";
     }
     const providerPrompt =
@@ -498,4 +498,17 @@ export const webPlugin: Plugin = {
       providerPrompt,
     ].join("\n");
   },
-};
+  };
+}
+
+/**
+ * WebPlugin：provider 选择器与提示词适配层。
+ */
+export class WebPlugin extends BasePlugin {
+  readonly name = "web";
+
+  constructor(agent: AgentRuntime | null = null) {
+    super(agent);
+    Object.assign(this, createWebPluginDefinition(this));
+  }
+}

package/src/plugin/builtins/workboard/Plugin.ts

@@ -6,76 +6,89 @@
  * - 当前通过 plugin HTTP 注入暴露 `/api/workboard/snapshot`，供 console 代理与 UI 消费。
  */
 
+import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
+import { BasePlugin } from "@/plugin/core/BasePlugin.js";
 import type { Plugin } from "@/plugin/types/Plugin.js";
 import { isPluginEnabled } from "@/plugin/core/Activation.js";
 import { getWorkboardSnapshotStore } from "@/plugin/builtins/workboard/runtime/Store.js";
 import type { WorkboardSnapshotResponse } from "@/plugin/builtins/workboard/types/Workboard.js";
 
-/**
- * Workboard 插件定义。
- */
-export const workboardPlugin: Plugin = {
-  name: "workboard",
-  title: "Workboard Snapshot",
-  description:
-    "Collects structured runtime activity snapshots so console surfaces can show what the current agent is doing now and what it recently worked on.",
-  availability(context) {
-    if (!isPluginEnabled({ plugin: workboardPlugin, context })) {
+function createWorkboardPluginDefinition(plugin: Plugin): Plugin {
+  return {
+    name: "workboard",
+    title: "Workboard Snapshot",
+    description:
+      "Collects structured runtime activity snapshots so console surfaces can show what the current agent is doing now and what it recently worked on.",
+    availability(context) {
+      if (!isPluginEnabled({ plugin, context })) {
+        return {
+          enabled: false,
+          available: false,
+          reasons: ["workboard plugin disabled in city config"],
+        };
+      }
       return {
-        enabled: false,
-        available: false,
-        reasons: ["workboard plugin disabled in city config"],
+        enabled: true,
+        available: true,
+        reasons: [],
       };
-    }
-    return {
-      enabled: true,
-      available: true,
-      reasons: [],
-    };
-  },
-  http: {
-    runtime: {
-      authPolicies: [
-        {
-          path: "/api/workboard/*",
-          method: "GET",
-          requireAuth: true,
-          anyPermissions: ["agent.read"],
-        },
-      ],
-      register({ app, getContext }) {
-        app.get("/api/workboard/snapshot", async (c) => {
-          try {
-            const availability = await workboardPlugin.availability?.(getContext());
-            if (availability && availability.available !== true) {
+    },
+    http: {
+      server: {
+        authPolicies: [
+          {
+            path: "/api/workboard/*",
+            method: "GET",
+            requireAuth: true,
+            anyPermissions: ["agent.read"],
+          },
+        ],
+        register({ app, getContext }) {
+          app.get("/api/workboard/snapshot", async (c) => {
+            try {
+              const availability = await plugin.availability?.(getContext());
+              if (availability && availability.available !== true) {
+                return c.json(
+                  {
+                    success: false,
+                    error: availability.reasons.join("; ") || "workboard unavailable",
+                  },
+                  503,
+                );
+              }
+
+              const snapshot = await getWorkboardSnapshotStore({
+                contextResolver: getContext,
+              }).readSnapshot();
+              const payload: WorkboardSnapshotResponse = {
+                success: true,
+                snapshot,
+              };
+              return c.json(payload);
+            } catch (error) {
               return c.json(
                 {
                   success: false,
-                  error: availability.reasons.join("; ") || "workboard unavailable",
+                  error: error instanceof Error ? error.message : String(error),
                 },
-                503,
+                500,
               );
             }
-
-            const snapshot = await getWorkboardSnapshotStore({
-              contextResolver: getContext,
-            }).readSnapshot();
-            const payload: WorkboardSnapshotResponse = {
-              success: true,
-              snapshot,
-            };
-            return c.json(payload);
-          } catch (error) {
-            return c.json(
-              {
-                success: false,
-                error: error instanceof Error ? error.message : String(error),
-              },
-              500,
-            );
-          }
-        });
+          });
+        },
       },
     },
-  },
-};
+  };
+}
+
+/**
+ * WorkboardPlugin：运行态观测面板插件。
+ */
+export class WorkboardPlugin extends BasePlugin {
+  readonly name = "workboard";
+
+  constructor(agent: AgentRuntime | null = null) {
+    super(agent);
+    Object.assign(this, createWorkboardPluginDefinition(this));
+  }
+}

package/src/plugin/builtins/workboard/runtime/Collector.ts

@@ -3,11 +3,11 @@
  *
  * 关键点（中文）
  * - 这里只做确定性采集，不引入 LLM 推理。
- * - 内部仍聚合 session、task、service 三类运行事实，但最终只输出对外安全的模糊状态。
+ * - 内部仍聚合 session、task、plugin runtime 三类运行事实，但最终只输出对外安全的模糊状态。
  */
 
-import { listTaskDefinitions } from "@/service/builtins/task/Action.js";
-import { listServiceStates } from "@/service/core/Manager.js";
+import { listTaskDefinitions } from "@/plugin/builtins/task/Action.js";
+import { listPluginStates } from "@/plugin/core/Manager.js";
 import { listControlSessionSummaries } from "@/runtime/server/http/control/SessionSummaryStore.js";
 import type { AgentContext } from "@/core/AgentContextTypes.js";
 import type { WorkboardSnapshot } from "@/plugin/builtins/workboard/types/Workboard.js";
@@ -32,13 +32,14 @@ export async function collectWorkboardSnapshot(
   const executingSessionIds = new Set(context.session.listExecutingSessionIds());
   const sessions = await listControlSessionSummaries({
     projectRoot: context.rootPath,
+    agentId: context.paths.agentId,
     executionContext: context,
     limit: WORKBOARD_RECENT_LIMIT + Math.max(executingSessionIds.size, 1),
     executingSessionIds,
   });
-  const services = listServiceStates({ context });
+  const runtimePlugins = listPluginStates({ context });
   const taskResult = await listTaskDefinitions({ projectRoot: context.rootPath });
-  const degradedCount = services.filter((item) => item.state !== "running").length;
+  const degradedCount = runtimePlugins.filter((item) => item.state !== "running").length;
 
   const current = sessions
     .filter((item) => item.executing === true)
@@ -71,7 +72,7 @@ export async function collectWorkboardSnapshot(
     signals: toWorkboardSignals({
       currentCount: current.length,
       recentCount: recent.length,
-      services,
+      plugins: runtimePlugins,
       taskResult,
     }),
   };

package/src/plugin/builtins/workboard/runtime/Normalizer.ts

@@ -7,8 +7,8 @@
  */
 
 import type { ControlSessionSummary } from "@/runtime/server/http/control/types/ControlViewData.js";
-import type { ServiceStateSnapshot } from "@/service/types/ServiceState.js";
-import type { TaskListResponse } from "@/service/builtins/task/types/TaskCommand.js";
+import type { PluginStateSnapshot } from "@/plugin/types/PluginState.js";
+import type { TaskListResponse } from "@/plugin/builtins/task/types/TaskCommand.js";
 import type {
   WorkboardActivityItem,
   WorkboardAgentSummary,
@@ -181,10 +181,10 @@ export function toWorkboardSummary(params: {
 export function toWorkboardSignals(params: {
   currentCount: number;
   recentCount: number;
-  services: ServiceStateSnapshot[];
+  plugins: PluginStateSnapshot[];
   taskResult: TaskListResponse;
 }): WorkboardSignalItem[] {
-  const degradedCount = params.services.filter((item) => item.state !== "running").length;
+  const degradedCount = params.plugins.filter((item) => item.state !== "running").length;
   const taskCount = Array.isArray(params.taskResult.tasks) ? params.taskResult.tasks.length : 0;
 
   return [