@upstash/workflow 0.2.23 → 0.3.0-rc1

package/express.js

@@ -31,20 +31,22 @@ var WORKFLOW_ID_HEADER = "Upstash-Workflow-RunId";
 var WORKFLOW_INIT_HEADER = "Upstash-Workflow-Init";
 var WORKFLOW_URL_HEADER = "Upstash-Workflow-Url";
 var WORKFLOW_FAILURE_HEADER = "Upstash-Workflow-Is-Failure";
+var WORKFLOW_FAILURE_CALLBACK_HEADER = "Upstash-Workflow-Failure-Callback";
 var WORKFLOW_FEATURE_HEADER = "Upstash-Feature-Set";
 var WORKFLOW_INVOKE_COUNT_HEADER = "Upstash-Workflow-Invoke-Count";
 var WORKFLOW_LABEL_HEADER = "Upstash-Label";
+var WORKFLOW_UNKOWN_SDK_VERSION_HEADER = "Upstash-Workflow-Unknown-Sdk";
+var WORKFLOW_UNKOWN_SDK_TRIGGER_HEADER = "upstash-workflow-trigger-by-sdk";
 var WORKFLOW_PROTOCOL_VERSION = "1";
 var WORKFLOW_PROTOCOL_VERSION_HEADER = "Upstash-Workflow-Sdk-Version";
 var DEFAULT_CONTENT_TYPE = "application/json";
 var NO_CONCURRENCY = 1;
 var DEFAULT_RETRIES = 3;
-var VERSION = "v0.2.22";
+var VERSION = "v1.0.0";
 var SDK_TELEMETRY = `@upstash/workflow@${VERSION}`;
 var TELEMETRY_HEADER_SDK = "Upstash-Telemetry-Sdk";
 var TELEMETRY_HEADER_FRAMEWORK = "Upstash-Telemetry-Framework";
 var TELEMETRY_HEADER_RUNTIME = "Upstash-Telemetry-Runtime";
-var TELEMETRY_HEADER_AGENT = "Upstash-Telemetry-Agent";
 
 // src/client/utils.ts
 var import_qstash2 = require("@upstash/qstash");
@@ -58,26 +60,36 @@ var WorkflowError = class extends import_qstash.QstashError {
   }
 };
 var WorkflowAbort = class extends Error {
-  stepInfo;
   stepName;
+  stepInfo;
   /**
-   * whether workflow is to be canceled on abort
-   */
-  cancelWorkflow;
-  /**
-   *
    * @param stepName name of the aborting step
    * @param stepInfo step information
-   * @param cancelWorkflow
    */
-  constructor(stepName, stepInfo, cancelWorkflow = false) {
+  constructor(stepName, stepInfo) {
     super(
       `This is an Upstash Workflow error thrown after a step executes. It is expected to be raised. Make sure that you await for each step. Also, if you are using try/catch blocks, you should not wrap context.run/sleep/sleepUntil/call methods with try/catch. Aborting workflow after executing step '${stepName}'.`
     );
     this.name = "WorkflowAbort";
     this.stepName = stepName;
     this.stepInfo = stepInfo;
-    this.cancelWorkflow = cancelWorkflow;
+  }
+};
+var WorkflowAuthError = class extends WorkflowAbort {
+  /**
+   * @param stepName name of the step found during authorization
+   */
+  constructor(stepName) {
+    super(stepName);
+    this.name = "WorkflowAuthError";
+    this.message = `This is an Upstash Workflow error thrown during authorization check. Found step '${stepName}' during dry-run.`;
+  }
+};
+var WorkflowCancelAbort = class extends WorkflowAbort {
+  constructor() {
+    super("cancel");
+    this.name = "WorkflowCancelAbort";
+    this.message = "Workflow has been canceled by user via context.cancel().";
   }
 };
 var WorkflowNonRetryableError = class extends WorkflowAbort {
@@ -85,22 +97,22 @@ var WorkflowNonRetryableError = class extends WorkflowAbort {
    * @param message error message to be displayed
    */
   constructor(message) {
-    super("fail", void 0, false);
+    super("non-retryable-error");
     this.name = "WorkflowNonRetryableError";
-    if (message) this.message = message;
+    this.message = message ?? "Workflow failed with non-retryable error.";
   }
 };
 var WorkflowRetryAfterError = class extends WorkflowAbort {
   retryAfter;
   /**
-   * @param retryAfter time in seconds after which the workflow should be retried
    * @param message error message to be displayed
+   * @param retryAfter time in seconds after which the workflow should be retried
    */
   constructor(message, retryAfter) {
-    super("retry", void 0, false);
+    super("retry-after-error");
     this.name = "WorkflowRetryAfterError";
+    this.message = message;
     this.retryAfter = retryAfter;
-    if (message) this.message = message;
   }
 };
 var formatWorkflowError = (error) => {
@@ -152,15 +164,21 @@ var makeCancelRequest = async (requester, workflowRunId) => {
   });
   return true;
 };
-var getSteps = async (requester, workflowRunId, messageId, debug) => {
+var getSteps = async (requester, workflowRunId, messageId, dispatchDebug) => {
   try {
     const steps = await requester.request({
       path: ["v2", "workflows", "runs", workflowRunId],
       parseResponseAsJson: true
     });
+    if (steps.length === 1) {
+      return {
+        steps,
+        workflowRunEnded: false
+      };
+    }
     if (!messageId) {
-      await debug?.log("INFO", "ENDPOINT_START", {
-        message: `Pulled ${steps.length} steps from QStashand returned them without filtering with messageId.`
+      await dispatchDebug?.("onInfo", {
+        info: `Pulled ${steps.length} steps from QStashand returned them without filtering with messageId.`
       });
       return { steps, workflowRunEnded: false };
     } else {
@@ -169,16 +187,15 @@ var getSteps = async (requester, workflowRunId, messageId, debug) => {
         return { steps: [], workflowRunEnded: false };
       }
       const filteredSteps = steps.slice(0, index + 1);
-      await debug?.log("INFO", "ENDPOINT_START", {
-        message: `Pulled ${steps.length} steps from QStash and filtered them to ${filteredSteps.length} using messageId.`
+      await dispatchDebug?.("onInfo", {
+        info: `Pulled ${steps.length} steps from QStash and filtered them to ${filteredSteps.length} using messageId.`
       });
       return { steps: filteredSteps, workflowRunEnded: false };
     }
   } catch (error) {
     if (isInstanceOf(error, import_qstash2.QstashError) && error.status === 404) {
-      await debug?.log("WARN", "ENDPOINT_START", {
-        message: "Couldn't fetch workflow run steps. This can happen if the workflow run succesfully ends before some callback is executed.",
-        error
+      await dispatchDebug?.("onWarning", {
+        warning: "Couldn't fetch workflow run steps. This can happen if the workflow run succesfully ends before some callback is executed."
       });
       return { steps: void 0, workflowRunEnded: true };
     } else {
@@ -248,6 +265,15 @@ function getQStashUrl(qstashClient) {
 function getEventId() {
   return `evt_${nanoid(15)}`;
 }
+function stringifyBody(body) {
+  if (body === void 0) {
+    return void 0;
+  }
+  if (typeof body === "string") {
+    return body;
+  }
+  return JSON.stringify(body);
+}
 
 // node_modules/neverthrow/dist/index.es.js
 var defaultErrorConfig = {
@@ -589,9 +615,9 @@ var Ok = class {
   }
   safeUnwrap() {
     const value = this.value;
-    return function* () {
+    return (function* () {
       return value;
-    }();
+    })();
   }
   _unsafeUnwrap(_) {
     return this.value;
@@ -650,10 +676,10 @@ var Err = class {
   }
   safeUnwrap() {
     const error = this.error;
-    return function* () {
+    return (function* () {
       yield err(error);
       throw new Error("Do not use this generator out of `safeTry`");
-    }();
+    })();
   }
   _unsafeUnwrap(config) {
     throw createNeverThrowError("Called `_unsafeUnwrap` on an Err", this, config);
@@ -691,23 +717,26 @@ var triggerFirstInvocation = async (params) => {
       invokeCount,
       delay,
       notBefore,
-      keepTriggerConfig
+      failureUrl,
+      retries,
+      retryDelay,
+      flowControl,
+      unknownSdk
     }) => {
       const { headers } = getHeaders({
         initHeaderValue: "true",
         workflowConfig: {
           workflowRunId: workflowContext.workflowRunId,
           workflowUrl: workflowContext.url,
-          failureUrl: workflowContext.failureUrl,
-          retries: workflowContext.retries,
-          retryDelay: workflowContext.retryDelay,
+          failureUrl,
+          retries,
+          retryDelay,
           telemetry: telemetry2,
-          flowControl: workflowContext.flowControl,
+          flowControl,
           useJSONContent: useJSONContent ?? false
         },
         invokeCount: invokeCount ?? 0,
-        userHeaders: workflowContext.headers,
-        keepTriggerConfig
+        userHeaders: workflowContext.headers
       });
       if (workflowContext.headers.get("content-type")) {
         headers["content-type"] = workflowContext.headers.get("content-type");
@@ -715,6 +744,9 @@ var triggerFirstInvocation = async (params) => {
       if (useJSONContent) {
         headers["content-type"] = "application/json";
       }
+      if (unknownSdk) {
+        headers[WORKFLOW_UNKOWN_SDK_TRIGGER_HEADER] = "true";
+      }
       if (workflowContext.label) {
         headers[WORKFLOW_LABEL_HEADER] = workflowContext.label;
       }
@@ -735,21 +767,15 @@ var triggerFirstInvocation = async (params) => {
     for (let i = 0; i < results.length; i++) {
       const result = results[i];
       const invocationParams = firstInvocationParams[i];
+      invocationParams.middlewareManager?.assignContext(invocationParams.workflowContext);
       if (result.deduplicated) {
-        await invocationParams.debug?.log("WARN", "SUBMIT_FIRST_INVOCATION", {
-          message: `Workflow run ${invocationParams.workflowContext.workflowRunId} already exists. A new one isn't created.`,
-          headers: invocationBatch[i].headers,
-          requestPayload: invocationParams.workflowContext.requestPayload,
-          url: invocationParams.workflowContext.url,
-          messageId: result.messageId
+        await invocationParams.middlewareManager?.dispatchDebug("onWarning", {
+          warning: `Workflow run ${invocationParams.workflowContext.workflowRunId} already exists. A new one isn't created.`
         });
         invocationStatuses.push("workflow-run-already-exists");
       } else {
-        await invocationParams.debug?.log("SUBMIT", "SUBMIT_FIRST_INVOCATION", {
-          headers: invocationBatch[i].headers,
-          requestPayload: invocationParams.workflowContext.requestPayload,
-          url: invocationParams.workflowContext.url,
-          messageId: result.messageId
+        await invocationParams.middlewareManager?.dispatchDebug("onInfo", {
+          info: `Workflow run started successfully with URL ${invocationParams.workflowContext.url}.`
         });
         invocationStatuses.push("success");
       }
@@ -771,7 +797,7 @@ var triggerRouteFunction = async ({
   onCleanup,
   onStep,
   onCancel,
-  debug
+  middlewareManager
 }) => {
   try {
     const result = await onStep();
@@ -780,27 +806,25 @@ var triggerRouteFunction = async ({
   } catch (error) {
     const error_ = error;
     if (isInstanceOf(error, import_qstash3.QstashError) && error.status === 400) {
-      await debug?.log("WARN", "RESPONSE_WORKFLOW", {
-        message: `tried to append to a cancelled workflow. exiting without publishing.`,
-        name: error.name,
-        errorMessage: error.message
+      await middlewareManager?.dispatchDebug("onWarning", {
+        warning: `Tried to append to a cancelled workflow. Exiting without publishing. Error: ${error.message}`
       });
       return ok("workflow-was-finished");
     } else if (isInstanceOf(error_, WorkflowNonRetryableError) || isInstanceOf(error_, WorkflowRetryAfterError)) {
       return ok(error_);
-    } else if (!isInstanceOf(error_, WorkflowAbort)) {
-      return err(error_);
-    } else if (error_.cancelWorkflow) {
+    } else if (isInstanceOf(error_, WorkflowCancelAbort)) {
       await onCancel();
       return ok("workflow-finished");
-    } else {
+    } else if (isInstanceOf(error_, WorkflowAbort)) {
       return ok("step-finished");
+    } else {
+      return err(error_);
     }
   }
 };
-var triggerWorkflowDelete = async (workflowContext, result, debug, cancel = false) => {
-  await debug?.log("SUBMIT", "SUBMIT_CLEANUP", {
-    deletedWorkflowRunId: workflowContext.workflowRunId
+var triggerWorkflowDelete = async (workflowContext, result, cancel = false, dispatchDebug) => {
+  await dispatchDebug?.("onInfo", {
+    info: `Deleting workflow run ${workflowContext.workflowRunId} from QStash` + (cancel ? " with cancel=true." : ".")
   });
   await workflowContext.qstashClient.http.request({
     path: ["v2", "workflows", "runs", `${workflowContext.workflowRunId}?cancel=${cancel}`],
@@ -808,18 +832,16 @@ var triggerWorkflowDelete = async (workflowContext, result, debug, cancel = fals
     parseResponseAsJson: false,
     body: JSON.stringify(result)
   });
-  await debug?.log(
-    "SUBMIT",
-    "SUBMIT_CLEANUP",
-    `workflow run ${workflowContext.workflowRunId} deleted.`
-  );
+  await dispatchDebug?.("onInfo", {
+    info: `Workflow run ${workflowContext.workflowRunId} deleted from QStash successfully.`
+  });
 };
 var recreateUserHeaders = (headers) => {
   const filteredHeaders = new Headers();
   const pairs = headers.entries();
   for (const [header, value] of pairs) {
     const headerLowerCase = header.toLowerCase();
-    const isUserHeader = !headerLowerCase.startsWith("upstash-workflow-") && // https://vercel.com/docs/edge-network/headers/request-headers#x-vercel-id
+    const isUserHeader = headerLowerCase !== "upstash-region" && !headerLowerCase.startsWith("upstash-workflow-") && // https://vercel.com/docs/edge-network/headers/request-headers#x-vercel-id
     !headerLowerCase.startsWith("x-vercel-") && !headerLowerCase.startsWith("x-forwarded-") && // https://blog.cloudflare.com/preventing-request-loops-using-cdn-loop/
     headerLowerCase !== "cf-connecting-ip" && headerLowerCase !== "cdn-loop" && headerLowerCase !== "cf-ew-via" && headerLowerCase !== "cf-ray" && // For Render https://render.com
     headerLowerCase !== "render-proxy-ttl" || headerLowerCase === WORKFLOW_LABEL_HEADER.toLocaleLowerCase();
@@ -834,12 +856,8 @@ var handleThirdPartyCallResult = async ({
   requestPayload,
   client,
   workflowUrl,
-  failureUrl,
-  retries,
-  retryDelay,
   telemetry: telemetry2,
-  flowControl,
-  debug
+  middlewareManager
 }) => {
   try {
     if (request.headers.get("Upstash-Workflow-Callback")) {
@@ -856,7 +874,7 @@ var handleThirdPartyCallResult = async ({
           client.http,
           workflowRunId2,
           messageId,
-          debug
+          middlewareManager?.dispatchDebug.bind(middlewareManager)
         );
         if (workflowRunEnded) {
           return ok("workflow-ended");
@@ -870,9 +888,8 @@ var handleThirdPartyCallResult = async ({
       }
       const callbackMessage = JSON.parse(callbackPayload);
       if (!(callbackMessage.status >= 200 && callbackMessage.status < 300) && callbackMessage.maxRetries && callbackMessage.retried !== callbackMessage.maxRetries) {
-        await debug?.log("WARN", "SUBMIT_THIRD_PARTY_RESULT", {
-          status: callbackMessage.status,
-          body: atob(callbackMessage.body ?? "")
+        await middlewareManager?.dispatchDebug("onWarning", {
+          warning: `Third party call returned status ${callbackMessage.status}. Retrying (${callbackMessage.retried} out of ${callbackMessage.maxRetries}).`
         });
         console.warn(
           `Workflow Warning: "context.call" failed with status ${callbackMessage.status} and will retry (retried ${callbackMessage.retried ?? 0} out of ${callbackMessage.maxRetries} times). Error Message:
@@ -905,11 +922,7 @@ ${atob(callbackMessage.body ?? "")}`
         workflowConfig: {
           workflowRunId,
           workflowUrl,
-          failureUrl,
-          retries,
-          retryDelay,
-          telemetry: telemetry2,
-          flowControl
+          telemetry: telemetry2
         },
         userHeaders,
         invokeCount: Number(invokeCount)
@@ -926,19 +939,17 @@ ${atob(callbackMessage.body ?? "")}`
         out: JSON.stringify(callResponse),
         concurrent: Number(concurrentString)
       };
-      await debug?.log("SUBMIT", "SUBMIT_THIRD_PARTY_RESULT", {
-        step: callResultStep,
-        headers: requestHeaders,
-        url: workflowUrl
+      await middlewareManager?.dispatchDebug("onInfo", {
+        info: `Submitting third party call result, step ${stepName} (${stepIdString}).`
       });
-      const result = await client.publishJSON({
+      await client.publishJSON({
         headers: requestHeaders,
         method: "POST",
         body: callResultStep,
         url: workflowUrl
       });
-      await debug?.log("SUBMIT", "SUBMIT_THIRD_PARTY_RESULT", {
-        messageId: result.messageId
+      await middlewareManager?.dispatchDebug("onInfo", {
+        info: `Third party call result submitted successfully, step ${stepName} (${stepIdString}).`
       });
       return ok("is-call-return");
     } else {
@@ -996,8 +1007,8 @@ var BaseLazyStep = class _BaseLazyStep {
       );
     }
     if (typeof stepName !== "string") {
-      console.warn(
-        "Workflow Warning: A workflow step name must be a string. In a future release, this will throw an error."
+      throw new WorkflowError(
+        `A workflow step name must be a string. Received "${stepName}" (${typeof stepName}).`
       );
     }
     this.stepName = stepName;
@@ -1059,12 +1070,8 @@ var BaseLazyStep = class _BaseLazyStep {
       workflowConfig: {
         workflowRunId: context.workflowRunId,
         workflowUrl: context.url,
-        failureUrl: context.failureUrl,
-        retries: DEFAULT_RETRIES === context.retries ? void 0 : context.retries,
-        retryDelay: context.retryDelay,
         useJSONContent: false,
-        telemetry: telemetry2,
-        flowControl: context.flowControl
+        telemetry: telemetry2
       },
       userHeaders: context.headers,
       invokeCount,
@@ -1080,9 +1087,6 @@ var BaseLazyStep = class _BaseLazyStep {
         body,
         headers,
         method: "POST",
-        retries: DEFAULT_RETRIES === context.retries ? void 0 : context.retries,
-        retryDelay: context.retryDelay,
-        flowControl: context.flowControl,
         url: context.url
       }
     ]);
@@ -1153,9 +1157,6 @@ var LazySleepStep = class extends BaseLazyStep {
         headers,
         method: "POST",
         url: context.url,
-        retries: DEFAULT_RETRIES === context.retries ? void 0 : context.retries,
-        retryDelay: context.retryDelay,
-        flowControl: context.flowControl,
         delay: isParallel ? void 0 : this.sleep
       }
     ]);
@@ -1198,9 +1199,6 @@ var LazySleepUntilStep = class extends BaseLazyStep {
         headers,
         method: "POST",
         url: context.url,
-        retries: DEFAULT_RETRIES === context.retries ? void 0 : context.retries,
-        retryDelay: context.retryDelay,
-        flowControl: context.flowControl,
         notBefore: isParallel ? void 0 : this.sleepUntil
       }
     ]);
@@ -1215,20 +1213,18 @@ var LazyCallStep = class _LazyCallStep extends BaseLazyStep {
   retryDelay;
   timeout;
   flowControl;
-  stringifyBody;
   stepType = "Call";
   allowUndefinedOut = false;
-  constructor(context, stepName, url, method, body, headers, retries, retryDelay, timeout, flowControl, stringifyBody) {
-    super(context, stepName);
-    this.url = url;
-    this.method = method;
-    this.body = body;
-    this.headers = headers;
-    this.retries = retries;
-    this.retryDelay = retryDelay;
-    this.timeout = timeout;
-    this.flowControl = flowControl;
-    this.stringifyBody = stringifyBody;
+  constructor(params) {
+    super(params.context, params.stepName);
+    this.url = params.url;
+    this.method = params.method ?? "GET";
+    this.body = params.body;
+    this.headers = params.headers ?? {};
+    this.retries = params.retries ?? 0;
+    this.retryDelay = params.retryDelay;
+    this.timeout = params.timeout;
+    this.flowControl = params.flowControl;
   }
   getPlanStep(concurrent, targetStep) {
     return {
@@ -1325,7 +1321,7 @@ var LazyCallStep = class _LazyCallStep extends BaseLazyStep {
         "Upstash-Callback-Workflow-CallType": "fromCallback",
         "Upstash-Callback-Workflow-Init": "false",
         "Upstash-Callback-Workflow-Url": context.url,
-        "Upstash-Callback-Feature-Set": "LazyFetch,InitialBody,WF_DetectTrigger",
+        "Upstash-Callback-Feature-Set": "LazyFetch,InitialBody,WF_DetectTrigger,WF_TriggerOnConfig",
         "Upstash-Callback-Forward-Upstash-Workflow-Callback": "true",
         "Upstash-Callback-Forward-Upstash-Workflow-StepId": step.stepId.toString(),
         "Upstash-Callback-Forward-Upstash-Workflow-StepName": this.stepName,
@@ -1338,22 +1334,10 @@ var LazyCallStep = class _LazyCallStep extends BaseLazyStep {
     };
   }
   async submitStep({ context, headers }) {
-    let callBody;
-    if (this.stringifyBody) {
-      callBody = JSON.stringify(this.body);
-    } else {
-      if (typeof this.body === "string") {
-        callBody = this.body;
-      } else {
-        throw new WorkflowError(
-          "When stringifyBody is false, body must be a string. Please check the body type of your call step."
-        );
-      }
-    }
     return await context.qstashClient.batch([
       {
         headers,
-        body: callBody,
+        body: this.body,
         method: this.method,
         url: this.url,
         retries: DEFAULT_RETRIES === this.retries ? void 0 : this.retries,
@@ -1473,28 +1457,10 @@ var LazyInvokeStep = class extends BaseLazyStep {
    * workflow id of the invoked workflow
    */
   workflowId;
-  constructor(context, stepName, {
-    workflow,
-    body,
-    headers = {},
-    workflowRunId,
-    retries,
-    retryDelay,
-    flowControl,
-    stringifyBody = true
-  }) {
+  constructor(context, stepName, params) {
     super(context, stepName);
-    this.params = {
-      workflow,
-      body,
-      headers,
-      workflowRunId: getWorkflowRunId(workflowRunId),
-      retries,
-      retryDelay,
-      flowControl,
-      stringifyBody
-    };
-    const { workflowId } = workflow;
+    this.params = params;
+    const { workflowId } = params.workflow;
     if (!workflowId) {
       throw new WorkflowError("You can only invoke workflow which has a workflowId");
     }
@@ -1534,11 +1500,7 @@ var LazyInvokeStep = class extends BaseLazyStep {
       workflowConfig: {
         workflowRunId: context.workflowRunId,
         workflowUrl: context.url,
-        failureUrl: context.failureUrl,
-        retries: context.retries,
-        retryDelay: context.retryDelay,
         telemetry: telemetry2,
-        flowControl: context.flowControl,
         useJSONContent: false
       },
       userHeaders: context.headers,
@@ -1548,20 +1510,8 @@ var LazyInvokeStep = class extends BaseLazyStep {
       invokerHeaders[key] = value;
     });
     invokerHeaders["Upstash-Workflow-Runid"] = context.workflowRunId;
-    let invokeBody;
-    if (this.params.stringifyBody) {
-      invokeBody = JSON.stringify(this.params.body);
-    } else {
-      if (typeof this.params.body === "string") {
-        invokeBody = this.params.body;
-      } else {
-        throw new WorkflowError(
-          "When stringifyBody is false, body must be a string. Please check the body type of your invoke step."
-        );
-      }
-    }
     const request = {
-      body: invokeBody,
+      body: stringifyBody(this.params.body),
       headers: Object.fromEntries(
         Object.entries(invokerHeaders).map((pairs) => [pairs[0], [pairs[1]]])
       ),
@@ -1572,34 +1522,19 @@ var LazyInvokeStep = class extends BaseLazyStep {
     return JSON.stringify(request);
   }
   getHeaders({ context, telemetry: telemetry2, invokeCount }) {
-    const {
-      workflow,
-      headers = {},
-      workflowRunId = getWorkflowRunId(),
-      retries,
-      retryDelay,
-      flowControl
-    } = this.params;
+    const { workflow, headers = {}, workflowRunId, retries, retryDelay, flowControl } = this.params;
     const newUrl = context.url.replace(/[^/]+$/, this.workflowId);
-    const {
-      retries: workflowRetries,
-      retryDelay: workflowRetryDelay,
-      failureFunction,
-      failureUrl,
-      useJSONContent,
-      flowControl: workflowFlowControl
-    } = workflow.options;
     const { headers: triggerHeaders, contentType } = getHeaders({
       initHeaderValue: "true",
       workflowConfig: {
-        workflowRunId,
+        workflowRunId: getWorkflowRunId(workflowRunId),
         workflowUrl: newUrl,
-        retries: retries ?? workflowRetries,
-        retryDelay: retryDelay ?? workflowRetryDelay,
+        retries,
+        retryDelay,
         telemetry: telemetry2,
-        failureUrl: failureFunction ? newUrl : failureUrl,
-        flowControl: flowControl ?? workflowFlowControl,
-        useJSONContent: useJSONContent ?? false
+        failureUrl: newUrl,
+        flowControl,
+        useJSONContent: workflow.useJSONContent ?? false
       },
       invokeCount: invokeCount + 1,
       userHeaders: new Headers(headers)
@@ -1701,20 +1636,6 @@ var LazyWaitForEventStep = class extends LazyWaitEventStep {
   }
 };
 
-// src/agents/constants.ts
-var AGENT_NAME_HEADER = "upstash-agent-name";
-var MANAGER_AGENT_PROMPT = `You are an agent orchestrating other AI Agents.
-
-These other agents have tools available to them.
-
-Given a prompt, utilize these agents to address requests.
-
-Don't always call all the agents provided to you at the same time. You can call one and use it's response to call another.
-
-Avoid calling the same agent twice in one turn. Instead, prefer to call it once but provide everything
-you need from that agent.
-`;
-
 // src/qstash/headers.ts
 var WorkflowHeaders = class {
   userHeaders;
@@ -1723,14 +1644,15 @@ var WorkflowHeaders = class {
   initHeaderValue;
   stepInfo;
   headers;
-  keepTriggerConfig;
+  /**
+   * @param params workflow header parameters
+   */
   constructor({
     userHeaders,
     workflowConfig,
     invokeCount,
     initHeaderValue,
-    stepInfo,
-    keepTriggerConfig
+    stepInfo
   }) {
     this.userHeaders = userHeaders;
     this.workflowConfig = workflowConfig;
@@ -1742,7 +1664,6 @@ var WorkflowHeaders = class {
       workflowHeaders: {},
       failureHeaders: {}
     };
-    this.keepTriggerConfig = keepTriggerConfig;
   }
   getHeaders() {
     this.addBaseHeaders();
@@ -1761,10 +1682,9 @@ var WorkflowHeaders = class {
       [WORKFLOW_INIT_HEADER]: this.initHeaderValue,
       [WORKFLOW_ID_HEADER]: this.workflowConfig.workflowRunId,
       [WORKFLOW_URL_HEADER]: this.workflowConfig.workflowUrl,
-      [WORKFLOW_FEATURE_HEADER]: "LazyFetch,InitialBody,WF_DetectTrigger" + (this.keepTriggerConfig ? ",WF_TriggerOnConfig" : ""),
+      [WORKFLOW_FEATURE_HEADER]: "LazyFetch,InitialBody,WF_DetectTrigger,WF_TriggerOnConfig",
       [WORKFLOW_PROTOCOL_VERSION_HEADER]: WORKFLOW_PROTOCOL_VERSION,
-      ...this.workflowConfig.telemetry ? getTelemetryHeaders(this.workflowConfig.telemetry) : {},
-      ...this.workflowConfig.telemetry && this.stepInfo?.lazyStep instanceof LazyCallStep && this.stepInfo.lazyStep.headers[AGENT_NAME_HEADER] ? { [TELEMETRY_HEADER_AGENT]: "true" } : {}
+      ...this.workflowConfig.telemetry ? getTelemetryHeaders(this.workflowConfig.telemetry) : {}
     };
     if (this.stepInfo?.lazyStep.stepType !== "Call") {
       this.headers.rawHeaders[`Upstash-Forward-${WORKFLOW_PROTOCOL_VERSION_HEADER}`] = WORKFLOW_PROTOCOL_VERSION;
@@ -1832,12 +1752,12 @@ var WorkflowHeaders = class {
     }
     this.headers.workflowHeaders["Failure-Callback"] = this.workflowConfig.failureUrl;
     this.headers.failureHeaders[`Forward-${WORKFLOW_FAILURE_HEADER}`] = "true";
-    this.headers.failureHeaders[`Forward-Upstash-Workflow-Failure-Callback`] = "true";
+    this.headers.failureHeaders[`Forward-${WORKFLOW_FAILURE_CALLBACK_HEADER}`] = "true";
     this.headers.failureHeaders["Workflow-Runid"] = this.workflowConfig.workflowRunId;
     this.headers.failureHeaders["Workflow-Init"] = "false";
     this.headers.failureHeaders["Workflow-Url"] = this.workflowConfig.workflowUrl;
     this.headers.failureHeaders["Workflow-Calltype"] = "failureCall";
-    this.headers.failureHeaders["Feature-Set"] = "LazyFetch,InitialBody,WF_DetectTrigger";
+    this.headers.failureHeaders["Feature-Set"] = "LazyFetch,InitialBody,WF_DetectTrigger,WF_TriggerOnConfig";
     if (this.workflowConfig.retries !== void 0 && this.workflowConfig.retries !== DEFAULT_RETRIES) {
       this.headers.failureHeaders["Retries"] = this.workflowConfig.retries.toString();
     }
@@ -1907,14 +1827,13 @@ var submitParallelSteps = async ({
   initialStepCount,
   invokeCount,
   telemetry: telemetry2,
-  debug
+  dispatchDebug
 }) => {
   const planSteps = steps.map(
     (step, index) => step.getPlanStep(steps.length, initialStepCount + index)
   );
-  await debug?.log("SUBMIT", "SUBMIT_STEP", {
-    length: planSteps.length,
-    steps: planSteps
+  await dispatchDebug("onInfo", {
+    info: `Submitting ${planSteps.length} parallel steps.`
   });
   const result = await context.qstashClient.batch(
     planSteps.map((planStep) => {
@@ -1923,10 +1842,6 @@ var submitParallelSteps = async ({
         workflowConfig: {
           workflowRunId: context.workflowRunId,
           workflowUrl: context.url,
-          failureUrl: context.failureUrl,
-          retries: context.retries,
-          retryDelay: context.retryDelay,
-          flowControl: context.flowControl,
           telemetry: telemetry2
         },
         userHeaders: context.headers,
@@ -1942,13 +1857,11 @@ var submitParallelSteps = async ({
       };
     })
   );
-  await debug?.log("INFO", "SUBMIT_STEP", {
-    messageIds: result.map((message) => {
-      return {
-        message: message.messageId
-      };
-    })
-  });
+  if (result && result.length > 0) {
+    await dispatchDebug("onInfo", {
+      info: `Submitted ${planSteps.length} parallel steps. messageIds: ${result.filter((r) => r).map((r) => r.messageId).join(", ")}.`
+    });
+  }
   throw new WorkflowAbort(planSteps[0].stepName, planSteps[0]);
 };
 var submitSingleStep = async ({
@@ -1958,14 +1871,13 @@ var submitSingleStep = async ({
   invokeCount,
   concurrency,
   telemetry: telemetry2,
-  debug
+  dispatchDebug,
+  dispatchLifecycle
 }) => {
-  const resultStep = await lazyStep.getResultStep(concurrency, stepId);
-  await debug?.log("INFO", "RUN_SINGLE", {
-    fromRequest: false,
-    step: resultStep,
-    stepCount: stepId
+  await dispatchLifecycle("beforeExecution", {
+    stepName: lazyStep.stepName
   });
+  const resultStep = await lazyStep.getResultStep(concurrency, stepId);
   const { headers } = lazyStep.getHeaders({
     context,
     step: resultStep,
@@ -1979,10 +1891,6 @@ var submitSingleStep = async ({
     invokeCount,
     telemetry: telemetry2
   });
-  await debug?.log("SUBMIT", "SUBMIT_STEP", {
-    length: 1,
-    steps: [resultStep]
-  });
   const submitResult = await lazyStep.submitStep({
     context,
     body,
@@ -1992,13 +1900,11 @@ var submitSingleStep = async ({
     step: resultStep,
     telemetry: telemetry2
   });
-  await debug?.log("INFO", "SUBMIT_STEP", {
-    messageIds: submitResult.map((message) => {
-      return {
-        message: message.messageId
-      };
-    })
-  });
+  if (submitResult && submitResult[0]) {
+    await dispatchDebug("onInfo", {
+      info: `Submitted step "${resultStep.stepName}" with messageId: ${submitResult[0].messageId}.`
+    });
+  }
   return resultStep;
 };
 
@@ -2007,21 +1913,31 @@ var AutoExecutor = class _AutoExecutor {
   context;
   promises = /* @__PURE__ */ new WeakMap();
   activeLazyStepList;
-  debug;
   nonPlanStepCount;
   steps;
   indexInCurrentList = 0;
   invokeCount;
   telemetry;
+  dispatchDebug;
+  dispatchLifecycle;
   stepCount = 0;
   planStepCount = 0;
   executingStep = false;
-  constructor(context, steps, telemetry2, invokeCount, debug) {
+  /**
+   * @param context workflow context
+   * @param steps list of steps
+   * @param dispatchDebug debug event dispatcher
+   * @param dispatchLifecycle lifecycle event dispatcher
+   * @param telemetry optional telemetry information
+   * @param invokeCount optional invoke count
+   */
+  constructor(context, steps, dispatchDebug, dispatchLifecycle, telemetry2, invokeCount) {
     this.context = context;
     this.steps = steps;
+    this.dispatchDebug = dispatchDebug;
+    this.dispatchLifecycle = dispatchLifecycle;
     this.telemetry = telemetry2;
     this.invokeCount = invokeCount ?? 0;
-    this.debug = debug;
     this.nonPlanStepCount = this.steps.filter((step) => !step.targetStep).length;
   }
   /**
@@ -2089,7 +2005,7 @@ var AutoExecutor = class _AutoExecutor {
   /**
    * Executes a step:
    * - If the step result is available in the steps, returns the result
-   * - If the result is not avaiable, runs the function
+   * - If the result is not available, runs the function
    * - Sends the result to QStash
    *
    * @param lazyStep lazy step to execute
@@ -2099,12 +2015,15 @@ var AutoExecutor = class _AutoExecutor {
     if (this.stepCount < this.nonPlanStepCount) {
       const step = this.steps[this.stepCount + this.planStepCount];
       validateStep(lazyStep, step);
-      await this.debug?.log("INFO", "RUN_SINGLE", {
-        fromRequest: true,
-        step,
-        stepCount: this.stepCount
-      });
-      return lazyStep.parseOut(step);
+      const parsedOut = lazyStep.parseOut(step);
+      const isLastMemoized = this.stepCount + 1 === this.nonPlanStepCount && this.steps.at(-1).stepId !== 0;
+      if (isLastMemoized) {
+        await this.dispatchLifecycle("afterExecution", {
+          stepName: lazyStep.stepName,
+          result: parsedOut
+        });
+      }
+      return parsedOut;
     }
     const resultStep = await submitSingleStep({
       context: this.context,
@@ -2113,15 +2032,15 @@ var AutoExecutor = class _AutoExecutor {
       invokeCount: this.invokeCount,
       concurrency: 1,
       telemetry: this.telemetry,
-      debug: this.debug
+      dispatchDebug: this.dispatchDebug,
+      dispatchLifecycle: this.dispatchLifecycle
     });
     throw new WorkflowAbort(lazyStep.stepName, resultStep);
   }
   /**
    * Runs steps in parallel.
    *
-   * @param stepName parallel step name
-   * @param stepFunctions list of async functions to run in parallel
+   * @param parallelSteps list of lazy steps to run in parallel
    * @returns results of the functions run in parallel
    */
   async runParallel(parallelSteps) {
@@ -2134,12 +2053,14 @@ var AutoExecutor = class _AutoExecutor {
         `Incompatible number of parallel steps when call state was '${parallelCallState}'. Expected ${parallelSteps.length}, got ${plannedParallelStepCount} from the request.`
       );
     }
-    await this.debug?.log("INFO", "RUN_PARALLEL", {
-      parallelCallState,
-      initialStepCount,
-      plannedParallelStepCount,
-      stepCount: this.stepCount,
-      planStepCount: this.planStepCount
+    await this.dispatchDebug("onInfo", {
+      info: `Executing parallel steps with: ` + JSON.stringify({
+        parallelCallState,
+        initialStepCount,
+        plannedParallelStepCount,
+        stepCount: this.stepCount,
+        planStepCount: this.planStepCount
+      })
     });
     switch (parallelCallState) {
       case "first": {
@@ -2149,7 +2070,7 @@ var AutoExecutor = class _AutoExecutor {
           initialStepCount,
           invokeCount: this.invokeCount,
           telemetry: this.telemetry,
-          debug: this.debug
+          dispatchDebug: this.dispatchDebug
         });
         break;
       }
@@ -2171,7 +2092,8 @@ var AutoExecutor = class _AutoExecutor {
             invokeCount: this.invokeCount,
             concurrency: parallelSteps.length,
             telemetry: this.telemetry,
-            debug: this.debug
+            dispatchDebug: this.dispatchDebug,
+            dispatchLifecycle: this.dispatchLifecycle
           });
           throw new WorkflowAbort(parallelStep.stepName, resultStep);
         } catch (error) {
@@ -2185,11 +2107,32 @@ var AutoExecutor = class _AutoExecutor {
         break;
       }
       case "discard": {
+        const resultStep = this.steps.at(-1);
+        const lazyStep = parallelSteps.find(
+          (planStep, index) => resultStep.stepId - index === initialStepCount
+        );
+        if (lazyStep) {
+          await this.dispatchLifecycle("afterExecution", {
+            stepName: lazyStep.stepName,
+            result: lazyStep.parseOut(resultStep)
+          });
+        }
         throw new WorkflowAbort("discarded parallel");
       }
       case "last": {
         const parallelResultSteps = sortedSteps.filter((step) => step.stepId >= initialStepCount).slice(0, parallelSteps.length);
         validateParallelSteps(parallelSteps, parallelResultSteps);
+        const isLastMemoized = this.stepCount + 1 === this.nonPlanStepCount && this.steps.at(-1).stepId !== 0;
+        if (isLastMemoized) {
+          const resultStep = this.steps.at(-1);
+          const lazyStep = parallelSteps.find(
+            (planStep, index) => resultStep.stepId - index === initialStepCount
+          );
+          await this.dispatchLifecycle("afterExecution", {
+            stepName: lazyStep.stepName,
+            result: lazyStep.parseOut(resultStep)
+          });
+        }
         return parallelResultSteps.map(
           (step, index) => parallelSteps[index].parseOut(step)
         );
@@ -2333,15 +2276,18 @@ var getProviderInfo = (api) => {
 // src/context/api/base.ts
 var BaseWorkflowApi = class {
   context;
+  /**
+   * @param context workflow context
+   */
   constructor({ context }) {
     this.context = context;
   }
   /**
    * context.call which uses a QStash API
    *
-   * @param stepName
-   * @param settings
-   * @returns
+   * @param stepName name of the step
+   * @param settings call settings including api configuration
+   * @returns call response
    */
   async callApi(stepName, settings) {
     const { url, appendHeaders, method } = getProviderInfo(settings.api);
@@ -2349,7 +2295,7 @@ var BaseWorkflowApi = class {
     return await this.context.call(stepName, {
       url,
       method: userMethod ?? method,
-      body,
+      body: typeof body === "string" ? body : JSON.stringify(body),
       headers: {
         ...appendHeaders,
         ...headers
@@ -2426,309 +2372,6 @@ var WorkflowApi = class extends BaseWorkflowApi {
   }
 };
 
-// src/agents/index.ts
-var import_openai2 = require("@ai-sdk/openai");
-
-// src/agents/adapters.ts
-var import_ai = require("ai");
-var fetchWithContextCall = async (context, agentCallParams, ...params) => {
-  const [input, init] = params;
-  try {
-    const headers = init?.headers ? Object.fromEntries(new Headers(init.headers).entries()) : {};
-    const body = init?.body ? JSON.parse(init.body) : void 0;
-    const agentName = headers[AGENT_NAME_HEADER];
-    const stepName = agentName ? `Call Agent ${agentName}` : "Call Agent";
-    const responseInfo = await context.call(stepName, {
-      url: input.toString(),
-      method: init?.method,
-      headers,
-      body,
-      timeout: agentCallParams?.timeout,
-      retries: agentCallParams?.retries,
-      retryDelay: agentCallParams?.retryDelay,
-      flowControl: agentCallParams?.flowControl
-    });
-    const responseHeaders = new Headers(
-      Object.entries(responseInfo.header).reduce(
-        (acc, [key, values]) => {
-          acc[key] = values.join(", ");
-          return acc;
-        },
-        {}
-      )
-    );
-    return new Response(JSON.stringify(responseInfo.body), {
-      status: responseInfo.status,
-      headers: responseHeaders
-    });
-  } catch (error) {
-    if (error instanceof Error && isInstanceOf(error, WorkflowAbort)) {
-      throw error;
-    } else {
-      console.error("Error in fetch implementation:", error);
-      throw error;
-    }
-  }
-};
-var createWorkflowModel = ({
-  context,
-  provider,
-  providerParams,
-  agentCallParams
-}) => {
-  return provider({
-    fetch: (...params) => fetchWithContextCall(context, agentCallParams, ...params),
-    ...providerParams
-  });
-};
-var wrapTools = ({
-  context,
-  tools
-}) => {
-  return Object.fromEntries(
-    Object.entries(tools).map((toolInfo) => {
-      const [toolName, tool3] = toolInfo;
-      const executeAsStep = "executeAsStep" in tool3 ? tool3.executeAsStep : true;
-      const aiSDKTool = convertToAISDKTool(tool3);
-      const execute = aiSDKTool.execute;
-      if (execute && executeAsStep) {
-        const wrappedExecute = (...params) => {
-          return context.run(`Run tool ${toolName}`, () => execute(...params));
-        };
-        aiSDKTool.execute = wrappedExecute;
-      }
-      return [toolName, aiSDKTool];
-    })
-  );
-};
-var convertToAISDKTool = (tool3) => {
-  const isLangchainTool = "invoke" in tool3;
-  return isLangchainTool ? convertLangchainTool(tool3) : tool3;
-};
-var convertLangchainTool = (langchainTool) => {
-  return (0, import_ai.tool)({
-    description: langchainTool.description,
-    parameters: langchainTool.schema,
-    execute: async (...param) => langchainTool.invoke(...param)
-  });
-};
-
-// src/agents/agent.ts
-var import_zod = require("zod");
-var import_ai2 = require("ai");
-
-// src/serve/utils.ts
-var isDisabledWorkflowContext = (context) => {
-  return "disabled" in context;
-};
-
-// src/agents/agent.ts
-var Agent = class {
-  name;
-  tools;
-  maxSteps;
-  background;
-  model;
-  temparature;
-  context;
-  constructor({ tools, maxSteps, background, name, model, temparature = 0.1 }, context) {
-    this.name = name;
-    this.tools = tools ?? {};
-    this.maxSteps = maxSteps;
-    this.background = background;
-    this.model = model;
-    this.temparature = temparature;
-    this.context = context;
-  }
-  /**
-   * Trigger the agent by passing a prompt
-   *
-   * @param prompt task to assign to the agent
-   * @returns Response as `{ text: string }`
-   */
-  async call({ prompt }) {
-    try {
-      if (isDisabledWorkflowContext(this.context)) {
-        await this.context.sleep("abort", 0);
-      }
-      const result = await (0, import_ai2.generateText)({
-        model: this.model,
-        tools: this.tools,
-        maxSteps: this.maxSteps,
-        system: this.background,
-        prompt,
-        headers: {
-          [AGENT_NAME_HEADER]: this.name
-        },
-        temperature: this.temparature
-      });
-      return { text: result.text };
-    } catch (error) {
-      if (isInstanceOf(error, import_ai2.ToolExecutionError)) {
-        if (error.cause instanceof Error && isInstanceOf(error.cause, WorkflowAbort)) {
-          throw error.cause;
-        } else if (isInstanceOf(error.cause, import_ai2.ToolExecutionError) && isInstanceOf(error.cause.cause, WorkflowAbort)) {
-          throw error.cause.cause;
-        } else {
-          throw error;
-        }
-      } else {
-        throw error;
-      }
-    }
-  }
-  /**
-   * Convert the agent to a tool which can be used by other agents.
-   *
-   * @returns the agent as a tool
-   */
-  asTool() {
-    const toolDescriptions = Object.values(this.tools).map((tool3) => tool3.description).join("\n");
-    return (0, import_ai2.tool)({
-      parameters: import_zod.z.object({ prompt: import_zod.z.string() }),
-      execute: async ({ prompt }) => {
-        return await this.call({ prompt });
-      },
-      description: `An AI Agent with the following background: ${this.background}Has access to the following tools: ${toolDescriptions}`
-    });
-  }
-};
-var ManagerAgent = class extends Agent {
-  agents;
-  /**
-   * A manager agent which coordinates agents available to it to achieve a
-   * given task
-   *
-   * @param name Name of the agent
-   * @param background Background of the agent. If not passed, default will be used.
-   * @param model LLM model to use
-   * @param agents: List of agents available to the agent
-   * @param maxSteps number of times the manager agent can call the LLM at most.
-   *   If the agent abruptly stops execution after calling other agents, you may
-   *   need to increase maxSteps
-   */
-  constructor({
-    agents,
-    background = MANAGER_AGENT_PROMPT,
-    model,
-    maxSteps,
-    name = "manager llm"
-  }, context) {
-    super(
-      {
-        background,
-        maxSteps,
-        tools: Object.fromEntries(agents.map((agent) => [agent.name, agent.asTool()])),
-        name,
-        model
-      },
-      context
-    );
-    this.agents = agents;
-  }
-};
-
-// src/agents/task.ts
-var Task = class {
-  context;
-  taskParameters;
-  constructor({
-    context,
-    taskParameters
-  }) {
-    this.context = context;
-    this.taskParameters = taskParameters;
-  }
-  /**
-   * Run the agents to complete the task
-   *
-   * @returns Result of the task as { text: string }
-   */
-  async run() {
-    const { prompt, ...otherParams } = this.taskParameters;
-    if ("agent" in otherParams) {
-      const agent = otherParams.agent;
-      const result = await agent.call({
-        prompt
-      });
-      return { text: result.text };
-    } else {
-      const { agents, maxSteps, model, background } = otherParams;
-      const managerAgent = new ManagerAgent(
-        {
-          model,
-          maxSteps,
-          agents,
-          name: "Manager LLM",
-          background
-        },
-        this.context
-      );
-      const result = await managerAgent.call({ prompt });
-      return { text: result.text };
-    }
-  }
-};
-
-// src/agents/index.ts
-var WorkflowAgents = class {
-  context;
-  constructor({ context }) {
-    this.context = context;
-  }
-  /**
-   * Defines an agent
-   *
-   * ```ts
-   * const researcherAgent = context.agents.agent({
-   *   model,
-   *   name: 'academic',
-   *   maxSteps: 2,
-   *   tools: {
-   *     wikiTool: new WikipediaQueryRun({
-   *       topKResults: 1,
-   *       maxDocContentLength: 500,
-   *     })
-   *   },
-   *   background:
-   *     'You are researcher agent with access to Wikipedia. ' +
-   *     'Utilize Wikipedia as much as possible for correct information',
-   * });
-   * ```
-   *
-   * @param params agent parameters
-   * @returns
-   */
-  agent(params) {
-    const wrappedTools = wrapTools({ context: this.context, tools: params.tools });
-    return new Agent(
-      {
-        ...params,
-        tools: wrappedTools
-      },
-      this.context
-    );
-  }
-  task(taskParameters) {
-    return new Task({ context: this.context, taskParameters });
-  }
-  /**
-   * creates an openai model for agents
-   */
-  openai(...params) {
-    const [model, settings] = params;
-    const { baseURL, apiKey, callSettings, ...otherSettings } = settings ?? {};
-    const openaiModel = this.AISDKModel({
-      context: this.context,
-      provider: import_openai2.createOpenAI,
-      providerParams: { baseURL, apiKey, compatibility: "strict" },
-      agentCallParams: callSettings
-    });
-    return openaiModel(model, otherSettings);
-  }
-  AISDKModel = createWorkflowModel;
-};
-
 // src/serve/serve-many.ts
 var getWorkflowId = (url) => {
   const components = url.split("/");
@@ -2804,56 +2447,160 @@ var getNewUrlFromWorkflowId = (url, workflowId) => {
   return url.replace(/[^/]+$/, workflowId);
 };
 
-// src/context/context.ts
-var WorkflowContext = class {
-  executor;
-  steps;
+// src/middleware/default-callbacks.ts
+var onErrorWithConsole = async ({ workflowRunId, error }) => {
+  console.error(`  [Upstash Workflow]: Error in workflow run ${workflowRunId}: ` + error);
+};
+var onWarningWithConsole = async ({ workflowRunId, warning }) => {
+  console.warn(`  [Upstash Workflow]: Warning in workflow run ${workflowRunId}: ` + warning);
+};
+var onInfoWithConsole = async ({
+  workflowRunId,
+  info
+}) => {
+  console.info(`  [Upstash Workflow]: Info in workflow run ${workflowRunId}: ` + info);
+};
+
+// src/middleware/manager.ts
+var MiddlewareManager = class {
+  middlewares;
+  workflowRunId;
+  context;
   /**
-   * QStash client of the workflow
+   * @param middlewares list of workflow middlewares
+   */
+  constructor(middlewares = []) {
+    this.middlewares = middlewares;
+  }
+  /**
+   * Assign workflow run ID - will be passed to debug events
    *
-   * Can be overwritten by passing `qstashClient` parameter in `serve`:
+   * @param workflowRunId workflow run id to assign
+   */
+  assignWorkflowRunId(workflowRunId) {
+    this.workflowRunId = workflowRunId;
+  }
+  /**
+   * Assign context - required for lifecycle events
    *
-   * ```ts
-   * import { Client } from "@upstash/qstash"
+   * also assigns workflowRunId from context
    *
-   * export const POST = serve(
-   *   async (context) => {
-   *     ...
-   *   },
-   *   {
-   *     qstashClient: new Client({...})
-   *   }
-   * )
-   * ```
+   * @param context workflow context to assign
    */
-  qstashClient;
+  assignContext(context) {
+    this.context = context;
+    this.workflowRunId = context.workflowRunId;
+  }
   /**
-   * Run id of the workflow
+   * Internal method to execute middlewares with common error handling logic
+   *
+   * @param event event name to dispatch
+   * @param params event parameters
    */
-  workflowRunId;
+  async executeMiddlewares(event, params) {
+    await Promise.all(this.middlewares.map((m) => m.ensureInit()));
+    await Promise.all(
+      this.middlewares.map(async (middleware) => {
+        const callback = middleware.getCallback(event);
+        if (callback) {
+          try {
+            await callback(params);
+          } catch (error) {
+            try {
+              const onErrorCallback = middleware.getCallback("onError") ?? onErrorWithConsole;
+              await onErrorCallback({
+                workflowRunId: this.workflowRunId,
+                error
+              });
+            } catch (onErrorError) {
+              console.error(
+                `Failed while executing "onError" of middleware "${middleware.name}", falling back to logging the error to console. Error: ${onErrorError}`
+              );
+              onErrorWithConsole({
+                workflowRunId: this.workflowRunId,
+                error
+              });
+            }
+          }
+        }
+      })
+    );
+    if (event === "onError") {
+      onErrorWithConsole({
+        workflowRunId: this.workflowRunId,
+        ...params
+      });
+    } else if (event === "onWarning") {
+      onWarningWithConsole({
+        workflowRunId: this.workflowRunId,
+        ...params
+      });
+    }
+  }
   /**
-   * URL of the workflow
+   * Dispatch a debug event (onError, onWarning, onInfo)
    *
-   * Can be overwritten by passing a `url` parameter in `serve`:
+   * @param event debug event name
+   * @param params event parameters
+   */
+  async dispatchDebug(event, params) {
+    const paramsWithRunId = {
+      ...params,
+      workflowRunId: this.workflowRunId
+    };
+    await this.executeMiddlewares(event, paramsWithRunId);
+  }
+  /**
+   * Dispatch a lifecycle event (beforeExecution, afterExecution, runStarted, runCompleted)
+   *
+   * @param event lifecycle event name
+   * @param params event parameters
+   */
+  async dispatchLifecycle(event, params) {
+    if (!this.context) {
+      throw new WorkflowError(
+        `Something went wrong while calling middlewares. Lifecycle event "${event}" was called before assignContext.`
+      );
+    }
+    const paramsWithContext = {
+      ...params,
+      context: this.context
+    };
+    await this.executeMiddlewares(event, paramsWithContext);
+  }
+};
+
+// src/context/context.ts
+var WorkflowContext = class {
+  executor;
+  steps;
+  /**
+   * QStash client of the workflow
+   *
+   * Can be overwritten by passing `qstashClient` parameter in `serve`:
    *
    * ```ts
+   * import { Client } from "@upstash/qstash"
+   *
    * export const POST = serve(
    *   async (context) => {
    *     ...
    *   },
    *   {
-   *     url: "new-url-value"
+   *     qstashClient: new Client({...})
    *   }
    * )
    * ```
    */
-  url;
+  qstashClient;
   /**
-   * URL to call in case of workflow failure with QStash failure callback
-   *
-   * https://upstash.com/docs/qstash/features/callbacks#what-is-a-failure-callback
+   * Run id of the workflow
+   */
+  workflowRunId;
+  /**
+   * URL of the workflow
    *
-   * Can be overwritten by passing a `failureUrl` parameter in `serve`:
+   * Can be overwritten by passing a `url` parameter in `serve`:
    *
    * ```ts
    * export const POST = serve(
@@ -2861,12 +2608,12 @@ var WorkflowContext = class {
    *     ...
    *   },
    *   {
-   *     failureUrl: "new-url-value"
+   *     url: "new-url-value"
    *   }
    * )
    * ```
    */
-  failureUrl;
+  url;
   /**
    * Payload of the request which started the workflow.
    *
@@ -2922,46 +2669,6 @@ var WorkflowContext = class {
    * Default value is set to `process.env`.
    */
   env;
-  /**
-   * Number of retries
-   */
-  retries;
-  /**
-   * Delay between retries.
-   *
-   * By default, the `retryDelay` is exponential backoff.
-   * More details can be found in: https://upstash.com/docs/qstash/features/retry.
-   *
-   * The `retryDelay` option allows you to customize the delay (in milliseconds) between retry attempts when message delivery fails.
-   *
-   * You can use mathematical expressions and the following built-in functions to calculate the delay dynamically.
-   * The special variable `retried` represents the current retry attempt count (starting from 0).
-   *
-   * Supported functions:
-   * - `pow`
-   * - `sqrt`
-   * - `abs`
-   * - `exp`
-   * - `floor`
-   * - `ceil`
-   * - `round`
-   * - `min`
-   * - `max`
-   *
-   * Examples of valid `retryDelay` values:
-   * ```ts
-   * 1000 // 1 second
-   * 1000 * (1 + retried)  // 1 second multiplied by the current retry attempt
-   * pow(2, retried) // 2 to the power of the current retry attempt
-   * max(10, pow(2, retried)) // The greater of 10 or 2^retried
-   * ```
-   */
-  retryDelay;
-  /**
-   * Settings for controlling the number of active requests
-   * and number of requests per second with the same key.
-   */
-  flowControl;
   /**
    * Label to apply to the workflow run.
    *
@@ -2984,30 +2691,31 @@ var WorkflowContext = class {
     headers,
     steps,
     url,
-    failureUrl,
-    debug,
     initialPayload,
     env,
-    retries,
-    retryDelay,
     telemetry: telemetry2,
     invokeCount,
-    flowControl,
-    label
+    label,
+    middlewareManager
   }) {
     this.qstashClient = qstashClient;
     this.workflowRunId = workflowRunId;
     this.steps = steps;
     this.url = url;
-    this.failureUrl = failureUrl;
     this.headers = headers;
     this.requestPayload = initialPayload;
     this.env = env ?? {};
-    this.retries = retries ?? DEFAULT_RETRIES;
-    this.retryDelay = retryDelay;
-    this.flowControl = flowControl;
     this.label = label;
-    this.executor = new AutoExecutor(this, this.steps, telemetry2, invokeCount, debug);
+    const middlewareManagerInstance = middlewareManager ?? new MiddlewareManager([]);
+    middlewareManagerInstance.assignContext(this);
+    this.executor = new AutoExecutor(
+      this,
+      this.steps,
+      middlewareManagerInstance.dispatchDebug.bind(middlewareManagerInstance),
+      middlewareManagerInstance.dispatchLifecycle.bind(middlewareManagerInstance),
+      telemetry2,
+      invokeCount
+    );
   }
   /**
    * Executes a workflow step
@@ -3037,7 +2745,7 @@ var WorkflowContext = class {
    * @returns result of the step function
    */
   async run(stepName, stepFunction) {
-    const wrappedStepFunction = () => this.executor.wrapStep(stepName, stepFunction);
+    const wrappedStepFunction = (() => this.executor.wrapStep(stepName, stepFunction));
     return await this.addStep(new LazyFunctionStep(this, stepName, wrappedStepFunction));
   }
   /**
@@ -3080,44 +2788,32 @@ var WorkflowContext = class {
     let callStep;
     if ("workflow" in settings) {
       const url = getNewUrlFromWorkflowId(this.url, settings.workflow.workflowId);
-      callStep = new LazyCallStep(
-        this,
+      const stringBody = typeof settings.body === "string" ? settings.body : settings.body === void 0 ? void 0 : JSON.stringify(settings.body);
+      callStep = new LazyCallStep({
+        context: this,
         stepName,
         url,
-        "POST",
-        settings.body,
-        settings.headers || {},
-        settings.retries || 0,
-        settings.retryDelay,
-        settings.timeout,
-        settings.flowControl ?? settings.workflow.options.flowControl,
-        settings.stringifyBody ?? true
-      );
+        method: "POST",
+        body: stringBody,
+        headers: settings.headers || {},
+        retries: settings.retries || 0,
+        retryDelay: settings.retryDelay,
+        timeout: settings.timeout,
+        flowControl: settings.flowControl
+      });
     } else {
-      const {
-        url,
-        method = "GET",
-        body,
-        headers = {},
-        retries = 0,
-        retryDelay,
-        timeout,
-        flowControl,
-        stringifyBody = true
-      } = settings;
-      callStep = new LazyCallStep(
-        this,
+      callStep = new LazyCallStep({
+        context: this,
         stepName,
-        url,
-        method,
-        body,
-        headers,
-        retries,
-        retryDelay,
-        timeout,
-        flowControl,
-        stringifyBody
-      );
+        url: settings.url,
+        method: settings.method ?? "GET",
+        body: settings.body,
+        headers: settings.headers ?? {},
+        retries: settings.retries ?? 0,
+        retryDelay: settings.retryDelay,
+        timeout: settings.timeout,
+        flowControl: settings.flowControl
+      });
     }
     return await this.addStep(callStep);
   }
@@ -3202,11 +2898,11 @@ var WorkflowContext = class {
   /**
    * Cancel the current workflow run
    *
-   * Will throw WorkflowAbort to stop workflow execution.
+   * Will throw WorkflowCancelAbort to stop workflow execution.
    * Shouldn't be inside try/catch.
    */
   async cancel() {
-    throw new WorkflowAbort("cancel", void 0, true);
+    throw new WorkflowCancelAbort();
   }
   /**
    * Adds steps to the executor. Needed so that it can be overwritten in
@@ -3220,60 +2916,6 @@ var WorkflowContext = class {
       context: this
     });
   }
-  get agents() {
-    return new WorkflowAgents({
-      context: this
-    });
-  }
-};
-
-// src/logger.ts
-var LOG_LEVELS = ["DEBUG", "INFO", "SUBMIT", "WARN", "ERROR"];
-var WorkflowLogger = class _WorkflowLogger {
-  logs = [];
-  options;
-  workflowRunId = void 0;
-  constructor(options) {
-    this.options = options;
-  }
-  async log(level, eventType, details) {
-    if (this.shouldLog(level)) {
-      const timestamp = Date.now();
-      const logEntry = {
-        timestamp,
-        workflowRunId: this.workflowRunId ?? "",
-        logLevel: level,
-        eventType,
-        details
-      };
-      this.logs.push(logEntry);
-      if (this.options.logOutput === "console") {
-        this.writeToConsole(logEntry);
-      }
-      await new Promise((resolve) => setTimeout(resolve, 100));
-    }
-  }
-  setWorkflowRunId(workflowRunId) {
-    this.workflowRunId = workflowRunId;
-  }
-  writeToConsole(logEntry) {
-    const JSON_SPACING = 2;
-    const logMethod = logEntry.logLevel === "ERROR" ? console.error : logEntry.logLevel === "WARN" ? console.warn : console.log;
-    logMethod(JSON.stringify(logEntry, void 0, JSON_SPACING));
-  }
-  shouldLog(level) {
-    return LOG_LEVELS.indexOf(level) >= LOG_LEVELS.indexOf(this.options.logLevel);
-  }
-  static getLogger(verbose) {
-    if (typeof verbose === "object") {
-      return verbose;
-    } else {
-      return verbose ? new _WorkflowLogger({
-        logLevel: "INFO",
-        logOutput: "console"
-      }) : void 0;
-    }
-  }
 };
 
 // src/serve/authorization.ts
@@ -3282,19 +2924,19 @@ var DisabledWorkflowContext = class _DisabledWorkflowContext extends WorkflowCon
   static disabledMessage = "disabled-qstash-worklfow-run";
   disabled = true;
   /**
-   * overwrite the WorkflowContext.addStep method to always raise WorkflowAbort
+   * overwrite the WorkflowContext.addStep method to always raise WorkflowAuthError
    * error in order to stop the execution whenever we encounter a step.
    *
    * @param _step
    */
   async addStep(_step) {
-    throw new WorkflowAbort(_DisabledWorkflowContext.disabledMessage);
+    throw new WorkflowAuthError(_DisabledWorkflowContext.disabledMessage);
   }
   /**
-   * overwrite cancel method to throw WorkflowAbort with the disabledMessage
+   * overwrite cancel method to throw WorkflowAuthError with the disabledMessage
    */
   async cancel() {
-    throw new WorkflowAbort(_DisabledWorkflowContext.disabledMessage);
+    throw new WorkflowAuthError(_DisabledWorkflowContext.disabledMessage);
   }
   /**
    * copies the passed context to create a DisabledWorkflowContext. Then, runs the
@@ -3317,18 +2959,14 @@ var DisabledWorkflowContext = class _DisabledWorkflowContext extends WorkflowCon
       headers: context.headers,
       steps: [],
       url: context.url,
-      failureUrl: context.failureUrl,
       initialPayload: context.requestPayload,
       env: context.env,
-      retries: context.retries,
-      retryDelay: context.retryDelay,
-      flowControl: context.flowControl,
       label: context.label
     });
     try {
       await routeFunction(disabledContext);
     } catch (error) {
-      if (isInstanceOf(error, WorkflowAbort) && error.stepName === this.disabledMessage || isInstanceOf(error, WorkflowNonRetryableError) || isInstanceOf(error, WorkflowRetryAfterError)) {
+      if (isInstanceOf(error, WorkflowAuthError) && error.stepName === this.disabledMessage || isInstanceOf(error, WorkflowNonRetryableError) || isInstanceOf(error, WorkflowRetryAfterError)) {
         return ok("step-found");
       }
       console.warn(
@@ -3388,7 +3026,7 @@ var deduplicateSteps = (steps) => {
   }
   return deduplicatedSteps;
 };
-var checkIfLastOneIsDuplicate = async (steps, debug) => {
+var checkIfLastOneIsDuplicate = async (steps, dispatchDebug) => {
   if (steps.length < 2) {
     return false;
   }
@@ -3399,14 +3037,41 @@ var checkIfLastOneIsDuplicate = async (steps, debug) => {
     const step = steps[index];
     if (step.stepId === lastStepId && step.targetStep === lastTargetStepId) {
       const message = `Upstash Workflow: The step '${step.stepName}' with id '${step.stepId}'  has run twice during workflow execution. Rest of the workflow will continue running as usual.`;
-      await debug?.log("WARN", "RESPONSE_DEFAULT", message);
-      console.warn(message);
+      await dispatchDebug?.("onWarning", {
+        warning: message
+      });
       return true;
     }
   }
   return false;
 };
 var validateRequest = (request) => {
+  if (request.headers.get(WORKFLOW_UNKOWN_SDK_VERSION_HEADER)) {
+    const workflowRunId2 = request.headers.get(WORKFLOW_ID_HEADER);
+    if (!workflowRunId2) {
+      throw new WorkflowError(
+        "Couldn't get workflow id from header when handling unknown sdk request"
+      );
+    }
+    return {
+      unknownSdk: true,
+      isFirstInvocation: true,
+      workflowRunId: workflowRunId2
+    };
+  }
+  if (request.headers.get(WORKFLOW_FAILURE_CALLBACK_HEADER)) {
+    const workflowRunId2 = request.headers.get(WORKFLOW_ID_HEADER);
+    if (!workflowRunId2) {
+      throw new WorkflowError(
+        "Couldn't get workflow id from header when handling failure callback request"
+      );
+    }
+    return {
+      unknownSdk: false,
+      isFirstInvocation: true,
+      workflowRunId: workflowRunId2
+    };
+  }
   const versionHeader = request.headers.get(WORKFLOW_PROTOCOL_VERSION_HEADER);
   const isFirstInvocation = !versionHeader;
   if (!isFirstInvocation && versionHeader !== WORKFLOW_PROTOCOL_VERSION) {
@@ -3420,11 +3085,20 @@ var validateRequest = (request) => {
   }
   return {
     isFirstInvocation,
-    workflowRunId
+    workflowRunId,
+    unknownSdk: false
   };
 };
-var parseRequest = async (requestPayload, isFirstInvocation, workflowRunId, requester, messageId, debug) => {
-  if (isFirstInvocation) {
+var parseRequest = async ({
+  requestPayload,
+  isFirstInvocation,
+  unknownSdk,
+  workflowRunId,
+  requester,
+  messageId,
+  dispatchDebug
+}) => {
+  if (isFirstInvocation && !unknownSdk) {
     return {
       rawInitialPayload: requestPayload ?? "",
       steps: [],
@@ -3434,16 +3108,14 @@ var parseRequest = async (requestPayload, isFirstInvocation, workflowRunId, requ
   } else {
     let rawSteps;
     if (!requestPayload) {
-      await debug?.log(
-        "INFO",
-        "ENDPOINT_START",
-        "request payload is empty, steps will be fetched from QStash."
-      );
+      await dispatchDebug?.("onInfo", {
+        info: "request payload is empty, steps will be fetched from QStash."
+      });
       const { steps: fetchedSteps, workflowRunEnded } = await getSteps(
         requester,
         workflowRunId,
         messageId,
-        debug
+        dispatchDebug
       );
       if (workflowRunEnded) {
         return {
@@ -3458,7 +3130,7 @@ var parseRequest = async (requestPayload, isFirstInvocation, workflowRunId, requ
       rawSteps = JSON.parse(requestPayload);
     }
     const { rawInitialPayload, steps } = processRawSteps(rawSteps);
-    const isLastDuplicate = await checkIfLastOneIsDuplicate(steps, debug);
+    const isLastDuplicate = await checkIfLastOneIsDuplicate(steps, dispatchDebug);
     const deduplicatedSteps = deduplicateSteps(steps);
     return {
       rawInitialPayload,
@@ -3468,16 +3140,21 @@ var parseRequest = async (requestPayload, isFirstInvocation, workflowRunId, requ
     };
   }
 };
-var handleFailure = async (request, requestPayload, qstashClient, initialPayloadParser, routeFunction, failureFunction, env, retries, retryDelay, flowControl, debug) => {
-  if (request.headers.get(WORKFLOW_FAILURE_HEADER) !== "true") {
+var handleFailure = async ({
+  request,
+  requestPayload,
+  qstashClient,
+  initialPayloadParser,
+  routeFunction,
+  failureFunction,
+  env,
+  dispatchDebug
+}) => {
+  if (request.headers.get(WORKFLOW_FAILURE_HEADER) !== "true" && !request.headers.get(WORKFLOW_FAILURE_CALLBACK_HEADER)) {
     return ok({ result: "not-failure-callback" });
   }
   if (!failureFunction) {
-    return err(
-      new WorkflowError(
-        "Workflow endpoint is called to handle a failure, but a failureFunction is not provided in serve options. Either provide a failureUrl or a failureFunction."
-      )
-    );
+    return ok({ result: "failure-function-undefined" });
   }
   try {
     const { status, header, body, url, sourceBody, workflowRunId } = JSON.parse(requestPayload);
@@ -3505,23 +3182,21 @@ var handleFailure = async (request, requestPayload, qstashClient, initialPayload
       headers: userHeaders,
       steps: [],
       url,
-      failureUrl: url,
-      debug,
       env,
-      retries,
-      retryDelay,
-      flowControl,
       telemetry: void 0,
       // not going to make requests in authentication check
-      label: userHeaders.get(WORKFLOW_LABEL_HEADER) ?? void 0
+      label: userHeaders.get(WORKFLOW_LABEL_HEADER) ?? void 0,
+      middlewareManager: void 0
     });
     const authCheck = await DisabledWorkflowContext.tryAuthentication(
       routeFunction,
       workflowContext
     );
     if (authCheck.isErr()) {
-      await debug?.log("ERROR", "ERROR", { error: authCheck.error.message });
-      throw authCheck.error;
+      await dispatchDebug?.("onError", {
+        error: authCheck.error
+      });
+      return err(authCheck.error);
     } else if (authCheck.value === "run-ended") {
       return err(new WorkflowError("Not authorized to run the failure function."));
     }
@@ -3532,74 +3207,309 @@ var handleFailure = async (request, requestPayload, qstashClient, initialPayload
       failHeaders: header,
       failStack
     });
-    return ok({ result: "is-failure-callback", response: failureResponse });
+    return ok({ result: "failure-function-executed", response: failureResponse });
   } catch (error) {
     return err(error);
   }
 };
 
-// src/serve/options.ts
+// src/serve/multi-region/handlers.ts
 var import_qstash10 = require("@upstash/qstash");
-var import_qstash11 = require("@upstash/qstash");
-var processOptions = (options) => {
-  const environment = options?.env ?? (typeof process === "undefined" ? {} : process.env);
-  const receiverEnvironmentVariablesSet = Boolean(
-    environment.QSTASH_CURRENT_SIGNING_KEY && environment.QSTASH_NEXT_SIGNING_KEY
+
+// src/serve/multi-region/utils.ts
+var VALID_REGIONS = ["EU_CENTRAL_1", "US_EAST_1"];
+var getRegionFromEnvironment = (environment) => {
+  const region = environment.QSTASH_REGION;
+  return normalizeRegionHeader(region);
+};
+function readEnvironmentVariables(environmentVariables, environment, region) {
+  const result = {};
+  for (const variable of environmentVariables) {
+    const key = region ? `${region}_${variable}` : variable;
+    result[variable] = environment[key];
+  }
+  return result;
+}
+function readClientEnvironmentVariables(environment, region) {
+  return readEnvironmentVariables(["QSTASH_URL", "QSTASH_TOKEN"], environment, region);
+}
+function readReceiverEnvironmentVariables(environment, region) {
+  return readEnvironmentVariables(
+    ["QSTASH_CURRENT_SIGNING_KEY", "QSTASH_NEXT_SIGNING_KEY"],
+    environment,
+    region
   );
-  return {
-    qstashClient: options?.qstashClient ?? new import_qstash11.Client({
-      baseUrl: environment.QSTASH_URL,
-      token: environment.QSTASH_TOKEN
-    }),
-    onStepFinish: (workflowRunId, _finishCondition, detailedFinishCondition) => {
-      if (detailedFinishCondition?.condition === "auth-fail") {
-        console.error(AUTH_FAIL_MESSAGE);
-        return new Response(
-          JSON.stringify({
-            message: AUTH_FAIL_MESSAGE,
-            workflowRunId
-          }),
-          {
-            status: 400,
-            headers: {
-              [WORKFLOW_PROTOCOL_VERSION_HEADER]: WORKFLOW_PROTOCOL_VERSION
-            }
-          }
-        );
-      } else if (detailedFinishCondition?.condition === "non-retryable-error") {
-        return new Response(JSON.stringify(formatWorkflowError(detailedFinishCondition.result)), {
-          headers: {
-            "Upstash-NonRetryable-Error": "true",
-            [WORKFLOW_PROTOCOL_VERSION_HEADER]: WORKFLOW_PROTOCOL_VERSION
-          },
-          status: 489
-        });
-      } else if (detailedFinishCondition?.condition === "retry-after-error") {
-        return new Response(JSON.stringify(formatWorkflowError(detailedFinishCondition.result)), {
-          headers: {
-            "Retry-After": detailedFinishCondition.result.retryAfter.toString(),
-            [WORKFLOW_PROTOCOL_VERSION_HEADER]: WORKFLOW_PROTOCOL_VERSION
-          },
-          status: 429
-        });
-      } else if (detailedFinishCondition?.condition === "failure-callback") {
-        return new Response(
-          JSON.stringify({ result: detailedFinishCondition.result ?? void 0 }),
-          {
-            status: 200,
-            headers: {
-              [WORKFLOW_PROTOCOL_VERSION_HEADER]: WORKFLOW_PROTOCOL_VERSION
-            }
-          }
+}
+function normalizeRegionHeader(region) {
+  if (!region) {
+    return void 0;
+  }
+  region = region.replaceAll("-", "_").toUpperCase();
+  if (VALID_REGIONS.includes(region)) {
+    return region;
+  }
+  console.warn(
+    `[Upstash Workflow] Invalid UPSTASH-REGION header value: "${region}". Expected one of: ${VALID_REGIONS.join(
+      ", "
+    )}.`
+  );
+  return void 0;
+}
+
+// src/serve/multi-region/handlers.ts
+var getHandlersForRequest = (qstashHandlers, regionHeader, isFirstInvocation) => {
+  if (qstashHandlers.mode === "single-region") {
+    return qstashHandlers.handlers;
+  }
+  let targetRegion;
+  if (isFirstInvocation) {
+    targetRegion = qstashHandlers.defaultRegion;
+  } else {
+    const normalizedRegion = regionHeader ? normalizeRegionHeader(regionHeader) : void 0;
+    targetRegion = normalizedRegion ?? qstashHandlers.defaultRegion;
+  }
+  const handler = qstashHandlers.handlers[targetRegion];
+  if (!handler) {
+    console.warn(
+      `[Upstash Workflow] No handler found for region "${targetRegion}". Falling back to default region.`
+    );
+    return qstashHandlers.handlers[qstashHandlers.defaultRegion];
+  }
+  return handler;
+};
+var createRegionalHandler = (environment, receiverConfig, region, clientOptions) => {
+  const clientEnv = readClientEnvironmentVariables(environment, region);
+  const client = new import_qstash10.Client({
+    ...clientOptions,
+    baseUrl: clientEnv.QSTASH_URL,
+    token: clientEnv.QSTASH_TOKEN
+  });
+  const receiver = getReceiver(environment, receiverConfig, region);
+  return { client, receiver };
+};
+var shouldUseMultiRegionMode = (environment, qstashClientOption) => {
+  const hasRegionEnv = Boolean(getRegionFromEnvironment(environment));
+  if (hasRegionEnv && (!qstashClientOption || !("http" in qstashClientOption))) {
+    return {
+      isMultiRegion: true,
+      defaultRegion: getRegionFromEnvironment(environment),
+      clientOptions: qstashClientOption
+    };
+  } else {
+    return { isMultiRegion: false };
+  }
+};
+var getQStashHandlers = ({
+  environment,
+  qstashClientOption,
+  receiverConfig
+}) => {
+  const multiRegion = shouldUseMultiRegionMode(environment, qstashClientOption);
+  if (multiRegion.isMultiRegion) {
+    const regions = ["US_EAST_1", "EU_CENTRAL_1"];
+    const handlers = {};
+    for (const region of regions) {
+      try {
+        handlers[region] = createRegionalHandler(
+          environment,
+          receiverConfig,
+          region,
+          multiRegion.clientOptions
         );
+      } catch (error) {
+        console.warn(`[Upstash Workflow] Failed to create handler for region ${region}:`, error);
       }
-      return new Response(JSON.stringify({ workflowRunId }), {
-        status: 200,
-        headers: {
-          [WORKFLOW_PROTOCOL_VERSION_HEADER]: WORKFLOW_PROTOCOL_VERSION
-        }
+    }
+    return {
+      mode: "multi-region",
+      handlers,
+      defaultRegion: multiRegion.defaultRegion
+    };
+  } else {
+    return {
+      mode: "single-region",
+      handlers: {
+        client: qstashClientOption && "http" in qstashClientOption ? qstashClientOption : new import_qstash10.Client({
+          ...qstashClientOption,
+          baseUrl: environment.QSTASH_URL,
+          token: environment.QSTASH_TOKEN
+        }),
+        receiver: getReceiver(environment, receiverConfig)
+      }
+    };
+  }
+};
+var getReceiver = (environment, receiverConfig, region) => {
+  if (typeof receiverConfig === "string") {
+    if (receiverConfig === "set-to-undefined") {
+      return void 0;
+    }
+    const receiverEnv = readReceiverEnvironmentVariables(environment, region);
+    return receiverEnv.QSTASH_CURRENT_SIGNING_KEY && receiverEnv.QSTASH_NEXT_SIGNING_KEY ? new import_qstash10.Receiver({
+      currentSigningKey: receiverEnv.QSTASH_CURRENT_SIGNING_KEY,
+      nextSigningKey: receiverEnv.QSTASH_NEXT_SIGNING_KEY
+    }) : void 0;
+  } else {
+    return receiverConfig;
+  }
+};
+var getQStashHandlerOptions = (...params) => {
+  const handlers = getQStashHandlers(...params);
+  return {
+    qstashHandlers: handlers,
+    defaultReceiver: handlers.mode === "single-region" ? handlers.handlers.receiver : handlers.handlers[handlers.defaultRegion].receiver,
+    defaultClient: handlers.mode === "single-region" ? handlers.handlers.client : handlers.handlers[handlers.defaultRegion].client
+  };
+};
+
+// src/middleware/middleware.ts
+var WorkflowMiddleware = class {
+  name;
+  initCallbacks;
+  /**
+   * Callback functions
+   *
+   * Initially set to undefined, will be populated after init is called
+   */
+  middlewareCallbacks = void 0;
+  constructor(parameters) {
+    this.name = parameters.name;
+    if ("init" in parameters) {
+      this.initCallbacks = parameters.init;
+    } else {
+      this.middlewareCallbacks = parameters.callbacks;
+    }
+  }
+  async ensureInit() {
+    if (!this.middlewareCallbacks) {
+      if (!this.initCallbacks) {
+        throw new WorkflowError(`Middleware "${this.name}" has no callbacks or init defined.`);
+      }
+      this.middlewareCallbacks = await this.initCallbacks();
+    }
+  }
+  /**
+   * Gets a callback function by name.
+   *
+   * @param callback name of the callback to retrieve
+   */
+  getCallback(callback) {
+    return this.middlewareCallbacks?.[callback];
+  }
+};
+
+// src/middleware/logging.ts
+var loggingMiddleware = new WorkflowMiddleware({
+  name: "logging",
+  callbacks: {
+    afterExecution(params) {
+      const { context, ...rest } = params;
+      console.log("  [Upstash Workflow]: Step executed:", {
+        workflowRunId: context.workflowRunId,
+        ...rest
+      });
+    },
+    beforeExecution(params) {
+      const { context, ...rest } = params;
+      console.log("  [Upstash Workflow]: Step execution started:", {
+        workflowRunId: context.workflowRunId,
+        ...rest
       });
     },
+    runStarted(params) {
+      const { context, ...rest } = params;
+      console.log("  [Upstash Workflow]: Workflow run started:", {
+        workflowRunId: context.workflowRunId,
+        ...rest
+      });
+    },
+    runCompleted(params) {
+      const { context, ...rest } = params;
+      console.log("  [Upstash Workflow]: Workflow run completed:", {
+        workflowRunId: context.workflowRunId,
+        ...rest
+      });
+    },
+    onError: onErrorWithConsole,
+    onWarning: onWarningWithConsole,
+    onInfo: onInfoWithConsole
+  }
+});
+
+// src/serve/options.ts
+var createResponseData = (workflowRunId, detailedFinishCondition) => {
+  const baseHeaders = {
+    [WORKFLOW_PROTOCOL_VERSION_HEADER]: WORKFLOW_PROTOCOL_VERSION,
+    "Upstash-workflow-sdk": VERSION
+  };
+  if (detailedFinishCondition?.condition === "auth-fail") {
+    return {
+      text: JSON.stringify({
+        message: AUTH_FAIL_MESSAGE,
+        workflowRunId
+      }),
+      status: 400,
+      headers: baseHeaders
+    };
+  } else if (detailedFinishCondition?.condition === "non-retryable-error") {
+    return {
+      text: JSON.stringify(formatWorkflowError(detailedFinishCondition.result)),
+      status: 489,
+      headers: {
+        ...baseHeaders,
+        "Upstash-NonRetryable-Error": "true"
+      }
+    };
+  } else if (detailedFinishCondition?.condition === "retry-after-error") {
+    return {
+      text: JSON.stringify(formatWorkflowError(detailedFinishCondition.result)),
+      status: 429,
+      headers: {
+        ...baseHeaders,
+        "Retry-After": detailedFinishCondition.result.retryAfter.toString()
+      }
+    };
+  } else if (detailedFinishCondition?.condition === "failure-callback-executed") {
+    return {
+      text: JSON.stringify({ result: detailedFinishCondition.result ?? void 0 }),
+      status: 200,
+      headers: baseHeaders
+    };
+  } else if (detailedFinishCondition?.condition === "failure-callback-undefined") {
+    return {
+      text: JSON.stringify({
+        workflowRunId,
+        finishCondition: detailedFinishCondition.condition
+      }),
+      status: 200,
+      headers: {
+        ...baseHeaders,
+        "Upstash-Workflow-Failure-Callback-Notfound": "true"
+      }
+    };
+  }
+  return {
+    text: JSON.stringify({
+      workflowRunId,
+      finishCondition: detailedFinishCondition.condition
+    }),
+    status: 200,
+    headers: baseHeaders
+  };
+};
+var processOptions = (options, internalOptions) => {
+  const environment = options?.env ?? (typeof process === "undefined" ? {} : process.env);
+  const {
+    qstashHandlers,
+    defaultClient: qstashClient,
+    defaultReceiver: receiver
+  } = getQStashHandlerOptions({
+    environment,
+    qstashClientOption: options?.qstashClient,
+    receiverConfig: options && "receiver" in options ? options.receiver ? options.receiver : "set-to-undefined" : "not-set"
+  });
+  return {
+    qstashClient,
     initialPayloadParser: (initialRequest) => {
       if (!initialRequest) {
         return void 0;
@@ -3614,35 +3524,38 @@ var processOptions = (options) => {
         throw error;
       }
     },
-    receiver: receiverEnvironmentVariablesSet ? new import_qstash10.Receiver({
-      currentSigningKey: environment.QSTASH_CURRENT_SIGNING_KEY,
-      nextSigningKey: environment.QSTASH_NEXT_SIGNING_KEY
-    }) : void 0,
+    receiver,
     baseUrl: environment.UPSTASH_WORKFLOW_URL,
     env: environment,
-    retries: DEFAULT_RETRIES,
-    useJSONContent: false,
     disableTelemetry: false,
-    onError: console.error,
-    ...options
+    ...options,
+    // merge middlewares
+    middlewares: [options?.middlewares ?? [], options?.verbose ? [loggingMiddleware] : []].flat(),
+    internal: {
+      generateResponse: internalOptions?.generateResponse ?? ((responseData) => {
+        return new Response(responseData.text, {
+          status: responseData.status,
+          headers: responseData.headers
+        });
+      }),
+      useJSONContent: internalOptions?.useJSONContent ?? false,
+      qstashHandlers
+    }
   };
 };
-var determineUrls = async (request, url, baseUrl, failureFunction, failureUrl, debug) => {
+var determineUrls = async (request, url, baseUrl, dispatchDebug) => {
   const initialWorkflowUrl = url ?? request.url;
   const workflowUrl = baseUrl ? initialWorkflowUrl.replace(/^(https?:\/\/[^/]+)(\/.*)?$/, (_, matchedBaseUrl, path) => {
     return baseUrl + (path || "");
   }) : initialWorkflowUrl;
   if (workflowUrl !== initialWorkflowUrl) {
-    await debug?.log("WARN", "ENDPOINT_START", {
-      warning: `Upstash Workflow: replacing the base of the url with "${baseUrl}" and using it as workflow endpoint.`,
-      originalURL: initialWorkflowUrl,
-      updatedURL: workflowUrl
+    await dispatchDebug("onInfo", {
+      info: `The workflow URL's base URL has been replaced with the provided baseUrl. Original URL: ${initialWorkflowUrl}, New URL: ${workflowUrl}`
     });
   }
-  const workflowFailureUrl = failureFunction ? workflowUrl : failureUrl;
   if (workflowUrl.includes("localhost")) {
-    await debug?.log("WARN", "ENDPOINT_START", {
-      message: `Workflow URL contains localhost. This can happen in local development, but shouldn't happen in production unless you have a route which contains localhost. Received: ${workflowUrl}`
+    await dispatchDebug("onInfo", {
+      info: `Workflow URL contains localhost. This can happen in local development, but shouldn't happen in production unless you have a route which contains localhost. Received: ${workflowUrl}`
     });
   }
   if (!(workflowUrl.startsWith("http://") || workflowUrl.startsWith("https://"))) {
@@ -3651,205 +3564,224 @@ var determineUrls = async (request, url, baseUrl, failureFunction, failureUrl, d
     );
   }
   return {
-    workflowUrl,
-    workflowFailureUrl
+    workflowUrl
   };
 };
 var AUTH_FAIL_MESSAGE = `Failed to authenticate Workflow request. If this is unexpected, see the caveat https://upstash.com/docs/workflow/basics/caveats#avoid-non-deterministic-code-outside-context-run`;
 
 // src/serve/index.ts
-var serveBase = (routeFunction, telemetry2, options) => {
+var serveBase = (routeFunction, telemetry2, options, internalOptions) => {
   const {
-    qstashClient,
-    onStepFinish,
     initialPayloadParser,
     url,
-    verbose,
-    receiver,
-    failureUrl,
     failureFunction,
     baseUrl,
     env,
-    retries,
-    retryDelay,
-    useJSONContent,
     disableTelemetry,
-    flowControl,
-    onError
-  } = processOptions(options);
+    middlewares,
+    internal
+  } = processOptions(options, internalOptions);
   telemetry2 = disableTelemetry ? void 0 : telemetry2;
-  const debug = WorkflowLogger.getLogger(verbose);
-  const handler = async (request) => {
-    await debug?.log("INFO", "ENDPOINT_START");
-    const { workflowUrl, workflowFailureUrl } = await determineUrls(
+  const { generateResponse: responseGenerator, useJSONContent } = internal;
+  const handler = async (request, middlewareManager) => {
+    await middlewareManager.dispatchDebug("onInfo", {
+      info: `Received request for workflow execution.`
+    });
+    const { workflowUrl } = await determineUrls(
       request,
       url,
       baseUrl,
-      failureFunction,
-      failureUrl,
-      debug
+      middlewareManager.dispatchDebug.bind(middlewareManager)
+    );
+    const { isFirstInvocation, workflowRunId, unknownSdk } = validateRequest(request);
+    const regionHeader = request.headers.get("upstash-region");
+    const { client: regionalClient, receiver: regionalReceiver } = getHandlersForRequest(
+      internal.qstashHandlers,
+      regionHeader,
+      isFirstInvocation
     );
     const requestPayload = await getPayload(request) ?? "";
-    await verifyRequest(requestPayload, request.headers.get("upstash-signature"), receiver);
-    const { isFirstInvocation, workflowRunId } = validateRequest(request);
-    debug?.setWorkflowRunId(workflowRunId);
-    const { rawInitialPayload, steps, isLastDuplicate, workflowRunEnded } = await parseRequest(
+    await verifyRequest(requestPayload, request.headers.get("upstash-signature"), regionalReceiver);
+    middlewareManager.assignWorkflowRunId(workflowRunId);
+    await middlewareManager.dispatchDebug("onInfo", {
+      info: `Run id identified. isFirstInvocation: ${isFirstInvocation}, unknownSdk: ${unknownSdk}`
+    });
+    const { rawInitialPayload, steps, isLastDuplicate, workflowRunEnded } = await parseRequest({
       requestPayload,
       isFirstInvocation,
+      unknownSdk,
       workflowRunId,
-      qstashClient.http,
-      request.headers.get("upstash-message-id"),
-      debug
-    );
+      requester: regionalClient.http,
+      messageId: request.headers.get("upstash-message-id"),
+      dispatchDebug: middlewareManager.dispatchDebug.bind(middlewareManager)
+    });
     if (workflowRunEnded) {
-      return onStepFinish(workflowRunId, "workflow-already-ended", {
-        condition: "workflow-already-ended"
-      });
+      return responseGenerator(
+        createResponseData(workflowRunId, {
+          condition: "workflow-already-ended"
+        })
+      );
     }
     if (isLastDuplicate) {
-      return onStepFinish(workflowRunId, "duplicate-step", {
-        condition: "duplicate-step"
-      });
+      return responseGenerator(
+        createResponseData(workflowRunId, {
+          condition: "duplicate-step"
+        })
+      );
     }
-    const failureCheck = await handleFailure(
+    const failureCheck = await handleFailure({
       request,
       requestPayload,
-      qstashClient,
+      qstashClient: regionalClient,
       initialPayloadParser,
       routeFunction,
       failureFunction,
       env,
-      retries,
-      retryDelay,
-      flowControl,
-      debug
-    );
+      dispatchDebug: middlewareManager.dispatchDebug.bind(middlewareManager)
+    });
     if (failureCheck.isErr()) {
       throw failureCheck.error;
-    } else if (failureCheck.value.result === "is-failure-callback") {
-      await debug?.log("WARN", "RESPONSE_DEFAULT", "failureFunction executed");
-      return onStepFinish(workflowRunId, "failure-callback", {
-        condition: "failure-callback",
-        result: failureCheck.value.response
+    } else if (failureCheck.value.result === "failure-function-executed") {
+      await middlewareManager.dispatchDebug("onInfo", {
+        info: `Handled failure callback.`
+      });
+      return responseGenerator(
+        createResponseData(workflowRunId, {
+          condition: "failure-callback-executed",
+          result: failureCheck.value.response
+        })
+      );
+    } else if (failureCheck.value.result === "failure-function-undefined") {
+      await middlewareManager.dispatchDebug("onInfo", {
+        info: `Failure callback invoked but no failure function defined.`
       });
+      return responseGenerator(
+        createResponseData(workflowRunId, {
+          condition: "failure-callback-undefined"
+        })
+      );
     }
     const invokeCount = Number(request.headers.get(WORKFLOW_INVOKE_COUNT_HEADER) ?? "0");
     const label = request.headers.get(WORKFLOW_LABEL_HEADER) ?? void 0;
     const workflowContext = new WorkflowContext({
-      qstashClient,
+      qstashClient: regionalClient,
       workflowRunId,
       initialPayload: initialPayloadParser(rawInitialPayload),
       headers: recreateUserHeaders(request.headers),
       steps,
       url: workflowUrl,
-      failureUrl: workflowFailureUrl,
-      debug,
       env,
-      retries,
-      retryDelay,
       telemetry: telemetry2,
       invokeCount,
-      flowControl,
-      label
+      label,
+      middlewareManager
     });
     const authCheck = await DisabledWorkflowContext.tryAuthentication(
       routeFunction,
       workflowContext
     );
     if (authCheck.isErr()) {
-      await debug?.log("ERROR", "ERROR", { error: authCheck.error.message });
       throw authCheck.error;
     } else if (authCheck.value === "run-ended") {
-      await debug?.log("ERROR", "ERROR", { error: AUTH_FAIL_MESSAGE });
-      return onStepFinish(
-        isFirstInvocation ? "no-workflow-id" : workflowContext.workflowRunId,
-        "auth-fail",
-        { condition: "auth-fail" }
+      await middlewareManager.dispatchDebug("onError", {
+        error: new Error(AUTH_FAIL_MESSAGE)
+      });
+      return responseGenerator(
+        createResponseData(isFirstInvocation ? "no-workflow-id" : workflowContext.workflowRunId, {
+          condition: "auth-fail"
+        })
       );
     }
     const callReturnCheck = await handleThirdPartyCallResult({
       request,
       requestPayload: rawInitialPayload,
-      client: qstashClient,
+      client: regionalClient,
       workflowUrl,
-      failureUrl: workflowFailureUrl,
-      retries,
-      retryDelay,
-      flowControl,
       telemetry: telemetry2,
-      debug
+      middlewareManager
     });
     if (callReturnCheck.isErr()) {
-      await debug?.log("ERROR", "SUBMIT_THIRD_PARTY_RESULT", {
-        error: callReturnCheck.error.message
-      });
       throw callReturnCheck.error;
     } else if (callReturnCheck.value === "continue-workflow") {
       const result = isFirstInvocation ? await triggerFirstInvocation({
         workflowContext,
         useJSONContent,
         telemetry: telemetry2,
-        debug,
-        invokeCount
+        invokeCount,
+        middlewareManager,
+        unknownSdk
       }) : await triggerRouteFunction({
-        onStep: async () => routeFunction(workflowContext),
+        onStep: async () => {
+          if (steps.length === 1) {
+            await middlewareManager.dispatchLifecycle("runStarted", {});
+          }
+          return await routeFunction(workflowContext);
+        },
         onCleanup: async (result2) => {
-          await triggerWorkflowDelete(workflowContext, result2, debug);
+          await middlewareManager.dispatchLifecycle("runCompleted", {
+            result: result2
+          });
+          await triggerWorkflowDelete(
+            workflowContext,
+            result2,
+            false,
+            middlewareManager.dispatchDebug.bind(middlewareManager)
+          );
         },
         onCancel: async () => {
           await makeCancelRequest(workflowContext.qstashClient.http, workflowRunId);
         },
-        debug
+        middlewareManager
       });
       if (result.isOk() && isInstanceOf(result.value, WorkflowNonRetryableError)) {
-        return onStepFinish(workflowRunId, result.value, {
-          condition: "non-retryable-error",
-          result: result.value
-        });
+        return responseGenerator(
+          createResponseData(workflowRunId, {
+            condition: "non-retryable-error",
+            result: result.value
+          })
+        );
       }
       if (result.isOk() && isInstanceOf(result.value, WorkflowRetryAfterError)) {
-        return onStepFinish(workflowRunId, result.value, {
-          condition: "retry-after-error",
-          result: result.value
-        });
+        return responseGenerator(
+          createResponseData(workflowRunId, {
+            condition: "retry-after-error",
+            result: result.value
+          })
+        );
       }
       if (result.isErr()) {
-        await debug?.log("ERROR", "ERROR", { error: result.error.message });
         throw result.error;
       }
-      await debug?.log("INFO", "RESPONSE_WORKFLOW");
-      return onStepFinish(workflowContext.workflowRunId, "success", {
-        condition: "success"
+      await middlewareManager.dispatchDebug("onInfo", {
+        info: `Workflow endpoint execution completed successfully.`
       });
+      return responseGenerator(
+        createResponseData(workflowContext.workflowRunId, {
+          condition: "success"
+        })
+      );
     } else if (callReturnCheck.value === "workflow-ended") {
-      return onStepFinish(workflowContext.workflowRunId, "workflow-already-ended", {
-        condition: "workflow-already-ended"
-      });
+      return responseGenerator(
+        createResponseData(workflowContext.workflowRunId, {
+          condition: "workflow-already-ended"
+        })
+      );
     }
-    await debug?.log("INFO", "RESPONSE_DEFAULT");
-    return onStepFinish("no-workflow-id", "fromCallback", {
-      condition: "fromCallback"
-    });
+    return responseGenerator(
+      createResponseData(workflowContext.workflowRunId, {
+        condition: "fromCallback"
+      })
+    );
   };
   const safeHandler = async (request) => {
+    const middlewareManager = new MiddlewareManager(middlewares);
     try {
-      return await handler(request);
+      return await handler(request, middlewareManager);
     } catch (error) {
       const formattedError = formatWorkflowError(error);
-      try {
-        onError?.(error);
-      } catch (onErrorError) {
-        const formattedOnErrorError = formatWorkflowError(onErrorError);
-        const errorMessage = `Error while running onError callback: '${formattedOnErrorError.message}'.
-Original error: '${formattedError.message}'`;
-        console.error(errorMessage);
-        return new Response(JSON.stringify({ error: errorMessage }), {
-          status: 500,
-          headers: {
-            [WORKFLOW_PROTOCOL_VERSION_HEADER]: WORKFLOW_PROTOCOL_VERSION
-          }
-        });
-      }
+      await middlewareManager.dispatchDebug("onError", {
+        error: isInstanceOf(error, Error) ? error : new Error(formattedError.message)
+      });
       return new Response(JSON.stringify(formattedError), {
         status: 500,
         headers: {
@@ -3896,10 +3828,14 @@ function createExpressHandler(params) {
       headers: new Headers(request_.headers),
       body: requestBody
     });
-    const { handler: serveHandler } = serveBase(routeFunction, telemetry, {
-      ...options,
-      useJSONContent: true
-    });
+    const { handler: serveHandler } = serveBase(
+      routeFunction,
+      telemetry,
+      options,
+      {
+        useJSONContent: true
+      }
+    );
     const response = await serveHandler(webRequest);
     for (const [key, value] of response.headers.entries()) {
       res.setHeader(key, value);
@@ -3919,7 +3855,8 @@ var createWorkflow = (...params) => {
   return {
     routeFunction,
     options,
-    workflowId: void 0
+    workflowId: void 0,
+    useJSONContent: true
   };
 };
 var serveMany = (workflows, options) => {