* Add 50, 100, 500 concurrent step benchmarks
Enable Promise.all and Promise.race benchmarks for 50, 100, and 500
concurrent steps (previously 100+ were skipped).
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add 50, 100, 500 sequential step benchmarks
Extends the sequential step benchmarks to test workflows with 50, 100,
and 500 sequential steps in addition to the existing 10 step test.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add full/quick benchmark suite toggle for CI
- Add BENCHMARK_FULL_SUITE env var to control which benchmarks run
- Quick suite (default for PRs): 10, 25, 50 step benchmarks
- Full suite (main branch, manual dispatch): adds 100, 500 step benchmarks
- Add workflow_dispatch input to manually trigger full suite from GitHub UI
- Skip 100+ sequential and concurrent step benchmarks by default
This keeps PR benchmarks fast while allowing full stress testing on demand.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add 25 sequential steps benchmark
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix benchmark API calls to use binary format
PR #853 changed the workflow trigger API to expect binary data
(application/octet-stream) instead of JSON. The e2e tests were updated
but the benchmark file was missed, causing all benchmarks to fail
silently since Jan 28.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Only run full benchmark suite on manual dispatch
Remove automatic full suite on main branch pushes - only run full suite
when manually triggered with full_suite=true.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Added support for `"use step"` directive in class instance methods, allowing instance methods to be used as workflow steps.
### What changed?
- Modified the SWC plugin to recognize and transform instance methods with the "use step" directive
- Added registration logic for instance method steps using `ClassName.prototype.methodName`
- Implemented proper serialization of class instances to preserve the `this` context across workflow/step boundaries
- Added comprehensive end-to-end tests for instance method steps
- Updated error handling to allow "use step" in instance methods while still preventing "use workflow" in instance methods
### How to test?
The PR includes a new end-to-end test `instanceMethodStepWorkflow` that demonstrates the functionality:
1. Run the e2e tests to verify the new instance method step functionality
2. The test creates a `Counter` class with instance methods marked as steps
3. It verifies that the instance methods can be called as steps with proper serialization of the `this` context
4. It also verifies that multiple instances of the same class can be used independently
### Why make this change?
This change enables a more natural object-oriented programming model when working with workflows. Previously, only static methods, standalone functions, and object methods could be marked as steps. Now, developers can create classes with instance methods that are steps, allowing for better encapsulation and more intuitive code organization. This is particularly useful for complex workflows that need to maintain state across multiple step invocations.
This PR ensures that all classes with custom serialization are automatically included in all bundle contexts (step, workflow, client) to ensure proper serialization/deserialization when crossing execution boundaries:
- Classes defined in any context can now be properly serialized when passing data between:
- Client → Workflow (when starting workflows)
- Workflow → Step (when calling steps)
- Step → Workflow (when returning step results)
- Workflow → Client (when returning workflow results)
- The build system now automatically discovers all files containing serializable classes and includes them in each bundle, regardless of where the class is originally defined.
- No manual configuration is required - cross-registration happens automatically during the build process.
Fixed class serialization/deserialization to properly respect VM context boundaries, ensuring workflow code only accesses classes registered in its own global context.
### What changed?
- Modified `getSerializationClass()` to no longer fall back to checking `globalThis` when a class isn't found in the provided global context
- Updated the serialization tests to properly simulate how classes are registered and accessed in both host and VM contexts
- Added VM-specific class registration in tests to better match production behavior where workflow code runs in isolation
### How to test?
- Run the updated serialization tests which now properly simulate the VM boundary
- Verify that class serialization/deserialization works correctly when classes are registered in their respective contexts
- Confirm that classes registered in one context aren't accessible from another context
### Why make this change?
This change ensures proper isolation between the host environment and workflow VM contexts, matching production serverless behavior where workflow code runs in isolation. Previously, the code could leak class registrations between contexts, potentially causing unexpected behavior or security issues. This fix maintains proper boundaries between execution contexts.
Fixed class ID generation for class expressions bound to variables in the SWC plugin.
### What changed?
- Added support for correctly handling class expressions with binding names that differ from internal class names
- Updated the SWC plugin to use the variable name (binding name) for registration instead of the internal class name
- Added test cases for class expressions with different binding names and anonymous class expressions
- Updated documentation to explain how class expressions with binding names are handled
### How to test?
Test with code patterns like:
```javascript
var Bash = class _Bash {
// Class implementation with serialization methods
};
```
Verify that the generated code correctly uses the binding name "Bash" for registration rather than the internal name "_Bash".
### Why make this change?
When a class expression is assigned to a variable, the internal class name is only accessible inside the class body, not at module level. Using the binding name ensures that the registration call references a symbol that's actually in scope at module level, preventing runtime errors when the code attempts to register the class for serialization.
Added automatic discovery for custom classes with workflow serialization, allowing serialization classes to be defined in separate files without requiring explicit directives.
### What changed?
- Added detection for files containing custom class serialization patterns:
- Files importing from `@workflow/serde`
- Files using `Symbol.for('workflow-serialize')` or `Symbol.for('workflow-deserialize')`
- Created shared utilities in `transform-utils.ts` for consistent pattern detection across all build tools
- Updated Next.js, Nitro, Rollup, and Vite plugins to use the new detection patterns
- Added exclusion logic to prevent re-processing of generated workflow files
- Added tests to verify the pattern detection works correctly
- Updated documentation in the SWC plugin spec to explain the new discovery mechanism
### How to test?
1. Create a class with custom serialization in a separate file:
```js
// models/point.js
export class Point {
constructor(x, y) {
this.x = x;
this.y = y;
}
static [Symbol.for('workflow-serialize')](instance) {
return { x: instance.x, y: instance.y };
}
static [Symbol.for('workflow-deserialize')](data) {
return new Point(data.x, data.y);
}
}
```
1. Import and use this class in a workflow or step file:
```js
'use workflow';
import { Point } from '../models/point';
export function myWorkflow() {
const point = new Point(10, 20);
return point;
}
```
1. Verify the class is properly serialized when passed between client and server
### Why make this change?
Previously, files containing custom serialization classes needed to include a `'use step'` directive to be discovered and transformed, even if they weren't actual step functions. This was unintuitive and could lead to confusion.
This change allows for a more natural code organization pattern where model classes with serialization can be defined in their own files without requiring directives. The build system will automatically discover and transform these files to ensure the serialization works correctly when the classes are used in workflows or steps.
* 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>
* Fix bundling behavior for dynamic imports and server-only, client-only imports
* Generate changeset
* Filter tsconfig to only pull in code from within the current working directory(workflow dir)
* Rewrite server-only and client-only
* add additional pseudo directives
* upmerge
* fix failing unit test
* fix(docs): align header nav responsive breakpoint with mobile menu
The desktop navigation links (Docs, Worlds, Examples) and search button
were using `xl:flex` (1280px) while the mobile hamburger menu used
`md:hidden` (768px). This created a gap between 768px-1280px where
neither the nav links nor the hamburger menu were visible.
Changed both to use `md:flex` so the navigation is visible at the same
breakpoint where the mobile menu button hides.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat(docs): add top-level nav links to mobile sidebar menu
The mobile hamburger menu only showed the docs table of contents.
Now it also includes the top-level navigation links (Docs, Worlds,
Examples) at the top of the sheet with a border separator.
This ensures all navigation is accessible at mobile viewports.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
The docs template refactor accidentally removed the SVG and ZIP file
exclusions from the middleware matcher, causing public static assets
like workflow-circle-symbol-light.svg and workflow-circle-symbol-dark.svg
to be processed by the i18n middleware instead of being served directly.
This restores the original behavior where static files are served from
the public folder without middleware interference.
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
* fix(docs): use true black backgrounds in dark mode and improve sidebar highlight visibility
- Change dark mode background from gray (oklch 0.145) to true black (oklch 0 0 0)
- Adjust card/popover backgrounds from oklch 0.205 to oklch 0.1 for better contrast
- Update secondary/muted/accent backgrounds from oklch 0.269 to oklch 0.15
- Set sidebar background to true black (oklch 0 0 0)
- Increase sidebar-accent from oklch 0.269 to oklch 0.2 for better visibility of highlighted items
- Set sidebar-accent-foreground to pure white (oklch 1 0 0) for maximum contrast
* chore: add empty changeset for docs styling change
Signed-off-by: Cursor Agent <cursoragent@cursor.com>
---------
Signed-off-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
* perf(builders): optimize workflow discovery with hybrid SWC approach
Apply SWC transforms only to files containing workflow/step directives
instead of all files. Uses regex for fast filtering, then SWC where needed.
- esbuild follows imports to build dependency graph
- regex detects 'use workflow'/'use step' directives
- SWC applied only to files with directives (<1% typically)
- other files use esbuild's built-in TS handling
* Remove blank line
* feat(next): add configurable `dirs` option to withWorkflow
Allow users to specify which directories to scan for workflow directives,
helping reduce memory usage and build times in large Next.js applications.
- Add `dirs` option that overrides the default directories
- Document all configuration options in API reference
- Add troubleshooting guide for OOM errors during build
* fix(docs): add missing imports in withWorkflow code example
Add missing import statements and nextConfig declaration to the
troubleshooting code example to fix docs typecheck.
* docs: move OOM troubleshooting to getting-started/next
Move the OOM troubleshooting section from the API reference to the
existing troubleshooting section in docs/getting-started/next.mdx
for better discoverability.
* move dirs inside workflow config
- Document fixed versioning for workflow and @workflow/core
- Add genversion pattern for build-time version injection
- Add turbo caching guidance for generated files
- Document executionContext field flexibility
- Document observability data hydration behavior
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
* Add workflow skill for Claude Code
Add custom slash commands for Claude Code:
- /pr command for creating PRs following repo conventions
Add workflow skill with comprehensive documentation:
- Main SKILL.md with core concepts and quick reference
- Reference docs for frameworks, AI agents, patterns, errors, and API
Signed-off-by: johnlindquist <johnlindquist@gmail.com>
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
* Update SKILL.md serialization docs for custom class support
Add documentation for custom class serialization using @workflow/serde
symbols (WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE) and clarify what can
and cannot be serialized based on recent PR #762.
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
* Fix incorrect API property names in SKILL.md
- Update sleep() example date from 2025 to 2027 (future date)
- Fix getWorkflowMetadata() to use correct properties: workflowRunId,
workflowStartedAt, url (not runId, workflowName)
- Fix getStepMetadata() to use correct property: attempt (not attemptNumber)
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
* Move skills to skill/workflow directory structure
Reorganize skill files to support multiple skills under ./skill/<name>/
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
* Rename skill to skills (plural)
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
* Refactor skills to use bundled docs from node_modules
- Update SKILL.md to direct agents to search node_modules/workflow/docs/
- Remove manually-maintained reference docs (ai-agents, api-reference, frameworks, patterns)
- Keep common-errors.md for practical troubleshooting
- Add prepack/postpack hooks to bundle docs in npm packages:
- workflow: All docs from docs/content/docs/
- @workflow/ai: AI-specific docs
- @workflow/core: foundations, how-it-works, api-reference
- @workflow/next: Next.js setup docs
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
* Add AI SDK step function guidance to SKILL.md
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
* Update SKILL.md formatting and add ecosystem section
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
* Align postpack scripts with AI SDK conventions
Use del-cli for postpack cleanup to match the AI SDK's cross-platform
approach. This ensures consistent tooling across both projects.
- Add del-cli ^5.1.0 to root devDependencies
- Update postpack in @workflow/core, @workflow/next, @workflow/ai, and
workflow packages from `rm -rf docs` to `del-cli docs`
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
* Add workflow health command to debugging documentation
Document the CLI health check command for verifying workflow/step
endpoint connectivity during local development and production.
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
* Address PR feedback: standardize on rm -rf and improve SKILL.md
- Remove del-cli dependency, use rm -rf consistently in postpack scripts
- Restructure SKILL.md to lead with "Prefer Step Functions" pattern
- Add sandbox limitations table for workflow-context workarounds
- Consolidate examples and remove duplication
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
* Consolidate common-errors.md into SKILL.md
Move useful tips (serialization, streaming, debugging) into main skill
file and remove the separate common-errors.md reference file.
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
---------
Signed-off-by: johnlindquist <johnlindquist@gmail.com>
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Pranay Prakash <pranay.gp@gmail.com>
Support provider-executed tools (AI SDK v6)
- Capture provider-executed tool results from stream
- Skip local execution for tools with providerExecuted: true
- Use correct AI SDK output types (json for objects, text for strings)
- Add warning when provider result is missing
Fixes#628Fixes#433Closes#434
* Add SDK version to workflow run executionContext for observability
Wire `@workflow/core` package version through the `executionContext` field
when creating workflow runs. Display the version in the observability UI
attribute panel. Uses genversion for build-time version injection.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix workflowCoreVersion extraction and add turbo.json for caching
- Extract workflowCoreVersion from executionContext in hydrateResourceIO
before stripping the context (addresses Copilot review comment)
- Add turbo.json to include src/version.ts in build outputs for caching
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Update workflowCoreVersion display name to @workflow/core version
Use a display name mapping to render the attribute as "@workflow/core version"
in the observability UI for better readability.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
* Use proper OpenAI import
```
Error: ../example/workflows/5_hooks.ts(36,22): error TS2351: This expression is not constructable.
Type 'typeof import("/vercel/path0/node_modules/.pnpm/openai@6.1.0_ws@8.18.3_zod@4.1.11/node_modules/openai/index")' has no construct signatures.
```
* .
Updated request body encoding to use CBOR instead of JSON for all API requests in the `@workflow/world-vercel` package.
### What changed?
- Replaced JSON.stringify with CBOR encoding for all request bodies in the Vercel World package
- Removed the `dateToStringReplacer` function as it's no longer needed with CBOR encoding
- Updated the `makeRequest` utility to handle CBOR encoding of request bodies
- Renamed data parameters to `requestData` to avoid confusion with the `data` parameter in `makeRequest`
### Why make this change?
CBOR encoding provides several advantages over JSON:
- More efficient binary encoding, resulting in smaller request payloads
- Native support for Date objects without needing custom replacers
- Consistent with the existing response handling which already uses CBOR
- Improves performance for API requests with large payloads
This change maintains API compatibility while improving the underlying transport mechanism.
Nathan Rajlich