@realqiyan/agent-task 0.1.0-rc.3 → 0.1.0-rc.4

package/dist/protocol/mcp-contract.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { absolutePath, identifier, timestamp } from "../shared/validation.js";
-import { nodeData, nodeStatusSchema, questionData, runStatusSchema, taskData, taskStatusSchema } from "../tasks/validation.js";
+import { cronScheduleData, nodeData, nodeStatusSchema, questionData, runStatusSchema, taskData, taskStatusSchema } from "../tasks/validation.js";
 /** Shared MCP initialization text; both the HTTP server and the local stdio proxy advertise it. */
 export const serverInstructions = `Agent Task runs caller-defined DAGs asynchronously with local ACP executors. A task is a persistent definition and schedule; a run is one execution. Task and run UUIDs are distinct from caller-defined DAG node IDs.
 Check service_status and executor_list before task_create. Poll task_run_list(taskId) at intervals for progress; use task_run_get for full outputs and task_run_reply for requested user facts. Creation returns a task, not a run or completed result. Disconnecting does not cancel work.
@@ -17,11 +17,10 @@ const scheduleOutput = z.discriminatedUnion("type", [
         type: z.literal("once"),
         at: timestamp.describe("Scheduled trigger, not actual execution start."),
     }).strict(),
-    z.object({
-        type: z.literal("interval"),
-        startAt: timestamp.describe("Anchor for the repeating schedule."),
-        seconds: z.number().int().describe("Fixed elapsed seconds between triggers."),
-    }).strict(),
+    cronScheduleData.safeExtend({
+        expression: cronScheduleData.shape.expression.describe("Five-field calendar Cron expression."),
+        timezone: cronScheduleData.shape.timezone.describe("Explicit timezone used to calculate calendar triggers."),
+    }),
 ]).describe("Stored schedule. Task status and nextAt are authoritative for future eligibility.");
 const taskNodeOutput = nodeData.safeExtend({
     id: nodeData.shape.id.describe("Caller-defined DAG node ID within this task; not a node-run UUID."),

package/dist/protocol/mcp.js

@@ -39,7 +39,7 @@ export function createMcpServer(service, fatal) {
     }
     register("service_status", "Check scheduler/storage health, coordinator configuration and capacity before creating work or when diagnosing a stalled run. Does not test model credentials or availability; use executor_list for executor readiness.", z.object({}).strict(), statusOutput, () => service.supervisor.status());
     register("executor_list", "Find local ACP executor IDs for task_create and inspect adapter preparation. Select only state=ready; this confirms launch dependencies, not native authentication or tool authorization. Does not refresh discovery or install adapters.", z.object({}).strict(), executorsOutput, () => ({ executors: service.executors.list().executors.map(executorStatus) }));
-    register("task_create", "Create a persistent task for immediate, one-time or interval execution. Supply the complete fixed DAG and a ready executor per node; the coordinator reviews deliveries and requests missing facts, but does not plan or reassign work. Requires service_status.coordinatorConfigured=true. Returns a task, not an execution result; find runs with task_run_list(taskId). Background model/ACP work survives MCP disconnection. Retry the same submission with the same requestKey and parameters, not a replacement task.", taskSchema, taskOutput, input => taskView(service.definitions.create(input)), { readOnly: false, destructive: false, idempotent: true, openWorld: true });
+    register("task_create", "Create a persistent task for immediate, one-time or Cron-scheduled execution. Supply the complete fixed DAG and a ready executor per node; the coordinator reviews deliveries and requests missing facts, but does not plan or reassign work. Requires service_status.coordinatorConfigured=true. Returns a task, not an execution result; find runs with task_run_list(taskId). Background model/ACP work survives MCP disconnection. Retry the same submission with the same requestKey and parameters, not a replacement task.", taskSchema, taskOutput, input => taskView(service.definitions.create(input)), { readOnly: false, destructive: false, idempotent: true, openWorld: true });
     register("task_list", "Find tasks and their future-trigger state, including cancelled and completed tasks. Returns compact records, oldest first; follow next for more. Use task_get for the full definition and task_run_list for execution outcomes.", taskListSchema, pageOutput(taskSummaryOutput), input => {
         const page = service.definitions.list(input.after, input.limit);
         return { items: page.items.map(taskSummary), next: page.next };

package/dist/protocol/task-contract.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { requestTimestamp } from "../shared/validation.js";
-import { nodeData, replyData, runStatusSchema, taskData, taskUpdateData } from "../tasks/validation.js";
+import { cronScheduleData, nodeData, replyData, runStatusSchema, taskData, taskUpdateData } from "../tasks/validation.js";
 export const nodeSchema = nodeData.extend({
     id: nodeData.shape.id.describe("Unique caller-defined ID in this DAG, referenced by dependsOn; not a run UUID."),
     prompt: z.string().trim().min(1).max(64_000).describe("Self-contained work and acceptance criteria for this executor. The task-level prompt is not copied here. Plain text/Markdown delivery is valid unless a format is required."),
@@ -26,7 +26,7 @@ export const taskRunListSchema = taskListSchema.extend({
 });
 export const taskUpdateSchema = taskUpdateData.extend({
     id: taskIdSchema.shape.id,
-    action: taskUpdateData.shape.action.describe("pause keeps the next trigger but suspends it; resume re-enables it without catch-up (past interval slots advance; past now/once slots become completed); cancel permanently removes future triggers. pause/resume require a remaining trigger. resume fails if any run has an interrupted node."),
+    action: taskUpdateData.shape.action.describe("pause keeps the next trigger but suspends it; resume re-enables it without catch-up (past Cron slots advance; past now/once slots become completed); cancel permanently removes future triggers. pause/resume require a remaining trigger. resume fails if any run has an interrupted node."),
 });
 export const taskSchema = taskData.extend({
     requestKey: taskData.shape.requestKey.describe("Caller-chosen creation key, scoped to the canonical workspace. Keep it stable for retries: identical normalized parameters return the existing task, including cancelled/completed tasks; changes conflict. A new key creates separate work, not a retry."),
@@ -40,11 +40,11 @@ export const taskSchema = taskData.extend({
             type: z.literal("once").describe("One slot at the specified future time."),
             at: requestTimestamp.describe("Future ISO 8601 trigger time with UTC Z or numeric offset; normalized to UTC."),
         }).strict(),
-        z.object({
-            type: z.literal("interval").describe("Repeating slots anchored to startAt, not to completion of the previous run."),
-            startAt: requestTimestamp.describe("First trigger, in the future, as ISO 8601 with UTC Z or numeric offset."),
-            seconds: z.number().int().min(60).max(31_536_000).describe("Fixed elapsed seconds between slots; not a calendar/timezone schedule."),
-        }).strict(),
+        cronScheduleData.safeExtend({
+            type: z.literal("cron").describe("Repeating calendar slots; the first match strictly after creation, not after the previous run completes."),
+            expression: z.string().trim().min(1).max(200).describe("Five fields: minute hour day-of-month month day-of-week, e.g. 0 9 * * 1-5. No seconds, @ aliases or hashed H fields. Day-of-month and day-of-week use OR when both are restricted."),
+            timezone: z.string().trim().min(1).max(100).describe("Required IANA timezone, e.g. Asia/Shanghai or UTC; never inferred from the server environment. DST follows cron-parser calendar rules."),
+        }),
     ]).describe("When runs become eligible, not guaranteed start times. Slots over 30 seconds late or overlapping a running/waiting run of this task are skipped, not queued for catch-up."),
     expiresAt: requestTimestamp.optional().describe("Cutoff for new runs and previously unstarted nodes, not a completion timeout. Must follow the first trigger. Existing ACP sessions may continue. ISO 8601 with timezone; omit for no cutoff."),
     maxRunSeconds: taskData.shape.maxRunSeconds.default(1800).describe("Run execution budget in seconds from coordinator start, excluding human-input waits; includes ACP execution. Separate from expiresAt and each node's session lifetime."),

package/dist/tasks/cron.js

@@ -0,0 +1,10 @@
+import { CronExpressionParser } from "cron-parser";
+/** Five calendar fields, deterministic expressions and an explicit IANA timezone. */
+export function parseCron(schedule, now) {
+    if (schedule.expression.trim().split(/\s+/).length !== 5 || /\bH\b/i.test(schedule.expression)) {
+        throw new Error("Cron requires five fields (minute hour day-of-month month day-of-week); hashed fields are not supported");
+    }
+    new Intl.DateTimeFormat("en", { timeZone: schedule.timezone });
+    return CronExpressionParser.parse(schedule.expression, { currentDate: now, tz: schedule.timezone });
+}
+//# sourceMappingURL=cron.js.map

package/dist/tasks/schedule.js

@@ -1,9 +1,10 @@
 import { TaskError } from "../shared/errors.js";
+import { parseCron } from "./cron.js";
 export function hasUncertainOutcome(run) {
     return run.nodes.some(node => node.status === "interrupted");
 }
 export function initialTime(schedule, now) {
-    return schedule.type === "now" ? now : Date.parse(schedule.type === "once" ? schedule.at : schedule.startAt);
+    return schedule.type === "now" ? now : schedule.type === "once" ? Date.parse(schedule.at) : parseCron(schedule, now).next().getTime();
 }
 export function resumeSchedule(task, now) {
     const next = structuredClone(task);
@@ -11,8 +12,8 @@ export function resumeSchedule(task, now) {
         throw new TaskError("precondition", "Task has no future schedule");
     next.status = "active";
     if (next.nextAt < now) {
-        if (next.input.schedule.type === "interval")
-            next.nextAt += (Math.floor((now - next.nextAt) / (next.input.schedule.seconds * 1000)) + 1) * next.input.schedule.seconds * 1000;
+        if (next.input.schedule.type === "cron")
+            next.nextAt = parseCron(next.input.schedule, now).next().getTime();
         else {
             next.nextAt = null;
             next.status = "completed";
@@ -29,9 +30,17 @@ export function dueTrigger(task, overlaps, now) {
     if (task.nextAt > now)
         return { kind: "none" };
     const schedule = task.input.schedule;
-    const count = schedule.type === "interval" ? Math.floor((now - task.nextAt) / (schedule.seconds * 1000)) + 1 : 1;
-    const at = task.nextAt + (schedule.type === "interval" ? (count - 1) * schedule.seconds * 1000 : 0);
-    return { kind: "due", at, count, nextAt: schedule.type === "interval" ? at + schedule.seconds * 1000 : null,
+    let count = 1, at = task.nextAt, nextAt = null;
+    if (schedule.type === "cron") {
+        const cron = parseCron(schedule, at);
+        nextAt = cron.next().getTime();
+        while (nextAt <= now) {
+            at = nextAt;
+            count++;
+            nextAt = cron.next().getTime();
+        }
+    }
+    return { kind: "due", at, count, nextAt,
         reason: overlaps ? "Previous round still active; slot skipped" : now - at > 30_000 ? "Late slot skipped" : null };
 }
 //# sourceMappingURL=schedule.js.map

package/dist/tasks/validation.js

@@ -1,9 +1,20 @@
 import { z } from "zod";
 import { absolutePath, identifier, text, timestamp } from "../shared/validation.js";
+import { parseCron } from "./cron.js";
+export const cronScheduleData = z.object({
+    type: z.literal("cron"), expression: text(200), timezone: text(100),
+}).strict().superRefine((schedule, ctx) => {
+    try {
+        parseCron(schedule, Date.UTC(2000, 0, 1)).next();
+    }
+    catch {
+        ctx.addIssue({ code: "custom", message: "Invalid five-field Cron expression or timezone" });
+    }
+});
 export const scheduleData = z.discriminatedUnion("type", [
     z.object({ type: z.literal("now") }).strict(),
     z.object({ type: z.literal("once"), at: timestamp }).strict(),
-    z.object({ type: z.literal("interval"), startAt: timestamp, seconds: z.number().int().min(60).max(31_536_000) }).strict(),
+    cronScheduleData,
 ]);
 export const taskStatusSchema = z.enum(["active", "paused", "cancelled", "completed", "expired"]);
 export const runStatusSchema = z.enum(["running", "succeeded", "failed", "interrupted", "skipped", "cancelled", "timed_out", "waiting_input"]);

package/docs/design-proposal.md

@@ -6,7 +6,7 @@
 
 ## 产品目标
 
-- 调用方通过 MCP 提交整体目标、DAG 和每节点的 ACP 执行端指派，支持立即、定时及周期执行。
+- 调用方通过 MCP 提交整体目标、DAG 和每节点的 ACP 执行端指派，支持立即、定时及 Cron 周期执行；Cron 使用五段表达式与显式时区，契约见 [task-contract.ts](../src/protocol/task-contract.ts)。
 - 任务不依赖发起客户端持续在线，保留执行、交付、失败和缺少用户事实的记录。
 - 初始化由用户确认目录、端口、令牌及协调模型；执行端自动发现并按需准备适配器。stdio 接入连接独立后台，宿主退出后后台继续调度；宿主配置由用户添加，不自动识别宿主当前项目。
 - 协调员推进既定 DAG、解释中间结果、处理澄清并组织交付；领域分析和工具操作交给执行端。
@@ -45,7 +45,7 @@ ACP 执行端：原生会话、领域推理和工具操作
 
 当前是调研和 MVP 验证阶段，直接调整接口和数据结构，不维护旧版兼容或业务库版本递增；这不授权迁移或删除历史数据。
 
-暂不实现：执行中修改 DAG、自动重试或跨端故障转移、丢失 ACP 会话的重连、人工核对后强制恢复、远程执行、多租户、日历时区调度、技能同步及动态 MCP 转发。它们需要独立产品决策，不因引入 durable 自动获得。
+暂不实现：执行中修改 DAG、自动重试或跨端故障转移、丢失 ACP 会话的重连、人工核对后强制恢复、远程执行、多租户、技能同步及动态 MCP 转发。它们需要独立产品决策，不因引入 durable 自动获得。
 
 启动方式见[部署说明](deployment.md)。[本机控制台](web-console.md)复用任务服务，使用独立管理员认证与浏览器请求边界；不提供文件下载或其他任务写操作。
 

package/docs/technical-design.md

@@ -8,7 +8,7 @@
 
 | 责任 | 实现入口 | 基础验证 |
 | --- | --- | --- |
-| 任务定义、执行端快照、未来触发控制 | [TaskDefinitions](../src/tasks/definitions.ts)、[图校验](../src/tasks/graph.ts)、[时间规则](../src/tasks/schedule.ts) | [tasks.test.mjs](../tests/tasks.test.mjs) |
+| 任务定义、执行端快照、未来触发控制 | [TaskDefinitions](../src/tasks/definitions.ts)、[图校验](../src/tasks/graph.ts)、[时间规则](../src/tasks/schedule.ts)、[Cron 解析](../src/tasks/cron.ts) | [tasks.test.mjs](../tests/tasks.test.mjs)、[schedule.test.mjs](../tests/schedule.test.mjs) |
 | Run 与节点状态的业务修改入口、派发与提交顺序 | [TaskRuns](../src/tasks/runs.ts)、[数据模型](../src/tasks/model.ts)、[窄能力契约](../src/tasks/ports.ts) | [tasks.test.mjs](../tests/tasks.test.mjs)、[task-storage.test.mjs](../tests/task-storage.test.mjs) |
 | 时钟、协调会话监督、取消与收尾 | [RunSupervisor](../src/tasks/supervisor.ts)、[NodeSessions](../src/tasks/sessions.ts) | [tasks.test.mjs](../tests/tasks.test.mjs)、[restart.test.mjs](../tests/restart.test.mjs) |
 | 人工事实等待与回复 | [纯状态规则](../src/tasks/human-input.ts)、[TaskRuns](../src/tasks/runs.ts) | [human-input.test.mjs](../tests/human-input.test.mjs) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@realqiyan/agent-task",
-  "version": "0.1.0-rc.3",
+  "version": "0.1.0-rc.4",
   "license": "MIT",
   "author": "realqiyan",
   "repository": {
@@ -61,6 +61,7 @@
     "@earendil-works/pi-ai": "1.3.0",
     "@earendil-works/pi-durable": "1.3.0",
     "@modelcontextprotocol/sdk": "1.32.1",
+    "cron-parser": "5.10.2",
     "express": "5.3.0",
     "zod": "4.6.7"
   },