@downcity/plugins 1.0.254 → 1.0.280

package/src/task/TaskPlugin.ts

@@ -8,6 +8,7 @@
  */
 
 import { BasePlugin, create_action } from "@downcity/agent";
+import type { AgentPluginContext } from "@downcity/agent";
 import type { PluginActions } from "@downcity/agent";
 import type { PluginContext } from "@downcity/agent";
 import type {
@@ -25,6 +26,7 @@ import {
 } from "@/task/runtime/TaskActionExecution.js";
 import { TASK_PLUGIN_PROMPT } from "@/task/runtime/TaskPluginSystem.js";
 import { resolve_runtime_timezone } from "@downcity/agent";
+import type { TaskWorkspaceRuntime } from "@/task/types/TaskWorkspaceRuntime.js";
 
 const TASK_LOG_PREFIX = "[TASK]";
 
@@ -44,7 +46,10 @@ export class TaskPlugin extends BasePlugin {
   /**
    * task plugin 的 system 文本提供器。
    */
-  readonly system = (): string => TASK_PLUGIN_PROMPT;
+  readonly system = async (context: PluginContext): Promise<string> => {
+    await this.start_cron_runtime(context);
+    return TASK_PLUGIN_PROMPT;
+  };
 
   /**
    * task plugin 的 action 定义表。
@@ -63,16 +68,10 @@ export class TaskPlugin extends BasePlugin {
    * - 这是 per-plugin-instance 的长期运行态。
    * - 不再复用 module-global 单例。
    */
-  public cronEngine: TaskCronTriggerEngine | null = null;
+  private readonly runtimes_by_workspace = new Map<string, TaskWorkspaceRuntime>();
 
-  /**
-   * 当前实例持有的运行中 task 锁。
-   *
-   * 关键点（中文）
-   * - scheduler reload 会替换 cron engine。
-   * - 锁必须挂在 plugin 实例上，避免 reload 后同一 task 被新旧调度器并发触发。
-   */
-  private readonly runningTaskIds = new Set<string>();
+  /** 各 Workspace 当前唯一的 cron 启动流程。 */
+  private readonly starts_by_workspace = new Map<string, Promise<TaskCronRegisterResult | null>>();
 
   constructor(options?: TaskPluginOptions) {
     super();
@@ -86,7 +85,7 @@ export class TaskPlugin extends BasePlugin {
       reload: create_action({
         description: "Reload the task scheduler from persisted tasks.",
         execute: async ({ context }) => {
-          const result = await this.restartCronRuntime(context);
+          const result = await this.restart_cron_runtime(context);
           context.logger.info(
             formatTaskLogMessage(
               `Task cron trigger reloaded (tasks=${result.tasksFound}, jobs=${result.jobsScheduled})`,
@@ -105,19 +104,13 @@ export class TaskPlugin extends BasePlugin {
     };
 
     this.lifecycle = {
-      start: async (context) => {
-        const result = await this.startCronRuntime(context);
-        if (!result) return;
-        context.logger.info(
-          formatTaskLogMessage(
-            `Task cron trigger started (tasks=${result.tasksFound}, jobs=${result.jobsScheduled})`,
-          ),
-        );
-      },
-      stop: async (context) => {
-        const stopped = await this.stopCronRuntime();
-        if (!stopped) return;
-        context.logger.info(formatTaskLogMessage("Task cron trigger stopped"));
+      start: async (_context: AgentPluginContext) => {},
+      stop: async (_context: AgentPluginContext) => {
+        await Promise.allSettled([...this.starts_by_workspace.values()]);
+        await Promise.all([...this.runtimes_by_workspace.keys()].map(async (workspace_id) => {
+          await this.stop_cron_runtime(workspace_id);
+        }));
+        this.starts_by_workspace.clear();
       },
     };
   }
@@ -125,42 +118,58 @@ export class TaskPlugin extends BasePlugin {
   /**
    * 启动当前实例的 cron runtime。
    */
-  async startCronRuntime(
+  async start_cron_runtime(
     context: PluginContext,
   ): Promise<TaskCronRegisterResult | null> {
-    if (this.cronEngine) return null;
-
-    const engine = new TaskCronTriggerEngine();
-    const registerResult = await registerTaskCronJobs({
-      context,
-      engine,
-      timezone: this.resolveTimezone(),
-      runningTaskIds: this.runningTaskIds,
-    });
-    await engine.start();
-    this.cronEngine = engine;
-    return registerResult;
+    if (this.runtimes_by_workspace.has(context.workspace_id)) return null;
+    const started = this.starts_by_workspace.get(context.workspace_id);
+    if (started) return await started;
+
+    const start_promise = (async () => {
+      const engine = new TaskCronTriggerEngine();
+      const running_task_ids = new Set<string>();
+      const register_result = await registerTaskCronJobs({
+        context,
+        engine,
+        timezone: this.resolveTimezone(),
+        runningTaskIds: running_task_ids,
+      });
+      await engine.start();
+      this.runtimes_by_workspace.set(context.workspace_id, {
+        cron_engine: engine,
+        running_task_ids,
+      });
+      return register_result;
+    })();
+    this.starts_by_workspace.set(context.workspace_id, start_promise);
+    try {
+      return await start_promise;
+    } finally {
+      if (this.starts_by_workspace.get(context.workspace_id) === start_promise) {
+        this.starts_by_workspace.delete(context.workspace_id);
+      }
+    }
   }
 
   /**
    * 停止当前实例的 cron runtime。
    */
-  async stopCronRuntime(): Promise<boolean> {
-    if (!this.cronEngine) return false;
-    const previous = this.cronEngine;
-    this.cronEngine = null;
-    await previous.stop();
+  async stop_cron_runtime(workspace_id: string): Promise<boolean> {
+    const runtime = this.runtimes_by_workspace.get(workspace_id);
+    if (!runtime) return false;
+    this.runtimes_by_workspace.delete(workspace_id);
+    await runtime.cron_engine.stop();
     return true;
   }
 
   /**
    * 重启当前实例的 cron runtime。
    */
-  async restartCronRuntime(
+  async restart_cron_runtime(
     context: PluginContext,
   ): Promise<TaskCronRegisterResult> {
-    await this.stopCronRuntime();
-    const started = await this.startCronRuntime(context);
+    await this.stop_cron_runtime(context.workspace_id);
+    const started = await this.start_cron_runtime(context);
     return (
       started || {
         tasksFound: 0,
@@ -181,7 +190,7 @@ export class TaskPlugin extends BasePlugin {
       context: params.context,
       action: params.action,
       title: params.title,
-      reloadScheduler: async (context) => this.restartCronRuntime(context),
+      reloadScheduler: async (context) => this.restart_cron_runtime(context),
     });
   }
 

package/src/task/runtime/Model.ts

@@ -142,16 +142,6 @@ export function normalizeTaskWhen(
   return { ok: true, value: canonical };
 }
 
-/**
- * 兼容旧调用名：返回 cron 表达式或 `@manual`。
- */
-export function normalizeTaskCronExpression(raw: string): string | null {
-  const when = normalizeTaskWhen(raw);
-  if (!when.ok) return null;
-  if (isTaskWhenOneShot(when.value)) return null;
-  return normalizeCronExpression(when.value);
-}
-
 export function isTaskWhenManual(input: string): boolean {
   const when = String(input || "").trim().toLowerCase();
   return when === "@manual";
@@ -213,9 +203,9 @@ export function parseTaskMarkdown(params: {
   taskId: string;
   markdown: string;
   taskMdPath: string;
-  project_root: string;
+  data_path: string;
 }): { ok: true; task: ShipTaskDefinitionV1 } | { ok: false; error: string } {
-  const { taskId, markdown, taskMdPath, project_root } = params;
+  const { taskId, markdown, taskMdPath, data_path } = params;
   const text = String(markdown ?? "");
   const { frontMatterYaml, body } = parseFrontMatter(text);
 
@@ -293,7 +283,7 @@ export function parseTaskMarkdown(params: {
   };
 
   const relTaskMdPath = path
-    .relative(project_root, taskMdPath)
+    .relative(data_path, taskMdPath)
     .split(path.sep)
     .join("/");
 

package/src/task/runtime/Paths.ts

@@ -2,9 +2,9 @@
  * Task System paths and identifiers.
  *
  * 约定（中文）
- * - task root: `./.downcity/task/`
- * - definition: `./.downcity/task/<taskId>/task.md`
- * - run dir: `./.downcity/task/<taskId>/<timestamp>/`
+ * - task root: `<Agent data>/task/`
+ * - definition: `<Agent data>/task/<taskId>/task.md`
+ * - run dir: `<Agent data>/task/<taskId>/<timestamp>/`
  *
  * 同时定义“task run session_id”格式，用于把 Agent 的 session 映射到 run 目录：
  * - `task-run:<taskId>:<timestamp>`
@@ -59,16 +59,16 @@ export function normalizeTaskId(input: string): string {
   return id;
 }
 
-export function getTaskRootDir(project_root: string): string {
-  return path.join(String(project_root || "").trim(), ".downcity", "task");
+export function getTaskRootDir(data_path: string): string {
+  return path.join(String(data_path || "").trim(), "task");
 }
 
-export function getTaskDir(project_root: string, taskId: string): string {
-  return path.join(getTaskRootDir(project_root), normalizeTaskId(taskId));
+export function getTaskDir(data_path: string, taskId: string): string {
+  return path.join(getTaskRootDir(data_path), normalizeTaskId(taskId));
 }
 
-export function getTaskMdPath(project_root: string, taskId: string): string {
-  return path.join(getTaskDir(project_root, taskId), "task.md");
+export function getTaskMdPath(data_path: string, taskId: string): string {
+  return path.join(getTaskDir(data_path, taskId), "task.md");
 }
 
 export function formatTaskRunTimestamp(date: Date = new Date()): string {
@@ -85,13 +85,13 @@ export function formatTaskRunTimestamp(date: Date = new Date()): string {
 }
 
 export function getTaskRunDir(
-  project_root: string,
+  data_path: string,
   taskId: string,
   timestamp: string,
 ): string {
   const ts = String(timestamp || "").trim();
   if (!ts) throw new Error("timestamp is required");
-  return path.join(getTaskDir(project_root, taskId), ts);
+  return path.join(getTaskDir(data_path, taskId), ts);
 }
 
 export function createTaskRunSessionId(taskId: string, timestamp: string): string {

package/src/task/runtime/Runner.ts

@@ -79,7 +79,7 @@ export async function runTaskNow(params: {
   taskId: string;
   trigger: ShipTaskRunTriggerV1;
   executionId?: string;
-  project_root?: string;
+  data_path?: string;
   /** 发起该任务的 Session step 已提交生效的 env 快照。 */
   workspace_env?: Readonly<Record<string, string>>;
   /** 发起该任务的 Session step 已提交生效的 instruction 快照。 */
@@ -102,19 +102,19 @@ export async function runTaskNow(params: {
   runDirRel: string;
 }> {
   const context = params.context;
-  const root = String(params.project_root || context.workspace_path || "").trim();
-  if (!root) throw new Error("project_root is required");
+  const root = String(params.data_path || context.data_path || "").trim();
+  if (!root) throw new Error("data_path is required");
 
   const startedAt = Date.now();
   const timestamp = formatTaskRunTimestamp(new Date(startedAt));
   const executionId = String(params.executionId || `${params.taskId}:${timestamp}`).trim();
 
-  const task = await readTask({ taskId: params.taskId, project_root: root });
+  const task = await readTask({ taskId: params.taskId, data_path: root });
   const runDirAbs = getTaskRunDir(root, task.taskId, timestamp);
   const { runDirRel } = await ensureRunDir({
     taskId: task.taskId,
     timestamp,
-    project_root: root,
+    data_path: root,
   });
   const filePaths = createTaskRunFilePaths(runDirAbs);
 
@@ -170,7 +170,6 @@ export async function runTaskNow(params: {
   if (taskKind === "script") {
     const scriptResult = await runScriptTaskBranch({
       context,
-      runDirAbs,
       session_id: task.frontmatter.session_id,
       scriptBody: task.body,
       runProgress,

package/src/task/runtime/Store.ts

@@ -2,9 +2,9 @@
  * Task storage (disk-backed).
  *
  * 关键点（中文）
- * - Task 的“唯一来源”是 `./.downcity/task/<taskId>/task.md`
+ * - Task 的“唯一来源”是 Agent 私有目录中的 `task/<taskId>/task.md`
  * - list/read/write 都只围绕 markdown 文件与目录结构，不引入数据库
- * - 运行产物目录：`./.downcity/task/<taskId>/<timestamp>/...`
+ * - 运行产物目录：Agent 私有目录中的 `task/<taskId>/<timestamp>/...`
  */
 
 import fs from "fs-extra";
@@ -52,11 +52,11 @@ function isDirectoryNameTimestamp(name: string): boolean {
  * 列出全部任务。
  *
  * 算法（中文）
- * - 遍历 `.downcity/task/*` 目录并解析每个 `task.md`。
+ * - 遍历 Agent 的 `task/*` 目录并解析每个 `task.md`。
  * - 通过子目录时间戳推断 `lastRunTimestamp`。
  */
-export async function listTasks(project_root: string): Promise<TaskListItem[]> {
-  const root = String(project_root || "").trim();
+export async function listTasks(data_path: string): Promise<TaskListItem[]> {
+  const root = String(data_path || "").trim();
   if (!root) return [];
 
   const dir = getTaskRootDir(root);
@@ -88,7 +88,7 @@ export async function listTasks(project_root: string): Promise<TaskListItem[]> {
       taskId,
       markdown: raw,
       taskMdPath,
-      project_root: root,
+      data_path: root,
     });
     if (!parsed.ok) continue;
 
@@ -136,11 +136,11 @@ export async function listTasks(project_root: string): Promise<TaskListItem[]> {
  * - 若磁盘中存在同 title 多定义，会拒绝并提示冲突。
  */
 export async function resolveTaskIdByTitle(params: {
-  project_root: string;
+  data_path: string;
   title: string;
 }): Promise<string> {
-  const root = String(params.project_root || "").trim();
-  if (!root) throw new Error("project_root is required");
+  const root = String(params.data_path || "").trim();
+  if (!root) throw new Error("data_path is required");
   const title = String(params.title || "").trim();
   if (!title) throw new Error("title is required");
 
@@ -156,9 +156,9 @@ export async function resolveTaskIdByTitle(params: {
 /**
  * 读取单个任务定义。
  */
-export async function readTask(params: { taskId: string; project_root: string }): Promise<ShipTaskDefinitionV1> {
-  const root = String(params.project_root || "").trim();
-  if (!root) throw new Error("project_root is required");
+export async function readTask(params: { taskId: string; data_path: string }): Promise<ShipTaskDefinitionV1> {
+  const root = String(params.data_path || "").trim();
+  if (!root) throw new Error("data_path is required");
   const taskId = normalizeTaskId(params.taskId);
 
   const taskMdPath = getTaskMdPath(root, taskId);
@@ -167,7 +167,7 @@ export async function readTask(params: { taskId: string; project_root: string })
     taskId,
     markdown: raw,
     taskMdPath,
-    project_root: root,
+    data_path: root,
   });
   if (!parsed.ok) throw new Error(parsed.error);
   return parsed.task;
@@ -178,10 +178,10 @@ export async function readTask(params: { taskId: string; project_root: string })
  */
 export async function deleteTask(params: {
   taskId: string;
-  project_root: string;
+  data_path: string;
 }): Promise<{ taskId: string; taskDirPath: string }> {
-  const root = String(params.project_root || "").trim();
-  if (!root) throw new Error("project_root is required");
+  const root = String(params.data_path || "").trim();
+  if (!root) throw new Error("data_path is required");
   const taskId = normalizeTaskId(params.taskId);
 
   const taskMdPath = getTaskMdPath(root, taskId);
@@ -208,11 +208,11 @@ export async function writeTask(params: {
   taskId: string;
   frontmatter: ShipTaskFrontmatterV1;
   body: string;
-  project_root: string;
+  data_path: string;
   overwrite?: boolean;
 }): Promise<{ taskId: string; taskMdPath: string }> {
-  const root = String(params.project_root || "").trim();
-  if (!root) throw new Error("project_root is required");
+  const root = String(params.data_path || "").trim();
+  if (!root) throw new Error("data_path is required");
   const taskId = normalizeTaskId(params.taskId);
 
   const dir = getTaskDir(root, taskId);
@@ -239,10 +239,10 @@ export async function writeTask(params: {
 export async function ensureRunDir(params: {
   taskId: string;
   timestamp: string;
-  project_root: string;
+  data_path: string;
 }): Promise<{ runDir: string; runDirRel: string }> {
-  const root = String(params.project_root || "").trim();
-  if (!root) throw new Error("project_root is required");
+  const root = String(params.data_path || "").trim();
+  if (!root) throw new Error("data_path is required");
   const taskId = normalizeTaskId(params.taskId);
   const runDir = getTaskRunDir(root, taskId, params.timestamp);
   await fs.ensureDir(runDir);

package/src/task/runtime/TaskActionExecution.ts

@@ -114,7 +114,7 @@ export async function executeTaskListAction(params: {
   return {
     success: true,
     data: await listTaskDefinitions({
-      project_root: params.context.workspace_path,
+      data_path: params.context.data_path,
       ...(params.payload.status ? { status: params.payload.status } : {}),
     }),
   };
@@ -130,7 +130,7 @@ export async function executeTaskCreateAction(params: {
 }) {
   const payload = params.payload;
   const result = await createTaskDefinition({
-    project_root: params.context.workspace_path,
+    data_path: params.context.data_path,
     request: payload,
   });
   if (!result.success) {
@@ -163,7 +163,7 @@ export async function executeTaskRunAction(params: {
 }) {
   const result = await runTaskDefinition({
     context: params.context,
-    project_root: params.context.workspace_path,
+    data_path: params.context.data_path,
     request: params.payload,
     execution_context: params.execution_context,
   });
@@ -189,7 +189,7 @@ export async function executeTaskDeleteAction(params: {
 }) {
   const payload = params.payload;
   const result = await deleteTaskDefinition({
-    project_root: params.context.workspace_path,
+    data_path: params.context.data_path,
     request: payload,
   });
   if (!result.success) {
@@ -222,7 +222,7 @@ export async function executeTaskUpdateAction(params: {
 }) {
   const payload = params.payload;
   const result = await updateTaskDefinition({
-    project_root: params.context.workspace_path,
+    data_path: params.context.data_path,
     request: payload,
   });
   if (!result.success) {
@@ -255,7 +255,7 @@ export async function executeTaskStatusAction(params: {
 }) {
   const payload = params.payload;
   const result = await setTaskStatus({
-    project_root: params.context.workspace_path,
+    data_path: params.context.data_path,
     request: payload,
   });
   if (!result.success) {

package/src/task/runtime/TaskPluginActionRegistry.ts

@@ -222,7 +222,7 @@ export function createTaskPluginActions(params: {
         return executeTaskRunAction({
           context: actionParams.context,
           payload: actionParams.input as TaskRunRequest,
-          execution_context: actionParams.execution_context,
+          execution_context: actionParams.execution.snapshot,
         });
       },
     }),

package/src/task/runtime/TaskRunnerRound.ts

@@ -273,14 +273,23 @@ export async function runAgentRound(params: {
  */
 export async function runScriptTask(params: {
   context: PluginContext;
-  runDirAbs: string;
   session_id: string;
   scriptBody: string;
 }): Promise<ScriptExecutionResult> {
   const body = String(params.scriptBody || "");
   if (!body.trim()) throw new Error("script task body cannot be empty");
 
-  const scriptAbs = path.join(params.runDirAbs, "task-script.sh");
+  const session_segment = String(params.session_id || "task")
+    .replace(/[^a-zA-Z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "task";
+  const execution_dir = path.join(
+    params.context.data_path,
+    "sandbox",
+    "task-scripts",
+    session_segment,
+  );
+  await fs.ensureDir(execution_dir);
+  const scriptAbs = path.join(execution_dir, "task-script.sh");
   await fs.writeFile(scriptAbs, body.endsWith("\n") ? body : `${body}\n`, "utf-8");
 
   const childEnv: NodeJS.ProcessEnv = {
@@ -294,9 +303,9 @@ export async function runScriptTask(params: {
   }
   const execResult = await shell.run_safe_command({
     execution_id: `task-script:${params.session_id}`,
-    execution_dir: params.runDirAbs,
+    execution_dir,
     cmd: `sh "${scriptAbs.replace(/(["\\$`])/g, "\\$1")}"`,
-    cwd: params.runDirAbs,
+    cwd: params.context.workspace_path,
     shell_path: "/bin/sh",
     login: false,
     base_env: childEnv,

package/src/task/runtime/TaskRunnerScript.ts

@@ -24,10 +24,6 @@ export interface RunScriptTaskBranchParams {
    * 当前 Agent 执行上下文。
    */
   context: PluginContext;
-  /**
-   * 当前 run 目录绝对路径。
-   */
-  runDirAbs: string;
   /**
    * script 任务绑定的 session_id。
    */
@@ -110,7 +106,6 @@ export async function runScriptTaskBranch(
   try {
     const scriptResult = await runScriptTask({
       context: params.context,
-      runDirAbs: params.runDirAbs,
       session_id: params.session_id,
       scriptBody: params.scriptBody,
     });

package/src/task/runtime/TaskRunnerSession.ts

@@ -9,8 +9,12 @@
  */
 
 import path from "node:path";
-import type { LanguageModel, Tool } from "ai";
-import type { PluginContext, SessionAttachmentStore } from "@downcity/agent";
+import type {
+  AgentModel,
+  AgentOptions,
+  PluginContext,
+  SessionAttachmentStore,
+} from "@downcity/agent";
 import { Executor } from "@downcity/agent";
 import type { SessionTurnExecutionResult } from "@downcity/agent";
 import type { TaskSessionRuntimePort } from "@/task/runtime/TaskRunnerTypes.js";
@@ -62,7 +66,7 @@ export async function appendTaskRoundUserMessage(params: {
  */
 export function createTaskSessionRuntimePort(params: {
   context: PluginContext;
-  model: LanguageModel;
+  model: AgentModel;
   runDirAbs: string;
   runSessionId: string;
   userSimulatorSessionId: string;
@@ -97,7 +101,7 @@ export function createTaskSessionRuntimePort(params: {
   if (!shell) {
     throw new Error("Task agent execution requires Agent to be configured with a Shell.");
   }
-  const shell_tools = shell.tools as unknown as Record<string, Tool>;
+  const shell_tools = shell.tools as NonNullable<AgentOptions["tools"]>;
   /**
    * Task runtime 当前只接收已经规范化的文本消息，不支持通过 Prompt 传入 Data URL 附件。
    * 显式提供适配器，避免把 Task 的临时 run 目录错误地当成普通 Session 附件目录。
@@ -127,7 +131,7 @@ export function createTaskSessionRuntimePort(params: {
     const created = new SessionMessages({
       session_id: key,
       store: create_session_message_store({
-        files: context.files,
+        files: context.data_files,
         session_id: key,
         file_path: path.join(messages_dir_path, "active.jsonl"),
         assistant_message_file_path: path.join(
@@ -242,7 +246,5 @@ export async function appendTaskDeferredMessages(params: {
   const { taskSessionRuntime, session_id, rawResult } = params;
   const messages = taskSessionRuntime.get_messages(session_id);
   const deferredUserMessages = rawResult.deferred_persisted_user_messages || [];
-  for (const deferred of deferredUserMessages) {
-    await messages.append_record(deferred);
-  }
+  await messages.append_deferred_user_messages(deferredUserMessages);
 }

package/src/task/types/TaskWorkspaceRuntime.ts

@@ -0,0 +1,12 @@
+/** TaskPlugin 在单个 Workspace 中持有的运行态类型。 */
+
+import type { TaskCronTriggerEngine } from "@/task/runtime/CronTrigger.js";
+
+/** 单个 Workspace 独立拥有的 Task 调度资源。 */
+export interface TaskWorkspaceRuntime {
+  /** 当前 Workspace 的 cron 触发引擎。 */
+  readonly cron_engine: TaskCronTriggerEngine;
+
+  /** 当前 Workspace 正在执行的任务 ID，用于阻止同一任务并发触发。 */
+  readonly running_task_ids: Set<string>;
+}