@aigne/afs-scheduler 1.12.0-beta.5

package/dist/types.d.cts

@@ -0,0 +1,384 @@
+import { DONamespace } from "./do-types.cjs";
+import { z } from "zod/v4";
+
+//#region src/types.d.ts
+interface BudgetEstimate {
+  tokens?: number;
+  duration?: number;
+  calls?: number;
+}
+type TaskStatus = "pending" | "running" | "done" | "failed" | "cancelled" | "budget-blocked" | "timeout";
+interface TaskEntry {
+  id: string;
+  status: TaskStatus;
+  taskPath: string;
+  args?: unknown;
+  estimate?: BudgetEstimate;
+  result?: TaskResult;
+  error?: string;
+  created: number;
+  started?: number;
+  ended?: number;
+  attempts: number;
+  procId?: string;
+  /** Caller identity that created the task. Used to authorize lifecycle actions. */
+  ownerKey?: string;
+  /** ID of the schedule that created this task (for duplicate protection) */
+  scheduleId?: string;
+  /** Heartbeat deadline — task times out if no heartbeat received by this time (epoch ms) */
+  deadline?: number;
+  /** Last heartbeat timestamp (epoch ms) */
+  lastHeartbeat?: number;
+  /** Timeout duration in ms — used for sliding window extension on heartbeat */
+  timeout?: number;
+  /** ID of the job this task belongs to (map-reduce) */
+  jobId?: string;
+  /** Batch index within the job (map task) */
+  batchIndex?: number;
+  /**
+   * Claim-based (pull model) task — not auto-executed via the internal
+   * executor. An external worker must `claim` it, do the work out-of-band,
+   * then `submit` the result. Set when `dispatch` is called with an
+   * `assignee` field (see #1067).
+   */
+  claimable?: boolean;
+  /**
+   * Claim constraint for claimable tasks: "" (or absent) = any worker may
+   * claim; a specific DID = only that worker may claim.
+   */
+  assignee?: string;
+  /** DID of the worker currently holding the claim/lease. */
+  claimedBy?: string;
+  /** Epoch ms when the task was most recently claimed. */
+  claimedAt?: number;
+  /**
+   * Opaque optimistic-concurrency token for the claim contract (see
+   * docs/guides/provider-authoring.md ifMatch). Regenerated whenever
+   * claim-relevant state changes (claim/reclaim/submit). Callers must treat
+   * this as opaque — never parse or compare beyond equality.
+   */
+  version?: string;
+}
+interface TaskResult {
+  success: boolean;
+  data?: unknown;
+  error?: string;
+}
+interface ScheduleEntry {
+  id: string;
+  name: string;
+  cron: string;
+  taskPath: string;
+  args?: unknown;
+  enabled: boolean;
+  created: number;
+  /** Caller identity that created the schedule. Used to authorize lifecycle actions. */
+  ownerKey?: string;
+  lastRun?: number;
+  nextRun?: number;
+}
+interface TaskContext {
+  procId?: string;
+}
+interface TaskExecutor {
+  run(taskId: string, taskPath: string, args: unknown, context?: TaskContext): Promise<TaskResult>;
+  cancel?(taskId: string): Promise<void>;
+}
+declare const DispatchArgsSchema: z.ZodObject<{
+  task: z.ZodString;
+  args: z.ZodOptional<z.ZodUnknown>;
+  estimate: z.ZodOptional<z.ZodObject<{
+    tokens: z.ZodOptional<z.ZodNumber>;
+    duration: z.ZodOptional<z.ZodNumber>;
+    calls: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strip>>;
+  proc: z.ZodOptional<z.ZodObject<{
+    type: z.ZodEnum<{
+      realm: "realm";
+      blocklet: "blocklet";
+      "agent-run": "agent-run";
+      "ash-script": "ash-script";
+      resource: "resource";
+    }>;
+    parentId: z.ZodOptional<z.ZodString>;
+    appId: z.ZodOptional<z.ZodString>;
+    budget: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strip>>;
+  assignee: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type DispatchArgs = z.infer<typeof DispatchArgsSchema>;
+declare const CancelArgsSchema: z.ZodObject<{
+  taskId: z.ZodString;
+}, z.core.$strip>;
+type CancelArgs = z.infer<typeof CancelArgsSchema>;
+declare const RetryArgsSchema: z.ZodObject<{
+  taskId: z.ZodString;
+}, z.core.$strip>;
+type RetryArgs = z.infer<typeof RetryArgsSchema>;
+declare const ScheduleArgsSchema: z.ZodObject<{
+  name: z.ZodString;
+  cron: z.ZodString;
+  task: z.ZodString;
+  args: z.ZodOptional<z.ZodUnknown>;
+  enabled: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type ScheduleArgs = z.infer<typeof ScheduleArgsSchema>;
+declare const UnscheduleArgsSchema: z.ZodObject<{
+  scheduleId: z.ZodOptional<z.ZodString>;
+  name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type UnscheduleArgs = z.infer<typeof UnscheduleArgsSchema>;
+declare const HeartbeatArgsSchema: z.ZodObject<{
+  taskId: z.ZodString;
+  progress: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+type HeartbeatArgs = z.infer<typeof HeartbeatArgsSchema>;
+declare const ClaimArgsSchema: z.ZodObject<{
+  taskId: z.ZodString;
+  workerId: z.ZodString;
+  leaseDuration: z.ZodOptional<z.ZodNumber>;
+  ifMatch: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ClaimArgs = z.infer<typeof ClaimArgsSchema>;
+declare const SubmitArgsSchema: z.ZodObject<{
+  taskId: z.ZodString;
+  workerId: z.ZodString;
+  success: z.ZodOptional<z.ZodBoolean>;
+  result: z.ZodOptional<z.ZodUnknown>;
+  artifacts: z.ZodOptional<z.ZodUnknown>;
+  verifyTask: z.ZodOptional<z.ZodString>;
+  verifyArgs: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+type SubmitArgs = z.infer<typeof SubmitArgsSchema>;
+interface TickResult {
+  dispatched: number;
+  timedOut: number;
+}
+type JobStatus = "pending" | "mapping" | "reducing" | "done" | "failed" | "cancelled";
+interface JobProgress {
+  pending: number;
+  running: number;
+  done: number;
+  failed: number;
+}
+interface JobEntry {
+  id: string;
+  name?: string;
+  status: JobStatus;
+  mapTask: string;
+  reduceTask?: string;
+  args?: unknown;
+  totalItems: number;
+  batchSize: number;
+  concurrency: number;
+  timeout?: number;
+  totalBatches: number;
+  progress: JobProgress;
+  /** Map task IDs, indexed by batchIndex */
+  mapTaskIds: string[];
+  reduceTaskId?: string;
+  /** Per-batch map results (null = failed or pending) */
+  mapResults: (unknown | null)[];
+  /** Final result: reduce output (if reduceTask) or mapResults */
+  result?: unknown;
+  error?: string;
+  created: number;
+  started?: number;
+  ended?: number;
+}
+declare const SubmitJobArgsSchema: z.ZodObject<{
+  name: z.ZodOptional<z.ZodString>;
+  mapTask: z.ZodString;
+  reduceTask: z.ZodOptional<z.ZodString>;
+  totalItems: z.ZodNumber;
+  batchSize: z.ZodOptional<z.ZodNumber>;
+  concurrency: z.ZodOptional<z.ZodNumber>;
+  args: z.ZodOptional<z.ZodUnknown>;
+  timeout: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type SubmitJobArgs = z.infer<typeof SubmitJobArgsSchema>;
+declare const CancelJobArgsSchema: z.ZodObject<{
+  jobId: z.ZodString;
+}, z.core.$strip>;
+type CancelJobArgs = z.infer<typeof CancelJobArgsSchema>;
+interface SchedulerSnapshot {
+  version: 1 | 2 | 3;
+  tasks: Record<string, TaskEntry>;
+  history: TaskEntry[];
+  /** v2+: cron schedules. Missing in v1 snapshots → treated as empty. */
+  schedules?: ScheduleEntry[];
+  /** v3+: map-reduce jobs. Missing in v1/v2 snapshots → treated as empty. */
+  jobs?: JobEntry[];
+}
+declare const SchedulerSnapshotSchema: z.ZodObject<{
+  version: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
+  tasks: z.ZodRecord<z.ZodString, z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodEnum<{
+      timeout: "timeout";
+      pending: "pending";
+      running: "running";
+      done: "done";
+      failed: "failed";
+      cancelled: "cancelled";
+      "budget-blocked": "budget-blocked";
+    }>;
+    taskPath: z.ZodString;
+    created: z.ZodNumber;
+    attempts: z.ZodNumber;
+    args: z.ZodOptional<z.ZodUnknown>;
+    estimate: z.ZodOptional<z.ZodObject<{
+      tokens: z.ZodOptional<z.ZodNumber>;
+      duration: z.ZodOptional<z.ZodNumber>;
+      calls: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    result: z.ZodOptional<z.ZodObject<{
+      success: z.ZodBoolean;
+      data: z.ZodOptional<z.ZodUnknown>;
+      error: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    error: z.ZodOptional<z.ZodString>;
+    started: z.ZodOptional<z.ZodNumber>;
+    ended: z.ZodOptional<z.ZodNumber>;
+    procId: z.ZodOptional<z.ZodString>;
+    ownerKey: z.ZodOptional<z.ZodString>;
+    scheduleId: z.ZodOptional<z.ZodString>;
+    deadline: z.ZodOptional<z.ZodNumber>;
+    lastHeartbeat: z.ZodOptional<z.ZodNumber>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    jobId: z.ZodOptional<z.ZodString>;
+    batchIndex: z.ZodOptional<z.ZodNumber>;
+    claimable: z.ZodOptional<z.ZodBoolean>;
+    assignee: z.ZodOptional<z.ZodString>;
+    claimedBy: z.ZodOptional<z.ZodString>;
+    claimedAt: z.ZodOptional<z.ZodNumber>;
+    version: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  history: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodEnum<{
+      timeout: "timeout";
+      pending: "pending";
+      running: "running";
+      done: "done";
+      failed: "failed";
+      cancelled: "cancelled";
+      "budget-blocked": "budget-blocked";
+    }>;
+    taskPath: z.ZodString;
+    created: z.ZodNumber;
+    attempts: z.ZodNumber;
+    args: z.ZodOptional<z.ZodUnknown>;
+    estimate: z.ZodOptional<z.ZodObject<{
+      tokens: z.ZodOptional<z.ZodNumber>;
+      duration: z.ZodOptional<z.ZodNumber>;
+      calls: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    result: z.ZodOptional<z.ZodObject<{
+      success: z.ZodBoolean;
+      data: z.ZodOptional<z.ZodUnknown>;
+      error: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    error: z.ZodOptional<z.ZodString>;
+    started: z.ZodOptional<z.ZodNumber>;
+    ended: z.ZodOptional<z.ZodNumber>;
+    procId: z.ZodOptional<z.ZodString>;
+    ownerKey: z.ZodOptional<z.ZodString>;
+    scheduleId: z.ZodOptional<z.ZodString>;
+    deadline: z.ZodOptional<z.ZodNumber>;
+    lastHeartbeat: z.ZodOptional<z.ZodNumber>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    jobId: z.ZodOptional<z.ZodString>;
+    batchIndex: z.ZodOptional<z.ZodNumber>;
+    claimable: z.ZodOptional<z.ZodBoolean>;
+    assignee: z.ZodOptional<z.ZodString>;
+    claimedBy: z.ZodOptional<z.ZodString>;
+    claimedAt: z.ZodOptional<z.ZodNumber>;
+    version: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  schedules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    cron: z.ZodString;
+    taskPath: z.ZodString;
+    args: z.ZodOptional<z.ZodUnknown>;
+    enabled: z.ZodBoolean;
+    created: z.ZodNumber;
+    ownerKey: z.ZodOptional<z.ZodString>;
+    lastRun: z.ZodOptional<z.ZodNumber>;
+    nextRun: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strip>>>;
+  jobs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<{
+      pending: "pending";
+      done: "done";
+      failed: "failed";
+      cancelled: "cancelled";
+      mapping: "mapping";
+      reducing: "reducing";
+    }>;
+    mapTask: z.ZodString;
+    reduceTask: z.ZodOptional<z.ZodString>;
+    args: z.ZodOptional<z.ZodUnknown>;
+    totalItems: z.ZodNumber;
+    batchSize: z.ZodNumber;
+    concurrency: z.ZodNumber;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    totalBatches: z.ZodNumber;
+    progress: z.ZodObject<{
+      pending: z.ZodNumber;
+      running: z.ZodNumber;
+      done: z.ZodNumber;
+      failed: z.ZodNumber;
+    }, z.core.$strip>;
+    mapTaskIds: z.ZodArray<z.ZodString>;
+    reduceTaskId: z.ZodOptional<z.ZodString>;
+    mapResults: z.ZodArray<z.ZodUnknown>;
+    result: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodString>;
+    created: z.ZodNumber;
+    started: z.ZodOptional<z.ZodNumber>;
+    ended: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strip>>>;
+}, z.core.$strip>;
+interface SchedulerProviderOptions {
+  name?: string;
+  description?: string;
+  executor?: TaskExecutor;
+  maxHistory?: number;
+  storagePath?: string;
+  /** AFS path where the proc provider is mounted. Default: "/proc" */
+  procPath?: string;
+  /** TTL for budget-blocked tasks in ms. Stale budget-blocked tasks are evicted on restore. Default: 86400000 (24h). Set to 0 to disable. */
+  budgetBlockedTTL?: number;
+  /** Timeout for cron/scheduled tasks in ms. Default: 0 (disabled). Runtimes with strict execution caps should set this explicitly. */
+  scheduledTaskTimeoutMs?: number;
+  /** Default lease duration (ms) for claim-based tasks when `claim` omits `leaseDuration`. Default: 300000 (5 min). */
+  defaultLeaseDuration?: number;
+  /**
+   * Default AFS task path for the verification agent task enqueued by
+   * `submit` when the caller omits `verifyTask`. No default — if neither is
+   * set, `submit` rejects with VALIDATION_ERROR (verification must never be
+   * silently skipped, per #777's agent-driven-verification decision).
+   */
+  verifyTaskPath?: string;
+  /**
+   * Hook called with each background task promise.
+   * In Cloudflare Workers, pass `ctx.waitUntil` to keep the isolate alive
+   * while fire-and-forget tasks complete.
+   */
+  waitUntil?: (promise: Promise<unknown>) => void;
+  /**
+   * DONamespace for Coordinator DOs.
+   * When set, submit-job and cancel-job delegate to Coordinator DOs
+   * instead of using in-memory coordination. Each job gets its own DO
+   * instance that manages wave dispatch via alarm chaining.
+   */
+  coordinatorNamespace?: DONamespace;
+}
+//#endregion
+export { BudgetEstimate, CancelArgs, CancelArgsSchema, CancelJobArgs, CancelJobArgsSchema, ClaimArgs, ClaimArgsSchema, DispatchArgs, DispatchArgsSchema, HeartbeatArgs, HeartbeatArgsSchema, JobEntry, JobProgress, JobStatus, RetryArgs, RetryArgsSchema, ScheduleArgs, ScheduleArgsSchema, ScheduleEntry, SchedulerProviderOptions, SchedulerSnapshot, SchedulerSnapshotSchema, SubmitArgs, SubmitArgsSchema, SubmitJobArgs, SubmitJobArgsSchema, TaskContext, TaskEntry, TaskExecutor, TaskResult, TaskStatus, TickResult, UnscheduleArgs, UnscheduleArgsSchema };
+//# sourceMappingURL=types.d.cts.map

package/dist/types.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.cts","names":[],"sources":["../src/types.ts"],"mappings":"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"}