fix: helpful error when external returns a non-cloneable value

src/conversation.ts

@@ -926,7 +926,18 @@ First return your data from `external` and then resume update handling using `wa
         // Recover values after loading them
         const ret = await this.controls.action(action, "external");
         // Clone them to provide immutability
-        const cloned = structuredClone(ret);
+        let cloned: typeof ret;
+        try {
+            cloned = structuredClone(ret);
+        } catch (err) {
+            throw new Error(
+                "The value returned from `external` could not be cloned \
+for replay. Return a value that `structuredClone` can handle, or pass \
+`beforeStore` and `afterLoad` to serialize it yourself.",
+                // @ts-ignore not available on old Node versions
+                { cause: err },
+            );
+        }
         if (cloned.ok) {
             return await afterLoad(cloned.ret);
         } else {

test/conversation.test.ts

@@ -340,6 +340,24 @@ describe("Conversation", () => {
         assertEquals(i, 1);
         assertEquals(j, 0);
     });
+    it("should throw a helpful error when `external` returns a non-cloneable value", async () => {
+        const ctx = mkctx();
+        let caught: unknown;
+        async function convo(conversation: Convo) {
+            try {
+                await conversation.external(() => () => 0);
+            } catch (e) {
+                caught = e;
+            }
+            await conversation.wait();
+        }
+        const first = await enterConversation(convo, ctx);
+        assertEquals(first.status, "handled");
+        assertInstanceOf(caught, Error);
+        assertStringIncludes(caught.message, "could not be cloned");
+        assertStringIncludes(caught.message, "beforeStore");
+        assert(caught.cause instanceof Error);
+    });
     it("should support external with custom error formats", async () => {
         const ctx = mkctx();
         let i = 0;