@voyantjs/workflow-runs 0.41.1 → 0.41.2

package/README.md

@@ -72,3 +72,51 @@ mountWorkflowRunsAdminRoutes(hono, {
 ```
 
 For self-hosted workflow services, keep runner registration close to the code that mounts the workflow service. The registry should dispatch to your external workflow server instead of importing worker-only runtime code into the admin API process. The resume path sends `ctx.resumeFromStep` plus `ctx.seedResults`; the self-host server starts a new run, pre-populates the journal with the seeded step outputs, and executes from the failed step onward.
+
+## Record `@voyantjs/workflows` executions
+
+Use `recordedWorkflow` as a drop-in replacement for `workflow(...)` when a
+workflow should appear in the workflow runs admin UI. The helper records start,
+success, and failure rows in `workflow_runs` without repeating recorder
+boilerplate in every workflow body.
+
+```ts
+import { recordedWorkflow } from "@voyantjs/workflow-runs"
+
+export const generatePdfWorkflow = recordedWorkflow({
+  id: "products.generate-pdf",
+  tags: ["products"],
+  async run(input, ctx) {
+    const renderer = ctx.services.resolve("products:pdf-renderer")
+    return renderer.generate(input)
+  },
+})
+```
+
+By default, `recordedWorkflow` resolves a Drizzle database from
+`ctx.services.resolve("db")`. It records the workflow id, trigger, run id as the
+correlation id, configured/runtime tags, input, result, parent run id for child
+workflow triggers, and errors. Recording is best-effort: database or serializer
+failures do not fail the workflow execution.
+
+You can customize the database service key or payload serializers:
+
+```ts
+export const syncCatalogWorkflow = recordedWorkflow(
+  {
+    id: "catalog.sync",
+    async run(input, ctx) {
+      return ctx.services.resolve("catalog:sync").run(input)
+    },
+  },
+  {
+    dbServiceName: "postgres",
+    input: ({ input }) => ({ catalogId: input.catalogId }),
+    result: ({ output }) => ({ changed: output.changed }),
+  },
+)
+```
+
+This helper only records observability data. Rerun and resume support still uses
+`WorkflowRunnerRegistry` registration so apps can choose which workflows are
+safe to dispatch from the admin UI.

package/dist/index.d.ts

@@ -21,4 +21,5 @@ export { mountWorkflowRunsAdminRoutes } from "./routes.js";
 export { type WorkflowIdempotency, type WorkflowRerunContext, type WorkflowResumeContext, type WorkflowRunner, WorkflowRunnerRegistry, } from "./runner.js";
 export { type NewWorkflowRun, type NewWorkflowRunStep, type WorkflowRun, type WorkflowRunErrorPayload, type WorkflowRunStep, workflowRunStatusEnum, workflowRunStepStatusEnum, workflowRunSteps, workflowRuns, } from "./schema.js";
 export { type ListWorkflowRunsQuery, type ListWorkflowRunsResult, workflowRunsService, } from "./service.js";
+export { type RecordedWorkflowOptions, type RecordedWorkflowResultContext, type RecordedWorkflowRunContext, recordedWorkflow, } from "./workflows.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,KAAK,qBAAqB,EAC1B,gBAAgB,EAChB,KAAK,mBAAmB,GACzB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAA;AAC1D,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,sBAAsB,GACvB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,uBAAuB,EAC5B,KAAK,eAAe,EACpB,qBAAqB,EACrB,yBAAyB,EACzB,gBAAgB,EAChB,YAAY,GACb,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,mBAAmB,GACpB,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,KAAK,qBAAqB,EAC1B,gBAAgB,EAChB,KAAK,mBAAmB,GACzB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAA;AAC1D,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,sBAAsB,GACvB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,uBAAuB,EAC5B,KAAK,eAAe,EACpB,qBAAqB,EACrB,yBAAyB,EACzB,gBAAgB,EAChB,YAAY,GACb,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,mBAAmB,GACpB,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,0BAA0B,EAC/B,gBAAgB,GACjB,MAAM,gBAAgB,CAAA"}

package/dist/index.js

@@ -21,3 +21,4 @@ export { mountWorkflowRunsAdminRoutes } from "./routes.js";
 export { WorkflowRunnerRegistry, } from "./runner.js";
 export { workflowRunStatusEnum, workflowRunStepStatusEnum, workflowRunSteps, workflowRuns, } from "./schema.js";
 export { workflowRunsService, } from "./service.js";
+export { recordedWorkflow, } from "./workflows.js";

package/dist/recorder.d.ts

@@ -71,5 +71,7 @@ export interface WorkflowRunRecorder {
  * workflow keeps running. The whole point of this layer is
  * observability, not durability.
  */
-export declare function beginWorkflowRun(db: PostgresJsDatabase, input: BeginWorkflowRunInput): Promise<WorkflowRunRecorder>;
+export declare function beginWorkflowRun(db: PostgresJsDatabase, input: BeginWorkflowRunInput, options?: {
+    reuseRunningRun?: boolean;
+}): Promise<WorkflowRunRecorder>;
 //# sourceMappingURL=recorder.d.ts.map

package/dist/recorder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../src/recorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAUjE,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IACtC,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAA;IAC3D,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACrD;;;;;OAKG;IACH,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAChE,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACjE,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACvC;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,mBAAmB,CAAC,CAwH9B"}
+{"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../src/recorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAUjE,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IACtC,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAA;IAC3D,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACrD;;;;;OAKG;IACH,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAChE,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACjE,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACvC;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,qBAAqB,EAC5B,OAAO,GAAE;IAAE,eAAe,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1C,OAAO,CAAC,mBAAmB,CAAC,CAgC9B"}

package/dist/recorder.js

@@ -24,7 +24,7 @@
  * persistence failures rather than rethrowing, so observability
  * outages never break the underlying business operation.
  */
-import { eq } from "drizzle-orm";
+import { and, desc, eq } from "drizzle-orm";
 import { workflowRunSteps, workflowRuns, } from "./schema.js";
 /**
  * Start a run and return a recorder bound to its id. The row is
@@ -35,7 +35,12 @@ import { workflowRunSteps, workflowRuns, } from "./schema.js";
  * workflow keeps running. The whole point of this layer is
  * observability, not durability.
  */
-export async function beginWorkflowRun(db, input) {
+export async function beginWorkflowRun(db, input, options = {}) {
+    if (options.reuseRunningRun && input.correlationId) {
+        const existingRunId = await findRunningWorkflowRun(db, input);
+        if (existingRunId)
+            return workflowRunRecorder(db, existingRunId);
+    }
     const insert = {
         workflowName: input.workflowName,
         trigger: input.trigger ?? "manual",
@@ -57,6 +62,26 @@ export async function beginWorkflowRun(db, input) {
     }
     if (!runId)
         return noopRecorder();
+    return workflowRunRecorder(db, runId);
+}
+async function findRunningWorkflowRun(db, input) {
+    const correlationId = input.correlationId;
+    if (!correlationId)
+        return null;
+    try {
+        const [row] = await db
+            .select({ id: workflowRuns.id })
+            .from(workflowRuns)
+            .where(and(eq(workflowRuns.workflowName, input.workflowName), eq(workflowRuns.correlationId, correlationId), eq(workflowRuns.status, "running")))
+            .orderBy(desc(workflowRuns.startedAt))
+            .limit(1);
+        return row?.id ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function workflowRunRecorder(db, runId) {
     const stepStarts = new Map();
     let nextSequence = 1;
     return {

package/dist/workflows.d.ts

@@ -0,0 +1,38 @@
+import { type WorkflowConfig, type WorkflowContext, type WorkflowDefinition } from "@voyantjs/workflows";
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+type MaybePromise<T> = T | Promise<T>;
+type JsonRecord = Record<string, unknown>;
+export interface RecordedWorkflowRunContext<TInput> {
+    input: TInput;
+    ctx: WorkflowContext<TInput>;
+    config: WorkflowConfig<TInput, unknown>;
+}
+export interface RecordedWorkflowResultContext<TInput, TOutput> extends RecordedWorkflowRunContext<TInput> {
+    output: TOutput;
+}
+export interface RecordedWorkflowOptions<TInput, TOutput> {
+    /**
+     * Database used by the workflow-runs recorder. When omitted, the helper
+     * resolves `ctx.services.resolve(dbServiceName)`.
+     */
+    db?: PostgresJsDatabase | ((args: RecordedWorkflowRunContext<TInput>) => MaybePromise<PostgresJsDatabase | null | undefined>);
+    /** Service-container key used when `db` is omitted. Defaults to `db`. */
+    dbServiceName?: string;
+    workflowName?: string | ((args: RecordedWorkflowRunContext<TInput>) => MaybePromise<string>);
+    trigger?: string | ((args: RecordedWorkflowRunContext<TInput>) => MaybePromise<string | null | undefined>);
+    correlationId?: string | ((args: RecordedWorkflowRunContext<TInput>) => MaybePromise<string | null | undefined>);
+    tags?: ReadonlyArray<string> | ((args: RecordedWorkflowRunContext<TInput>) => MaybePromise<ReadonlyArray<string> | null | undefined>);
+    input?: false | ((args: RecordedWorkflowRunContext<TInput>) => MaybePromise<JsonRecord | null | undefined>);
+    result?: false | ((args: RecordedWorkflowResultContext<TInput, TOutput>) => MaybePromise<JsonRecord | null | undefined>);
+    parentRunId?: string | ((args: RecordedWorkflowRunContext<TInput>) => MaybePromise<string | null | undefined>);
+    triggeredByUserId?: string | ((args: RecordedWorkflowRunContext<TInput>) => MaybePromise<string | null | undefined>);
+    resumeFromStep?: string | ((args: RecordedWorkflowRunContext<TInput>) => MaybePromise<string | null | undefined>);
+}
+/**
+ * Declare a `@voyantjs/workflows` workflow whose run lifecycle is mirrored into
+ * the `workflow_runs` observability tables. Recording is best-effort: database,
+ * metadata, or serialization failures never change workflow execution behavior.
+ */
+export declare function recordedWorkflow<TInput = unknown, TOutput = unknown>(config: WorkflowConfig<TInput, TOutput>, options?: RecordedWorkflowOptions<TInput, TOutput>): WorkflowDefinition<TInput, TOutput>;
+export {};
+//# sourceMappingURL=workflows.d.ts.map

package/dist/workflows.d.ts.map

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

package/dist/workflows.js

@@ -0,0 +1,154 @@
+import { workflow, } from "@voyantjs/workflows";
+import { beginWorkflowRun, } from "./recorder.js";
+const WAITPOINT_PENDING = Symbol.for("voyant.workflows.waitpointPending");
+/**
+ * Declare a `@voyantjs/workflows` workflow whose run lifecycle is mirrored into
+ * the `workflow_runs` observability tables. Recording is best-effort: database,
+ * metadata, or serialization failures never change workflow execution behavior.
+ */
+export function recordedWorkflow(config, options = {}) {
+    return workflow({
+        ...config,
+        async run(input, ctx) {
+            const recorder = await startRecording(config, options, input, ctx);
+            try {
+                const output = await config.run(input, ctx);
+                await completeRecording(recorder, options, config, input, ctx, output);
+                return output;
+            }
+            catch (err) {
+                if (isWaitpointPending(err))
+                    throw err;
+                await failRecording(recorder, err);
+                throw err;
+            }
+        },
+    });
+}
+async function startRecording(config, options, input, ctx) {
+    try {
+        const args = {
+            input,
+            ctx,
+            config: config,
+        };
+        const db = await resolveDb(options, args);
+        if (!db)
+            return null;
+        const beginInput = {
+            workflowName: await resolveValue(options.workflowName, args, config.id),
+            trigger: await resolveValue(options.trigger, args, triggerName(ctx)),
+            correlationId: await resolveValue(options.correlationId, args, ctx.run.id),
+            tags: [
+                ...dedupe([...(config.tags ?? []), ...ctx.run.tags, ...(await resolveTags(options, args))]),
+            ],
+            input: await resolveInput(options, args),
+            parentRunId: await resolveValue(options.parentRunId, args, parentRunId(ctx)),
+            triggeredByUserId: await resolveValue(options.triggeredByUserId, args, triggeredByUserId(ctx)),
+            resumeFromStep: await resolveValue(options.resumeFromStep, args, null),
+        };
+        return await beginWorkflowRun(db, beginInput, { reuseRunningRun: ctx.invocationCount > 1 });
+    }
+    catch {
+        return null;
+    }
+}
+async function completeRecording(recorder, options, config, input, ctx, output) {
+    if (!recorder)
+        return;
+    try {
+        await recorder.complete(await resolveResult(options, { input, ctx, config, output }));
+    }
+    catch {
+        // best-effort observability only
+    }
+}
+async function failRecording(recorder, err) {
+    if (!recorder)
+        return;
+    try {
+        await recorder.fail(err);
+    }
+    catch {
+        // best-effort observability only
+    }
+}
+async function resolveDb(options, args) {
+    if (typeof options.db === "function")
+        return options.db(args);
+    if (options.db)
+        return options.db;
+    const serviceName = options.dbServiceName ?? "db";
+    return args.ctx.services.resolve(serviceName);
+}
+async function resolveTags(options, args) {
+    if (Array.isArray(options.tags))
+        return options.tags;
+    if (typeof options.tags === "function")
+        return (await options.tags(args)) ?? [];
+    return [];
+}
+async function resolveInput(options, args) {
+    if (options.input === false)
+        return null;
+    if (typeof options.input === "function")
+        return (await options.input(args)) ?? null;
+    return toJsonRecord(args.input);
+}
+async function resolveResult(options, args) {
+    try {
+        if (options.result === false)
+            return null;
+        if (typeof options.result === "function")
+            return (await options.result(args)) ?? null;
+        return toJsonRecord(args.output);
+    }
+    catch {
+        return null;
+    }
+}
+async function resolveValue(value, args, fallback) {
+    if (typeof value === "function") {
+        return ((await value(args)) ?? fallback);
+    }
+    return (value ?? fallback);
+}
+function triggerName(ctx) {
+    const trigger = ctx.run.triggeredBy;
+    if (trigger.kind === "event")
+        return trigger.eventType;
+    if (trigger.kind === "schedule")
+        return `schedule:${trigger.scheduleId}`;
+    if (trigger.kind === "parent")
+        return "parent";
+    return "api";
+}
+function parentRunId(ctx) {
+    const trigger = ctx.run.triggeredBy;
+    return trigger.kind === "parent" ? trigger.parentRunId : null;
+}
+function triggeredByUserId(ctx) {
+    const trigger = ctx.run.triggeredBy;
+    return trigger.kind === "api" ? (trigger.actor ?? null) : null;
+}
+function toJsonRecord(value) {
+    if (value === undefined || value === null)
+        return null;
+    if (isPlainRecord(value))
+        return value;
+    return { value };
+}
+function isPlainRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function isWaitpointPending(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        err[WAITPOINT_PENDING] === true);
+}
+function dedupe(values) {
+    return [...new Set(values)];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyantjs/workflow-runs",
-  "version": "0.41.1",
+  "version": "0.41.2",
   "description": "Workflow run recording, admin routes, and rerun/resume dispatch primitives for Voyant operator apps.",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,20 +29,27 @@
       "types": "./dist/recorder.d.ts",
       "import": "./dist/recorder.js",
       "default": "./dist/recorder.js"
+    },
+    "./workflows": {
+      "types": "./dist/workflows.d.ts",
+      "import": "./dist/workflows.js",
+      "default": "./dist/workflows.js"
     }
   },
   "dependencies": {
     "drizzle-orm": "^0.45.2",
     "hono": "^4.12.10",
     "zod": "^4.3.6",
-    "@voyantjs/core": "0.41.1",
-    "@voyantjs/db": "0.41.1",
-    "@voyantjs/hono": "0.41.1"
+    "@voyantjs/core": "0.41.2",
+    "@voyantjs/db": "0.41.2",
+    "@voyantjs/hono": "0.41.2",
+    "@voyantjs/workflows": "0.41.2"
   },
   "devDependencies": {
     "typescript": "^6.0.2",
     "vitest": "^4.1.2",
-    "@voyantjs/voyant-typescript-config": "0.1.0"
+    "@voyantjs/voyant-typescript-config": "0.1.0",
+    "@voyantjs/workflows-orchestrator": "0.41.2"
   },
   "files": [
     "dist"