mirror of
https://github.com/vercel/workflow.git
synced 2026-09-14 19:59:43 +08:00
backport/pr-2718-to-stable
21 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 github-actions[bot]
|
4763e06eb7 |
[docs] Add "Step executed multiple times" error page (#2310) (#2333)
Co-authored-by: Peter Wielander <mittgfu@gmail.com> |
||
|
github-actions[bot]
|
326d93a4ae |
Backport #2012: Expose conflicting run id on hook conflicts (#2016)
Co-authored-by: Pranay Prakash <pranay.gp@gmail.com> Co-authored-by: Nathan Rajlich <n@n8.io> Co-authored-by: Peter Wielander <mittgfu@gmail.com> Co-authored-by: Peter Wielander <peter.wielander@vercel.com> |
||
|
github-actions[bot]
|
b385a2d6eb |
[backport] classify SDK encryption failures as RUNTIME_ERROR (#2145) (#2165)
Co-authored-by: Nathan Rajlich <n@n8.io> Co-authored-by: Peter Wielander <mittgfu@gmail.com> |
||
|
Pranay Prakash
|
5fd7d9c2a1 | Retry replay divergence before failing event logs (#2208) | ||
|
John Lindquist
|
5b6d0779c0 |
docs: March docs audit and alignment (#1466)
* docs: clarify Next monorepo setup Prevent confusion when Next.js apps live below the repository root and workflow code imports sibling workspace packages. This documents the output tracing root requirement at the point where users configure withWorkflow, so monorepo setups follow the same working patterns as the shipped Next.js integration instead of failing due to unresolved workspace imports. Ploop-Iter: 1 * ploop: iteration 2 checkpoint Automated checkpoint commit. Ploop-Iter: 2 * ploop: iteration 3 checkpoint Automated checkpoint commit. Ploop-Iter: 3 * docs: audit recent documentation coverage Capture recent workflow documentation updates so the public docs and package guidance stay aligned with the implementation and current docs-typecheck behavior. Ploop-Iter: 1 * docs: align docs-typecheck docs Document the current docs verification contract so contributors do not assume JavaScript examples are type-checked when only TypeScript snippets are enforced today. Add regression coverage around the README language and framework integration guidance to keep those docs aligned with the implemented Next.js and docs-typecheck behavior as future changes land. Ploop-Iter: 2 * docs: add start() troubleshooting guidance Document the most common causes of the invalid workflow function error so users can resolve start() failures from the API docs and Next.js setup flow without having to infer build-time requirements from runtime behavior. Keep the new troubleshooting page aligned with the shipped runtime message and add regression coverage so future wording or cross-link changes do not silently break that guidance. Ploop-Iter: 3 * docs: align NestJS setup docs Document both supported NestJS module formats and add a regression check so the getting-started guide stays aligned with the package README as the integration evolves. Ploop-Iter: 1 * docs: tighten NestJS CommonJS guidance Keep the NestJS getting-started guide consistent across the ESM and CommonJS paths so readers do not mix module settings or import styles mid-setup. Strengthen the docs regression coverage around the later guide sections so future edits are more likely to preserve the supported CommonJS path documented in the package README. Ploop-Iter: 2 * docs: align docs with recent workflow guidance Document the recently added troubleshooting and observability patterns so the public docs stay aligned with the behavior users now encounter in practice. This keeps the NestJS guide, workflow API reference, and docs regression coverage in sync with the runtime-facing guidance from recent changes. Ploop-Iter: 3 * docs: audit docs coverage Why: keep the docs aligned with recent API and runtime behavior changes so examples and reference pages don’t drift from the supported surface. Ploop-Iter: 1 * test: add docs audit guards Add regression coverage for doc surfaces that are easy to drift from implementation so docs audits catch mismatches early and keep published guidance aligned with the supported API surface. Ploop-Iter: 2 * docs: add docs audit guards Keep new observability and server-testing guidance anchored to machine-readable interfaces so follow-up implementation changes do not silently drift away from the documented agent and automation patterns. Ploop-Iter: 3 * docs: align observability troubleshooting guidance Keep the docs consistent so users get the same guidance when debugging hook token collisions and correlating workflow events with platform logs. This prevents the event-sourcing reference from drifting away from the observability and error docs, and adds guard tests to catch regressions. Ploop-Iter: 1 * Remove the unreferenced image file img-a-clean-minimal-technical-architecture-d-2026-02-27T14-07-52-1.png from the repo root, workbench/fastify/public/index.html (a Nitro example mistakenly placed in the fastify workbench by a ploop checkpoint), all .claude/worktrees/* submodule references, and all 15 string-presence audit guard tests in packages/docs-typecheck/src/__tests__/ (they only assert keyword presence, not semantic correctness). None of these belong in the docs audit PR. * Address all PR #1466 review feedback from VaguelySerious, pranaygp, and ijjk: 1. Remove the "Machine-Readable Surfaces" section from docs/content/docs/observability/index.mdx (reviewers say it's unnecessary and already in world docs) 2. Remove all @skip-typecheck annotations from durable-agent.mdx (8) and server-based.mdx (1) — types exist in built packages/ai/dist after pnpm build 3. In durable-agent.mdx, change "machine-readable tool activity" to "tool call details" in the stream() return description 4. In durable-agent.mdx "Aborting Long-Running Streams" section, add a warning callout that abortSignal is not yet supported (blocked by #1301), recommend timeout instead 5. In event-sourcing.mdx, update requestId description: "On Vercel, requestId is the platform request ID when available. Other worlds are not expected to provide a requestId." 6. In get-world.mdx, change "user-friendly names from the machine-readable workflowName field" to "human-readable names from the workflowName field" 7. In start-invalid-workflow-function.mdx, add "// Does NOT work" comment above the bad example line 8. In with-workflow.mdx: reframe outputFileTracingRoot as a workaround (Next.js auto-detects by default per ijjk); change options description from "control local development behavior" to "configure the Next.js integration"; scope the callout to "workflows.local options only affect local development" 9. Drop the withWorkflow() options callout from docs/content/docs/getting-started/next.mdx 10. Remove the Next.js-specific outputFileTracingRoot callout from framework-integrations.mdx 11. Add a Troubleshooting section with the start() invalid-workflow-function error to all 9 non-Next getting-started guides (astro, express, fastify, hono, nestjs, nitro, nuxt, sveltekit, vite), each with framework-appropriate config check in point 2 * docs: absorb unique accuracy fixes from PR #1200 Cherry-picked 6 still-needed fixes from #1200 that aren't covered by this audit PR or #1516: - Fix npx workflow description (observability) - Remove fetch from restricted modules list (errors) - Fix package name @workflow-worlds/postgres → @workflow/world-postgres (deploying) - Fix stream wording (foundations/starting-workflows) - Fix import path simple → simple-streaming (foundations/streaming) - Add close(), getEncryptionKeyForRun(), writeToStreamMulti() to World interface, update create() and streamer signatures (deploying/building-a-world) * docs: address review feedback on March docs audit - durable-agent.mdx: "structured tool activity" → "tool call information" per VaguelySerious's suggestion - next.mdx: drop monorepo callout from getting-started per pranaygp (too much context too early; info is in withWorkflow API ref) * docs: fix 2 typecheck failures in encryption and nestjs guides - encryption.mdx: add skip-typecheck for interface signature block (getEncryptionKeyForRun overloads are not runnable code) - nestjs.mdx: add skip-typecheck for WorkflowModule.forRoot config snippet (fragment inside callout, full import shown above) Verified: pnpm vitest run passes 300/300 in docs-typecheck. |
||
|
Harpreet
|
cdf90d5a38 |
Rename Workflow DevKit to Workflow SDK, remove beta badge, add tweet wall (#1541)
* Rename Workflow DevKit to Workflow SDK, remove beta badge, add tweet wall - Rename "Workflow DevKit" to "Workflow SDK" across all files (~108 files) - Rename standalone "WDK" references to "Workflow SDK" - Remove beta badge from homepage hero - Add tweet wall component to homepage with 4 builder testimonials Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Rename Workflow DevKit to Workflow SDK, remove beta badge, add tweet wall - Rename "Workflow DevKit" to "Workflow SDK" across all files (~108 files) - Rename standalone "WDK" references to "Workflow SDK" - Remove beta badge from homepage hero - Add tweet wall component to homepage with 4 builder testimonials Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Harpreet Arora <harpreet.txt@gmail.com> * Address review: fix missed trigger phrase renames and bump skill versions - Rename "workflow devkit" to "workflow sdk" in trigger phrases for both skill files - Bump workflow-init SKILL.md version to 1.1 - Bump workflow SKILL.md version to 1.5 - Note: CLAUDE.md is a symlink to AGENTS.md, already renamed Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Harpreet Arora <harpreet.txt@gmail.com> * link correct tweet --------- Signed-off-by: Harpreet Arora <harpreet.txt@gmail.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: Karthik Kalyanaraman <karthik.kalyanaraman@vercel.com> |
||
|
Nathan Rajlich
|
7db491b89c | Add Workflow Globals reference page documenting available workflow VM APIs (#1548) | ||
|
Pranay Prakash
|
672d9195a4 |
Fix step/workflow not found errors to fail gracefully instead of queue retry (#1452)
* feat: enhance error handling for missing workflow functions Slack-Thread: https://vercel.slack.com/archives/C09G3EQAL84/p1773856370214769?thread_ts=1773856370.214769&cid=C09G3EQAL84 Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * fix: update step not found handling to match FatalError pattern Move step function validation after step_started and call step_failed directly if not found. Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * changes Signed-off-by: Pranay Prakash <pranay.gp@gmail.com> * feat: add StepNotRegisteredError and WorkflowNotRegisteredError semantic errors Introduce dedicated error types for when step/workflow functions are not registered in the current deployment, replacing generic WorkflowRuntimeError. These are infrastructure errors (not user code errors) with proper error slugs, docs pages, and a new FUNCTION_NOT_REGISTERED error code. Step not found fails the step (like FatalError) so the workflow can handle it gracefully. Workflow not found fails the run. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: address PR review comments - Remove FUNCTION_NOT_REGISTERED error code, use RUNTIME_ERROR instead - Use .is() instead of instanceof for WorkflowRuntimeError check in runtime.ts - Remove non-working example from WorkflowNotRegisteredError docs (custom errors not serialized yet) - Update all references from FUNCTION_NOT_REGISTERED to RUNTIME_ERROR Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * feat: add e2e tests for step/workflow not registered errors and fix docs typecheck E2E tests: - WorkflowNotRegisteredError: start a run with a fake workflowId, verify the run fails with RUNTIME_ERROR - StepNotRegisteredError (caught): workflow catches the step failure, verify workflow completes and step is marked failed - StepNotRegisteredError (uncaught): verify the run fails when workflow doesn't catch the error Step not registered is tested by manually invoking useStep with a non-existent step ID in the workflow VM — this is the same pattern the SWC transform generates for real step calls. Also fix docs typecheck by using declare/\@setup pattern instead of \@skip-typecheck for code samples. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: cast globalThis to any for Symbol index access in e2e workflow TypeScript's strict mode doesn't allow using a symbol to index globalThis. Cast to any since this runs in the workflow VM where the symbol is defined. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: classify WorkflowNotRegisteredError as RUNTIME_ERROR The .is() check uses name-based matching, so WorkflowNotRegisteredError (name='WorkflowNotRegisteredError') doesn't match WorkflowRuntimeError.is(). Add explicit check in classifyRunError so the error code is RUNTIME_ERROR instead of USER_ERROR. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: use instanceof for WorkflowRuntimeError checks, improve docs Address PR review feedback: 1. Revert .is() checks back to instanceof WorkflowRuntimeError in runtime.ts and classify-error.ts. instanceof catches all subclasses (current and future), which is the correct behavior for these catch blocks. 2. Remove duplicated try/catch example from step-not-registered-error API reference (troubleshooting page already has it). 3. Add Callout in API reference docs clarifying that .is() works in server-side Node.js code but not inside "use workflow" functions where errors arrive deserialized from the event log. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * changes Signed-off-by: Pranay Prakash <pranay.gp@gmail.com> --------- Signed-off-by: Pranay Prakash <pranay.gp@gmail.com> Co-authored-by: v0 <v0[bot]@users.noreply.github.com> Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|
Pranay Prakash
|
32cc0755bd |
docs: document error codes and remove docs typecheck import inference (#1445)
* docs: document error codes in errors and retries guide Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * changes Signed-off-by: Pranay Prakash <pranay.gp@gmail.com> * docs: address PR review comments on error codes guide - Add missing `start` import from `workflow/api` - Note that `cause.code` may be undefined for older runs - Remove invalid `--withData` flag and use `npx workflow` CLI style - Remove empty changeset (docs-only change needs no changeset) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: correct WorkflowRunFailedError import and docs typecheck - Import from `@workflow/errors` instead of `workflow` (not re-exported) - Add WorkflowRunFailedError to import inference map - Add myWorkflow placeholder to docs globals Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: remove import inference from docs typecheck, add explicit imports Remove the import-inference system that auto-added imports to doc snippets before typechecking. This was masking real issues — if a snippet imported from the wrong module or was missing an import, the typechecker silently fixed it instead of catching the bug. All 24 affected doc snippets now have explicit, correct imports that match what users would actually write. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: remove unused sleep import from rate limiting example Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Signed-off-by: Pranay Prakash <pranay.gp@gmail.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|
Pranay Prakash
|
73a851ada6 |
feat: add HookConflictError for hook token conflicts (#1448)
* feat: add HookConflictError for hook token conflicts Replace WorkflowRuntimeError with a dedicated HookConflictError class for hook token conflicts. This correctly classifies the error as a USER_ERROR (duplicate token is a user mistake) rather than a RUNTIME_ERROR. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: use HookConflictError.is() instead of instanceof in docs The .is() static method handles cross-VM/realm boundaries where instanceof can be unreliable. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|
Pranay Prakash
|
15e6bc008c |
Fix docs typechecker to resolve workflow module types (#1271)
* Fix docs typechecker to actually resolve workflow module types The docs typechecker was silently failing to resolve `workflow` imports because: 1. repoRoot was computed 4 levels up instead of 3 2. No path mappings for workspace packages 3. Missing TS lib files for disposable and DOM iterables This meant all imported symbols became `any` and type errors in docs code samples went undetected. Fixes: - Fix repoRoot: '../../../..' -> '../../..' - Add path mappings for workflow, @workflow/core, @workflow/ai, etc. - Add lib.dom.iterable.d.ts and lib.esnext.disposable.d.ts - Fix regex that ate first line of some code blocks - Auto-skip error demonstration code blocks - Add respondWith to global Request for webhook doc patterns Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix docs typecheck failures against updated base branch - Skip incomplete code samples (with `...`/`/* ... */`) from type checking - Fix sleep("1 month") → sleep("30d") (valid ms duration) - Fix run.result() → run.returnValue (correct Run API) - Add skip-typecheck for docs with intentionally simplified types Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix doc code samples to typecheck instead of skipping them - hook-conflict.mdx: use error.message.includes() instead of non-existent error.slug - get-hook-by-token.mdx: cast hook.metadata to expected shape - ai/index.mdx: fix tool inputSchema to match execute function params - get-writable.mdx: use ModelMessage[], spread result.messages, use model placeholder - Add myModel global placeholder for docs examples Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Narrow TS2307 ignore to only non-mapped modules Instead of blanket-ignoring all "Cannot find module" errors (TS2307), only ignore them for modules not in our explicit paths mappings. This ensures workspace package imports (workflow, @workflow/core, etc.) are validated while still allowing relative imports and framework deps. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|
Nathan Rajlich
|
89f96306ea |
fix(docs): correct retry instructions in corrupted-event-log error page (#1059)
Remove reference to non-existent 'npx workflow runs start' CLI command. The correct way to retry is via the Re-run button in the Workflow Dashboard. |
||
|
Pranay Prakash
|
c2b4fe9906 |
fix(core): detect and fatal error on orphaned/invalid events (#1055)
* fix(core): detect and fatal error on orphaned/invalid events in EventsConsumer When an event log has duplicate or invalid events (e.g., 2 wait_completed for a single wait_created), the EventsConsumer gets stuck: the orphaned event has no callback to consume it, so eventIndex never advances, blocking all subsequent events and hanging the workflow forever. This adds deferred orphaned event detection that raises a WorkflowRuntimeError instead. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * add corrupted-event-log error slug and docs page Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * add changeset for orphaned event detection Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * address PR feedback on docs and JSDoc - Add JSDoc to EventsConsumer constructor's onUnconsumedEvent parameter - Rewrite docs to clarify this is a SDK/server bug, not user code - Remove cancel/programmatic retry advice; run is already marked failed - Emphasize error is uncatchable inside workflow code - Add steps: upgrade package, retry via dashboard/CLI, report issue on GitHub Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * address PR review: structured options, required callback, reorder docs - Change EventsConsumer constructor to use structured EventsConsumerOptions object - Make onUnconsumedEvent required (all callsites provide it) - Move corrupted-event-log card to last position in errors index - Update all callsites in tests Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix docs code sample to pass type-checking Use correct imports (getRun from workflow/api) and declare variables to satisfy the docs-typecheck CI job. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * add e2e test for parallel sleep (Promise.all with 10x sleep) Adds parallelSleepWorkflow that does Promise.all with 10 concurrent sleep('1s') calls, and an e2e test asserting it completes or fails within a reasonable time (not hanging). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix parallelSleep e2e test: await returnValue instead of checking status run.status returns immediately and the workflow is still 'running'. Use run.returnValue which polls until completion. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix parallelSleep e2e: assert parallel completion under 10s The test verifies 10 concurrent sleep('1s') calls complete in parallel (~1s) rather than serially (10s) or hanging indefinitely. 30s timeout is sufficient since the workflow should finish in ~1-2s. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> |
||
|
Hayden Bleasel
|
2cc8c3dc9c |
Update docs (#1010)
* Run update script * Update deps * Restore code block modifications * Reapply navbar patch * Restore custom proxy config * Add md-metadata * Add new frontmatter |
||
|
Pranay Prakash
|
41f28d8b80 |
fix(docs): complete OpenGraph image integration for docs pages (#917)
* changeset Signed-off-by: voyager14 <21mh124@queensu.ca> * refactor OG image generation into shared utility Signed-off-by: voyager14 <21mh124@queensu.ca> * fix og image height mismatch Signed-off-by: voyager14 <21mh124@queensu.ca> * fix: add missing getPageImage and include OG assets in Vercel output Signed-off-by: voyager14 <21mh124@queensu.ca> * exclude og in middleware Signed-off-by: voyager14 <21mh124@queensu.ca> * fix(docs): wire up OpenGraph images for docs pages Complete the OG image integration that was started in PR #858: - Add openGraph.images metadata to docs page generateMetadata using the getPageImage helper from source.ts - Add metadataBase to the root layout so Next.js can resolve OG URLs - Remove unused generatePageMetadata helper from docs-page.tsx This ensures docs pages like /docs/how-it-works/event-sourcing have proper OpenGraph images when shared on social media. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Signed-off-by: Pranay Prakash <pranay.gp@gmail.com> * fix(docs): use dynamic OG image for homepage The static opengraph-image.png at the app root wasn't being served because all routes are under [lang]/. Next.js OG images need to be in the same route segment as the page they apply to. - Create dynamic opengraph-image.tsx in [lang]/(home)/ using the shared createOgImage utility - Remove the unused static opengraph-image.png from app root Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(docs): use dynamic metadataBase for preview deployments The metadataBase was hardcoded to useworkflow.dev, which caused preview deployments to generate OG image URLs pointing to production instead of the preview URL. Now uses: - Production: https://useworkflow.dev - Preview: https://${VERCEL_URL} - Local dev: http://localhost:3000 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(docs): address PR review comments for OG images - Fix semibold font weight from 500 to 600 (semibold is weight 600) - Extract OG_IMAGE_SIZE constant to lib/og/index.tsx for consistency - Use shared constant in all opengraph-image.tsx files Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(docs): match OG image styling to production design - Fix title styling: "Workflow:" in white, rest in grey (#888888) - Remove description from homepage OG image - Adjust positioning and font size to match expected design - Reduce text width to prevent overflow Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(docs): add display flex for Satori multi-child divs Satori requires explicit display: flex on divs with multiple children. Added flex flex-wrap to the title div containing the two spans. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(docs): simplify OG image layout with stacked title Use separate divs for "Workflow:" and title instead of trying to inline them with flex-wrap, which was causing layout issues in Satori. - "Workflow:" on first line in white - Title on second line in grey - Reduced font size slightly to prevent overflow - Properly stacked with flex-col layout Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(docs): correct OG image positioning below background Workflow: text The background.png already contains "Workflow:" text, so we only need to render the dynamic title positioned below it. - Remove hardcoded "Workflow:" from JSX (it's in the background image) - Adjust top positioning to 290px to place title below background text - Restore textWrap: balance for proper text flow Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(docs): align OG title with background Workflow: text Position and size title to match background image's Workflow: text, using non-breaking spaces for horizontal offset so title flows inline. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(docs): restore debug border on OG image container Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(docs): add homepage OG route and fix positioning - Add /og route for homepage OG image (avoids i18n middleware conflict) - Remove broken opengraph-image.tsx that conflicted with middleware - Add explicit openGraph metadata to homepage - Restore debug border for positioning Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(docs): add OG routes for worlds pages - Add /og/worlds route for worlds listing page - Add /og/worlds/[id] route for individual world pages - Remove broken opengraph-image.tsx that conflicted with i18n middleware - Add explicit openGraph metadata to worlds pages Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(docs): remove badge from worlds OG images Badge was causing layout issues with title positioning. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs: add descriptions to AI, foundations, how-it-works, deploying, and observability pages Add terse descriptions for OG image rendering to: - 8 AI docs - 9 foundations docs - 4 how-it-works docs - 5 deploying docs - 1 observability doc Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs: add descriptions to API reference, errors, and remaining getting-started pages Add terse descriptions for OG image rendering to: - 23 API reference docs (workflow, workflow/api, @workflow/ai, workflow/next) - 9 errors docs - 5 getting-started docs (Astro, Express, Fastify, NestJS, Vite) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Signed-off-by: voyager14 <21mh124@queensu.ca> Signed-off-by: Pranay Prakash <pranay.gp@gmail.com> Co-authored-by: voyager14 <21mh124@queensu.ca> Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> |
||
|
Pranay Prakash
|
4966b728a8 |
implement event-sourced architecture (#621)
* perf: implement event-sourced architecture
* Apply suggestions from code review
* Improve invalid event log handling in step/hook/wait
* Handle serialized workflow run errors correctly
* log error in failing test
* Handle queue idempotency in vercel world
* hotfix for error propogation
* Fix: Incorrect HTTP status code 409 should be 410 for terminal run state rejections in postgres storage
* Fix: The code attempts to pass an unsupported `fatal` property when creating a `step_failed` event. The TypeScript schema for `step_failed` events only allows `error` and `stack` properties, so the `fatal` property causes a compilation error.
This commit fixes the issue reported at packages/core/src/runtime/step-handler.ts:133-139
## TypeScript error: Invalid property 'fatal' in step_failed event
**What fails:** TypeScript compilation fails in `packages/core` due to an invalid property in the `step_failed` event creation.
**How to reproduce:**
```bash
cd /vercel/sandbox/primary
pnpm run -F @workflow/core build
```
**Result:**
```
src/runtime/step-handler.ts(133,32): error TS2769: No overload matches this call.
Overload 1 of 2, '(runId: null, data: { eventType: "run_created"; ... }, gave the following error.
Argument of type 'string' is not assignable to parameter of type 'null'.
Overload 2 of 2, '(runId: string, data: CreateEventRequest, params?: CreateEventParams | undefined): Promise<EventResult>', gave the following error.
Object literal may only specify known properties, and 'fatal' does not exist in type '{ error: any; stack?: string | undefined; }'.
```
**Issue:** The code attempted to pass a `fatal: true` property in the `eventData` object when creating a `step_failed` event. However, the event schema defined in `packages/world/src/events.ts` for `StepFailedEventSchema` only allows `error` and `stack` properties - the `fatal` property is not part of the schema.
Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>
* Fix: Code silently skips updating workflowRun if result.run is undefined, causing workflows to be incorrectly skipped instead of throwing an error
* Add hook_conflict event type for duplicate token detection
Implements hook_conflict events across all world implementations to handle
cases where a workflow attempts to use a hook token already claimed by another
workflow. Instead of throwing errors, the system now records hook_conflict
events in the event log, enabling deterministic replay.
- Add HookConflictEvent schema to @workflow/world
- Implement hook_conflict in world-local, world-postgres, and suspension-handler
- Update hook consumer to reject promises with WorkflowRuntimeError on conflict
- Add HOOK_CONFLICT error slug with documentation
- Add e2e and unit tests for conflict scenarios
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add changeset for hook_conflict events
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add unit tests for hook_conflict handling
- Add tests for hook_conflict event in workflow.test.ts
- Fix world-postgres test to not expect removed message field
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Improve hook-conflict.mdx error guide
- Remove redundant third point in 'Why This Happens' section
- Add example showing how to handle WorkflowRuntimeError for hook conflicts
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix docs validation: add hook-conflict to errors index
- Fix broken link in hook-conflict.mdx (/docs/foundations/webhooks -> /docs/api-reference/workflow/create-webhook)
- Add hook-conflict to errors index page so it's discoverable by the docs link validator
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix world-local tests for hook_conflict event behavior
Update tests to expect hook_conflict events instead of thrown errors when
duplicate hook tokens are used. This aligns with the new event-sourced
approach where conflicts are recorded as events rather than thrown.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add specVersion property to World interface for backwards compatibility
- Add specVersion property to World interface to track world package version
- Add specVersion to WorkflowRun schema and run_created event data
- World implementations (vercel, local, postgres) set specVersion from npm version
- Server can use specVersion to route operations based on world version
- Add specVersion display to observability UI attribute panel
- Add spec_version column to postgres runs schema
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add migration for spec_version column in postgres schema
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add drizzle migration journal and snapshot for spec_version column
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Regenerate postgres migration using drizzle-kit
- Properly generates migration with drizzle-kit CLI
- Removes deprecated 'paused' status from enum
- Adds spec_version column
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add backwards compatibility for event-sourced runs
- Add RunNotSupportedError for runs requiring newer world versions
- Add semver-based version utilities (isLegacyVersion) to @workflow/world
- World implementations check specVersion and route to legacy handlers
- Legacy runs (< 4.1.0): run_cancelled skips event storage, wait_completed stores event only
- New runs always get current world version (4.1.0-beta.0)
- Make EventResult.event optional for legacy compatibility
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Refactor spec version from semver strings to integers
Replace semver-based version compatibility with explicit integer spec versions:
- SPEC_VERSION_LEGACY (1): pre-event-sourcing runs
- SPEC_VERSION_CURRENT (2): event-sourced architecture
Use branded SpecVersion type to enforce importing from @workflow/world.
Remove semver dependency from world, world-local, and world-postgres.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Store error as CBOR in postgres world for consistency with input/output
- Add error_cbor bytea columns to workflow_runs and workflow_steps tables
- Deprecate text error column, rename to errorJson with fallback parsing
- Remove JSON.stringify from error writes (run_failed, step_failed, step_retrying)
- Add parseErrorJson helper for backwards compatibility with legacy data
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Use WorkflowRuntimeError and improve run entity handling in core runtime
- Replace generic Error with WorkflowRuntimeError for runtime assertions
- Add explicit check for run entity in run_created response
- Use run.runId instead of event.runId for consistency
- Use actual run status instead of hardcoded 'pending' in attributes
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add specVersion to Step, Hook, and Event entities
- Add specVersion field to Step, Hook, and Event interfaces in @workflow/world
- Add spec_version column to steps, hooks, events tables in postgres schema
- Set specVersion to SPEC_VERSION_CURRENT when creating entities in all worlds
- Update migration to include spec_version columns for all entity tables
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Refactor world-local storage into modular files
Split storage.ts (1041 lines) into smaller, focused modules:
- storage/filters.ts: Data filtering helpers
- storage/helpers.ts: ULID and date utilities
- storage/hooks-storage.ts: Hook CRUD operations
- storage/legacy.ts: Legacy event handling
- storage/runs-storage.ts: Run get/list operations
- storage/steps-storage.ts: Step get/list operations
- storage/events-storage.ts: Event create/list operations
- storage/index.ts: Main composition
Also extracted test helpers to test-helpers.ts for reusability.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Remove genversion and World.specVersion property
The World.specVersion string property was never actually read - only
the numeric SPEC_VERSION_CURRENT is used for backwards compatibility.
- Remove genversion dependency and generated version.ts from @workflow/world
- Remove specVersion property from World interface and all implementations
- Minor fix: correct error message to reference 'workflow' package
- Minor fix: correct error source priority in world-vercel events.ts
- Minor fix: update comment in runtime.ts
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Remove genversion from world-local, world-postgres, and world-vercel
These packages no longer need genversion since we removed the
World.specVersion property in the previous commit.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Remove version.ts from .gitignore files
No longer needed after removing genversion.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add legacy/backwards compatibility tests
Tests for world-local and world-postgres covering:
- Legacy runs (specVersion < 2 or null/undefined)
- run_cancelled handling (updates run, no event stored)
- wait_completed handling (stores event only)
- Rejection of unsupported events
- Hook cleanup on cancellation
- Future runs (specVersion > current)
- Rejection with RunNotSupportedError
- Current version runs (normal processing)
- Legacy error parsing (errorJson field parsing)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add hook_received support for legacy runs
When resumeHook() is called on a legacy run (specVersion < 2), the
hook_received event was previously rejected. This adds support for
storing hook_received events on legacy runs without entity mutation,
matching the behavior of wait_completed.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix missing genversion in world-vercel
Signed-off-by: Peter Wielander <mittgfu@gmail.com>
* Remove deprecated workflow_completed, workflow_failed, and workflow_started events
Replace with run_completed, run_failed, and run_started equivalents.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add specVersion to EventWithRefsSchema in world-vercel
The manually-created EventWithRefsSchema was missing the specVersion field,
which caused specVersion to be stripped when using lazy (refs) mode for events.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Wire specVersion from client through world backends
- Core runtime now sends specVersion in run_created eventData
- world-local accepts specVersion from eventData (defaults to current)
- world-postgres accepts specVersion from eventData (defaults to current)
This matches workflow-server behavior where v2 endpoints accept
specVersion from the client, while v1 endpoints default to legacy.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Move specVersion to event object level, propagate to entities
- Add specVersion to BaseEventSchema (event level, not eventData)
- Remove specVersion from RunCreatedEventSchema.eventData
- Core runtime sends specVersion on event object
- world-local reads specVersion from event, propagates to run/step/hook entities
- world-postgres reads specVersion from event, propagates to run/step/hook entities
This ensures specVersion flows from client through event to all created entities.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Update specVersion to be optional in types for backwards compatibility
- specVersion is optional in all entity schemas (runs, steps, hooks, events)
for backwards compatibility with legacy data in storage
- Runtime always sends specVersion on event requests
- world-local and world-postgres provide fallback to SPEC_VERSION_CURRENT
- Test helpers include specVersion in all event creation calls
- EventWithRefsSchema in world-vercel defaults specVersion to 1 for legacy
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix world-vercel queue tests missing VERCEL_DEPLOYMENT_ID setup
Two tests were calling queue.queue() without setting up
VERCEL_DEPLOYMENT_ID, causing them to fail with "No deploymentId
provided" error before reaching the code they were testing.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add specVersion to all event creation calls in core package
The server's CreateEventSchemaV2 requires specVersion on all events,
but only run_created was sending it. This caused 400 Bad Request errors
for all other event types (run_started, run_completed, run_failed,
run_cancelled, step_created, step_started, step_completed, step_failed,
step_retrying, hook_created, hook_received, wait_created, wait_completed).
Now all event creation calls include specVersion: SPEC_VERSION_CURRENT.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Signed-off-by: Peter Wielander <mittgfu@gmail.com>
Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Peter Wielander <mittgfu@gmail.com>
|
||
|
Malte Ubl
|
75630fe1d8 |
Type check all the docs and READMEs (#715)
* Type check all the docs and READMEs
* mdx
DCO Remediation Commit for Malte Ubl <malte.ubl@gmail.com>
I, Malte Ubl <malte.ubl@gmail.com>, hereby add my Signed-off-by to this commit:
|
||
|
Copilot
|
b56aae3fe9 |
Override timeout functions in workflow VM context to throw helpful errors (#505)
* Initial plan * Override timeout functions in workflow VM context to throw helpful errors Co-authored-by: TooTallNate <71256+TooTallNate@users.noreply.github.com> * Use WorkflowRuntimeError instead of vmGlobalThis.Error for timeout functions Co-authored-by: pranaygp <1797812+pranaygp@users.noreply.github.com> * Add docs page for timeout-in-workflow error Co-authored-by: pranaygp <1797812+pranaygp@users.noreply.github.com> * Reorder unavailable functions list: set* functions first, then clear* functions Co-authored-by: TooTallNate <71256+TooTallNate@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: TooTallNate <71256+TooTallNate@users.noreply.github.com> Co-authored-by: pranaygp <1797812+pranaygp@users.noreply.github.com> |
||
|
Nathan Rajlich
|
b7b717aae5 | Use double quote strings in docs consistently (#531) | ||
|
Hayden Bleasel
|
c0991b4ff7 |
Update docs (#349)
* Initial migration
* Remove ExperimentalPackageCallout
* Remove Callout imports
* Add missing dep
* Update postgres-world.mdx
* Add missing deps, remove unused files
* Restore homepage css
* Update logo, fix homepage
* Update run-anywhere.tsx
* Remove duplicate h1 tags
* Fix package install commands
* Update global.css
* Update code-block.tsx
* Fix framework descriptions
* Remove unused files
* Fix steps
* Update sidebar.tsx
* Remove excess horizontal rules
* Remove unused components
* Cleanup home code-block component
* Update route.ts
* Add missing feed dep
* Rename middleware to proxy
* Update next config
* Update route.tsx
* Move generateDefinition call into tsx
* Update page.tsx
* Update sidebar.tsx
* Update layout.tsx
* Remove unused files
* Fix nav
* Update route.ts
* Remove deprecated lint:links
* Load fonts locally
* Update layout.tsx
* Update route.ts
* Update Geistdocs
* Update hero.tsx
* Update search.tsx
* Update search.tsx
* docs: update url structure in chat tools example
* chore: replace gpt-5 reasoning with gpt-5.1
* docs: update instructions for llm to be more workflow-centric
* Revert "docs: update instructions for llm to be more workflow-centric"
This reverts commit
|
||
|
Gal Schlezinger
|
4ca9a3edbd |
Introducing Workflow DevKit
build durable, resilient, and observable workflows. Co-authored-by: Nathan Rajlich <n@n8.io> Co-authored-by: Pranay Prakash <pranay.gp@gmail.com> Co-authored-by: Adrian <me@adriandlam.com> Co-authored-by: JJ Kasper <jj@jjsweb.site> Co-authored-by: Vercel Release Bot <88769842+vercel-release-bot@users.noreply.github.com> Co-authored-by: Peter Wielander <mittgfu@gmail.com> Co-authored-by: Hayden Bleasel <hello@haydenbleasel.com> Co-authored-by: Gal Schlezinger <gal@spitfire.co.il> Co-authored-by: Manuel Muñoz Solera <mamuso@mamuso.net> Co-authored-by: Garrett <garrett.tolbert@vercel.com> Co-authored-by: Lars Grammel <lars.grammel@gmail.com> Co-authored-by: Pooya Parsa <pyapar@gmail.com> Co-authored-by: Tom Dale <tom@tomdale.net> Co-authored-by: Vishal Yathish <135551666+visyat@users.noreply.github.com> Co-authored-by: josh <144584931+dancer@users.noreply.github.com> |