mirror of
https://github.com/vercel/workflow.git
synced 2026-09-14 19:59:43 +08:00
main
427 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Peter Wielander
|
382cdf4f60 | Split tarball hosting out of docs into its own project (#1893) | ||
|
Peter Wielander
|
2f52d14f38 | [vitest] [world-local] Fix local-world data recovery isolation (#1895) | ||
|
Nathan Rajlich
|
cd50618d1f |
ci: switch Vercel deployment-protection bypass to OIDC Trusted Sources (#1882)
* ci: switch Vercel deployment-protection bypass to OIDC Trusted Sources The e2e, benchmark, and docs-smoke CI jobs previously used the static `VERCEL_AUTOMATION_BYPASS_SECRET` deployment-protection bypass token to reach protected Vercel deployments. Switch them over to the new OIDC Trusted Sources flow: the GitHub Actions runner mints a short-lived OIDC token via `core.getIDToken()` and forwards it on requests in the `x-vercel-trusted-oidc-idp-token` header. Each workbench project (and `workflow-docs`) has been configured with a matching trusted-source rule: aud=https://github.com/vercel, repository=vercel/workflow The shared header helper now lives at `scripts/trusted-sources-headers.mjs` and is imported by both the e2e/bench tests and the docs smoke script, removing the previous duplication. * rename to VERCEL_OIDC_TOKEN and wire through world-vercel - Rename the env var from VERCEL_TRUSTED_OIDC_TOKEN to VERCEL_OIDC_TOKEN to match Vercel's convention (also read by @vercel/oidc's getVercelOidcToken()). - In @workflow/world-vercel, replace the legacy VERCEL_WORKFLOW_SERVER_PROTECTION_BYPASS / x-vercel-protection-bypass flow with VERCEL_OIDC_TOKEN / x-vercel-trusted-oidc-idp-token. The trusted-source header is attached on every outbound workflow-server request (both proxied through api.vercel.com and direct). - Drop the bypass header from the encryption-key and resolve-latest-deployment fetches: those go to api.vercel.com which is public. - Drop VERCEL_WORKFLOW_SERVER_PROTECTION_BYPASS plumbing from tests.yml. - Update the pending world-vercel changeset to describe the final trusted-sources flow. * . * . * ci: add statuses:read permission for wait-for-vercel-project action The action queries /commits/{sha}/status (Commit Statuses API) in addition to the Deployments API, in order to extract the Vercel `dpl_...` ID. With an explicit permissions block in place, GITHUB_TOKEN now needs `statuses: read` or the action 403s when resolving the deployment ID. Reported by Copilot review on #1882. * ci(docs): log status code and body when waitForServer times out Helps diagnose deployment-protection / OIDC-trusted-source bypass failures (e.g. SSO redirects) on the workflow-docs preview. * ci(docs): log OIDC token claims (aud, repository, etc.) for diagnostics Helps determine whether the bypass is failing because of missing trusted-source config, claim mismatch, or audience mismatch. * ci(docs): add curl debug step to verify OIDC header reaches Vercel * . * ci: remove debug logging now that trusted-sources config is correct The fetch-failure root cause was the trusted-sources rule format: the labs workbench projects had been PATCHed with just `to.slugs` (no `preset`), but Vercel's edge requires the dashboard-form-style `to.preset: 'all-custom'` field plus `development` in the slug list to match incoming requests. After re-PATCHing all projects with the correct format, the bypass works end-to-end. * ci(docs): debug — test trusted-sources bypass against docs and labs deployments Trying repository_owner claim added to one labs project to see if that fixes the bypass. * ci(docs): revert curl debug step The GitHub Actions OIDC trusted-sources bypass returns 401 on all tested projects regardless of claim configuration (including workflow-docs which was set up via the dashboard). This is not a per-project config issue. Need to investigate with Vercel team before continuing. * ci(docs): probe trusted-sources bypass and surface x-vercel-id Adds a debug step that does two HEAD requests against the docs preview deployment (with and without the OIDC trusted-sources header) and prints the response status line plus `x-vercel-id` for each. The proxy-side trusted-sources changes for GitHub Actions OIDC tokens are rolling out gradually (~12+ hours), so the edge-node identifier in `x-vercel-id` helps explain why a request might succeed or fail during the rollout window. Also includes `x-vercel-id` in the `waitForServer` timeout error so post-mortem analysis of failing runs has the same edge-node info. * ci(docs): drop trusted-sources curl probe — bypass works once proxy fix reaches the serving edge node The probe served its purpose: confirmed the bypass is functional once the request lands on a region that has the proxy-side trusted-sources fix rolled out. The waitForServer error message still surfaces x-vercel-id for any future rollout-window debugging. * . * world-vercel: log outbound OIDC token claims once per process Adds a one-shot diagnostic that prints the non-sensitive claims of the OIDC token (`iss`, `aud`, `owner_id`, `project_id`, `environment`, `sub`, `scope`, `exp`) on the first request that uses bearer auth. This is invaluable for debugging Vercel deployment-protection trusted-source rule mismatches: a 401 from the edge tells you nothing about why the rule didn't match, and the token's claims are the only thing that determines that. The signature is never logged. Gated to once per process — Vercel-issued tokens are process-stable for the lambda's lifetime so further log lines would just be redundant spam. * world-vercel: route trusted-sources header through getVercelOidcToken() The Authorization bearer correctly preferred config.token (a static Vercel auth token from CLI / Actions runner) and fell back to getVercelOidcToken() inside a Vercel function. But the trusted-sources bypass header (x-vercel-trusted-oidc-idp-token) was being read directly from process.env.VERCEL_OIDC_TOKEN inside getHeaders(). That env var is the bake-time token, frozen at deployment-creation time — on a project that has been redeployed after a settings change, it carries stale claims (e.g. an iss from when the project was briefly in 'global' mode) that no longer match the workflow-server's trusted-sources rule. Move trusted-sources header attachment from getHeaders() (sync) to getHttpConfig() (async) and source it from getVercelOidcToken(). That function reads getContext().headers['x-vercel-oidc-token'] first — a freshly minted per-request token that always reflects current project settings — and only falls back to the env var when that header is missing. Bearer auth source remains config.token-first. Also expand the diagnostic to log claims from BOTH the per-request OIDC token AND the bake-time env var so the divergence is visible in logs when debugging future trusted-source mismatches. Removes the now-misleading getProtectionBypassHeader() helper (its 'read env var directly' semantics were exactly the bug). * world-vercel: skip OIDC trusted-sources header on proxied path The two outbound flows have different auth requirements: 1. Proxied (usingProxy=true) — calls api.vercel.com/v1/workflow. Public endpoint, authenticated with a static Vercel auth token via config.token. The api-workflow proxy mints its own OIDC token before forwarding to workflow-server, so the trusted-sources bypass header on the SDK→proxy hop is meaningless. CLI, GitHub Actions, and other API-client callers take this path. 2. Direct (usingProxy=false) — runs inside a Vercel deployment talking straight to workflow-server. workflow-server validates a Vercel OIDC bearer; Vercel's edge validates the trusted-sources header. Both must come from getVercelOidcToken() (the per-request fresh token), not process.env.VERCEL_OIDC_TOKEN (the bake-time token that can be stale after a project config change). Previously getHttpConfig attached x-vercel-trusted-oidc-idp-token on both paths whenever getVercelOidcToken() resolved. That accidentally forwarded the GitHub Actions OIDC token (when wired into VERCEL_OIDC_TOKEN by the test runner) onto every SDK→proxy request, which is harmless but wrong-by-design — the proxy is public, doesn't look at that header on its inbound side, and the GHA token isn't its intended audience. Bearer auth source rules: - Proxied: only config.token. (No fallback to OIDC; that auth pathway doesn't go through the proxy's auth checks.) - Direct: config.token (for tests / local dev), falling back to getVercelOidcToken() (for Vercel-runtime calls). * world-vercel: throw if proxied path is hit without a Vercel auth token The api-workflow proxy authenticates the caller with a regular Vercel auth token (not OIDC), so reaching the proxied path with no config.token is always wrong: the proxy will reject the request and the SDK caller would see an opaque 401 with no actionable hint. Throw at config-resolution time with a clear message that points to the WORKFLOW_VERCEL_AUTH_TOKEN env var the SDK reads from. Adds tests covering both the no-token-throws case and the with-token-attaches- bearer-and-skips-trusted-sources case. * test(e2e): include x-vercel-id in startWorkflowViaHttp error message When the trusted-sources bypass returns 401, the error message now surfaces the response's x-vercel-id header so we can identify which edge node served the failure. Helps distinguish proxy-rollout incompleteness from actual config errors during incremental rollouts of edge-side changes. * ci: mint GHA OIDC tokens on demand to survive 5-minute expiry GitHub Actions OIDC tokens have a hard 5-minute lifetime that cannot be extended (no API to ask for a longer TTL — exp is always iat + ~300s). Pre-minting once at the start of the job and shipping the result down to the test runner via env var means tests that run late in the suite hit an expired token and 401 on /api/trigger-pages (and any other trusted-sources protected endpoint). Move minting into scripts/trusted-sources-headers.mjs: - getTrustedSourcesHeaders() is now async. - It calls the runner's ACTIONS_ID_TOKEN_REQUEST_URL endpoint directly (the env vars GHA exposes when permissions: id-token: write is on) and re-mints 60s before the cached token's exp. - Falls back to process.env.VERCEL_OIDC_TOKEN for non-GHA contexts (Vercel runtime, local dev). Workflow files drop the now-redundant 'Mint OIDC token' step and the VERCEL_OIDC_TOKEN env-var passthrough on the test step. The runner env vars propagate to subsequent steps automatically. Updates all 17 callers in e2e.test.ts / bench.bench.ts / utils.ts / docs/scripts/check-docs-smoke.mjs to await the now-async call. * address PR #1882 code review - Drop `statuses: read` from the three workflow permission blocks (the wait-for-vercel-project action works without it on a public repo). - Revert the `x-vercel-id` debug logging in `startWorkflowViaHttp`. - Delete `packages/world-vercel/src/jwt-claims.ts` (debug-only helper). - Drop the JWT claims diagnostic logging from `getHttpConfig`. - Tighten the auth-flow comment in `getHttpConfig` and remove the historical 'no longer attaches' note from `getHeaders`/its test. - Restore `.changeset/world-vercel-protection-bypass.md` (already shipped in a beta release per .changeset/pre.json). - Trim the `.changeset/world-vercel-trusted-sources.md` description to one short paragraph. * docs(AGENTS): document local VERCEL_OIDC_TOKEN via vercel env pull Configured trustedSources.projects on all 11 workbench app projects so each one accepts a Vercel-issued OIDC token from any of the others. A developer running e2e locally can now do `vercel env pull` from any workbench app's directory and use the resulting VERCEL_OIDC_TOKEN to bypass Deployment Protection on any of the workbench preview/prod deployments — no need to disable protection on the project just to run the suite locally. |
||
|
Mitul Shah
|
03dfab35e7 | Updated Workflow Trace viewer (#1454) | ||
|
Karthik Kalyan
|
64c66d211e |
docs(cookbook): rewrite core recipes, dedupe, and reorder sidebar (#1850)
* fix(docs): highlight active top-bar nav item and drop duplicate keys Match the current pathname (accounting for the hidden default locale) and forward an `active` prop to the Radix NavigationMenuLink so the selected top-bar item stays highlighted. Also remove module-level `key` props from the intro Loading/Success/Error indicators — they fired React's duplicate-key warning whenever two lines shared a state. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * update saga cookbook docs with adaptation guidance and streaming example Made-with: Cursor * docs(cookbook): rewrite core recipes, dedupe, reorder sidebar Pass over the cookbook focused on correctness, concrete examples, and tighter information architecture. Rewrites: - Saga / Batching / Scheduling: concrete use cases (order fulfillment, CSV import, cancellable drip campaign); added "how it works" + "adapting" sections. - Durable Agent / Human-in-the-Loop / Stop Workflow: fixed broken patterns (tool invocations don't stream before return; prepareStep flag checks never fire); canonical single example per page. - AI SDK integration: refocused from DurableAgent showcase to streamText(); added multi-turn session pattern with durable stream slicing, ai-sdk.dev deep links, and a pitfalls section. - Sandbox integration: rewrote around the real @vercel/sandbox SDK; flagship pattern is one workflow run = one persistent sandbox session that outlives the 5-hour VM cap via snapshot rotation. - Chat SDK integration: full rewrite — previous page documented AI SDK's useChat, not chat-sdk.dev. New page covers durable chat sessions, Mermaid flowchart, and cross-SDK serialization. - Publishing Libraries: swapped ASCII tree for Fumadocs <Files> (font-independent); corrected isomorphic guidance ("use workflow" / "use step" are safe no-ops when SWC plugin doesn't process them); added Mux AI and World ID adopter examples with canonical links. Deletions (redundant or flawed): - Fan-Out, Conditional Routing (covered by Batching / not a pattern). - Tool Streaming, Tool Orchestration (covered by foundations/streaming and ai/defining-tools). - Durable Objects (hook-in-loop bug; framing doesn't hold up). - Custom Serialization, Isomorphic Packages (merged into foundations/serialization and publishing-libraries respectively). Sidebar restructure: - Reordered: Overview -> Agent Patterns -> Common Patterns -> Integrations -> Advanced (Agent Patterns leads since it drives most new-visitor traffic). - Moved Child Workflows + Distributed Abort Controller from Common Patterns to Advanced (composition / coordination concerns, not common reliability recipes); permanent redirects added in next.config.ts. Made-with: Cursor * docs(cookbook): rename Agent Stop Signal → Agent Cancellation, migrate common patterns The agent cancellation page now covers two named patterns — Hard Cancellation via getRun(runId).cancel() and Stop Signal via a hook + Promise.race — so the prior "Agent Stop Signal" title biased toward only one of them. Rename to the broader noun phrase and update the intro, description, and section heading to frame both approaches equally. Also migrate all patterns from foundations/common-patterns into dedicated cookbook recipes (timeouts, sequential-and-parallel, workflow-composition) and remove the foundations page. Permanent redirects added for the prior URLs (stop-workflow, agent-stop-signal, foundations/common-patterns) so no inbound link breaks. Made-with: Cursor * docs(cookbook): fix CI typecheck failures on three snippets - publishing-libraries.mdx: the second processPayment snippet uses getWorkflowRunId() defined in the prior block. Each block is type-checked independently, so add @skip-typecheck (matches the existing pattern in this file). - ai-sdk.mdx: the "snapshot tailIndex first" pitfall is a fragment referencing probe / turnHook / run / text from the surrounding multi-turn pattern. Add @skip-typecheck. - chat-sdk.mdx: the [platform] webhook route used Next.js 15 typegen (RouteContext<"/api/webhooks/[platform]">), which isn't part of the docs-typecheck environment. Switch to the manually-typed { params }: { params: Promise<{ platform: string }> } form — still fully supported by Next.js 15+ and doesn't depend on .next/types. Made-with: Cursor --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> |
||
|
Pranay Prakash
|
b27921985c |
Add distributed abort controller guide and implementation (#1811)
* feat: add distributed abort controller guide and implementation Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * feat: implement abort signal step function and refactor workflows to use it Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * feat: enhance distributed abort controller with user-provided ID Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * feat: enhance distributed abort controller with TTL and reconnection logic Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * feat: add grace period to abort controller workflow Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * feat: add distributed abort controller workflow and tests Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * add the pattern to the sidebar * fix: correct start() call signature and run.id → run.runId start() takes args as a positional second argument, not an options object property. The Run object exposes runId, not id. Made-with: Cursor * fix: address PR review comments on distributed abort controller - Make abort() idempotent by catching hook-not-found/expired errors - Add error handling to signal getter's stream reader IIFE - Fix tests: use instance methods instead of non-existent static methods, pass required ttlMs/graceMs args, include expired field in assertions Made-with: Cursor * fix: add missing import to Custom TTL docs code sample The docs typecheck runs each code block in isolation. The Custom TTL example was missing the DistributedAbortController import. Made-with: Cursor * fix: only sleep grace period on TTL expiration, not manual abort Manual aborts now complete immediately instead of sleeping through the full TTL + grace period. This fixes vitest timeouts where all 3 distributed-abort-controller tests exceeded the 30s limit. Made-with: Cursor * fix: wait for hook registration before aborting in test The DistributedAbortController instance test was timing out because abort() was called before the workflow had registered the hook. The idempotent catch silently swallowed the "not found" error, leaving the workflow running forever. - Make runId readonly (was private) so tests can access it - Add waitForHook(getRun(controller.runId)) before controller.abort() Made-with: Cursor * fix: apply conditional grace period to E2E workflow copy The distributedAbortControllerWorkflow in 99_e2e.ts had the same unconditional grace sleep bug, causing the reconnect test to timeout at 60s while waiting ~66s for the grace period after manual abort. Made-with: Cursor --------- Co-authored-by: v0 <v0[bot]@users.noreply.github.com> Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> Co-authored-by: Karthik Kalyanaraman <karthik.kalyanaraman@vercel.com> |
||
|
John Lindquist
|
cda0b12eed |
docs(migration-guides): audit and fix accuracy across four source frameworks (#1779)
Co-authored-by: VaguelySerious <mittgfu@gmail.com> Co-authored-by: Peter Wielander <mittgfu@gmail.com> |
||
|
Pranay Prakash
|
f102ed925d |
Add Python SDK beta documentation page (#1775)
* feat: add Python SVG icon and related documentation Slack-Thread: https://vercel.slack.com/archives/C0AG7R4PU22/p1776354109663229?thread_ts=1776354109.663229&cid=C0AG7R4PU22 Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * feat: reintroduce Python SDK card in getting-started guide Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * feat: add beta badge to Python SDK documentation sidebar item Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * feat: enhance sidebar item with badge and layout update Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * feat: refactor sidebar item badges to use array and function for mapping Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * feat: add Python getting started guide card in beta Added a new card for the Python getting started guide with a beta badge. Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * feat: simplify description of Workflow Python SDK Updated the description for clarity and conciseness. Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * feat: enhance Python SDK documentation and examples Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com> * fix: update Python SDK documentation link for language parameter 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> |
||
|
Karthik Kalyan
|
40fe57fa75 | fix sitemap (#1773) | ||
|
Pranay Prakash
|
f41fb74d38 | docs: remove experimental labeling from workflow ai api refs (#1774) | ||
|
christopherkindl
|
fbdd4e7398 |
Refine homepage feature grid and templates section (#1745)
* Refine homepage: simplify feature grid, update templates section Remove "Zero infrastructure management", "Deploy confidently", "No timeout limits", and "Pay for what you use" sections from the feature grid. Update the observability section with new copy, larger typography, and CTA buttons for Vercel and self-hosting. Redesign the templates section with a side-by-side layout, "All examples" button, and vercel.com/workflow card images with dark mode support. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: christopherkindl <53372002+christopherkindl@users.noreply.github.com> * Make observability CTA buttons stack vertically on mobile Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: christopherkindl <53372002+christopherkindl@users.noreply.github.com> * Add Vercel section with o11y dashboard, update homepage layout - Add O11yDashboard SVG component with Vercel dashboard preview showing sidebar nav and observability trace visualization - Add VercelSection with desktop (offset right) and mobile views - Update "Run anywhere" section with new copy and CTA buttons - Normalize all grid section buttons to h-10 - Fix mobile padding in UseCases section - Remove barrel file for vercel-com-visuals, use direct imports Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: christopherkindl <53372002+christopherkindl@users.noreply.github.com> * Make use-case selector inline on mobile Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: christopherkindl <53372002+christopherkindl@users.noreply.github.com> --------- Signed-off-by: christopherkindl <53372002+christopherkindl@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|
Pranay Prakash
|
5f4d683383 | [docs] Fix comment missing closing brace (#1767) | ||
|
Nathan Rajlich
|
173756dc4d |
[docs] Rename workflowdevkit to workflowsdk and useworkflow.dev to workflow-sdk.dev (#1759)
* [docs] Rename workflowdevkit references to workflowsdk * [docs] Rename useworkflow.dev to workflow-sdk.dev * [chore] Add changeset for domain rename * [docs] Revert sitemap rewrite to useworkflow.dev (crawled-sitemap not yet available for new domain) |
||
|
christopherkindl
|
6fba441999 |
[docs] Remove performance section on worlds pages (#1753)
Co-authored-by: Peter Wielander <mittgfu@gmail.com> |
||
|
Mitul Shah
|
3d784a5edb |
Content negation for cookbook route (#1752)
* cookbook md * Update proxy.ts |
||
|
Mitul Shah
|
c1405fbf08 |
Fix "Edit this page on GitHub" link path (#1750)
* feat: add redirect rule to strip.md extension from routes Added a new redirect to remove.md extension from any route. Slack-Thread: https://vercel.slack.com/archives/C09125LC4AX/p1776281595825439?thread_ts=1776281595.825439&cid=C09125LC4AX Co-authored-by: Mitul Shah <19615826+mitul-s@users.noreply.github.com> * feat: update GitHub edit URL path for Geistdocs component Updated GitHub edit URL to correct directory structure for documentation files. Slack-Thread: https://vercel.slack.com/archives/C09125LC4AX/p1776281595825439?thread_ts=1776281595.825439&cid=C09125LC4AX Co-authored-by: Mitul Shah <19615826+mitul-s@users.noreply.github.com> * Update next.config.ts * Fix URL path in EditSource component Signed-off-by: Mitul Shah <mitulxshah@gmail.com> --------- Signed-off-by: Mitul Shah <mitulxshah@gmail.com> Co-authored-by: v0 <v0[bot]@users.noreply.github.com> Co-authored-by: Mitul Shah <19615826+mitul-s@users.noreply.github.com> |
||
|
John Lindquist
|
ffefbbce01 |
[docs] Polish migration guides for scanability (#1721)
Co-authored-by: Peter Wielander <mittgfu@gmail.com> |
||
|
Pranay Prakash
|
4edf581306 | Add workflow runtime detection example to getWorkflowMetadata docs (#1744) | ||
|
christopherkindl
|
f26db3416f |
Add command-prompt component to docs (#1733)
* [docs] Add command-prompt component Port the command-prompt compound component from vercel-marketing for use on the workflow docs/landing page. Replaces geist icon imports with hard-copied SVG fallbacks and uses the local cn() utility. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * [docs] Replace hero CTA with command-prompt component Swap the "Get Started" button and inline `npm i workflow` copy block for the CommandPrompt compound component, matching the vercel.com/workflow hero. Shows "For humans" / "For agents" tabs with animated copy-to-clipboard. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * [docs] Fix icon alignment and add missing font utilities - Remove conflicting p-3.5 on copy button (was larger than w-6 h-6 container) - Use size-8 for the copy button hit target with flex centering - Remove geist-specific -mt-0.5 hack on check icon - Add text-label-14-mono and text-label-16-mono utility classes to match geist DS typography tokens used by the command-prompt component Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * [docs] Fix copy button alignment in command-prompt - Use size-8 instead of size-6 + p-3.5 for proper icon centering - Both icon spans use absolute + flex centering - Remove -mt-0.5 geist-specific hack on check icon - Nudge copy button 2px right for optical alignment Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * DCO Remediation Commit for christopherkindl <53372002+christopherkindl@users.noreply.github.com> I, christopherkindl <53372002+christopherkindl@users.noreply.github.com>, hereby add my Signed-off-by to this commit: |
||
|
christopherkindl
|
80595e6463 |
[home][docs] migrate to new geistdocs facelift (#1666)
* fix: migrate to new facelift * add: max-w- for footer * update * DCO Remediation Commit for christopherkindl <53372002+christopherkindl@users.noreply.github.com> I, christopherkindl <53372002+christopherkindl@users.noreply.github.com>, hereby add my Signed-off-by to this commit: |
||
|
Nathan Rajlich
|
335a7ce6a6 |
fix(docs): correct API usage in cookbook examples (#1709)
* fix(docs): correct API usage in cookbook examples
Fix 9 issues across 6 cookbook files found during API audit:
- ai-sdk, chat-sdk: return start() returned Run not Response;
use createUIMessageStreamResponse with run.readable instead
- tool-orchestration: getWritable() is available at workflow level
(table was wrong); remove invalid generic on createWebhook()
- stop-workflow: replace non-existent { stop: true } prepareStep
return with { toolChoice: "none" }; move maxSteps from
DurableAgent constructor to stream() options
- durable-objects: remove erroneous "use step" from API route
- child-workflows: fix comment referencing non-existent statuses
(queued/starting -> pending/running)
* fix(docs): correct serialization claims, imports, and patterns in cookbook
- Fix @workflow/ai import path: providers/anthropic -> anthropic
(serializable-steps, durable-objects)
- Remove 'Bundle optimization with dynamic imports' section from
serializable-steps — SWC plugin dead-code-eliminates unused
imports from the workflow bundle automatically
- Fix serialization claims in publishing-libraries: workflow supports
Date, Map, Set, RegExp, BigInt, Uint8Array, URL, Error, and custom
serde classes — not just JSON. Link to serialization reference.
- Rewrite secrets guidance: encryption protects the event log, so
this is a best practice not a hard requirement
- Fix custom-serialization: class instances throw a serialization
error (not silently lose prototype chain); remove incorrect
'Manual Registration for Library Authors' section (the build
process discovers classes in node_modules); fix return new this
-> return new WorkflowStorageClient; reorder Decision Guide to
recommend custom serde as the default approach
* fix(docs): add code highlights, remove serde shorthand, fix credential guidance
- Add [!code highlight] markers to key lines across all 23 cookbook
files to emphasize important API calls and patterns
- Remove step-as-factory comparison section from custom-serialization
page — the page should focus solely on custom class serialization
- Replace 'serde' shorthand with explicit 'custom class serialization'
throughout for clarity
- Rewrite credential guidance in publishing-libraries to present
both patterns (env vars and passing explicitly) as equally valid
when workflow encryption is enabled
|
||
|
Nathan Rajlich
|
b67f54f1eb |
fix(docs): remove aspirational workflow-level deduplication pattern (#1705)
The 'Pattern: Workflow-level deduplication' section documented a
start({ id }) API that does not exist. Run IDs are auto-generated
ULIDs and there is no option to specify a custom ID. Remove the
section and related references.
|
||
|
Karthik Kalyan
|
fb8e42dd76 | remove secure credential (#1723) | ||
|
Karthik Kalyan
|
3f4870cb6d |
[docs] Update tweet wall (#1708)
* update tweet wall * update tweet wall |
||
|
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>
|
||
|
christopherkindl
|
8a7c59cacb |
fix(docs): remove scroll-smooth from html to fix navigation scroll position (#1694)
The global `scroll-smooth` CSS class on <html> caused Next.js navigation scroll-to-top to animate instead of jumping instantly, making cross-page links appear stuck at the previous scroll position. Signed-off-by: christopherkindl <53372002+christopherkindl@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.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)
|
||
|
Rich Haines
|
bfb1a60040 |
Add AI agent detection and automatic markdown rewrites (#1532)
* Add AI agent detection and automatic markdown rewrites When AI agents (Claude, ChatGPT, Cursor, etc.) request docs pages, the proxy now detects them and transparently rewrites to the markdown route — matching the geistdocs template default. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix: Missing import for `isAIAgent` in `docs/proxy.ts` causes a ReferenceError at runtime when the AI agent detection code path is reached. This commit fixes the issue reported at docs/proxy.ts:68 **Bug explanation:** In `docs/proxy.ts`, the function `isAIAgent` is called on line 68 (`const agentResult = isAIAgent(request)`) within the AI agent detection block (lines 63-87). However, this function was never imported into the file. The function is defined and exported in `docs/lib/ai-agent-detection.ts`, but the import statement was omitted when the AI agent detection feature was added to `proxy.ts`. This would cause a `ReferenceError: isAIAgent is not defined` at runtime whenever a request matches the condition on lines 64-67 (any request to `/docs` or `/docs/*` that doesn't include `/llms.mdx/`). This is a critical path — every docs page request would hit this code. **Fix explanation:** Added the missing import statement: `import { isAIAgent } from '@/lib/ai-agent-detection';` at line 10 of `proxy.ts`, after the existing imports. This correctly resolves the `isAIAgent` reference to the exported function in `docs/lib/ai-agent-detection.ts`. Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com> Co-authored-by: molebox <hello@richardhaines.dev> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com> |
||
|
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> |
||
|
John Lindquist
|
fb97b6be64 |
fix: await convertToModelMessages in docs chat API route (#1526)
convertToModelMessages is async but was not being awaited, so a Promise was passed to streamText instead of the resolved ModelMessage array. This caused Zod validation to fail on every chat request with: "Invalid prompt: The messages do not match the ModelMessage[] schema." |