@smithers-orchestrator/scheduler 0.16.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 William Cory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,190 @@
+{
+  "name": "@smithers-orchestrator/scheduler",
+  "version": "0.16.0",
+  "description": "Pure decision engine: session, scheduler, and task state management for Smithers workflows",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./TaskState": {
+      "types": "./src/index.d.ts"
+    },
+    "./TaskStateMap": {
+      "types": "./src/index.d.ts"
+    },
+    "./ReadonlyTaskStateMap": {
+      "types": "./src/index.d.ts"
+    },
+    "./TaskRecord": {
+      "types": "./src/index.d.ts"
+    },
+    "./buildStateKey": {
+      "types": "./src/index.d.ts",
+      "import": "./src/buildStateKey.js",
+      "default": "./src/buildStateKey.js"
+    },
+    "./parseStateKey": {
+      "types": "./src/index.d.ts",
+      "import": "./src/parseStateKey.js",
+      "default": "./src/parseStateKey.js"
+    },
+    "./cloneTaskStateMap": {
+      "types": "./src/index.d.ts",
+      "import": "./src/cloneTaskStateMap.js",
+      "default": "./src/cloneTaskStateMap.js"
+    },
+    "./isTerminalState": {
+      "types": "./src/index.d.ts",
+      "import": "./src/isTerminalState.js",
+      "default": "./src/isTerminalState.js"
+    },
+    "./PlanNode": {
+      "types": "./src/index.d.ts"
+    },
+    "./ScheduleResult": {
+      "types": "./src/index.d.ts"
+    },
+    "./RalphMeta": {
+      "types": "./src/index.d.ts"
+    },
+    "./ContinuationRequest": {
+      "types": "./src/index.d.ts"
+    },
+    "./RalphState": {
+      "types": "./src/index.d.ts"
+    },
+    "./RalphStateMap": {
+      "types": "./src/index.d.ts"
+    },
+    "./RetryWaitMap": {
+      "types": "./src/index.d.ts"
+    },
+    "./ScheduleSnapshot": {
+      "types": "./src/index.d.ts"
+    },
+    "./Scheduler": {
+      "types": "./src/index.d.ts",
+      "import": "./src/Scheduler.js",
+      "default": "./src/Scheduler.js"
+    },
+    "./SchedulerLive": {
+      "types": "./src/index.d.ts",
+      "import": "./src/SchedulerLive.js",
+      "default": "./src/SchedulerLive.js"
+    },
+    "./buildPlanTree": {
+      "types": "./src/index.d.ts",
+      "import": "./src/buildPlanTree.js",
+      "default": "./src/buildPlanTree.js"
+    },
+    "./scheduleTasks": {
+      "types": "./src/index.d.ts",
+      "import": "./src/scheduleTasks.js",
+      "default": "./src/scheduleTasks.js"
+    },
+    "./WorkflowSession": {
+      "types": "./src/index.d.ts",
+      "import": "./src/WorkflowSession.js",
+      "default": "./src/WorkflowSession.js"
+    },
+    "./WorkflowSessionService": {
+      "types": "./src/index.d.ts",
+      "import": "./src/WorkflowSessionService.js",
+      "default": "./src/WorkflowSessionService.js"
+    },
+    "./WorkflowSessionOptions": {
+      "types": "./src/index.d.ts"
+    },
+    "./makeWorkflowSession": {
+      "types": "./src/index.d.ts",
+      "import": "./src/makeWorkflowSession.js",
+      "default": "./src/makeWorkflowSession.js"
+    },
+    "./WorkflowSessionLive": {
+      "types": "./src/index.d.ts",
+      "import": "./src/WorkflowSessionLive.js",
+      "default": "./src/WorkflowSessionLive.js"
+    },
+    "./EngineDecision": {
+      "types": "./src/index.d.ts"
+    },
+    "./RenderContext": {
+      "types": "./src/index.d.ts"
+    },
+    "./WaitReason": {
+      "types": "./src/index.d.ts"
+    },
+    "./RunResult": {
+      "types": "./src/index.d.ts"
+    },
+    "./TaskOutput": {
+      "types": "./src/index.d.ts"
+    },
+    "./TaskFailure": {
+      "types": "./src/index.d.ts"
+    },
+    "./TokenUsage": {
+      "types": "./src/index.d.ts"
+    },
+    "./RetryPolicy": {
+      "types": "./src/index.d.ts"
+    },
+    "./CachePolicy": {
+      "types": "./src/index.d.ts"
+    },
+    "./SmithersWorkflowOptions": {
+      "types": "./src/index.d.ts"
+    },
+    "./ApprovalResolution": {
+      "types": "./src/index.d.ts"
+    },
+    "./ContinueAsNewTransition": {
+      "types": "./src/index.d.ts"
+    },
+    "./retryPolicyToSchedule": {
+      "types": "./src/index.d.ts",
+      "import": "./src/retryPolicyToSchedule.js",
+      "default": "./src/retryPolicyToSchedule.js"
+    },
+    "./retryScheduleDelayMs": {
+      "types": "./src/index.d.ts",
+      "import": "./src/retryScheduleDelayMs.js",
+      "default": "./src/retryScheduleDelayMs.js"
+    },
+    "./computeRetryDelayMs": {
+      "types": "./src/index.d.ts",
+      "import": "./src/computeRetryDelayMs.js",
+      "default": "./src/computeRetryDelayMs.js"
+    },
+    "./nowMs": {
+      "types": "./src/index.d.ts",
+      "import": "./src/nowMs.js",
+      "default": "./src/nowMs.js"
+    },
+    "./*": {
+      "types": "./src/index.d.ts",
+      "import": "./src/*.js",
+      "default": "./src/*.js"
+    }
+  },
+  "files": [
+    "src/"
+  ],
+  "dependencies": {
+    "effect": "^3.21.0",
+    "@smithers-orchestrator/errors": "0.16.0",
+    "@smithers-orchestrator/graph": "0.16.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "~5.9.3"
+  },
+  "scripts": {
+    "build": "tsup --dts-only",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/ApprovalResolution.ts

@@ -0,0 +1,7 @@
+export type ApprovalResolution = {
+  readonly approved: boolean;
+  readonly note?: string;
+  readonly decidedBy?: string;
+  readonly optionKey?: string;
+  readonly payload?: unknown;
+};

package/src/CachePolicy.ts

@@ -0,0 +1,8 @@
+export type CachePolicy<Ctx = any> = {
+  by?: (ctx: Ctx) => unknown;
+  version?: string;
+  key?: string;
+  ttlMs?: number;
+  scope?: "run" | "workflow" | "global";
+  [key: string]: unknown;
+};

package/src/ContinuationRequest.ts

@@ -0,0 +1,3 @@
+export type ContinuationRequest = {
+  readonly stateJson?: string;
+};

package/src/ContinueAsNewTransition.ts

@@ -0,0 +1,9 @@
+export type ContinueAsNewTransition = {
+  readonly reason: "explicit" | "loop-threshold" | "driver";
+  readonly iteration?: number;
+  readonly statePayload?: unknown;
+  readonly stateJson?: string;
+  readonly newRunId?: string;
+  readonly carriedStateBytes?: number;
+  readonly ancestryDepth?: number;
+};

package/src/EngineDecision.ts

@@ -0,0 +1,19 @@
+import type { TaskDescriptor } from "@smithers-orchestrator/graph";
+import type { ContinueAsNewTransition } from "./ContinueAsNewTransition.ts";
+import type { RenderContext } from "./RenderContext.ts";
+import type { RunResult } from "./RunResult.ts";
+import type { WaitReason } from "./WaitReason.ts";
+
+export type EngineDecision =
+  | { readonly _tag: "Execute"; readonly tasks: readonly TaskDescriptor[] }
+  | { readonly _tag: "ReRender"; readonly context: RenderContext }
+  | {
+      readonly _tag: "Wait";
+      readonly reason: WaitReason;
+    }
+  | {
+      readonly _tag: "ContinueAsNew";
+      readonly transition: ContinueAsNewTransition;
+    }
+  | { readonly _tag: "Finished"; readonly result: RunResult }
+  | { readonly _tag: "Failed"; readonly error: unknown };

package/src/PlanNode.ts

@@ -0,0 +1,32 @@
+export type PlanNode =
+  | { readonly kind: "task"; readonly nodeId: string }
+  | { readonly kind: "sequence"; readonly children: readonly PlanNode[] }
+  | { readonly kind: "parallel"; readonly children: readonly PlanNode[] }
+  | {
+      readonly kind: "ralph";
+      readonly id: string;
+      readonly children: readonly PlanNode[];
+      readonly until: boolean;
+      readonly maxIterations: number;
+      readonly onMaxReached: "fail" | "return-last";
+      readonly continueAsNewEvery?: number;
+    }
+  | {
+      readonly kind: "continue-as-new";
+      readonly stateJson?: string;
+    }
+  | { readonly kind: "group"; readonly children: readonly PlanNode[] }
+  | {
+      readonly kind: "saga";
+      readonly id: string;
+      readonly actionChildren: readonly PlanNode[];
+      readonly compensationChildren: readonly PlanNode[];
+      readonly onFailure: "compensate" | "compensate-and-fail" | "fail";
+    }
+  | {
+      readonly kind: "try-catch-finally";
+      readonly id: string;
+      readonly tryChildren: readonly PlanNode[];
+      readonly catchChildren: readonly PlanNode[];
+      readonly finallyChildren: readonly PlanNode[];
+    };

package/src/RalphMeta.ts

@@ -0,0 +1,7 @@
+export type RalphMeta = {
+  readonly id: string;
+  readonly until: boolean;
+  readonly maxIterations: number;
+  readonly onMaxReached: "fail" | "return-last";
+  readonly continueAsNewEvery?: number;
+};

package/src/RalphState.ts

@@ -0,0 +1,4 @@
+export type RalphState = {
+  readonly iteration: number;
+  readonly done: boolean;
+};

package/src/RalphStateMap.ts

@@ -0,0 +1,3 @@
+import type { RalphState } from "./RalphState.ts";
+
+export type RalphStateMap = Map<string, RalphState>;

package/src/ReadonlyTaskStateMap.ts

@@ -0,0 +1,3 @@
+import type { TaskState } from "./TaskState.ts";
+
+export type ReadonlyTaskStateMap = ReadonlyMap<string, TaskState>;

package/src/RenderContext.ts

@@ -0,0 +1,14 @@
+import type { WorkflowGraph } from "@smithers-orchestrator/graph";
+import type { TaskOutput } from "./TaskOutput.ts";
+
+export type RenderContext = {
+  readonly runId: string;
+  readonly graph?: WorkflowGraph | null;
+  readonly iteration?: number;
+  readonly iterations?: Record<string, number> | ReadonlyMap<string, number>;
+  readonly input?: unknown;
+  readonly outputs?: Record<string, unknown[]> | ReadonlyMap<string, TaskOutput>;
+  readonly auth?: unknown;
+  readonly taskStates?: unknown;
+  readonly ralphIterations?: ReadonlyMap<string, number>;
+};

package/src/RetryPolicy.ts

@@ -0,0 +1,6 @@
+export type RetryBackoff = "fixed" | "linear" | "exponential";
+
+export type RetryPolicy = {
+  backoff?: RetryBackoff;
+  initialDelayMs?: number;
+};

package/src/RetryWaitMap.ts

@@ -0,0 +1 @@
+export type RetryWaitMap = Map<string, number>;

package/src/RunResult.ts

@@ -0,0 +1,15 @@
+export type RunResult = {
+  readonly runId: string;
+  readonly status:
+    | "running"
+    | "finished"
+    | "failed"
+    | "cancelled"
+    | "continued"
+    | "waiting-approval"
+    | "waiting-event"
+    | "waiting-timer";
+  readonly output?: unknown;
+  readonly error?: unknown;
+  readonly nextRunId?: string;
+};

package/src/ScheduleResult.ts

@@ -0,0 +1,15 @@
+import type { TaskDescriptor } from "@smithers-orchestrator/graph";
+import type { ContinuationRequest } from "./ContinuationRequest.ts";
+import type { RalphMeta } from "./RalphMeta.ts";
+
+export type ScheduleResult = {
+  readonly runnable: readonly TaskDescriptor[];
+  readonly pendingExists: boolean;
+  readonly waitingApprovalExists: boolean;
+  readonly waitingEventExists: boolean;
+  readonly waitingTimerExists: boolean;
+  readonly readyRalphs: readonly RalphMeta[];
+  readonly continuation?: ContinuationRequest;
+  readonly nextRetryAtMs?: number;
+  readonly fatalError?: string;
+};

package/src/ScheduleSnapshot.ts

@@ -0,0 +1,8 @@
+import type { PlanNode } from "./PlanNode.ts";
+import type { ScheduleResult } from "./ScheduleResult.ts";
+
+export type ScheduleSnapshot = {
+  readonly plan: PlanNode | null;
+  readonly result: ScheduleResult;
+  readonly computedAtMs: number;
+};

package/src/Scheduler.js

@@ -0,0 +1,28 @@
+import { Context } from "effect";
+/** @typedef {import("@smithers-orchestrator/graph").TaskDescriptor} TaskDescriptor */
+/** @typedef {import("./TaskStateMap.ts").TaskStateMap} TaskStateMap */
+/** @typedef {import("./PlanNode.ts").PlanNode} PlanNode */
+/** @typedef {import("./RalphStateMap.ts").RalphStateMap} RalphStateMap */
+/** @typedef {import("./RetryWaitMap.ts").RetryWaitMap} RetryWaitMap */
+/** @typedef {import("./ScheduleResult.ts").ScheduleResult} ScheduleResult */
+
+/**
+ * @typedef {{
+ *   readonly schedule: (
+ *     plan: PlanNode | null,
+ *     states: TaskStateMap,
+ *     descriptors: Map<string, TaskDescriptor>,
+ *     ralphState: RalphStateMap,
+ *     retryWait: RetryWaitMap,
+ *     nowMs: number,
+ *   ) => import("effect").Effect.Effect<ScheduleResult>
+ * }} SchedulerService
+ */
+
+const SchedulerBase =
+  /** @type {Context.TagClass<Scheduler, "Scheduler", SchedulerService>} */ (
+    /** @type {unknown} */ (Context.Tag("Scheduler")())
+  );
+
+export class Scheduler extends SchedulerBase {
+}

package/src/SchedulerLive.js

@@ -0,0 +1,8 @@
+import { Effect, Layer } from "effect";
+import { Scheduler } from "./Scheduler.js";
+import { scheduleTasks } from "./scheduleTasks.js";
+
+/** @type {Layer.Layer<Scheduler, never, never>} */
+export const SchedulerLive = Layer.succeed(Scheduler, {
+    schedule: (plan, states, descriptors, ralphState, retryWait, nowMs) => Effect.sync(() => scheduleTasks(plan, states, descriptors, ralphState, retryWait, nowMs)),
+});

package/src/SmithersWorkflowOptions.ts

@@ -0,0 +1,43 @@
+export type SmithersAlertSeverity = "info" | "warning" | "critical";
+
+export type SmithersAlertLabels = Record<string, string>;
+
+export type SmithersAlertReactionKind =
+  | "emit-only"
+  | "pause"
+  | "cancel"
+  | "open-approval"
+  | "deliver";
+
+export type SmithersAlertReaction =
+  | { kind: "emit-only" }
+  | { kind: "pause" }
+  | { kind: "cancel" }
+  | { kind: "open-approval" }
+  | { kind: "deliver"; destination: string };
+
+export type SmithersAlertReactionRef = string | SmithersAlertReaction;
+
+export type SmithersAlertPolicyDefaults = {
+  owner?: string;
+  severity?: SmithersAlertSeverity;
+  runbook?: string;
+  labels?: SmithersAlertLabels;
+};
+
+export type SmithersAlertPolicyRule = SmithersAlertPolicyDefaults & {
+  afterMs?: number;
+  reaction?: SmithersAlertReactionRef;
+};
+
+export type SmithersAlertPolicy = {
+  defaults?: SmithersAlertPolicyDefaults;
+  rules?: Record<string, SmithersAlertPolicyRule>;
+  reactions?: Record<string, SmithersAlertReaction>;
+};
+
+export type SmithersWorkflowOptions = {
+  alertPolicy?: SmithersAlertPolicy;
+  cache?: boolean;
+  workflowHash?: string;
+};

package/src/TaskFailure.ts

@@ -0,0 +1,5 @@
+export type TaskFailure = {
+  readonly nodeId: string;
+  readonly iteration: number;
+  readonly error: unknown;
+};

package/src/TaskOutput.ts

@@ -0,0 +1,9 @@
+import type { TokenUsage } from "./TokenUsage.ts";
+
+export type TaskOutput = {
+  readonly nodeId: string;
+  readonly iteration: number;
+  readonly output: unknown;
+  readonly text?: string | null;
+  readonly usage?: TokenUsage | null;
+};

package/src/TaskRecord.ts

@@ -0,0 +1,10 @@
+import type { TaskDescriptor } from "@smithers-orchestrator/graph";
+import type { TaskState } from "./TaskState.ts";
+
+export type TaskRecord = {
+  readonly descriptor: TaskDescriptor;
+  readonly state: TaskState;
+  readonly output?: unknown;
+  readonly error?: unknown;
+  readonly updatedAtMs: number;
+};

package/src/TaskState.ts

@@ -0,0 +1,10 @@
+export type TaskState =
+  | "pending"
+  | "waiting-approval"
+  | "waiting-event"
+  | "waiting-timer"
+  | "in-progress"
+  | "finished"
+  | "failed"
+  | "cancelled"
+  | "skipped";

package/src/TaskStateMap.ts

@@ -0,0 +1,3 @@
+import type { TaskState } from "./TaskState.ts";
+
+export type TaskStateMap = Map<string, TaskState>;

package/src/TokenUsage.ts

@@ -0,0 +1,9 @@
+export type TokenUsage = {
+  readonly inputTokens?: number;
+  readonly outputTokens?: number;
+  readonly cacheReadTokens?: number;
+  readonly cacheWriteTokens?: number;
+  readonly reasoningTokens?: number;
+  readonly totalTokens?: number;
+  readonly [key: string]: unknown;
+};

package/src/WaitReason.ts

@@ -0,0 +1,8 @@
+export type WaitReason =
+  | { readonly _tag: "Approval"; readonly nodeId: string }
+  | { readonly _tag: "Event"; readonly eventName: string }
+  | { readonly _tag: "Timer"; readonly resumeAtMs: number }
+  | { readonly _tag: "RetryBackoff"; readonly waitMs: number }
+  | { readonly _tag: "HotReload" }
+  | { readonly _tag: "OrphanRecovery"; readonly count: number }
+  | { readonly _tag: "ExternalTrigger" };

package/src/WorkflowSession.js

@@ -0,0 +1,10 @@
+import { Context } from "effect";
+/** @typedef {import("./WorkflowSessionService.ts").WorkflowSessionService} WorkflowSessionService */
+
+const WorkflowSessionBase =
+  /** @type {Context.TagClass<WorkflowSession, "WorkflowSession", WorkflowSessionService>} */ (
+    /** @type {unknown} */ (Context.Tag("WorkflowSession")())
+  );
+
+export class WorkflowSession extends WorkflowSessionBase {
+}

package/src/WorkflowSessionLive.js

@@ -0,0 +1,6 @@
+import { Layer } from "effect";
+import { WorkflowSession } from "./WorkflowSession.js";
+import { makeWorkflowSession } from "./makeWorkflowSession.js";
+
+/** @type {Layer.Layer<WorkflowSession, never, never>} */
+export const WorkflowSessionLive = Layer.sync(WorkflowSession, makeWorkflowSession);

package/src/WorkflowSessionOptions.ts

@@ -0,0 +1,10 @@
+export type WorkflowSessionOptions = {
+  readonly runId?: string;
+  readonly nowMs?: () => number;
+  readonly requireStableFinish?: boolean;
+  readonly requireRerenderOnOutputChange?: boolean;
+  readonly initialRalphState?: ReadonlyMap<string, {
+    readonly iteration: number;
+    readonly done: boolean;
+  }>;
+};

package/src/WorkflowSessionService.ts

@@ -0,0 +1,52 @@
+import type { Effect } from "effect";
+import type { WorkflowGraph } from "@smithers-orchestrator/graph";
+import type { TaskStateMap } from "./TaskStateMap.ts";
+import type { ApprovalResolution } from "./ApprovalResolution.ts";
+import type { ScheduleSnapshot } from "./ScheduleSnapshot.ts";
+import type { EngineDecision } from "./EngineDecision.ts";
+import type { TaskFailure } from "./TaskFailure.ts";
+import type { TaskOutput } from "./TaskOutput.ts";
+
+export type WorkflowSessionService = {
+  readonly submitGraph: (graph: WorkflowGraph) => Effect.Effect<EngineDecision>;
+  readonly taskCompleted: (output: TaskOutput) => Effect.Effect<EngineDecision>;
+  readonly taskFailed: (failure: TaskFailure) => Effect.Effect<EngineDecision>;
+  readonly approvalResolved: (
+    nodeId: string,
+    resolution: ApprovalResolution,
+  ) => Effect.Effect<EngineDecision>;
+  readonly approvalTimedOut: (nodeId: string) => Effect.Effect<EngineDecision>;
+  readonly eventReceived: (
+    eventName: string,
+    payload: unknown,
+    correlationId?: string | null,
+  ) => Effect.Effect<EngineDecision>;
+  readonly signalReceived: (
+    signalName: string,
+    payload: unknown,
+    correlationId?: string | null,
+  ) => Effect.Effect<EngineDecision>;
+  readonly timerFired: (
+    nodeId: string,
+    firedAtMs?: number,
+  ) => Effect.Effect<EngineDecision>;
+  readonly hotReloaded: (graph: WorkflowGraph) => Effect.Effect<EngineDecision>;
+  readonly heartbeatTimedOut: (
+    nodeId: string,
+    iteration?: number,
+    details?: Record<string, unknown>,
+  ) => Effect.Effect<EngineDecision>;
+  readonly cacheResolved: (
+    output: TaskOutput,
+    cached: boolean,
+  ) => Effect.Effect<EngineDecision>;
+  readonly cacheMissed: (
+    nodeId: string,
+    iteration?: number,
+  ) => Effect.Effect<EngineDecision>;
+  readonly recoverOrphanedTasks: () => Effect.Effect<EngineDecision>;
+  readonly cancelRequested: () => Effect.Effect<EngineDecision>;
+  readonly getTaskStates: () => Effect.Effect<TaskStateMap>;
+  readonly getSchedule: () => Effect.Effect<ScheduleSnapshot | null>;
+  readonly getCurrentGraph: () => Effect.Effect<WorkflowGraph | null>;
+};