mirror of
https://github.com/vercel/workflow.git
synced 2026-09-14 19:59:43 +08:00
codex/replay-sync-decode
299 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Karthik Kalyan
|
fb8e42dd76 | remove secure credential (#1723) | ||
|
John Lindquist
|
41d0d7e39d |
docs: add workflow migration guides and skill (#1584)
* docs: add workflow migration guides and migration skill Create migration guides for AWS Step Functions, Inngest, and Temporal under docs/content/docs/getting-started/. Each guide provides side-by-side code comparisons and a realistic order-processing saga example. Add skills/migrating-to-vercel-workflow/ with SKILL.md, reference docs for each source platform (aws-step-functions, inngest, temporal), shared patterns, resume routing, runtime targets, and 5 eval scenarios. Update create-webhook API reference with webhook resume choice clarifications. Update getting-started meta.json to include migration guide navigation entries. * In PR #1584 (migration-guides branch), make two changes to the migration guides: 1. Move migration guides to a top-level "Migration Guides" nav section: - Create docs/content/docs/migration-guides/ directory - Move the 3 migrating-from-*.mdx files from getting-started/ into migration-guides/ - Create migration-guides/meta.json with title "Migration Guides" listing temporal, inngest, aws-step-functions - Add "migration-guides" between "errors" and "api-reference" in docs/content/docs/meta.json - Remove the 3 migration entries from getting-started/meta.json 2. Replace all "Vercel Workflow" language with "Workflow SDK" across docs and skills: - In all 3 MDX migration guides: replace "Vercel Workflow" with "the Workflow SDK" or "Workflow SDK" in frontmatter, headings, table headers, and body text - Replace "shipping on Vercel" with neutral phrasing, "Vercel-managed execution" with "managed execution", "Vercel's infrastructure" with neutral phrasing - Replace Vercel-specific pricing paragraphs with generic "Efficient resource usage" bullet - Replace "Deploy to Vercel first..." checklist items with neutral deployment guidance - Keep vercel-world prerequisite links (real package name) - Rename skills/migrating-to-vercel-workflow/ to skills/migrating-to-workflow-sdk/ - Update all skill SKILL.md, evals/, and references/ files to replace "Vercel Workflow" with "Workflow SDK" - Update runtime-targets.md section headers from "Non-Vercel" to "Self-hosted" * fix type checks --------- Co-authored-by: Karthik Kalyanaraman <karthik.kalyanaraman@vercel.com> |
||
|
John Lindquist
|
851a530164 |
Add cookbook with 50 workflow pattern recipes (#1564)
* Add cookbook section with 50 workflow pattern recipes
Migrate the "Workflow API Explorer" decision tree concept from
workflow-campaign-demos into useworkflow.dev docs as a Cookbook.
Infrastructure:
- docs/lib/cookbook-tree.ts: decision tree data, 50 recipe metadata entries, slug-to-category mapping
- docs/components/geistdocs/cookbook-explorer.tsx: interactive "I want to..." decision tree UI with breadcrumb navigation
- docs/content/docs/cookbook/index.mdx: landing page rendering CookbookExplorer component
- docs/content/docs/cookbook/meta.json + 8 category meta.json files for sidebar nav
- docs/content/docs/meta.json: added cookbook to docs nav between foundations and how-it-works
- docs/app/[lang]/docs/[[...slug]]/page.tsx: registered CookbookExplorer component
50 recipe MDX files across 8 categories (payments, approvals, resilience,
notifications, webhooks, data-processing, routing, observability), each with:
- Frontmatter (title, description, type: guide, summary with use-case scenario)
- Simplified code snippet (core pattern only, stripped of demo UI concerns)
- Full implementation code snippet (exact source from campaign demos)
- Key APIs section with links to API reference docs
* ploop: iteration 1 checkpoint
Automated checkpoint commit.
Ploop-Iter: 1
* fix: polish cookbook public routing
Keep the cookbook surface canonical at /cookbooks so docs navigation, sitemap output, and AI/chat entry points stop leaking the legacy /docs/cookbook paths.
Correct the approval-chain example so the docs teach the intended sequential approval semantics instead of implying the workflow approves after the first successful level. This keeps the cookbook aligned with the docs quality bar and avoids misleading readers with inconsistent behavior.
Ploop-Iter: 2
* docs: canonicalize cookbook doc routes
Align cookbook-facing docs outputs with the new public route so
redirects, sitemap entries, and LLM-facing exports stay consistent.
This keeps the polished cookbook section discoverable at its canonical
location while trimming the last demo-heavy recipe examples toward the
same concise style as the rest of the docs.
Ploop-Iter: 3
* ploop: iteration 4 checkpoint
Automated checkpoint commit.
Ploop-Iter: 4
* fix(docs): finalize cookbook route split
Keep cookbook content discoverable after moving it to a first-class /cookbooks surface so navigation, canonical metadata, and markdown consumers resolve the new public URLs consistently.
Avoid serving the legacy /docs/cookbook tree as if it were still part of the docs section, which reduces duplicate navigation paths and prevents stale static output from competing with the new route structure.
Ploop-Iter: 5
* docs: improve cookbook discovery
The cookbook landing page needs to work for both exploratory users and users who already know the pattern they want. This keeps the guided decision tree while adding shared category metadata and a searchable browse mode so recipe discovery feels faster and more consistent with the rest of the docs experience.
Ploop-Iter: 6
* docs: refine cookbook pattern examples
Tighten the simplified cookbook recipes so the examples teach the intended workflow semantics clearly and consistently. The changes keep the documentation focused on the core control-flow patterns reviewers called out, while removing ambiguity around partial arrivals, deadlines, and first-success behavior.
Ploop-Iter: 7
* docs: decouple cookbook sidebar tree
Separate cookbook navigation from the docs page tree so the standalone /cookbooks experience stays stable after the route move and the main docs sidebar no longer leaks cookbook entries.\n\nThis keeps cookbook navigation driven by explicit recipe metadata, which avoids duplicated section titles and makes the docs and cookbook surfaces easier to evolve independently.\n\nPloop-Iter: 8
* fix(docs): align cookbook public nav
Keep cookbook pages on their public /cookbooks surface so metadata and copied markdown do not leak legacy /docs/cookbook paths.\n\nSimplify sidebar rendering to trust the injected page tree, which avoids route-specific filtering and keeps cookbook navigation consistent with the active layout tree.\n\nPloop-Iter: 9
* refactor(docs): decouple cookbook routing
Move cookbook rendering off the shared docs route so cookbook pages can behave like a first-class docs surface without leaking cookbook-specific UI into the main docs experience.
Centralizing cookbook tree filtering keeps sidebar behavior consistent in one place and avoids duplicate cookbook navigation state across layouts.
Ploop-Iter: 10
* docs: improve cookbook explorer accessibility
Improve the cookbooks entrypoint so loading and keyboard navigation
are usable without visual cues, and keep guided and browse modes
resilient while the route hydrates.
Ploop-Iter: 11
* ploop: iteration 12 checkpoint
Automated checkpoint commit.
Ploop-Iter: 12
* docs: rename cookbooks route to cookbook (singular)
* docs: add 5 cookbook overview design variations
Add getRecipeHref, getRecipesByCategory, and collectSlugs helpers to
cookbook-tree.ts, then create 5 distinct overview page variations at
/cookbook/v1 through /cookbook/v5 for side-by-side comparison:
- v1: Category Grid (zero-JS scannable overview)
- v2: Search-First (real-time filtering with category pills)
- v3: Accordion Catalog (expandable category sections)
- v4: Decision Wizard (step-by-step guided questions)
- v5: Problem-Solution Table (master-detail by scenario)
Also adds .impeccable.md with project design context.
* docs: remove unrelated package.json bumps and generated artifacts
* docs: restructure cookbook from 50 recipes into 27 consolidated pages
Restructure the cookbook based on team meeting feedback, toolbar comments,
mux-ai pattern analysis, and Vercel org code search. Consolidates duplicates,
adds missing patterns, ensures all examples have proper directives and
type-check against the real workflow SDK.
New structure:
- common-patterns/ (9): saga, batching, rate-limiting, fan-out,
scheduling, idempotency, webhooks, content-router, child-workflows
- agent-patterns/ (5): durable-agent, tool-streaming,
human-in-the-loop, tool-orchestration, stop-workflow
- integrations/ (3): ai-sdk, sandbox, chat-sdk
- advanced/ (6): serializable-steps, durable-objects,
isomorphic-packages, secure-credentials, custom-serialization,
publishing-libraries
All 92 code snippets pass docs-typecheck against real workflow SDK types.
Deleted 8 old category folders. Updated cookbook-tree.ts, explorer, nav.
* docs: add workflow migration guides
Help teams evaluating the GA launch translate existing durable workflow systems into Vercel Workflow without reverse-engineering concept parity from product docs alone.
The guides focus on real migration decisions and concrete TypeScript examples so adoption can be driven by implementation clarity rather than platform marketing.
Ploop-Iter: 1
* ploop: iteration 2 checkpoint
Automated checkpoint commit.
Ploop-Iter: 2
* docs: refine workflow migration guides
Clarify the migration narrative for GA so teams evaluating a move from Temporal, Inngest, or Step Functions get examples that are realistic enough to trust and pricing guidance that matches the current platform model.
The Inngest guide needed a complete order-saga flow so the durable orchestration, compensation, and streaming patterns read as a credible migration target instead of a partial sketch. The pricing language across all three guides also needed to be aligned with current Workflow and Vercel compute billing semantics to avoid creating the wrong cost expectations during evaluation.
Ploop-Iter: 3
* ploop: iteration 1 checkpoint
Automated checkpoint commit.
Ploop-Iter: 1
* docs(skill): refine workflow migration guidance
Clarify migration rules so agents choose the correct resume primitive, keep streaming guidance aligned with runtime behavior, and avoid implying Vercel-managed execution for self-hosted targets.
This reduces avoidable migration mistakes in generated guidance and keeps the skill consistent with the acceptance criteria used to evaluate it.
Ploop-Iter: 2
* ploop: iteration 3 checkpoint
Automated checkpoint commit.
Ploop-Iter: 3
* docs(skills): refine workflow migration guidance
Reduce the migration skill entry point to the decision surface agents need\nso they can select the correct resume pattern without carrying duplicate\nexamples in the initial context.\n\nClarify framework precedence so prompts that explicitly ask for\nframework-agnostic boundaries do not get Hono- or Next-specific route\nshapes, while preserving framework-specific examples when requested.\n\nCentralize canonical resume examples in the shared patterns reference to\nkeep the guidance consistent across migration paths and reduce drift.\n\nPloop-Iter: 4
* docs: add workflow deep-dive references
Add a cohesive set of deep-dive reference articles so the GA launch
has architecture-level documentation grounded in the current SDK
implementation. This gives readers verified explanations of runtime,
replay, streaming, compiler, and cost-model behavior while linking the
series together for easier navigation.
Ploop-Iter: 1
* ploop: iteration 5 checkpoint
Automated checkpoint commit.
Ploop-Iter: 5
* docs: normalize deep-dive related links
Keep the new deep-dive reference pages cross-linked so readers can move between adjacent runtime concepts without depending on older how-it-works pages alone.
This preserves navigational consistency across the GA launch docs set and reduces the chance that architectural explanations drift into isolated pages that are harder to discover and maintain.
Ploop-Iter: 2
* docs(skill): refine workflow migration routing
Tighten the migration guidance so agents choose the correct resume surface and runtime boundary earlier, reducing incorrect mixed patterns in generated migrations.
Add explicit fast paths for self-hosted targets and Step Functions task-token callbacks so the skill stays consistent on callback URL vs deterministic resume decisions.
Ploop-Iter: 6
* docs: refine workflow migration skill guidance
Clarify route selection so the migration skill composes resume, runtime, and app-boundary concerns deterministically. Add a canonical Step Functions self-hosted Hono callback recipe so migrations produce the correct callback-url pattern without mixing incompatible hook surfaces.\n\nPloop-Iter: 7
* docs: checkpoint deep-dive drafts
Preserve the verified GA launch deep-dive drafts in git so the campaign work can continue from a stable checkpoint.
Capture the reviewed documentation progress now to reduce risk of drift between source-backed research and the publishable drafts.
Ploop-Iter: 3
* docs(skills): tighten workflow migration routing
Clarify the migration skill's route-selection rules so generated guidance stays consistent across resume surfaces, runtime targets, and named framework boundaries.
This reduces ambiguous outputs where agents might mix framework syntaxes or invent callback routes for webhook-based flows, which leads to migration guidance that does not match the user's runtime model.
Ploop-Iter: 8
* docs: finalize workflow deep dives
Clarify the runtime mechanics behind the GA deep-dive series so launch content stays aligned with the implementation and existing docs. Tightening these explanations reduces the risk of readers internalizing inaccurate mental models about replay, compilation, and workflow execution.\n\nPloop-Iter: 4
* docs(skills): refine workflow migration routing
Clarify route selection so migrations choose the correct resume surface and app boundary patterns for the target runtime and framework. Strengthen verification guidance to reject invented callback routes in URL-based flows and keep examples aligned with the documented migration rules.
Ploop-Iter: 9
* docs: sync compiler deep-dive runtime details
Align the compiler deep-dive trio with the actual Workflow runtime so launch materials describe the same execution model users rely on. This keeps the GA narrative accurate around deterministic replay, step queue triggers, and runtime bundle responsibilities, reducing the risk of docs teaching an architecture the SDK does not implement.
Ploop-Iter: 5
* docs(skill): tighten workflow migration guidance
Reduce hot-path skill context so migration routing stays easier to select and
verify during activation.
Trimmed examples and converted long invalid samples into concise failure rules
so the skill points agents to on-demand references instead of loading bulky
worked code by default.
Ploop-Iter: 10
* docs: tighten workflow migration guidance
Clarify route-key planning and resume-surface defaults so migration outputs
stay deterministic when prompts underspecify callback behavior.
Strengthen the deep-dive docs to trace runtime handoffs more directly,
which reduces ambiguity about how the compiler split maps to durable
execution behavior.
Ploop-Iter: 11
* docs: refine streaming and cost deep dives
Clarify the operational model behind durable streaming and zero-cost suspension so launch materials stay source-accurate for readers comparing workflow runtimes.
The updates make the workflow-step boundary, persistence path, and queue-driven cost story more explicit, reducing ambiguity around where stream I/O is allowed and why long waits do not consume compute.
Ploop-Iter: 6
* ploop: iteration 12 checkpoint
Automated checkpoint commit.
Ploop-Iter: 12
* docs: tighten deep-dive streaming accuracy
Align the launch deep dives with the current runtime so campaign content does not misstate suspension behavior or streaming backend capabilities.
These edits clarify the distinct resume paths for step suspension versus timed waits and document the backend-specific streaming guarantees now available across local, Vercel, and Postgres worlds, reducing the risk that readers build incorrect mental models from launch materials.
Ploop-Iter: 7
* docs(skills): refine callback resume taxonomy
Clarify when migrations should use deterministic internal resume versus generated callback URLs so skill outputs stay consistent across frameworks and hosting targets. Distinguish default webhook responses from manual-response flows to prevent ambiguous guidance and keep the shared callback references directly inspectable.\n\nPloop-Iter: 13
* docs: refine deep-dive runtime wording
Clarify the runtime semantics behind suspension and durable streaming so the GA launch materials stay aligned with the source of truth.
These edits tighten descriptions around wake-up paths, backend behavior, and stream lifecycle details to reduce ambiguity for readers comparing the docs to the implementation.
Ploop-Iter: 8
* docs: clarify webhook response mode defaults
Clarify when migrations should use the default webhook behavior versus
manual responses so agents make the same callback choice across the
skill entrypoint, shared patterns, and API reference.
This reduces avoidable ambiguity for callback-url prompts and makes the
default 202 behavior explicit unless a prompt requires custom response
semantics.
Ploop-Iter: 14
* docs: align cost model wake-up semantics
Prevent the GA launch materials from teaching an incorrect mental model about how suspended runs wake back up. The updated wording keeps the blog, social, and reference variants anchored to the real runtime paths so readers understand which transitions are queue-delayed, which are step-driven re-enqueues, and why that distinction matters for the cost story.
Ploop-Iter: 9
* ploop: iteration 10 checkpoint
Automated checkpoint commit.
Ploop-Iter: 10
* docs: clarify webhook resume choices
Explain the resume-surface decision points so migration and API guidance steer authors toward the correct webhook or hook pattern for the prompt.
Reduce common callback-routing mistakes early in the docs and skill so agents make fewer wrong assumptions during workflow migrations.
Ploop-Iter: 15
* docs: tighten cost model deep dives
Clarify the cost-model narrative so launch materials make source-verifiable
claims about suspension, wake-up paths, and polling behavior.
This keeps the GA messaging aligned with the runtime's actual control
flow and avoids overclaiming where the implementation has narrower
semantics than the original copy suggested.
Ploop-Iter: 11
* docs(skills): tighten resume routing guidance
Keep the migration skill entrypoint small so agents load the routing contract only when the source actually pauses for external resume. Clarify the public webhook docs around the default callback flow to reduce accidental use of lower-level runtime APIs.\n\nPloop-Iter: 16
* docs: tighten deep-dive runtime claims
Align the launch materials with the current runtime semantics so the
cost-model and execution-model narrative stays defensible against the
actual implementation.
This keeps the GA campaign focused on claims we can support directly from
source, especially around suspension, re-enqueue behavior, and the
difference between orchestration compute and client-side polling helpers.
Ploop-Iter: 12
* docs: correct cost model deep dive claims
Align the cost-model launch content with the runtime's actual suspension and re-entry mechanics so GA messaging does not overstate identical-cost waits or imply residency that the queue-based engine does not have.
This keeps the public explanation consistent with source-backed behavior around timed wake-ups, explicit workflow re-queue after step completion, and the distinction between idle worker residency and boundary I/O.
Ploop-Iter: 13
* chore: remove non-cookbook files from cookbook branch
Remove deep-dive articles, migration guides/skill, vercel-toolbar skill,
workflow-skills test fixtures, and misc artifacts that belong in separate
branches (deep-dives, migration-guides). Revert create-webhook.mdx,
getting-started/meta.json, and code-transform.mdx to main versions.
* docs: address toolbar feedback on cookbook pages
Address Vercel toolbar comments from Nathan Rajlich, Peter Wielander, Pranay Prakash, and Karthik Kalyanaraman on the cookbook branch.
In saga.mdx, remove the unnecessary `if (!(error instanceof FatalError)) throw error;` guard in the catch block — compensations should always unwind regardless of error type. Replace the `while/pop()!()` loop with a cleaner `for...of reverse()` to avoid the non-null assertion.
In ai-sdk.mdx, split the "Using Different Providers" section into two subsections: "Vercel Gateway (string model IDs)" clarifying that all string model IDs route through Gateway, and "Direct Provider Access" showing how to import from provider packages like `@workflow/ai/openai` to bypass Gateway. Change the "Tool Functions as Steps" section to "Tool Functions with Steps" and reword to explain that tool execute functions can optionally include steps via "use step" but don't have to — when they aren't steps, they run in workflow context and can modify workflow state directly.
In sandbox.mdx, rewrite the page to reflect that `@vercel/sandbox` now has first-class Workflow SDK support. Replace all `declare function` stubs and `// TODO` placeholders with real `import { Sandbox } from "@vercel/sandbox"`. Remove the four separate "use step" wrapper functions (provisionSandbox, runCommand, teardownSandbox, saveSandboxSnapshot) and show direct `Sandbox.create()`, `sandbox.runCommand()`, and `sandbox.destroy()` calls in the workflow function since these implicitly run as steps. Simplify the agent tool example to use inline execute functions that call Sandbox methods directly with an `activeSandbox` variable for workflow state.
Across all cookbook files, replace "Workflow DevKit" with "Workflow SDK" (8 instances in 5 files: publishing-libraries.mdx, secure-credentials.mdx, ai-sdk.mdx, chat-sdk.mdx, sandbox.mdx).
* docs: simplify cookbook index to plain MDX listing
Replace the interactive CookbookExplorer (726-line decision tree + browse
component) with a simple MDX page that lists recipes grouped by category
with linked titles and descriptions. Remove v1-v5 design variations and
trim cookbook-tree.ts to sidebar-only metadata.
* fix type checks
---------
Co-authored-by: Karthik Kalyanaraman <karthik.kalyanaraman@vercel.com>
|
||
|
Peter Wielander
|
873b4e2bb4 | [core] Refactor getWorld interface to be asynchronous (#942) | ||
|
Peter Wielander
|
66d49c0db6 | [world] Restructure stream interface, require run ID for all step and stream operations (#1293) | ||
|
Pranay Prakash
|
a78420c43d |
Add Turborepo caching configuration to Next.js docs (#1668)
* docs: add Turborepo caching troubleshooting to Next.js guide Slack-Thread: https://vercel.slack.com/archives/C09125LC4AX/p1775744289881469?thread_ts=1775744289.881469&cid=C09125LC4AX Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * Address review: add src/app path and fix jsonc code fence --------- Co-authored-by: v0 <v0[bot]@users.noreply.github.com> Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> Co-authored-by: Nathan Rajlich <n@n8.io> |
||
|
Nathan Rajlich
|
ec517fa225 |
Add features.encryption to WorkflowMetadata (#1652)
* Add features.encryption to WorkflowMetadata Expose a `features` object on `getWorkflowMetadata()` so library authors can detect at runtime whether encryption is enabled for the current workflow run, allowing them to conditionally handle sensitive data serialization. * Improve docs example: show workflow-level encryption check Step inputs are serialized before the step body runs, so the encryption check should happen in the workflow function before passing data to steps. * Fix docs example: show encryption check on step return value Step return values are serialized to the event log after the step body runs, so this is where the check is actually useful - controlling what data gets persisted as output. * Fix docs typecheck: declare external function in code sample * minor |
||
|
Nathan Rajlich
|
0a86de3afd |
Inline all SWC plugin step registrations, remove workflow/internal/private (#1632)
The SWC compiler plugin no longer generates import statements. All step function registrations and closure variable access are now self-contained inline IIFEs with zero module dependencies |
||
|
John Lindquist
|
b176aceb7c |
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. |
||
|
Peter Wielander
|
c8dce52606 | [core] [world] Lazy run creation on start (#1537) | ||
|
Karthik Kalyan
|
ce8a80eb82 | [docs] Add vercel world consumer function security documentation (#1543) | ||
|
Pranay Prakash
|
047c01bc15 |
Make start() types unknown when deploymentId is provided (#1367)
* fix: update types and documentation for start function overloads Ensure types are 'unknown[]' and 'unknown' for 'deploymentId' and update exports and documentation. Slack-Thread: https://vercel.slack.com/archives/C09G3EQAL84/p1773368990070059?thread_ts=1773368990.070059&cid=C09G3EQAL84 Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * fix: use generics in deploymentId overloads to avoid contravariance issue Addresses PR review feedback: typed workflows like WorkflowFunction<[string], number> were not assignable to WorkflowFunction<unknown[], unknown> under strictFunctionTypes. Changed to generic parameters while keeping Run<unknown> return type. Also adds type-level tests for overload resolution. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * chore: add changeset for start() deploymentId type changes Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.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> |
||
|
Peter Wielander
|
136c1f4e97 | [docs] Tidy world API docs and document new stream helpers (#1581) | ||
|
Nathan Rajlich
|
7e33c62736 |
Rename 'Workflow Development Kit' / 'DevKit' to 'Workflow SDK' (#1595)
* Rename 'Workflow Development Kit' / 'DevKit' to 'Workflow SDK' across docs, code, and config
Follow-up to
|
||
|
Nathan Rajlich
|
a3d70353e5 |
docs: rename 'Complex Example' to 'Instance Methods as Steps' (#1592)
* docs: rename 'Complex Example' to 'Instance Methods as Steps' in serialization guide Rework the section title and introductory copy to better reflect the purpose: making classes with Node.js APIs / side effects workflow-compatible by adding "use step" to instance methods. * docs: clarify that the static requirement applies to serialization hooks Make the callout explicitly name WORKFLOW_SERIALIZE and WORKFLOW_DESERIALIZE so it doesn't read as a blanket restriction on instance methods, which would contradict the 'Instance Methods as Steps' section below. |
||
|
Lucas Ralph
|
e574ad2107 |
[docs] Split World API docs into sub-pages, update skill.md (#1457)
Signed-off-by: Lucas Ralph <lucas.ralph@vercel.com> Co-authored-by: Peter Wielander <mittgfu@gmail.com> |
||
|
Pranay Prakash
|
9cb1fc9482 |
docs: add webhook security disclaimer (#1574)
* docs: add webhook security disclaimer * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Peter Wielander <mittgfu@gmail.com> Signed-off-by: Pranay Prakash <pranay.gp@gmail.com> --------- Signed-off-by: Pranay Prakash <pranay.gp@gmail.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Peter Wielander <mittgfu@gmail.com> |
||
|
Peter Wielander
|
5ca55af2bd | [docs] Link to Vercel World pricing and limits pages (#1559) | ||
|
Nathan Rajlich
|
4f646e3d58 |
Polyfill TC39 Uint8Array base64/hex methods in workflow VM context (#1547)
* Polyfill TC39 `Uint8Array` base64/hex methods in workflow VM context * Replace `declare global` with local type interfaces to avoid type leakage * Document Uint8Array base64/hex methods in Workflow Globals page |
||
|
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) | ||
|
Nathan Rajlich
|
55c821ee85 |
Add missing workflow/errors card to API Reference index (#1549)
|
||
|
Nathan Colosimo
|
e045b59dc4 |
[world-postgres] Add maxPoolSize config for graphile (#1527)
Co-authored-by: Peter Wielander <mittgfu@gmail.com> |
||
|
Matan Kushner
|
52db376c39 |
Support projects with Node.js step dependencies in vitest plugin (#1524)
Co-authored-by: Peter Wielander <mittgfu@gmail.com> |
||
|
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> |
||
|
Peter Wielander
|
01bbe66d5a | [world] Add stream pagination and metadata endpoints (#1470) | ||
|
Peter Wielander
|
c1389ddf3f | Remove NestJS Vercel integration while in experimental phase (#1485) | ||
|
Pranay Prakash
|
2ef33d2828 |
feat: export semantic error types and add API reference docs (#1447)
* feat: export semantic error types and add API reference documentation Add missing error exports (HookNotFoundError, EntityConflictError, RunExpiredError, TooEarlyError, ThrottleError, RunNotSupportedError, WorkflowWorldError) to workflow/internal/errors. Create new error classes for world-level semantics. Tighten TSDoc comments on all error classes. Add API reference docs for all error types. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: use @setup declarations, workflow/errors import, and errors/ doc section - Replace @skip-typecheck with proper `declare` + `// @setup` lines so code samples are typechecked but setup lines hidden from readers - Add `workflow/errors` export to package.json (public API, replaces `workflow/internal/errors` in docs) - Add `workflow/errors` path mapping in docs-typecheck type-checker - Add HookConflictError to re-export list - Move all error docs under api-reference/workflow/errors/ subdirectory - Update all internal cross-references and links Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * refactor: move error docs to top-level workflow-errors section - Move semantic error docs to api-reference/workflow-errors/ (matching the workflow/errors import path, like workflow-api for workflow/api) - Keep FatalError and RetryableError in api-reference/workflow/ since they're imported from workflow, not workflow/errors - Fix all cross-reference links Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * chore: update HTTP debug logger JSDoc to clarify scope Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: make TooEarlyError.retryAfter a number (seconds) matching WorkflowWorldError TooEarlyError.retryAfter is now seconds (number) instead of a Date, consistent with ThrottleError and WorkflowWorldError. The conversion from seconds to Date is done at the consumer site (step-handler) rather than at construction time. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: address review feedback on docs accuracy - WorkflowWorldError docs: add status, code, url, retryAfter properties to TSDoc; clarify that .is() only matches direct instances (not subclasses); use instanceof in catch-all example - TooEarlyError/ThrottleError docs: mark retryAfter as optional (?) to match actual type definitions Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|
Peter Wielander
|
823f58e5c6 |
Revert "Add support for calling start() inside workflow functions (#1133)" (#1475)
This reverts commit
|
||
|
Peter Wielander
|
78f1b0e19f | [core] Support negative startIndex for streaming (#1460) | ||
|
Peter Wielander
|
2b07294313 | [core] Ensure open stream flush is await-able in pendingOps (#1446) | ||
|
Pranay Prakash
|
e889860984 |
Add support for calling start() inside workflow functions (#1133)
* Add support for calling `start()` directly inside workflow functions Enable `start()` to work in workflow context by routing through an internal step (`__workflow_start`), reusing existing step infrastructure with no new event types or server changes needed. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Address PR review feedback - Use typeof check instead of truthiness for WORKFLOW_START symbol - Validate start() options in workflow context (reject unsupported options like world) - Set maxRetries=0 on __workflow_start step to prevent orphaned child runs - Add unit tests for createStart factory (6 tests) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Make Run serializable in workflow context with step-backed methods - Add Run serialization via __serializable marker + custom Run reducer/reviver in the serialization module (avoids SWC plugin injecting class-serialization imports) - Create WorkflowRun class factory (packages/core/src/workflow/run.ts) with step-backed methods: cancel(), status, returnValue, workflowName, createdAt, startedAt, completedAt, exists - Register 8 built-in steps (__run_cancel, __run_status, etc.) in step-handler - Update __workflow_start to return full Run object (serialized → WorkflowRun in VM) - Update createStart to pass through step result directly - Update docs to reflect full Run support in workflow context Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix start() in workflow VM by delegating from api-workflow stub The workflow VM loads api-workflow.ts (via the "workflow" export condition) which stubs all runtime functions. The start stub needs to check for the injected WORKFLOW_START symbol and delegate to it, otherwise start() throws "doesn't allow this runtime usage" in the workflow context. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Address PR review: fix stale WORKFLOW_SERIALIZE comments and register Run in host registry - Update comments in step-handler.ts and start.ts to reference the actual serialization mechanism (Run reducer with __serializable marker) instead of the stale WORKFLOW_SERIALIZE reference - Register Run class in the host's class registry from step-handler.ts so the Run reviver can deserialize Run/WorkflowRun instances in step context Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Add docs for recursive/repeating workflows and deploymentId: "latest" - Document using start() for self-chaining workflows to avoid large event logs - Add examples for batch processing and cron-like repeating patterns - Document deploymentId: "latest" option with type safety warning - Update skill file with same patterns Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Return full Run object from startFromWorkflow e2e workflow Update the e2e workflow to return the childRun object directly instead of just childRun.runId, exercising Run serialization across the workflow boundary. Update e2e test assertions to match. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Add recursive fibonacci e2e test for start() in workflow Demonstrates recursive workflow composition: fibonacciWorkflow starts new instances of itself via start() + Promise.all to compute fib(6)=8, fanning out across independent workflow runs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Move Run method steps to builtins with "use step" directives Refactor: instead of manually registering Run method steps via registerStepFunction in step-handler.ts, define them as proper "use step" functions in builtins.ts with __builtin_ prefix. This leverages the existing SWC plugin infrastructure — functions starting with "__builtin" get stable bare-name step IDs. - Add __builtin_run_{cancel,status,return_value,...} to both builtins files - Use dynamic import() for getRun inside step bodies to avoid pulling Node.js modules into the workflow bundle - Remove manual registerStepFunction calls from step-handler.ts - Update WorkflowRun step references to __builtin_run_* names - Fix step name display in web observability: fall back to raw name instead of "?" for built-in steps that don't follow step//module//fn format - Add fibonacciWorkflow default args for nextjs-turbopack workbench UI Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Render Run objects as clickable links in web observability UI - Add RunRef type and Run reviver to observabilityRevivers so serialized Run objects are hydrated as RunRef instead of showing raw Uint8Array - Add RunRefInline component (purple badge with run ID) that navigates to the target run on click, matching the StreamRef pattern - Thread onRunClick callback through the component chain: WorkflowTraceViewer → EntityDetailPanel → AttributePanel → DataInspector - Wire up navigation in the web app's run-detail-view - Add startFromWorkflow default args for workbench UI Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Throw error instead of silent fallback when Run class not in registry Address PR review: the Run reviver now throws if the class isn't found in the registry, instead of silently returning a plain { runId } object that would break the assumption of getting a valid Run instance. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix e2e failures: allow retries on Run getter steps, fix docs code samples - Remove maxRetries=0 from read-only Run getter steps (status, returnValue, workflowName, etc.) — these are safe to retry and need retries when the child workflow hasn't completed within the step timeout. Only cancel keeps maxRetries=0. - Fix docs code samples: use correct import path (workflow/api not workflow), add declare statements for helper functions used in examples. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Use standard step//module//function naming for built-in steps Update the SWC plugin's __builtin_ special case to generate proper step//@workflow/core//{name} IDs instead of bare function names. This makes parseStepName work correctly for built-in steps, showing: - StepName: "Run#returnValue" (not "__builtin_run_return_value") - ModuleSpecifier: "@workflow/core" (not the raw function name) Convention: __builtin_Run_cancel → step//@workflow/core//Run#cancel (uppercase prefix + underscore → instance method # notation) - Move __workflow_start to builtins.ts as __builtin_start - Rename __builtin_run_* to __builtin_Run_* for proper # notation - Update WorkflowRun step refs to use full step// IDs - Remove manual registerStepFunction from step-handler.ts - Update SWC spec.md with new naming examples Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Remove SWC __builtin special case, use standard step naming for builtins Remove the SWC plugin's __builtin_ special case so built-in steps get standard step//{module}@{version}//{fn} IDs like any other step. This makes parseStepName work correctly, showing proper StepName and ModuleSpecifier in observability. The VM reconstructs the same IDs via builtinStepId() which uses the @workflow/core version to build: step//workflow/internal/builtins@{v}//{fn} - Remove __builtin special case from SWC plugin (revert to original) - Add builtinStepId() helper shared by workflow.ts, start.ts, run.ts - Rename Run steps: __builtin_Run_cancel → Run_cancel, etc. - Rename start step: __builtin_start → start - Move start step from manual registerStepFunction to builtins.ts - Keep __builtin_response_* names unchanged (pre-existing) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Use static class methods for Run steps to get Run.method naming Refactor Run method steps from standalone functions (Run_cancel) to static methods on a Run class, so the SWC plugin generates step IDs with the standard static method convention: Run.cancel, Run.returnValue, Run.status, etc. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Address PR review: tests, docs warnings, skill fix - Add TODO on Run.returnValue about polling blocking (replace with system hooks once AbortSignal/AbortController PR lands) - Add docs callout warning about returnValue holding workers alive - Fix SKILL.md contradiction that said start() can't be used in workflows - Enhance suspension test to assert step arguments are forwarded - Add WorkflowRun unit tests: serializable marker, runId, registry, delegation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix response builtins: adopt this-serialization from PR #1413 The rebase onto main didn't fully adopt PR #1413's refactor of response builtins to use `this` instead of explicit parameters. The old pattern (resJson(this) wrappers) passed `this` as an argument, but the step functions now expect `this` to be set via method call context. Switch to Object.defineProperties on Request/Response prototypes, matching main's approach. Also document WORKFLOW_PUBLIC_MANIFEST=1 for local e2e testing. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Address docs review: returnValue polling is temporary, link to start() API ref - Update returnValue warning to note this is a temporary implementation that will be replaced with internal hooks - Replace inline deploymentId: "latest" docs with link to the existing start() API reference which already covers it comprehensively Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix e2e tests: replace collectedRunIds with trackRun API PR #1426 replaced the manual collectedRunIds array with a trackRun() helper. The start() wrapper already auto-tracks, so just remove the manual push calls and add trackRun for the child run. 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 <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
|
f7bbe71e39 |
Add TSDoc for stepName field and document world.steps API (#1451)
* feat: add stepName field for human-readable step names Slack-Thread: https://vercel.slack.com/archives/C09125LC4AX/p1773936163539109?thread_ts=1773936163.539109&cid=C09125LC4AX Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * docs: add step examples with resolveData and hydration, document parseStepName/parseWorkflowName utilities - Split step examples into two: one with resolveData: 'none' for efficient listing without data, and one showing how to hydrate input/output with observabilityRevivers - Add TSDoc to stepName and workflowName fields explaining the machine-readable format and how to use parse utilities - Document parseStepName() and parseWorkflowName() from @workflow/utils/parse-name for extracting shortName and moduleSpecifier for UI display - Add Callout explaining the naming format --------- Co-authored-by: v0 <v0[bot]@users.noreply.github.com> Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> |
||
|
Nathan Rajlich
|
31bc57e513 |
Add encryption documentation and world features manifest (#1432)
* Add encryption documentation and world features manifest - Add encryption.mdx under How it Works explaining end-to-end encryption - Add features array to worlds-manifest.json (encryption for Vercel World) - Display encryption support in WorldDetailHero and WorldCardSimple - Add cross-references from Vercel World and Observability pages * Derive WorldFeature type from const array * Address review feedback: simplify key explanation, show 'No' for missing encryption, fix tooltip |
||
|
Nathan Rajlich
|
c31afa8099 |
Add documentation for custom class serialization (#810)
* Add documentation for custom class serialization
* Enhance serialization docs: custom class examples with 'use step' instance methods
- Add custom classes to Supported Serializable Types with anchor link
- Replace verbose parenthetical in Requirements with back-link
- Add [!code highlight] to Basic Example serde methods
- Simplify geometry.ts to import Point instead of redefining it
- Rewrite Complex Example to demonstrate 'use step' on instance methods
with realistic APIs (database, HTTP) and contrast with workflow-context methods
- Add pass-by-value note for 'this' context with return-and-reassign pattern
* Fix docs typecheck: use correct @expect-error codes for Order examples
* Fix pre-existing docs typecheck failures in workflow-serde API reference
Add @skip-typecheck to bare static method signatures that aren't valid
standalone TypeScript.
* Revert extractor changes, use HTML comments for @expect-error markers
The docs typecheck extractor only supports HTML comment syntax for
@expect-error on main. Use <!-- @expect-error:XXXX --> instead of
{/* @expect-error:XXXX */} to match the existing convention.
* Use MDX comment syntax for @expect-error markers, add MDX support to extractor
MDX files don't support HTML comments (<!-- -->). The extractor's
@expect-error regex only supported HTML syntax, but @skip-typecheck
already supported both. This aligns @expect-error to also support
the MDX comment syntax ({/* @expect-error:XXXX */}).
|
||
|
Nathan Rajlich
|
97e43846f0 |
docs: add documentation for deploymentId: "latest" in start() (#1409)
* docs: add documentation for `deploymentId: "latest"` in `start()` * docs: clarify deploymentId as Vercel-specific, add return value compat note |
||
|
Pranay Prakash
|
74aea7b0af |
Add DurableAgent compat tests, e2e tests, and migrate to AI SDK v6 (#1362)
* Add DurableAgent compat tests, e2e agent tests, and migrate to AI SDK v6 - Port ToolLoopAgent test suite as DurableAgent compatibility spec (34 tests, all expected to fail — each maps to a feature gap to implement) - Add e2e workflow definitions using mock LLM providers (no API keys needed) - Add e2e test file for DurableAgent workflows - Migrate all AI SDK types from V2 to V3 (LanguageModelV2 → V3, etc.) - Drop AI SDK v5 support: ai peer dep ^5||^6 → ^6, @ai-sdk/provider ^2||^3 → ^3 - Update ai catalog version from 5.0.104 to 6.0.116 - Simplify CompatibleLanguageModel to just LanguageModelV3 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Address PR review feedback - Remove providerExecuted guard on tool-result stream parts (V3: all tool-results are provider-executed by definition) - Remove providerExecuted spread from tool-output-available UI chunks - Replace inline MockLanguageModelV3 with import from ai/test (works without msw in AI SDK v6) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Remove streamTextIterator mock from compat tests, use it.fails for gaps Tests now exercise the real DurableAgent code path instead of mocking the core iterator. 5 tests pass (features DurableAgent already has), 29 are marked it.fails() for known API gaps that will alert when fixed. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Implement Tier 1+2 gaps, add @workflow/ai/test mock provider, wire e2e in CI DurableAgent API additions: - Add `instructions` (string | SystemModelMessage | SystemModelMessage[]) as alias for deprecated `system` on constructor - Add `onStepFinish` and `onFinish` on constructor, merged with stream options (constructor first, then stream — matching ToolLoopAgent) - Add `timeout` on stream options (converted to AbortSignal) - Add `text`, `finishReason`, `totalUsage` to onFinish event Test infrastructure: - Add @workflow/ai/test export with `mockModel()` wrapper that wraps MockLanguageModelV3 from ai/test as an async step function - E2e workflows now use mockModel() + convertArrayToReadableStream from @workflow/ai/test instead of inline V2 mock models - Add e2e-agent.test.ts to test:e2e script so it runs in CI - Flip 6 compat tests from it.fails → it (now passing) Score: 11 passing / 23 it.fails (was 5/29) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Remove e2e agent tests — mock models can't serialize across step boundary The workflow runtime serializes step arguments, and function closures (like mock model doStream callbacks) aren't serializable. Mock models only work in unit tests where 'use step' is a no-op. Real e2e agent tests would need either a mock HTTP server or real provider credentials. Also removes 'use step' from mockModel wrapper (closures aren't serializable) and reverts test:e2e script and example workbench dep. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Add working e2e agent tests with mock model step factories Mock model factories use the same 'use step' pattern as real providers (anthropic, openai). Closure variables are bound to locals at the step body level so the SWC plugin detects them via __private_getClosureVars. All 4 e2e tests pass against local dev server: - agentBasicE2e: text response (11s) - agentToolCallE2e: single tool call + text (11s) - agentMultiStepE2e: 3 sequential tool calls (12s) - agentErrorToolE2e: FatalError recovery (11s) Also adds e2e-agent.test.ts to test:e2e script for CI. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Use @workflow/ai/test package imports for e2e mock models Split mock provider into two files to work around SWC constructor closure bug: mock-create.ts has the model creation logic, mock.ts has the 'use step' wrappers that capture only serializable args (strings, plain object arrays). Exports mockTextModel(text) and mockSequenceModel(responses) — same 'use step' pattern as real providers (anthropic, openai, etc.). E2e workflows now import directly from @workflow/ai/test. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Simplify mock provider, add comprehensive e2e tests for all features + gaps Mock provider: - Replace mock-create.ts with mock-function-wrapper.ts that simply wraps MockLanguageModelV3 constructor in a function (SWC class closure bug) - mockTextModel/mockSequenceModel use mockProvider() from wrapper file - Bind closure vars at step body level (_text = text) for SWC detection - Fix AbortController not available in workflow VM sandbox E2e tests (13 total, all passing): - Core: basic text, tool call, multi-step, error recovery (4) - Callbacks: onStepFinish constructor+stream, onFinish constructor+stream (2) - Features: instructions, timeout (2) - GAPs documented: onStart, onStepStart, onToolCallStart, onToolCallFinish, prepareCall (5 — complete but callbacks not called) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Add tool approval (needsApproval) gap tests, fix SWC closure var binding Unit tests: 2 new it.fails() tests for tool approval - needsApproval: true should pause agent (pending tool call, no result) - needsApproval as function should receive tool input E2e tests: 1 new test for tool approval gap - Documents that needsApproval is currently ignored (tool executes anyway) Also fixes: - Bind closure vars at step body level in mock provider (_text = text, _responses = responses) so SWC plugin detects them - Guard AbortController usage in workflow VM (not available in sandbox) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Add default args for agent e2e workflows in UI definitions The nextjs-turbopack UI calls workflows with hardcoded default args. Without these entries, agent workflows were called with no args, causing prompt=undefined → ModelMessage validation failure. Also removes debug logging. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Add DurableAgent chat UI with tools, update docs for AI SDK v6 Chat UI: - Tab-based layout with Workflows (existing) and DurableAgent Chat tabs - Chat powered by DurableAgent + WorkflowChatTransport + ai-elements - Tools: getWeather (fake data), calculate (math expressions) - Uses createUIMessageStreamResponse for proper stream serialization - Reconnect route at /api/chat/[runId]/stream - ai-elements components: conversation, message, prompt-input, tool - onStepFinish + onFinish callbacks with console logging Docs (AI SDK v6 migration): - system → instructions in DurableAgent constructor examples (10 places) - LanguageModelV2Prompt → LanguageModelV3Prompt in type references (3 places) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix tool rendering, add reasoning support, model picker, observability links - Fix tool part rendering: use `input`/`output` props (not `args`/`result`) and `tool-{name}` part type (AI SDK v6 format) - Add reasoning support for Opus 4.5 via providerOptions - Model picker: Haiku 4.5, Sonnet 4, Opus 4.5 (reasoning), GPT-5.2, GPT-5.3 - Fix observability links: localhost:3456 for local, Vercel dashboard for prod - Add suggestions above prompt input - Add MessageParts component handling text, tool, reasoning, step-start - Add loading spinner for submitted state - Update docs: system → instructions, LanguageModelV2Prompt → V3 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix tool output rendering: use input/output props on ToolInput/ToolOutput Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix: Documentation for `PrepareStepInfo` and `PrepareStepResult` interfaces references the obsolete `LanguageModelV2` type while the codebase has fully migrated to `LanguageModelV3`. This commit fixes the issue reported at docs/content/docs/ai/message-queueing.mdx:36 **Bug explanation:** The codebase migrated from AI SDK V2 to V3. In `packages/ai/src/agent/types.ts`, `CompatibleLanguageModel` is defined as `LanguageModelV3` (from `@ai-sdk/provider`). The actual TypeScript interfaces in `packages/ai/src/agent/durable-agent.ts` use `string | (() => Promise<CompatibleLanguageModel>)` which resolves to `LanguageModelV3`. However, the documentation in `docs/content/docs/ai/message-queueing.mdx` at lines 36 and 43 still referenced `LanguageModelV2` for the `model` field in both `PrepareStepInfo` and `PrepareStepResult`. This is inconsistent because: 1. The `messages` fields in the same interfaces were correctly updated to `LanguageModelV3Prompt` 2. The actual source code uses `LanguageModelV3` via `CompatibleLanguageModel` 3. There is no `LanguageModelV2` type anywhere in the codebase This would mislead developers reading the documentation into using the wrong type. **Fix explanation:** Changed both `LanguageModelV2` references to `LanguageModelV3` on lines 36 and 43 of the documentation file, matching the actual codebase types. Verified no other stale `LanguageModelV2` references remain in the docs directory. Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com> Co-authored-by: pranaygp <pranay.gp@gmail.com> * Fix instructions tests: flip from it.fails to it, update snapshots The 3 instructions tests (string, SystemModelMessage, array) now pass. The snapshots include the assistant reply message from the agent loop, which is a behavioral difference from ToolLoopAgent (DurableAgent captures the prompt after the full loop iteration). Score: 14 passing / 22 it.fails (was 11/25) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix getReadable call: pass startIndex as options object Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix docs type errors and turbopack build Docs: - Add await to convertToModelMessages() calls (now async in AI SDK v6) - Change LanguageModelV3Prompt → ModelMessage[] in type references - Change LanguageModelV3 → LanguageModel in PrepareStepInfo - Update docs-globals.d.ts convertToModelMessages return type - Add LanguageModel to import inference map DurableAgent: - Update OutputSpecification to match AI SDK v6 Output interface (type→name, parsePartial→parsePartialOutput, parseOutput→parseCompleteOutput, responseFormat now PromiseLike) Turbopack build: - Remove streamdown plugins from MessageResponse (plugins prop API changed in streamdown 2.4.0, causing type mismatch in CI) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix pnpm-workspace.yaml: use double quotes for catalog entries The stage-workbench-with-tarballs.mjs script only strips double quotes when parsing catalog keys. Single-quoted @-scoped entries (e.g., '@types/node') weren't matched, causing "unresolved catalog dependencies" errors in CI. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix CI build failures, add changeset - Remove streamdown plugins from reasoning.tsx (same CI type mismatch) - Cast ToolHeader type prop and WorkflowChatTransport to fix type errors - Fix pnpm-workspace.yaml single→double quotes for staging script - Add minor changeset for @workflow/ai (breaking: AI SDK v6 migration) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Sync webpack workbench with turbopack: add chat UI deps and symlinks - Symlink app-shell.tsx, chat-client.tsx, agent_chat workflow, chat API routes into nextjs-webpack - Add matching deps: streamdown, @streamdown/*, shiki, cmdk, nanoid, motion, @radix-ui/react-use-controllable-state Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix circular symlink: restore chat-client.tsx as real file in turbopack The previous commit accidentally converted turbopack's chat-client.tsx into a circular symlink pointing to itself. Webpack's symlink to it then couldn't resolve, breaking both builds on Vercel. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Add missing deps to webpack: use-stick-to-bottom, radix-ui, @vercel/blob Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix model picker: merge body params via prepareSendMessagesRequest WorkflowChatTransport sends { messages } by default, ignoring the body option from ChatRequestOptions. Use prepareSendMessagesRequest to merge { messages, ...body } so the model selection reaches the API. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix WorkflowChatTransport: forward body/headers from ChatRequestOptions The transport hardcoded body: undefined when calling prepareSendMessagesRequest, so extra body params (like model selection) from sendMessage({ body: { model } }) were silently dropped. Now forwards options.body and options.headers to both prepareSendMessagesRequest and the default request body. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix model IDs: use real AI Gateway model names gpt-5.2 and gpt-5.3 don't exist in the AI Gateway. Replace with gpt-4o and gpt-4o-mini. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Use correct AI Gateway model IDs: Opus 4.5, GPT-5.2, GPT-5.3 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Enable reasoning for all model providers - Anthropic: thinking.type='enabled' with 10k token budget - OpenAI: reasoningEffort='high' - Instructions kept for all models (no longer conditionally removed) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix OpenAI reasoning: use 'medium' effort (GPT-5.3 doesn't support 'high') Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Address all PR review comments - Change changeset from minor to patch (repo convention) - Use ?? instead of || for system/instructions fallback - Clean up timeout: store ID, clearTimeout in finally, { once: true } listeners - Update class docstring example to use instructions - Map unrecognized finish reasons to 'other' with validation - Fix duplicate test, align assertion for unrecognized type - Support ^ exponentiation in calculate tool - Remove debug console.log from chat client - Fix ReactNode/ComponentProps type imports in UI components - Remove unused MockLanguageModelV3 re-exports from mock.ts Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Remove accidentally created empty mock2.ts Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Change changeset back to minor for breaking AI SDK v6 migration Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix agent e2e tests: add Vercel world setup for CI The agent e2e tests only configured the local filesystem world but not the Vercel world backend. On CI (Vercel prod tests), this caused VercelOidcTokenError because the world wasn't initialized. Now matches the setup pattern from e2e.test.ts: configures Vercel world with OIDC token and project config from CI environment variables. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Deduplicate e2e test utilities: extract shared code to utils.ts Extract manifest fetching, workflow lookup, world setup, and types into shared utils.ts. Both e2e.test.ts and e2e-agent.test.ts now import from the same source, eliminating ~200 lines of duplication. Shared utilities: - WorkflowManifest interface - fetchManifest() with caching - getWorkflowMetadata() with retry and fallback - setupWorld() handling local/Vercel/Postgres backends Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix missing deploymentUrl args in e2e.test.ts after utils refactor Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Add @workflow/ai dep to all workbenches for agent e2e tests All workbenches now have @workflow/ai as a dependency and the 100_durable_agent_e2e.ts symlink, so agent e2e tests run everywhere. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix missing imports in e2e.test.ts: add fetchManifest and sleep The utils refactor removed these imports but they're still used: - fetchManifest: used in stepFunctionAsStartArgWorkflow test - sleep (setTimeout): used in webhookWorkflow test Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com> |
||
|
Pranay Prakash
|
fb5a500ead |
feat: add exists getter to Run class (#1336)
* feat: add `exists` getter to `Run` class Allow checking if a workflow run exists without catching errors. Returns `true` if the run is found, `false` for WorkflowRunNotFoundError, and re-throws any other errors. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * address PR feedback: use resolveData: 'none' in exists getter, fix docs wording Pass { resolveData: 'none' } to world.runs.get() in the exists getter to skip fetching input/output payloads. Update docs to say "without throwing when the run is not found" instead of "without throwing an error". 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> |
||
|
Peter Wielander
|
456c1aa455 | Add vitest plugin for testing full workflows without setting up a server (#1237) | ||
|
Pranay Prakash
|
30e24d441e |
Merge commit from fork
* Prevent deterministic tokens in createWebhook Remove the `token` option from `WebhookOptions` to prevent unauthorized access to the public webhook endpoint. Webhook tokens are now always randomly generated. Deterministic tokens remain available for `createHook()` with server-side `resumeHook()`. **BREAKING CHANGE**: `createWebhook()` no longer accepts a `token` option. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Address PR feedback: throw on token, revert unnecessary doc changes, replace examples - createWebhook() now throws an error if token is passed at runtime instead of silently stripping it - Revert unnecessary changes to create-hook.mdx (only keep slack_webhook -> slack_messages prefix change) - Replace Slack webhook examples in create-webhook.mdx and hooks.mdx with generic event collector examples that make sense without deterministic tokens Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Address andresriancho's feedback: stricter token check, add unit test - Use `token !== undefined` instead of `if (token)` for correctness (empty string should also be rejected) - Add unit test verifying createWebhook({ token: "anything" }) throws the expected error message Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * change changeset to minor * 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> * Revert "Fix docs typechecker to actually resolve workflow module types" This reverts commit 02d42ac866e6db1b6d016339739344cdd9538e90. * chore: trigger CI Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|
John Lindquist
|
4ac75f4806 |
Add Fluid compute callout to Vercel World docs (#1242)
* Add Fluid compute warning callout to Vercel World docs Follow-up from #1216 review feedback to include the FluidComputeCallout on the Vercel World page. * Register FluidComputeCallout in worlds/[id] page The /worlds/vercel route uses a separate page component from /docs/... and was missing the FluidComputeCallout in its MDX component map, causing a 500 error. |
||
|
Pranay Prakash
|
4ab4412ae6 |
Add Run.wakeUp() method to interrupt pending sleeps (#1232)
* feat: add testing section and navigation link Create new 'testing/' section and update Foundations index page. Slack-Thread: https://vercel.slack.com/archives/C09125LC4AX/p1772375177894629?thread_ts=1772375177.894629&cid=C09125LC4AX Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * docs: fix testing page API references and examples Slack-Thread: https://vercel.slack.com/archives/C09125LC4AX/p1772375177894629?thread_ts=1772375177.894629&cid=C09125LC4AX Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * fix: update testing.mdx and meta.json for docs-writer guidelines Slack-Thread: https://vercel.slack.com/archives/C09125LC4AX/p1772375177894629?thread_ts=1772375177.894629&cid=C09125LC4AX Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * feat: clarify unit testing focus on steps, remove workflow example Update documentation to emphasize unit testing for steps only. Slack-Thread: https://vercel.slack.com/archives/C09125LC4AX/p1772375177894629?thread_ts=1772375177.894629&cid=C09125LC4AX Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * feat: reorganize testing page and fix unit test section Move testing to top-level, fix content and update meta files. Slack-Thread: https://vercel.slack.com/archives/C09125LC4AX/p1772375177894629?thread_ts=1772375177.894629&cid=C09125LC4AX Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * feat: add Nitro server setup and observability section to tests Add 'globalSetup' script and vitest config, and update docs for test debugging. Slack-Thread: https://vercel.slack.com/archives/C09125LC4AX/p1772375177894629?thread_ts=1772375177.894629&cid=C09125LC4AX Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * [ci] Disable claude code CI (#1231) * feat: add `Run.wakeUp()` method to programmatically interrupt pending sleeps Exposes the existing `wakeUpRun` logic as an instance method on the `Run` class, allowing users to skip sleep() calls in tests or custom UIs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: address PR review comments - Fix JSDoc @returns to describe StopSleepResult object instead of number - Clean up global world state in afterEach to prevent test leakage - Add delay before wakeUp() in docs example to allow workflow replay Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * chore: restore claude.yml to match base branch The file was removed on main but still exists on the base branch. Restoring it so this PR's diff only contains relevant changes. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: add imports to standalone code snippet in get-run docs The docs test type-checks each code block independently, so the standalone wakeUp snippet needs its own imports and run variable. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: use @setup preamble for standalone wakeUp snippet Use the // @setup comment pattern to provide type context without rendering the setup line, keeping the snippet lean. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: document // @setup preamble pattern in docs-writer agent Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.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: Peter Wielander <mittgfu@gmail.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|
John Lindquist
|
42361d651b |
Add Fluid compute warning callout across deployment docs (#1216)
Signed-off-by: John Lindquist <johnlindquist@gmail.com> Co-authored-by: Peter Wielander <mittgfu@gmail.com> |
||
|
Pranay Prakash
|
329ad19806 |
Add Testing documentation as top-level page (#1229)
* feat: add testing section and navigation link Create new 'testing/' section and update Foundations index page. Slack-Thread: https://vercel.slack.com/archives/C09125LC4AX/p1772375177894629?thread_ts=1772375177.894629&cid=C09125LC4AX Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * docs: fix testing page API references and examples Slack-Thread: https://vercel.slack.com/archives/C09125LC4AX/p1772375177894629?thread_ts=1772375177.894629&cid=C09125LC4AX Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * fix: update testing.mdx and meta.json for docs-writer guidelines Slack-Thread: https://vercel.slack.com/archives/C09125LC4AX/p1772375177894629?thread_ts=1772375177.894629&cid=C09125LC4AX Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * feat: clarify unit testing focus on steps, remove workflow example Update documentation to emphasize unit testing for steps only. Slack-Thread: https://vercel.slack.com/archives/C09125LC4AX/p1772375177894629?thread_ts=1772375177.894629&cid=C09125LC4AX Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * feat: reorganize testing page and fix unit test section Move testing to top-level, fix content and update meta files. Slack-Thread: https://vercel.slack.com/archives/C09125LC4AX/p1772375177894629?thread_ts=1772375177.894629&cid=C09125LC4AX Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * feat: add Nitro server setup and observability section to tests Add 'globalSetup' script and vitest config, and update docs for test debugging. Slack-Thread: https://vercel.slack.com/archives/C09125LC4AX/p1772375177894629?thread_ts=1772375177.894629&cid=C09125LC4AX Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> --------- Co-authored-by: v0 <v0[bot]@users.noreply.github.com> Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> |
||
|
Pranay Prakash
|
02681dce4a |
feat(core): add hook.dispose() method to release hook tokens early (#1181)
* feat(core): add hook.dispose() method to release hook tokens early Add a `dispose()` method to the Hook interface that allows workflows to explicitly release hook tokens for reuse by other workflows while the current workflow is still running. This enables handoff patterns where one workflow can transfer a hook token to another workflow. - Add `dispose()` method to Hook interface in create-hook.ts - Implement dispose functionality in workflow/hook.ts - Add HookDisposedInvocationQueueItem to global.ts - Handle hook_disposed events in suspension-handler.ts - Update documentation in hooks.mdx and create-hook.mdx - Add e2e test for hook token reuse after explicit disposal https://claude.ai/code/session_01AkvrXduyFTbtV2joTPHrDH * feat(core): implement TypeScript Disposable spec for hooks Add Symbol.dispose to Hook interface to support the TC39 Explicit Resource Management proposal. This allows hooks to be used with the `using` keyword for automatic disposal when exiting scope. https://claude.ai/code/session_01AkvrXduyFTbtV2joTPHrDH * docs: prefer `using` keyword for hooks and webhooks Update all documentation and e2e tests to use the `using` keyword as the recommended approach for creating hooks and webhooks. This leverages the TC39 Explicit Resource Management proposal for automatic disposal. - Update e2e tests to use `using` syntax - Update foundational hooks guide to recommend `using` - Update create-hook API reference with `using` examples - Update create-webhook API reference with `using` examples - Update example workflow to use `using` https://claude.ai/code/session_01AkvrXduyFTbtV2joTPHrDH * chore: simplify `using` examples in docs and e2e tests Remove unnecessary block scopes and excessive comments about automatic disposal. Block scopes are only used when early disposal is relevant (like in the handoff test). https://claude.ai/code/session_01AkvrXduyFTbtV2joTPHrDH * docs: add brief explanation of `using` in first examples Add a one-liner explaining the `using` keyword in the intro examples of the API reference docs, so new users understand the syntax. https://claude.ai/code/session_01AkvrXduyFTbtV2joTPHrDH * fix: address PR review comments - Restore code highlights (`[!code highlight]`) that were unintentionally removed from pre-existing doc examples - Move `using` explanation from prose to inline code comment in intro examples - Add `{/* @skip-typecheck */}` to incomplete manual dispose() snippet - Add 409 (conflict/duplicate) error handling for hook_disposed events in suspension handler to handle workflow re-invocation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: polyfill Symbol.dispose in workflow VM context The workflow VM sandbox doesn't have Symbol.dispose/Symbol.asyncDispose available, causing `using` keyword to fail with "Symbol.dispose is not defined" at runtime. Add polyfill in the VM context creation. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: use VM's Symbol.dispose for hook disposable support The workflow VM sandbox has its own Symbol object with a polyfilled Symbol.dispose. The hook object was using the host's Symbol.dispose, which is a different symbol instance. The SWC-compiled `using` keyword looks up the VM's Symbol.dispose on the object, causing "Object not disposable" errors. Fix by setting Symbol.dispose on the hook object dynamically using the VM's globalThis.Symbol.dispose from the orchestrator context. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: revert webhookWorkflow to create all webhooks upfront The webhookWorkflow e2e test creates 3 webhooks that must all exist before the test sends HTTP requests. Using `using` with sequential creation meant only the first webhook existed at the first suspension point. Revert to `const` since all webhooks need to be created upfront. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: eliminate hook_disposed queue item, use flag pattern for disposal Instead of adding a separate HookDisposedInvocationQueueItem to the queue on dispose, keep the HookInvocationQueueItem throughout the hook lifecycle and track state with flags (hasCreatedEvent, disposed). A closure variable (hasDisposedEvent) makes disposeHook() a pure no-op on replay, avoiding redundant server calls and 409 errors. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: delete hook from invocations queue on hook_disposed terminal event Match the pattern used by steps (step_completed/step_failed) and waits (wait_completed) where the queue item is removed on the terminal event. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * test: verify dispose() is safe when called twice after replay Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * test: add comprehensive edge case tests for hook disposal - WorkflowSuspension counts disposed hooks separately from active hooks - Dispose after hook_created replay produces correct suspension - Dispose before first suspension (needs both create + dispose) - Multiple hooks where only one is disposed - Dispose on a conflicted hook is safe (no crash) - Symbol.dispose calls disposeHook correctly (using keyword pattern) - Iterator break without dispose keeps hook alive in queue - Await after dispose on first invocation triggers suspension Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: remove unsafe cast by adding Symbol.dispose to hook object literal Add [Symbol.dispose] directly to the hook object so it satisfies the Hook<T> type without `as unknown as`. The VM's Symbol.dispose is still added separately when it differs from the host's. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: address remaining Copilot review comments - Rename test to match new behavior (hooks stay in queue, not removed) - Use neutral "processed" verb in WorkflowSuspension message when mixed item types are present - Remove extends Disposable from Hook interface to avoid requiring lib.esnext.disposable in downstream consumers (explicit [Symbol.dispose]() method is still declared on the interface) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: drain pending promises in disposeHook to prevent orphaned awaits When dispose() is called while a promise is pending (e.g., iterator suspended on yield await this, or direct await hook after dispose), the promise would hang forever since the event consumer will never deliver another hook_received. Now disposeHook() clears the promises array and triggers a WorkflowSuspension so the runtime processes the disposal cleanly. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * chore: remove workflow from changeset, keep only @workflow/core Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com> |
||
|
Kevin
|
1f9a67c759 | [world-postgres] Replace pg-boss with graphile-worker (#1124) | ||
|
Pranay Prakash
|
5e06a7c833 |
Materialize waits as entities to prevent duplicate wait_completed events (#1057)
* Handle 409 conflict when completing waits that were already completed When multiple concurrent workflow invocations race to complete the same wait, the server returns 409 (conflict) for duplicates. This change handles the 409 gracefully in both runtime.ts (sleep elapsed check) and runs.ts (wakeUpRun), preventing crashes and treating already-completed waits as successful. Also updates event-sourcing docs to reflect that waits are now materialized as entities in storage with atomic completion guarantees. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Point e2e tests at workflow-server preview for wait materialization branch Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Materialize waits as entities in local and postgres worlds to prevent duplicate wait_completed events Adds Wait type/schema to the shared world package and implements wait entity materialization in both local (filesystem) and postgres world implementations, matching the DynamoDB behavior. wait_created creates a wait entity with status 'waiting', and wait_completed transitions it to 'completed' with guards that reject duplicates (409). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix waitId to use composite key for consistency with postgres world Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Clean up wait entities on terminal run states and register waits migration Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Clear WORKFLOW_SERVER_URL_OVERRIDE for merge Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Update changeset for all affected packages and restore server URL override Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Clear WORKFLOW_SERVER_URL_OVERRIDE now that server PR is merged The server-side changes (vercel/workflow-server#265) have been merged to main and deployed to production, so we no longer need to point at the preview URL. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> |