pg-workflows 0.11.0 → 0.13.0

package/dist/index.cjs

@@ -65,6 +65,7 @@ var __export = (target, all) => {
 var exports_src = {};
 __export(exports_src, {
   workflow: () => workflow,
+  otelPlugin: () => otelPlugin,
   createWorkflowRef: () => createWorkflowRef,
   WorkflowStatus: () => WorkflowStatus,
   WorkflowRunNotFoundError: () => WorkflowRunNotFoundError,
@@ -83,6 +84,8 @@ var import_pg_boss = require("pg-boss");
 var PAUSE_EVENT_NAME = "__internal_pause";
 var WORKFLOW_RUN_QUEUE_NAME = "workflow-run";
 var WORKFLOW_RUN_DLQ_QUEUE_NAME = "workflow_run_dlq";
+var SCHEDULE_QUEUE_PREFIX = "__pgw_schedule_";
+var scheduleQueueNameFor = (workflowId) => `${SCHEDULE_QUEUE_PREFIX}${workflowId}`;
 var DEFAULT_PGBOSS_SCHEMA = "pgboss_v12_pgworkflow";
 var MAX_WORKFLOW_ID_LENGTH = 256;
 var MAX_RESOURCE_ID_LENGTH = 256;
@@ -94,7 +97,7 @@ var isInvokeChildWorkflowTimelineEntry = (entry) => !!entry && typeof entry ===
 
 // src/db/migration.ts
 var MIGRATION_LOCK_ID = 738291645;
-var CURRENT_SCHEMA_VERSION = 4;
+var CURRENT_SCHEMA_VERSION = 5;
 async function runMigrations(db) {
   if (await isSchemaUpToDate(db)) {
     return;
@@ -157,6 +160,9 @@ async function runMigrations(db) {
     commands.push("ALTER TABLE workflow_runs ADD COLUMN IF NOT EXISTS parent_step_id varchar(256)");
     commands.push("ALTER TABLE workflow_runs ADD COLUMN IF NOT EXISTS parent_resource_id varchar(256)");
   }
+  if (currentVersion < 5) {
+    commands.push("ALTER TABLE workflow_runs ADD COLUMN IF NOT EXISTS scheduled_at timestamp with time zone");
+  }
   if (currentVersion === 0) {
     commands.push(`INSERT INTO workflow_schema_version (version) VALUES (${CURRENT_SCHEMA_VERSION})`);
   } else {
@@ -222,7 +228,8 @@ function mapRowToWorkflowRun(row) {
     idempotencyKey: row.idempotency_key,
     parentRunId: row.parent_run_id,
     parentStepId: row.parent_step_id,
-    parentResourceId: row.parent_resource_id
+    parentResourceId: row.parent_resource_id,
+    scheduledAt: row.scheduled_at ? new Date(row.scheduled_at) : null
   };
 }
 async function insertWorkflowRun({
@@ -236,7 +243,8 @@ async function insertWorkflowRun({
   idempotencyKey,
   parentRunId,
   parentStepId,
-  parentResourceId
+  parentResourceId,
+  scheduledAt
 }, db) {
   const runId = generateKSUID("run");
   const now = new Date;
@@ -256,9 +264,10 @@ async function insertWorkflowRun({
       idempotency_key,
       parent_run_id,
       parent_step_id,
-      parent_resource_id
+      parent_resource_id,
+      scheduled_at
     )
-    VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16)
+    VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17)
     ON CONFLICT (idempotency_key) WHERE idempotency_key IS NOT NULL DO NOTHING
     RETURNING *`, [
     runId,
@@ -276,7 +285,8 @@ async function insertWorkflowRun({
     idempotencyKey ?? null,
     parentRunId ?? null,
     parentStepId ?? null,
-    parentResourceId ?? null
+    parentResourceId ?? null,
+    scheduledAt ?? null
   ]);
   if (result.rows[0]) {
     return { run: mapRowToWorkflowRun(result.rows[0]), created: true };
@@ -305,6 +315,23 @@ async function getWorkflowRun({
   }
   return mapRowToWorkflowRun(run);
 }
+async function getWorkflowLastRun({
+  workflowId,
+  resourceId
+}, db) {
+  const result = resourceId ? await db.executeSql(`SELECT * FROM workflow_runs
+         WHERE workflow_id = $1 AND resource_id = $2
+         ORDER BY created_at DESC
+         LIMIT 1`, [workflowId, resourceId]) : await db.executeSql(`SELECT * FROM workflow_runs
+         WHERE workflow_id = $1
+         ORDER BY created_at DESC
+         LIMIT 1`, [workflowId]);
+  const run = result.rows[0];
+  if (!run) {
+    return null;
+  }
+  return mapRowToWorkflowRun(run);
+}
 async function updateWorkflowRun({
   runId,
   resourceId,
@@ -852,7 +879,9 @@ function createWorkflowRef(id, options) {
     handler,
     inputSchema: options?.inputSchema,
     timeout: defineOptions?.timeout,
-    retries: defineOptions?.retries
+    retries: defineOptions?.retries,
+    schedule: defineOptions?.schedule,
+    timezone: defineOptions?.timezone
   });
   Object.defineProperty(ref, "id", { value: id, enumerable: true });
   Object.defineProperty(ref, "inputSchema", {
@@ -862,12 +891,14 @@ function createWorkflowRef(id, options) {
   return ref;
 }
 function createWorkflowFactory(plugins = []) {
-  const factory = (id, handler, { inputSchema, timeout, retries } = {}) => ({
+  const factory = (id, handler, { inputSchema, timeout, retries, schedule, timezone } = {}) => ({
     id,
     handler,
     inputSchema,
     timeout,
     retries,
+    schedule,
+    timezone,
     plugins: plugins.length > 0 ? plugins : undefined
   });
   factory.use = (plugin) => createWorkflowFactory([
@@ -979,6 +1010,56 @@ function parseDuration(duration) {
   return ms;
 }
 
+// src/schedule.ts
+var import_cron_parser = require("cron-parser");
+var CRON_TOKEN = /^[0-9*/,?\-LW#]+$/;
+function looksLikeCronString(value) {
+  const tokens = value.trim().split(/\s+/);
+  if (tokens.length !== 5 && tokens.length !== 6)
+    return false;
+  return tokens.every((t) => CRON_TOKEN.test(t));
+}
+function validateCronExpression(expression, timezone) {
+  try {
+    import_cron_parser.CronExpressionParser.parse(expression, { tz: timezone });
+  } catch (e) {
+    throw new WorkflowEngineError(`Invalid cron expression "${expression}" (timezone: ${timezone}): ${e instanceof Error ? e.message : String(e)}`);
+  }
+}
+function durationMsToCron(ms, original) {
+  if (ms < MS_PER_MINUTE) {
+    throw new WorkflowEngineError(`Schedule interval must be at least 1 minute; got ${ms}ms from ${JSON.stringify(original)}`);
+  }
+  if (ms % MS_PER_DAY === 0) {
+    const days = ms / MS_PER_DAY;
+    if (days === 1)
+      return "0 0 * * *";
+    throw cronStepError(original, `${days} days`);
+  }
+  if (ms % MS_PER_HOUR === 0) {
+    const hours = ms / MS_PER_HOUR;
+    if (24 % hours === 0)
+      return `0 */${hours} * * *`;
+    throw cronStepError(original, `${hours} hours`);
+  }
+  const minutes = ms / MS_PER_MINUTE;
+  if (Number.isInteger(minutes) && 60 % minutes === 0)
+    return `*/${minutes} * * * *`;
+  throw cronStepError(original, `${minutes} minutes`);
+}
+function cronStepError(original, label) {
+  return new WorkflowEngineError(`Schedule interval ${JSON.stringify(original)} (${label}) doesn't map cleanly to a recurring cron expression. Use a value that divides 60 minutes, 24 hours, or 1 day — or pass an explicit cron string.`);
+}
+function resolveSchedule(schedule, timezone) {
+  const tz = timezone ?? "UTC";
+  if (typeof schedule === "string" && looksLikeCronString(schedule)) {
+    validateCronExpression(schedule, tz);
+    return { cron: schedule, timezone: tz };
+  }
+  const ms = parseDuration(schedule);
+  return { cron: durationMsToCron(ms, schedule), timezone: tz };
+}
+
 // src/engine.ts
 var LOG_PREFIX2 = "[WorkflowEngine]";
 var StepTypeToIcon = {
@@ -1065,10 +1146,41 @@ class WorkflowEngine {
       await this.boss.work(WORKFLOW_RUN_DLQ_QUEUE_NAME, { pollingIntervalSeconds: 0.5, batchSize: 1 }, (jobs) => this.handleWorkflowRunDlq(jobs));
       this.logger.log(`Worker started for queue ${WORKFLOW_RUN_DLQ_QUEUE_NAME}`);
     }
+    if (asEngine) {
+      const scheduled = Array.from(this.workflows.values()).flatMap((wf) => wf.schedule == null ? [] : [{ id: wf.id, resolved: resolveSchedule(wf.schedule, wf.timezone) }]);
+      await Promise.allSettled(scheduled.map(({ id, resolved }) => this.registerWorkflowSchedule(id, resolved).catch((error) => {
+        this.logger.error(`Failed to register schedule for "${id}", skipping`, error instanceof Error ? error : new Error(String(error)), { workflowId: id });
+      })));
+    }
     this._started = true;
     this.logger.log("Workflow engine started!");
   }
+  async registerWorkflowSchedule(workflowId, resolvedSchedule) {
+    const scheduleQueueName = scheduleQueueNameFor(workflowId);
+    await this.boss.createQueue(scheduleQueueName);
+    await this.boss.schedule(scheduleQueueName, resolvedSchedule.cron, null, {
+      tz: resolvedSchedule.timezone
+    });
+    await this.boss.work(scheduleQueueName, { batchSize: 1, includeMetadata: true }, async (jobs) => {
+      const scheduledAt = jobs[0]?.startAfter ?? new Date;
+      try {
+        await this.createWorkflowRun({ workflowId, input: {}, scheduledAt });
+      } catch (error) {
+        this.logger.error(`Schedule fire failed to start a run for workflow "${workflowId}"`, error instanceof Error ? error : new Error(String(error)), { workflowId });
+        throw error;
+      }
+    });
+    this.logger.log(`Schedule registered for workflow "${workflowId}": ${resolvedSchedule.cron} (${resolvedSchedule.timezone})`, { workflowId });
+  }
+  async unscheduleWorkflow(workflowId) {
+    try {
+      await this.boss.unschedule(scheduleQueueNameFor(workflowId));
+    } catch (error) {
+      this.logger.error(`Failed to unschedule "${workflowId}"`, error instanceof Error ? error : new Error(String(error)), { workflowId });
+    }
+  }
   async stop() {
+    await Promise.allSettled(Array.from(this.workflows.values()).filter((wf) => wf.schedule != null).map((wf) => this.unscheduleWorkflow(wf.id)));
     await this.boss.stop();
     if (this._ownsPool) {
       await this.pool.end();
@@ -1081,10 +1193,14 @@ class WorkflowEngine {
       throw new WorkflowEngineError(`Workflow ${definition.id} is already registered`, definition.id);
     }
     const { steps } = parseWorkflowHandler(definition.handler);
+    const resolvedSchedule = definition.schedule ? resolveSchedule(definition.schedule, definition.timezone) : undefined;
     this.workflows.set(definition.id, {
       ...definition,
       steps
     });
+    if (this._started && resolvedSchedule) {
+      await this.registerWorkflowSchedule(definition.id, resolvedSchedule);
+    }
     this.logger.log(`Registered workflow "${definition.id}" with steps:`);
     for (const step of steps.values()) {
       const tags = [];
@@ -1099,10 +1215,17 @@ class WorkflowEngine {
     return this;
   }
   async unregisterWorkflow(workflowId) {
+    const existing = this.workflows.get(workflowId);
+    if (existing?.schedule != null && this._started) {
+      await this.unscheduleWorkflow(workflowId);
+    }
     this.workflows.delete(workflowId);
     return this;
   }
   async unregisterAllWorkflows() {
+    if (this._started) {
+      await Promise.allSettled(Array.from(this.workflows.values()).filter((wf) => wf.schedule != null).map((wf) => this.unscheduleWorkflow(wf.id)));
+    }
     this.workflows.clear();
     return this;
   }
@@ -1152,6 +1275,7 @@ class WorkflowEngine {
     parentRunId,
     parentStepId,
     parentResourceId,
+    scheduledAt,
     enqueue = true,
     db
   }) {
@@ -1185,7 +1309,8 @@ class WorkflowEngine {
       idempotencyKey,
       parentRunId,
       parentStepId,
-      parentResourceId
+      parentResourceId,
+      scheduledAt
     }, targetDb);
     const insertAndEnqueue = async (targetDb) => {
       const result = await insertRun(targetDb);
@@ -1368,6 +1493,14 @@ class WorkflowEngine {
     }
     return run;
   }
+  async getWorkflowLastRun({
+    workflowId,
+    resourceId
+  }) {
+    validateWorkflowId(workflowId);
+    validateResourceId(resourceId);
+    return getWorkflowLastRun({ workflowId, resourceId }, this.db);
+  }
   async updateRun({
     runId,
     resourceId,
@@ -1589,21 +1722,33 @@ class WorkflowEngine {
       };
       let step = { ...baseStep };
       const plugins = workflow2.plugins ?? [];
-      for (const plugin of plugins) {
-        const extra = plugin.methods(step);
-        step = { ...step, ...extra };
-      }
       const context = {
         input: run.input,
         workflowId: run.workflowId,
         runId: run.id,
+        resourceId: run.resourceId ?? undefined,
+        attempt: run.retryCount,
         get timeline() {
           return run?.timeline ?? {};
         },
         logger: this.logger,
-        step
+        step,
+        schedule: run.scheduledAt ? { timestamp: run.scheduledAt } : undefined
       };
-      const result = await workflow2.handler(context);
+      for (const plugin of plugins) {
+        const extra = plugin.methods(step, context);
+        step = { ...step, ...extra };
+        context.step = step;
+      }
+      let next = () => workflow2.handler(context);
+      for (const plugin of [...plugins].reverse()) {
+        if (plugin.wrap) {
+          const inner = next;
+          const wrap = plugin.wrap;
+          next = () => wrap(context, inner);
+        }
+      }
+      const result = await next();
       run = await this.getRun({ runId, resourceId: scopedResourceId });
       const isLastParsedStep = run.currentStepId === workflow2.steps[workflow2.steps.length - 1]?.id;
       const hasPluginSteps = (workflow2.plugins?.length ?? 0) > 0;
@@ -2136,6 +2281,176 @@ ${error.stack}` : String(error)
     }, this.db);
   }
 }
+// src/plugins/otel.ts
+var import_api = require("@opentelemetry/api");
+var DEFAULT_PREFIX = "pg_workflows";
+function isCachedHit(timeline, stepId, kind) {
+  const entry = timeline[stepId];
+  if (entry && typeof entry === "object" && "output" in entry && entry.output !== undefined) {
+    return true;
+  }
+  if (kind === "invokeChildWorkflow" && timeline[invokeChildWorkflowTimelineKey(stepId)]) {
+    return true;
+  }
+  return false;
+}
+function otelPlugin(options = {}) {
+  const tracer = options.tracer ?? import_api.trace.getTracer("pg-workflows");
+  const prefix = options.spanNamePrefix ?? DEFAULT_PREFIX;
+  const extraAttrs = options.attributes;
+  return {
+    name: "opentelemetry",
+    methods: (step, context) => {
+      const wrapVoidish = (kind, base) => {
+        return async (stepId, ...args) => {
+          if (isCachedHit(context.timeline, stepId, kind)) {
+            return base(stepId, ...args);
+          }
+          const capturedCtx = import_api.context.active();
+          const startTime = new Date;
+          let result;
+          let originalErr;
+          let thrownError;
+          try {
+            result = await base(stepId, ...args);
+          } catch (err) {
+            originalErr = err;
+            thrownError = err instanceof Error ? err : new Error(String(err));
+          }
+          const span = tracer.startSpan(`${prefix}.step.${kind}`, {
+            startTime,
+            attributes: { "step.id": stepId, "step.type": kind }
+          }, capturedCtx);
+          if (thrownError) {
+            span.recordException(thrownError);
+            span.setStatus({ code: import_api.SpanStatusCode.ERROR, message: thrownError.message });
+            span.end();
+            throw originalErr;
+          }
+          span.setStatus({ code: import_api.SpanStatusCode.OK });
+          span.end();
+          return result;
+        };
+      };
+      return {
+        run: async (stepId, handler) => {
+          if (isCachedHit(context.timeline, stepId, "run")) {
+            return step.run(stepId, handler);
+          }
+          const capturedCtx = import_api.context.active();
+          const startTime = new Date;
+          let result;
+          let originalErr;
+          let thrownError;
+          try {
+            result = await step.run(stepId, handler);
+          } catch (err) {
+            originalErr = err;
+            thrownError = err instanceof Error ? err : new Error(String(err));
+          }
+          if (result === undefined && !thrownError) {
+            return;
+          }
+          const span = tracer.startSpan(`${prefix}.step.run`, {
+            startTime,
+            attributes: { "step.id": stepId, "step.type": "run" }
+          }, capturedCtx);
+          if (thrownError) {
+            span.recordException(thrownError);
+            span.setStatus({ code: import_api.SpanStatusCode.ERROR, message: thrownError.message });
+            span.end();
+            throw originalErr;
+          }
+          span.setStatus({ code: import_api.SpanStatusCode.OK });
+          span.end();
+          return result;
+        },
+        waitFor: wrapVoidish("waitFor", step.waitFor),
+        delay: wrapVoidish("delay", step.delay),
+        sleep: wrapVoidish("delay", step.delay),
+        waitUntil: wrapVoidish("waitUntil", step.waitUntil),
+        pause: wrapVoidish("pause", step.pause),
+        poll: async (stepId, conditionFn, pollOptions) => {
+          const capturedCtx = import_api.context.active();
+          const startTime = new Date;
+          let result;
+          let originalErr;
+          let thrownError;
+          try {
+            result = await step.poll(stepId, conditionFn, pollOptions);
+          } catch (err) {
+            originalErr = err;
+            thrownError = err instanceof Error ? err : new Error(String(err));
+          }
+          const span = tracer.startSpan(`${prefix}.step.poll`, {
+            startTime,
+            attributes: { "step.id": stepId, "step.type": "poll" }
+          }, capturedCtx);
+          if (thrownError) {
+            span.recordException(thrownError);
+            span.setStatus({ code: import_api.SpanStatusCode.ERROR, message: thrownError.message });
+            span.end();
+            throw originalErr;
+          }
+          span.setStatus({ code: import_api.SpanStatusCode.OK });
+          span.end();
+          return result;
+        },
+        invokeChildWorkflow: async (stepId, refOrParams, inputArg, optionsArg) => {
+          if (isCachedHit(context.timeline, stepId, "invokeChildWorkflow")) {
+            return step.invokeChildWorkflow(stepId, refOrParams, inputArg, optionsArg);
+          }
+          const capturedCtx = import_api.context.active();
+          const startTime = new Date;
+          let result;
+          let originalErr;
+          let thrownError;
+          try {
+            result = await step.invokeChildWorkflow(stepId, refOrParams, inputArg, optionsArg);
+          } catch (err) {
+            originalErr = err;
+            thrownError = err instanceof Error ? err : new Error(String(err));
+          }
+          const span = tracer.startSpan(`${prefix}.step.invokeChildWorkflow`, {
+            startTime,
+            attributes: { "step.id": stepId, "step.type": "invokeChildWorkflow" }
+          }, capturedCtx);
+          if (thrownError) {
+            span.recordException(thrownError);
+            span.setStatus({ code: import_api.SpanStatusCode.ERROR, message: thrownError.message });
+            span.end();
+            throw originalErr;
+          }
+          span.setStatus({ code: import_api.SpanStatusCode.OK });
+          span.end();
+          return result;
+        }
+      };
+    },
+    wrap: (context, next) => tracer.startActiveSpan(`${prefix}.workflow.run`, {
+      attributes: {
+        "workflow.id": context.workflowId,
+        "workflow.run_id": context.runId,
+        "workflow.attempt": context.attempt,
+        ...context.resourceId ? { "workflow.resource_id": context.resourceId } : {},
+        ...extraAttrs ? extraAttrs(context) : {}
+      }
+    }, async (span) => {
+      try {
+        const result = await next();
+        span.setStatus({ code: import_api.SpanStatusCode.OK });
+        return result;
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        span.recordException(error);
+        span.setStatus({ code: import_api.SpanStatusCode.ERROR, message: error.message });
+        throw err;
+      } finally {
+        span.end();
+      }
+    })
+  };
+}
 
-//# debugId=B0870008EFFA04F064756E2164756E21
+//# debugId=12905C6BC12C3A1664756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/index.d.cts

@@ -23,6 +23,8 @@ type WorkflowRun = {
 	parentRunId: string | null;
 	parentStepId: string | null;
 	parentResourceId: string | null;
+	/** Set when the run was started by a recurring schedule; the timestamp the schedule fired. */
+	scheduledAt: Date | null;
 };
 import { StandardSchemaV1 } from "@standard-schema/spec";
 type DurationObject = {
@@ -33,6 +35,7 @@ type DurationObject = {
 	seconds?: number;
 };
 type Duration = string | DurationObject;
+type Schedule = string | Exclude<Duration, string>;
 declare enum WorkflowStatus {
 	PENDING = "pending",
 	RUNNING = "running",
@@ -63,6 +66,18 @@ type WorkflowOptions<I extends InputParameters> = {
 	timeout?: number;
 	retries?: number;
 	inputSchema?: I;
+	/**
+	* Recurring schedule. Accepts a cron expression (`'0 9 * * 1-5'`),
+	* a duration string (`'5m'`, `'1 hour'`), or a `DurationObject`.
+	*/
+	schedule?: Schedule;
+	/** IANA timezone for cron expressions. Defaults to UTC. Ignored for duration-based schedules. */
+	timezone?: string;
+};
+/** Metadata about a scheduled fire, exposed on `ctx.schedule` for runs triggered by a schedule. */
+type ScheduleContext = {
+	/** Time the schedule fired this run. */
+	timestamp: Date;
 };
 type StepBaseContext = {
 	run: <T>(stepId: string, handler: () => Promise<T>) => Promise<T>;
@@ -126,7 +141,13 @@ interface WorkflowPlugin<
 	TStepExt = object
 > {
 	name: string;
-	methods: (step: TStepBase) => TStepExt;
+	methods: (step: TStepBase, context: WorkflowContext) => TStepExt;
+	/**
+	* Optional middleware around the workflow handler call. Composes in
+	* registration order — the first plugin passed to `.use()` wraps everything
+	* inside. Implementations MUST call `next()` exactly once.
+	*/
+	wrap?: (context: WorkflowContext, next: () => Promise<unknown>) => Promise<unknown>;
 }
 type WorkflowContext<
 	TInput extends InputParameters = InputParameters,
@@ -136,8 +157,14 @@ type WorkflowContext<
 	step: TStep;
 	workflowId: string;
 	runId: string;
+	/** Tenant/scope identifier set when the run was started, if any. */
+	resourceId?: string;
+	/** Zero-based retry attempt number (= `run.retryCount`). */
+	attempt: number;
 	timeline: Record<string, unknown>;
 	logger: WorkflowLogger;
+	/** Set only for runs triggered by a recurring schedule. */
+	schedule?: ScheduleContext;
 };
 type WorkflowDefinition<TInput extends InputParameters = InputParameters> = {
 	id: string;
@@ -146,6 +173,8 @@ type WorkflowDefinition<TInput extends InputParameters = InputParameters> = {
 	inputSchema?: TInput;
 	timeout?: number;
 	retries?: number;
+	schedule?: Schedule;
+	timezone?: string;
 	plugins?: WorkflowPlugin[];
 };
 type StepInternalDefinition = {
@@ -321,6 +350,8 @@ declare class WorkflowEngine {
 		batchSize?: number;
 		heartbeatSeconds?: number;
 	}): Promise<void>;
+	private registerWorkflowSchedule;
+	private unscheduleWorkflow;
 	stop(): Promise<void>;
 	registerWorkflow(definition: WorkflowDefinition<InputParameters>): Promise<WorkflowEngine>;
 	unregisterWorkflow(workflowId: string): Promise<WorkflowEngine>;
@@ -373,6 +404,15 @@ declare class WorkflowEngine {
 		exclusiveLock?: boolean;
 		db?: Db;
 	}): Promise<WorkflowRun>;
+	/**
+	* Fetch the most recently created run for a workflow, optionally scoped to a
+	* `resourceId`. Useful for cron-style incremental syncs where the next run
+	* needs the previous run's completion timestamp as a cursor.
+	*/
+	getWorkflowLastRun({ workflowId, resourceId }: {
+		workflowId: string;
+		resourceId?: string;
+	}): Promise<WorkflowRun | null>;
 	updateRun({ runId, resourceId, data, expectedStatuses }: {
 		runId: string;
 		resourceId?: string;
@@ -452,4 +492,14 @@ declare class WorkflowEngineError extends Error {
 declare class WorkflowRunNotFoundError extends WorkflowEngineError {
 	constructor(runId?: string, workflowId?: string);
 }
-export { workflow, createWorkflowRef, WorkflowStatus, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowRun, WorkflowRef, WorkflowPlugin, WorkflowOptions, WorkflowLogger, WorkflowEngineOptions, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, WorkflowClientOptions, WorkflowClient, StepBaseContext, StartWorkflowOptions, InputParameters, InferInputParameters, Duration };
+import { AttributeValue, Tracer } from "@opentelemetry/api";
+type OtelPluginOptions = {
+	/** Tracer to use. Defaults to `trace.getTracer('pg-workflows')`. */
+	tracer?: Tracer;
+	/** Prefix for all span names. Defaults to `pg_workflows`. */
+	spanNamePrefix?: string;
+	/** Extra attributes merged onto the workflow.run span. */
+	attributes?: (context: WorkflowContext) => Record<string, AttributeValue>;
+};
+declare function otelPlugin(options?: OtelPluginOptions): WorkflowPlugin<StepBaseContext, object>;
+export { workflow, otelPlugin, createWorkflowRef, WorkflowStatus, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowRun, WorkflowRef, WorkflowPlugin, WorkflowOptions, WorkflowLogger, WorkflowEngineOptions, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, WorkflowClientOptions, WorkflowClient, StepBaseContext, StartWorkflowOptions, ScheduleContext, Schedule, OtelPluginOptions, InputParameters, InferInputParameters, Duration };