feat(workflow-engine): add retryOnTimeout opt-in for step timeout retries

Author: abcxff

rivetkit-typescript/packages/workflow-engine/docs/retries.md

@@ -24,7 +24,7 @@ await ctx.step({
 
 - `maxRetries` defaults to 3.
 - `retryBackoffBase` and `retryBackoffMax` control exponential delay.
-- `timeout` limits how long the step can run; timeouts are treated as critical failures.
+- `timeout` limits how long the step can run; by default a timeout is treated as a critical failure with no retry. Set `retryOnTimeout: true` on the step to retry timeouts like any other error.
 
 ## Unrecoverable Errors
 
@@ -46,7 +46,7 @@ await ctx.step("halt", async () => {
 });
 ```
 
-`StepTimeoutError` is also treated as critical, so timeouts bypass retries.
+`StepTimeoutError` is treated as critical by default and bypasses retries. Opt into normal retry behavior with `retryOnTimeout: true`; when retries exhaust on a timeout the `try`-step failure `kind` is `"timeout"`.
 
 ## Exhaustion and Recovery
 

rivetkit-typescript/packages/workflow-engine/src/context.ts

@@ -941,8 +941,9 @@ export class WorkflowContextImpl implements WorkflowContextInterface {
 			}
 			entry.dirty = true;
 
-			// Timeout errors are treated as critical (no retry)
-			if (error instanceof StepTimeoutError) {
+			// Timeout errors are treated as critical by default. Steps opt
+			// into retrying on timeout with retryOnTimeout: true.
+			if (error instanceof StepTimeoutError && !config.retryOnTimeout) {
 				metadata.status = "exhausted";
 				metadata.error = String(error);
 				await this.notifyStepError(config, metadata.attempts, error, {
@@ -1008,7 +1009,10 @@ export class WorkflowContextImpl implements WorkflowContextInterface {
 				attachTryStepFailure(
 					new StepExhaustedError(config.name, String(error)),
 					{
-						kind: "exhausted",
+						kind:
+							error instanceof StepTimeoutError
+								? "timeout"
+								: "exhausted",
 						stepName: config.name,
 						attempts: metadata.attempts,
 						error: extractErrorInfo(error),
@@ -1027,7 +1031,9 @@ export class WorkflowContextImpl implements WorkflowContextInterface {
 	 *
 	 * Note: This does NOT cancel the underlying operation. JavaScript Promises
 	 * cannot be cancelled once started. When a timeout occurs:
-	 * - The step is marked as failed with StepTimeoutError
+	 * - The step is rejected with StepTimeoutError. By default this is treated
+	 *   as a critical failure with no retry. Set retryOnTimeout: true on the
+	 *   step config to retry timeouts like any other error.
 	 * - The underlying async operation continues running in the background
 	 * - Any side effects from the operation may still occur
 	 *

rivetkit-typescript/packages/workflow-engine/src/types.ts

@@ -399,6 +399,8 @@ export interface StepConfig<T> {
 	retryBackoffMax?: number;
 	/** Timeout in ms for step execution (default: 30000). Set to 0 to disable. */
 	timeout?: number;
+	/** If true, step timeouts retry like any other error instead of failing immediately as critical. Default: false. */
+	retryOnTimeout?: boolean;
 }
 
 export type TryStepCatchKind =

rivetkit-typescript/packages/workflow-engine/tests/steps.test.ts

@@ -519,6 +519,54 @@ for (const mode of modes) {
 			).rejects.toThrow(CriticalError);
 		});
 
+		it("should retry steps that exceed timeout when retryOnTimeout is set", async () => {
+			let attempts = 0;
+			const workflow = async (ctx: WorkflowContextInterface) => {
+				return await ctx.step({
+					name: "timeout-step",
+					timeout: 5,
+					retryOnTimeout: true,
+					maxRetries: 2,
+					retryBackoffBase: 1,
+					retryBackoffMax: 1,
+					run: async () => {
+						attempts++;
+						await new Promise((resolve) => setTimeout(resolve, 25));
+						return "late";
+					},
+				});
+			};
+
+			if (mode === "yield") {
+				const firstResult = await runWorkflow(
+					"wf-1",
+					workflow,
+					undefined,
+					driver,
+					{ mode },
+				).result;
+				expect(firstResult.state).toBe("sleeping");
+				await new Promise((resolve) => setTimeout(resolve, 10));
+
+				const secondResult = await runWorkflow(
+					"wf-1",
+					workflow,
+					undefined,
+					driver,
+					{ mode },
+				).result;
+				expect(secondResult.state).toBe("sleeping");
+				await new Promise((resolve) => setTimeout(resolve, 10));
+			}
+
+			await expect(
+				runWorkflow("wf-1", workflow, undefined, driver, { mode })
+					.result,
+			).rejects.toThrow(StepExhaustedError);
+
+			expect(attempts).toBe(3);
+		});
+
 		it("should fail when a step is not awaited", async () => {
 			const workflow = async (ctx: WorkflowContextInterface) => {
 				const first = ctx.step("step-a", async () => "a");