Add user stack track to error reporting (#218)

pass through RunResult to improve error line tracking

add example of catching an error

Fixes #167

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

<!-- This is an auto-generated comment: release notes by coderabbit.ai -->

## Summary by CodeRabbit

## Release Notes

* **New Features**
  * Added example workflow demonstrating error catching and automatic retry mechanisms for failed operations.

* **Improvements**
  * Enhanced workflow step execution with improved error handling and explicit result state interpretation.

* **Tests**
  * Added comprehensive test coverage for workflow step execution, error propagation, and cancellation scenarios.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: ianmacartney

example/convex/_generated/api.d.ts

@@ -9,6 +9,7 @@
  */
 
 import type * as admin from "../admin.js";
+import type * as catchError from "../catchError.js";
 import type * as example from "../example.js";
 import type * as nestedWorkflow from "../nestedWorkflow.js";
 import type * as passingSignals from "../passingSignals.js";
@@ -23,6 +24,7 @@ import type {
 
 declare const fullApi: ApiFromModules<{
   admin: typeof admin;
+  catchError: typeof catchError;
   example: typeof example;
   nestedWorkflow: typeof nestedWorkflow;
   passingSignals: typeof passingSignals;

example/convex/catchError.ts

@@ -0,0 +1,47 @@
+import { v } from "convex/values";
+import { WorkflowId } from "@convex-dev/workflow";
+import { internal } from "./_generated/api.js";
+import { internalAction, internalMutation } from "./_generated/server.js";
+import { workflow } from "./example.js";
+
+export const alwaysFails = internalAction({
+  args: {},
+  returns: v.null(),
+  handler: async (_ctx, _args) => {
+    throw new Error("This action always fails for testing");
+  },
+});
+
+export const catchErrorWorkflow = workflow.define({
+  args: { manualRetries: v.number() },
+  returns: v.number(),
+  handler: async (step, args): Promise<number> => {
+    let i;
+    for (i = 0; i < args.manualRetries + 1; i++) {
+      try {
+        await step.runAction(internal.catchError.alwaysFails, {});
+        return i;
+      } catch (e) {
+        if (e instanceof Error) {
+          console.error(e.name, e.message, e.stack);
+        } else {
+          console.error("Caught error in workflow handler:", e);
+        }
+      }
+    }
+    return i;
+  },
+});
+
+export const start = internalMutation({
+  args: { manualRetries: v.optional(v.number()) },
+  returns: v.string(),
+  handler: async (ctx, args) => {
+    const id: WorkflowId = await workflow.start(
+      ctx,
+      internal.catchError.catchErrorWorkflow,
+      { manualRetries: args.manualRetries ?? 0 },
+    );
+    return id;
+  },
+});

src/client/step.ts

@@ -44,8 +44,7 @@ export type StepRequest = {
   retry: RetryBehavior | boolean | undefined;
   schedulerOptions: SchedulerOptions;
 
-  resolve: (result: unknown) => void;
-  reject: (error: unknown) => void;
+  resolve: (result: RunResult) => void;
 };
 
 export class StepExecutor {
@@ -140,17 +139,7 @@ export class StepExecutor {
         `Assertion failed: no outcome for completed function call`,
       );
     }
-    switch (entry.step.runResult.kind) {
-      case "success":
-        message.resolve(entry.step.runResult.returnValue);
-        break;
-      case "failed":
-        message.reject(new Error(entry.step.runResult.error));
-        break;
-      case "canceled":
-        message.reject(new Error("Canceled"));
-        break;
-    }
+    message.resolve(entry.step.runResult);
   }
 
   async startSteps(messages: StepRequest[]): Promise<JournalEntry[]> {