@smithers-orchestrator/scheduler 0.24.0 → 0.24.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/scheduler",
-  "version": "0.24.0",
+  "version": "0.24.2",
   "description": "Pure decision engine: session, scheduler, and task state management for Smithers workflows",
   "type": "module",
   "sideEffects": false,
@@ -176,8 +176,8 @@
   ],
   "dependencies": {
     "effect": "^3.21.1",
-    "@smithers-orchestrator/errors": "0.24.0",
-    "@smithers-orchestrator/graph": "0.24.0"
+    "@smithers-orchestrator/errors": "0.24.2",
+    "@smithers-orchestrator/graph": "0.24.2"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/WorkflowSessionOptions.ts

@@ -1,3 +1,13 @@
+import type { TaskDescriptor } from "@smithers-orchestrator/graph/TaskDescriptor";
+
+/** A breached Aspects budget for a task that is about to be dispatched. */
+export type AspectBudgetBreach = {
+  readonly kind: "tokens" | "latency";
+  readonly limit: number;
+  readonly current: number;
+  readonly onExceeded: "fail" | "warn" | "skip-remaining";
+};
+
 export type WorkflowSessionOptions = {
   readonly runId?: string;
   readonly nowMs?: () => number;
@@ -7,4 +17,22 @@ export type WorkflowSessionOptions = {
     readonly iteration: number;
     readonly done: boolean;
   }>;
+  /**
+   * Evaluate a runnable task's Aspects budgets against the run's accumulated
+   * usage. Return the first breach, or `null`/`undefined` when within budget.
+   * Only invoked for tasks that would otherwise execute.
+   */
+  readonly evaluateAspectBudget?: (
+    descriptor: TaskDescriptor,
+  ) => AspectBudgetBreach | null | undefined;
+  /** Called when a task is skipped because its budget was exceeded (`skip-remaining`). */
+  readonly onAspectBudgetSkip?: (
+    descriptor: TaskDescriptor,
+    breach: AspectBudgetBreach,
+  ) => void;
+  /** Called when a task continues despite an exceeded budget (`warn`). */
+  readonly onAspectBudgetWarn?: (
+    descriptor: TaskDescriptor,
+    breach: AspectBudgetBreach,
+  ) => void;
 };

package/src/index.d.ts

@@ -199,6 +199,12 @@ type WorkflowSessionService$2 = {
     readonly getCurrentGraph: () => Effect.Effect<WorkflowGraph | null>;
 };
 
+type AspectBudgetBreach$1 = {
+    readonly kind: "tokens" | "latency";
+    readonly limit: number;
+    readonly current: number;
+    readonly onExceeded: "fail" | "warn" | "skip-remaining";
+};
 type WorkflowSessionOptions$2 = {
     readonly runId?: string;
     readonly nowMs?: () => number;
@@ -208,6 +214,9 @@ type WorkflowSessionOptions$2 = {
         readonly iteration: number;
         readonly done: boolean;
     }>;
+    readonly evaluateAspectBudget?: (descriptor: TaskDescriptor$3) => AspectBudgetBreach$1 | null | undefined;
+    readonly onAspectBudgetSkip?: (descriptor: TaskDescriptor$3, breach: AspectBudgetBreach$1) => void;
+    readonly onAspectBudgetWarn?: (descriptor: TaskDescriptor$3, breach: AspectBudgetBreach$1) => void;
 };
 
 type TaskRecord$1 = {

package/src/makeWorkflowSession.js

@@ -530,6 +530,28 @@ export function makeWorkflowSession(options = {}) {
                 changed = true;
                 continue;
             }
+            const budgetBreach = options.evaluateAspectBudget?.(task);
+            if (budgetBreach) {
+                if (budgetBreach.onExceeded === "skip-remaining") {
+                    options.onAspectBudgetSkip?.(task, budgetBreach);
+                    state.states.set(key, "skipped");
+                    changed = true;
+                    continue;
+                }
+                if (budgetBreach.onExceeded === "warn") {
+                    options.onAspectBudgetWarn?.(task, budgetBreach);
+                }
+                else {
+                    return {
+                        _tag: "Failed",
+                        error: new SmithersError("ASPECT_BUDGET_EXCEEDED", `Aspects ${budgetBreach.kind} budget exceeded for task "${task.nodeId}": ${budgetBreach.current} >= ${budgetBreach.limit}`, {
+                            kind: budgetBreach.kind,
+                            limit: budgetBreach.limit,
+                            current: budgetBreach.current,
+                        }),
+                    };
+                }
+            }
             state.states.set(key, "in-progress");
             executable.push(task);
             changed = true;