octaflow 0.14.0

package/dist/dispatcher-pgboss/index.d.ts

@@ -0,0 +1,170 @@
+import "../index-D_fOYfmf.js";
+import { n as Logger } from "../logger-BCus3AOa.js";
+import { n as Dispatcher } from "../dispatcher-BydjyrgU.js";
+import { z } from "zod";
+import { PgBoss } from "pg-boss";
+//#region src/dispatcher-pgboss/payload.d.ts
+/**
+ * The wire payload for a step job. It is the flow-core `DispatchStepPayload`
+ * plus the `partitionKey` — the worker needs the partition to reconstruct a
+ * partition-scoped engine before calling `executeStep`.
+ */
+declare const WIRE_STEP_PAYLOAD_SCHEMA: z.ZodObject<{
+  partitionKey: z.ZodString;
+  workflowId: z.ZodNumber;
+  stepId: z.ZodNumber;
+  stepKey: z.ZodString;
+  stepType: z.ZodString;
+}, z.core.$strip>;
+type WireStepPayload = z.infer<typeof WIRE_STEP_PAYLOAD_SCHEMA>;
+interface StepQueueConfig {
+  /** Retries before a job is dead-lettered. Default 2. */
+  retryLimit?: number;
+  /** Seconds between retries. Default 30. */
+  retryDelay?: number;
+  /** Seconds before an in-flight job is considered expired. Default 600. */
+  expireInSeconds?: number;
+}
+declare const DEFAULT_STEP_QUEUE_CONFIG: Required<StepQueueConfig>;
+/**
+ * The wire payload for a scheduled (or ad-hoc) workflow **start**. Carries the
+ * partition plus what `engine.startWorkflow` needs; the host resolves `workflowType`
+ * to a definition. `idempotencyKey` is forwarded to the start so overlapping
+ * cron ticks don't double-start.
+ */
+declare const WIRE_START_PAYLOAD_SCHEMA: z.ZodObject<{
+  partitionKey: z.ZodString;
+  workflowType: z.ZodString;
+  input: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  entityRef: z.ZodOptional<z.ZodString>;
+  idempotencyKey: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type WireStartPayload = z.infer<typeof WIRE_START_PAYLOAD_SCHEMA>;
+//#endregion
+//#region src/dispatcher-pgboss/queue.d.ts
+/**
+ * Create the step queue and its dead-letter queue (idempotent). Call once at
+ * startup; the dispatcher also calls it lazily on first enqueue.
+ */
+declare function ensureStepQueue(boss: PgBoss, queueName: string, config?: StepQueueConfig): Promise<void>;
+interface PgBossDispatcherDeps {
+  boss: PgBoss;
+  queueName: string;
+  /** Partition this dispatcher is bound to — stamped into every enqueued job. */
+  partitionKey: string;
+  config?: StepQueueConfig;
+}
+/** A flow-core `Dispatcher` backed by pg-boss. */
+declare function createPgBossDispatcher(deps: PgBossDispatcherDeps): Dispatcher;
+interface PgBossStepWorkerOptions {
+  /** Steps fetched per poll. Default 1. */
+  batchSize?: number;
+  /** Base poll interval in seconds (pg-boss minimum 0.5). Default: pg-boss's own. */
+  pollingIntervalSeconds?: number;
+  /**
+   * Poll interval used while pg-boss's LISTEN/NOTIFY is active for the queue, where
+   * polling is only a backstop. Ignored when notify is off or unavailable.
+   */
+  notifyPollingIntervalSeconds?: number;
+  /**
+   * Keep fetching with no delay while every fetch returns a full `batchSize` batch;
+   * the first short fetch ends the burst. Ignored when `batchSize` is 1.
+   *
+   * **Worth enabling for throughput.** Without it a worker spends most of its time
+   * waiting out the poll interval: it drains a batch in milliseconds, then sleeps.
+   * See the performance table in the README.
+   */
+  burstWhenBatchFull?: boolean;
+  /** Burst while the queue's cached ready count exceeds this. Reacts on pg-boss's stats cadence. */
+  burstWhenReadyExceeds?: number;
+  /**
+   * How many steps from one fetched batch run at a time. Default 1 (serial).
+   *
+   * Raising this only helps once the worker is not poll-bound — pair it with
+   * `burstWhenBatchFull`. Each in-flight step needs a store connection, so keep
+   * `concurrency × workers` within your Postgres pool and `max_connections`.
+   */
+  concurrency?: number;
+}
+interface PgBossStepWorkerDeps {
+  boss: PgBoss;
+  queueName: string;
+  config?: StepQueueConfig;
+  logger?: Logger;
+  workerOptions?: PgBossStepWorkerOptions;
+}
+/** Handles a single step job. Reconstruct the partition-scoped engine and call
+ * `engine.executeStep(workflowId, stepId)`. Throw to trigger a pg-boss retry. */
+type StepJobProcessor = (payload: WireStepPayload) => Promise<void>;
+/** A pg-boss worker that drives `executeStep` for step jobs. */
+declare function createPgBossStepWorker(deps: PgBossStepWorkerDeps): {
+  start: (process: StepJobProcessor) => Promise<void>;
+  stop: () => Promise<void>;
+};
+interface PgBossDlqWorkerDeps {
+  boss: PgBoss;
+  queueName: string;
+  logger?: Logger;
+  pollingIntervalSeconds?: number;
+}
+/** Invoked for a step job that exhausted all retries. Typically calls
+ * `engine.handleStepExhausted(workflowId, stepId, reason)`. */
+type DlqProcessor = (payload: WireStepPayload) => Promise<void>;
+/** A pg-boss worker on the step queue's dead-letter queue. */
+declare function createPgBossDlqWorker(deps: PgBossDlqWorkerDeps): {
+  start: (onDlq: DlqProcessor) => Promise<void>;
+  stop: () => Promise<void>;
+};
+//#endregion
+//#region src/dispatcher-pgboss/scheduler.d.ts
+/** Create the start queue (idempotent). */
+declare function ensureStartQueue(boss: PgBoss, queueName: string): Promise<void>;
+interface PgBossSchedulerDeps {
+  boss: PgBoss;
+  /** Queue scheduled start jobs are sent to (and the start worker reads). */
+  queueName: string;
+  /** Partition stamped into every scheduled start payload. */
+  partitionKey: string;
+  logger?: Logger;
+}
+interface ScheduleStartInput {
+  /** Unique key for this schedule within the queue (allows many crons per queue). */
+  key: string;
+  /** Cron expression (5- or 6-field). */
+  cron: string;
+  /** Workflow type to start (the host resolves it to a definition). */
+  workflowType: string;
+  input?: Record<string, unknown>;
+  entityRef?: string;
+  /** Forwarded to the start so overlapping ticks don't double-start. */
+  idempotencyKey?: string;
+  /** Optional IANA time zone (default UTC). */
+  tz?: string;
+}
+/** Registers cron schedules that enqueue workflow-start jobs. */
+declare function createPgBossScheduler(deps: PgBossSchedulerDeps): {
+  /** Create or replace a cron schedule that starts a workflow. */
+  schedule(input: ScheduleStartInput): Promise<void>;
+  /** Remove a schedule by key. */
+  unschedule(key: string): Promise<void>;
+  /** List the schedules registered on this queue. */
+  list(): Promise<import("pg-boss").Schedule[]>;
+};
+/** Invoked for each start job — typically resolves the type and calls `engine.startWorkflow`. */
+type StartJobProcessor = (payload: WireStartPayload) => Promise<void>;
+interface PgBossStartWorkerDeps {
+  boss: PgBoss;
+  queueName: string;
+  logger?: Logger;
+  workerOptions?: {
+    batchSize?: number;
+    pollingIntervalSeconds?: number;
+  };
+}
+/** A pg-boss worker on the start queue that drives a host start callback. */
+declare function createPgBossStartWorker(deps: PgBossStartWorkerDeps): {
+  start: (process: StartJobProcessor) => Promise<void>;
+  stop: () => Promise<void>;
+};
+//#endregion
+export { DEFAULT_STEP_QUEUE_CONFIG, DlqProcessor, PgBossDispatcherDeps, PgBossDlqWorkerDeps, PgBossSchedulerDeps, PgBossStartWorkerDeps, PgBossStepWorkerDeps, PgBossStepWorkerOptions, ScheduleStartInput, StartJobProcessor, StepJobProcessor, StepQueueConfig, WIRE_START_PAYLOAD_SCHEMA, WIRE_STEP_PAYLOAD_SCHEMA, WireStartPayload, WireStepPayload, createPgBossDispatcher, createPgBossDlqWorker, createPgBossScheduler, createPgBossStartWorker, createPgBossStepWorker, ensureStartQueue, ensureStepQueue };

package/dist/dispatcher-pgboss/index.js

@@ -0,0 +1,301 @@
+import { z } from "zod";
+//#region src/dispatcher-pgboss/payload.ts
+/**
+* The wire payload for a step job. It is the flow-core `DispatchStepPayload`
+* plus the `partitionKey` — the worker needs the partition to reconstruct a
+* partition-scoped engine before calling `executeStep`.
+*/
+const WIRE_STEP_PAYLOAD_SCHEMA = z.object({
+	partitionKey: z.string().min(1),
+	workflowId: z.number().int().positive(),
+	stepId: z.number().int().positive(),
+	stepKey: z.string().min(1),
+	stepType: z.string().min(1)
+});
+const DEFAULT_STEP_QUEUE_CONFIG = {
+	retryLimit: 2,
+	retryDelay: 30,
+	expireInSeconds: 600
+};
+/**
+* The wire payload for a scheduled (or ad-hoc) workflow **start**. Carries the
+* partition plus what `engine.startWorkflow` needs; the host resolves `workflowType`
+* to a definition. `idempotencyKey` is forwarded to the start so overlapping
+* cron ticks don't double-start.
+*/
+const WIRE_START_PAYLOAD_SCHEMA = z.object({
+	partitionKey: z.string().min(1),
+	workflowType: z.string().min(1),
+	input: z.record(z.string(), z.unknown()).default({}),
+	entityRef: z.string().optional(),
+	idempotencyKey: z.string().optional()
+});
+//#endregion
+//#region src/dispatcher-pgboss/queue.ts
+function dlqName(queueName) {
+	return `${queueName}-dlq`;
+}
+/**
+* Create the step queue and its dead-letter queue (idempotent). Call once at
+* startup; the dispatcher also calls it lazily on first enqueue.
+*/
+async function ensureStepQueue(boss, queueName, config = {}) {
+	const cfg = {
+		...DEFAULT_STEP_QUEUE_CONFIG,
+		...config
+	};
+	const dlq = dlqName(queueName);
+	const swallowExists = (error) => {
+		if (error instanceof Error && error.message.includes("already exists")) return;
+		throw error;
+	};
+	try {
+		await boss.createQueue(dlq, { retryLimit: 0 });
+	} catch (e) {
+		swallowExists(e);
+	}
+	try {
+		await boss.createQueue(queueName, {
+			retryLimit: cfg.retryLimit,
+			retryDelay: cfg.retryDelay,
+			expireInSeconds: cfg.expireInSeconds,
+			deadLetter: dlq
+		});
+	} catch (e) {
+		swallowExists(e);
+	}
+}
+/** A flow-core `Dispatcher` backed by pg-boss. */
+function createPgBossDispatcher(deps) {
+	const { boss, queueName, partitionKey } = deps;
+	const cfg = {
+		...DEFAULT_STEP_QUEUE_CONFIG,
+		...deps.config
+	};
+	let ensured = false;
+	return { async enqueueStep(payload, options) {
+		try {
+			const wire = {
+				partitionKey,
+				...payload
+			};
+			const parsed = WIRE_STEP_PAYLOAD_SCHEMA.safeParse(wire);
+			if (!parsed.success) return {
+				ok: false,
+				error: {
+					key: "queue_error",
+					message: `Invalid step payload: ${parsed.error.message}`
+				}
+			};
+			if (!ensured) {
+				await ensureStepQueue(boss, queueName, cfg);
+				ensured = true;
+			}
+			const startAfter = options?.startAfterSeconds;
+			if (!await boss.send(queueName, parsed.data, {
+				retryLimit: cfg.retryLimit,
+				retryDelay: cfg.retryDelay,
+				expireInSeconds: cfg.expireInSeconds,
+				...startAfter != null && startAfter > 0 ? { startAfter } : {}
+			})) return {
+				ok: false,
+				error: {
+					key: "queue_error",
+					message: `Failed to enqueue job to ${queueName}`
+				}
+			};
+			return {
+				ok: true,
+				value: void 0
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				error: {
+					key: "queue_error",
+					message: error instanceof Error ? error.message : "Unknown enqueue error"
+				}
+			};
+		}
+	} };
+}
+/** A pg-boss worker that drives `executeStep` for step jobs. */
+function createPgBossStepWorker(deps) {
+	const { boss, queueName } = deps;
+	let workerId = null;
+	async function start(process) {
+		await ensureStepQueue(boss, queueName, deps.config);
+		const opts = deps.workerOptions ?? {};
+		const lanes = Math.max(1, opts.concurrency ?? 1);
+		const workOpts = {
+			batchSize: opts.batchSize ?? 1,
+			perJobResults: true,
+			...opts.pollingIntervalSeconds != null && { pollingIntervalSeconds: opts.pollingIntervalSeconds },
+			...opts.notifyPollingIntervalSeconds != null && { notifyPollingIntervalSeconds: opts.notifyPollingIntervalSeconds },
+			...opts.burstWhenBatchFull != null && { burstWhenBatchFull: opts.burstWhenBatchFull },
+			...opts.burstWhenReadyExceeds != null && { burstWhenReadyExceeds: opts.burstWhenReadyExceeds }
+		};
+		workerId = await boss.work(queueName, workOpts, async (jobs) => {
+			const results = [];
+			const pending = [...jobs];
+			await Promise.all(Array.from({ length: Math.min(lanes, pending.length) }, async () => {
+				for (;;) {
+					const job = pending.shift();
+					if (!job) break;
+					const parsed = WIRE_STEP_PAYLOAD_SCHEMA.safeParse(job.data);
+					if (!parsed.success) {
+						results.push({
+							id: job.id,
+							status: "deadletter",
+							output: { message: `Invalid step payload for job ${job.id}: ${parsed.error.message}` }
+						});
+						continue;
+					}
+					try {
+						await process(parsed.data);
+						results.push({
+							id: job.id,
+							status: "completed"
+						});
+					} catch (error) {
+						results.push({
+							id: job.id,
+							status: "failed",
+							output: { message: error instanceof Error ? error.message : String(error) }
+						});
+					}
+				}
+			}));
+			return results;
+		});
+	}
+	async function stop() {
+		if (workerId) {
+			await boss.offWork(workerId);
+			workerId = null;
+		}
+	}
+	return {
+		start,
+		stop
+	};
+}
+/** A pg-boss worker on the step queue's dead-letter queue. */
+function createPgBossDlqWorker(deps) {
+	const { boss, queueName, logger } = deps;
+	const dlq = dlqName(queueName);
+	let workerId = null;
+	async function start(onDlq) {
+		workerId = await boss.work(dlq, { pollingIntervalSeconds: deps.pollingIntervalSeconds ?? 30 }, async (jobs) => {
+			for (const job of jobs) {
+				const parsed = WIRE_STEP_PAYLOAD_SCHEMA.safeParse(job.data);
+				if (!parsed.success) {
+					logger?.error("Invalid payload in DLQ", void 0, { jobId: job.id });
+					continue;
+				}
+				logger?.error("Step job dead-lettered", void 0, {
+					jobId: job.id,
+					workflowId: parsed.data.workflowId,
+					stepId: parsed.data.stepId,
+					stepKey: parsed.data.stepKey
+				});
+				try {
+					await onDlq(parsed.data);
+				} catch (error) {
+					logger?.error("DLQ handler failed", error instanceof Error ? error : void 0, { jobId: job.id });
+				}
+			}
+		});
+	}
+	async function stop() {
+		if (workerId) {
+			await boss.offWork(workerId);
+			workerId = null;
+		}
+	}
+	return {
+		start,
+		stop
+	};
+}
+//#endregion
+//#region src/dispatcher-pgboss/scheduler.ts
+/** Create the start queue (idempotent). */
+async function ensureStartQueue(boss, queueName) {
+	try {
+		await boss.createQueue(queueName);
+	} catch (e) {
+		if (e instanceof Error && e.message.includes("already exists")) return;
+		throw e;
+	}
+}
+/** Registers cron schedules that enqueue workflow-start jobs. */
+function createPgBossScheduler(deps) {
+	const { boss, queueName, partitionKey } = deps;
+	let ensured = false;
+	async function ensure() {
+		if (!ensured) {
+			await ensureStartQueue(boss, queueName);
+			ensured = true;
+		}
+	}
+	return {
+		/** Create or replace a cron schedule that starts a workflow. */
+		async schedule(input) {
+			await ensure();
+			const payload = {
+				partitionKey,
+				workflowType: input.workflowType,
+				input: input.input ?? {},
+				entityRef: input.entityRef,
+				idempotencyKey: input.idempotencyKey
+			};
+			await boss.schedule(queueName, input.cron, payload, {
+				key: input.key,
+				...input.tz ? { tz: input.tz } : {}
+			});
+		},
+		/** Remove a schedule by key. */
+		async unschedule(key) {
+			await boss.unschedule(queueName, key);
+		},
+		/** List the schedules registered on this queue. */
+		async list() {
+			return (await boss.getSchedules()).filter((s) => s.name === queueName);
+		}
+	};
+}
+/** A pg-boss worker on the start queue that drives a host start callback. */
+function createPgBossStartWorker(deps) {
+	const { boss, queueName, logger } = deps;
+	let workerId = null;
+	async function start(process) {
+		await ensureStartQueue(boss, queueName);
+		const workOpts = {
+			batchSize: deps.workerOptions?.batchSize ?? 1,
+			...deps.workerOptions?.pollingIntervalSeconds != null && { pollingIntervalSeconds: deps.workerOptions.pollingIntervalSeconds }
+		};
+		workerId = await boss.work(queueName, workOpts, async (jobs) => {
+			for (const job of jobs) {
+				const parsed = WIRE_START_PAYLOAD_SCHEMA.safeParse(job.data);
+				if (!parsed.success) {
+					logger?.error("Invalid start payload", void 0, { jobId: job.id });
+					continue;
+				}
+				await process(parsed.data);
+			}
+		});
+	}
+	async function stop() {
+		if (workerId) {
+			await boss.offWork(workerId);
+			workerId = null;
+		}
+	}
+	return {
+		start,
+		stop
+	};
+}
+//#endregion
+export { DEFAULT_STEP_QUEUE_CONFIG, WIRE_START_PAYLOAD_SCHEMA, WIRE_STEP_PAYLOAD_SCHEMA, createPgBossDispatcher, createPgBossDlqWorker, createPgBossScheduler, createPgBossStartWorker, createPgBossStepWorker, ensureStartQueue, ensureStepQueue };

package/dist/hooks-CDRFQZbT.d.ts

@@ -0,0 +1,56 @@
+import { B as WorkflowDefinition, E as StartOptions, F as StepId, I as StepRecord, K as FlowErrorShape, U as WorkflowRecord, V as WorkflowId, q as Result } from "./index-D_fOYfmf.js";
+//#region src/core/hooks.d.ts
+interface BeforeStartArgs {
+  definition: WorkflowDefinition;
+  input: Record<string, unknown>;
+  options?: StartOptions;
+}
+interface BeforeStartResult {
+  /** Extra metadata persisted on the workflow row (merged over `options.metadata`). */
+  metadata?: Record<string, unknown>;
+}
+interface BuildStepContextArgs {
+  workflowId: WorkflowId;
+  stepId: StepId;
+  stepKey: string;
+  partitionKey: string;
+  workflow: WorkflowRecord;
+  step: StepRecord;
+}
+interface AfterStepArgs<TContext> {
+  workflowId: WorkflowId;
+  stepId: StepId;
+  partitionKey: string;
+  workflow: WorkflowRecord;
+  step: StepRecord;
+  output: Record<string, unknown>;
+  /** The same context object that was handed to the step handler. */
+  context: TContext;
+}
+interface WorkflowCompletedArgs {
+  workflowId: WorkflowId;
+  partitionKey: string;
+  workflow: WorkflowRecord;
+}
+interface WorkflowHooks<TContext = unknown> {
+  /**
+   * Runs before a workflow is created. Return an error to reject the start
+   * (e.g. quota exceeded) — the engine passes the error through untouched.
+   */
+  onBeforeStart?(args: BeforeStartArgs): Promise<Result<BeforeStartResult, FlowErrorShape>>;
+  /**
+   * Produces the per-step `context` handed to the handler (and later to
+   * `onAfterStep`). This is where the AI add-on resolves and instruments a model.
+   * If omitted, handlers receive `undefined` as their context.
+   */
+  buildStepContext?(args: BuildStepContextArgs): TContext | Promise<TContext>;
+  /**
+   * Runs after a step handler succeeds, before the step is marked completed.
+   * The AI add-on reads token usage off `context` here and persists cost.
+   */
+  onAfterStep?(args: AfterStepArgs<TContext>): Promise<void>;
+  /** Runs once when a workflow reaches `completed` (e.g. daily usage rollup). */
+  onWorkflowCompleted?(args: WorkflowCompletedArgs): Promise<void>;
+}
+//#endregion
+export { WorkflowCompletedArgs as a, BuildStepContextArgs as i, BeforeStartArgs as n, WorkflowHooks as o, BeforeStartResult as r, AfterStepArgs as t };