Commit Graph

210 Commits

Author SHA1 Message Date
github-actions[bot] 326d93a4ae Backport #2012: Expose conflicting run id on hook conflicts (#2016)
Co-authored-by: Pranay Prakash <pranay.gp@gmail.com>
Co-authored-by: Nathan Rajlich <n@n8.io>
Co-authored-by: Peter Wielander <mittgfu@gmail.com>
Co-authored-by: Peter Wielander <peter.wielander@vercel.com>
2026-06-10 17:06:26 +02:00
github-actions[bot] b385a2d6eb [backport] classify SDK encryption failures as RUNTIME_ERROR (#2145) (#2165)
Co-authored-by: Nathan Rajlich <n@n8.io>
Co-authored-by: Peter Wielander <mittgfu@gmail.com>
2026-06-02 12:49:01 +02:00
Pranay Prakash 5fd7d9c2a1 Retry replay divergence before failing event logs (#2208) 2026-06-01 23:24:35 +00:00
Nathan Rajlich cab9a5334f docs(stable): update docs/README and docs-checks comment for tarballs move (#2094)
Per-deployment SDK tarballs are now built by the tarballs/ app, not by
docs/. Remove the outdated reference to docs/scripts/pack.ts (which no
longer exists) and point readers at tarballs/README.md.
2026-05-22 11:58:29 -07:00
github-actions[bot] c3f3a756f9 Add workflow versioning docs (#2010) (#2014)
* Add workflow versioning docs

* Link cookbook patterns to versioning docs

* Align v5 start docs with native workflow support

* Address versioning docs review feedback

* Address versioning preview comment

* Address versioning toolbar feedback

* Cross-link versioning docs

* Address latest versioning toolbar feedback

* Rename versioning self-upgrade section

* Address versioning PR review comments

Signed-off-by: Pranay Prakash <pranay.gp@gmail.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-05-18 16:53:15 -07:00
github-actions[bot] a5e82e5661 docs(ai): update durable agents guide to use ToolLoopAgent (#1975) (#1990)
The AI SDK renamed `Experimental_Agent` to `ToolLoopAgent`. Update the
"Building Durable AI Agents" page's API route snippet (v4 and v5) so it
matches the current AI SDK API.

Signed-off-by: Karthik Kalyan <105607645+karthikscale3@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-18 15:31:46 -07:00
github-actions[bot] 76352f0b66 [codex] Fix detached ArrayBuffer proxy DX (#1985) (#1998)
* fix(world-local): explain detached ArrayBuffer proxy failures

* fix(docs): make proxy handler anchor navigable

* fix(docs): open accordions for hash links

Signed-off-by: Pranay Prakash <pranay.gp@gmail.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-05-14 16:06:42 -07:00
github-actions[bot] 14326adcf9 Auto-remove workflow packages from serverExternalPackages (#1481) (#1940)
* Warn when serverExternalPackages hides workflow-enabled packages

Add a build-time warning when packages in serverExternalPackages contain
workflow code ('use step', 'use workflow', or serialization classes).
These packages are completely invisible to the workflow compiler when
externalized, causing silent runtime failures.

The warning detects workflow patterns via two methods:
- Fast path: check package.json dependencies for @workflow/serde
- Thorough path: read the package entry file and run pattern detection

Also adds documentation in the serialization guide about the
externalization footgun for 3rd-party packages.

* Auto-remove workflow packages from serverExternalPackages

When workflow-enabled dependencies are externalized in Next.js, compiler transforms are skipped and runtime failures follow. Detect those packages in withWorkflow, remove them from serverExternalPackages for the current build, and keep a generalized externalPackages warning fallback for non-Next builders.

* Address review feedback: add entry-point limitation comment and missing test case

Signed-off-by: Nathan Rajlich <n@n8.io>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-05-06 07:59:43 +00:00
Peter Wielander bb910f2571 [backport] [workbench] Add TanStack Start workbench (#1875, #1907) (#1914)
* [workbench] Add TanStack Start workbench and tests (#1875)

(cherry picked from commit 8202663857)

* Fix pnpm type issue after tanstack PR (#1907)

(cherry picked from commit a7071bf3d4)
2026-05-04 19:30:39 +00:00
Peter Wielander e428cdb1d5 [vitest] [world-local] Backport: Fix local-world data recovery isolation (#1895) (#1898) 2026-05-04 09:38:34 +00:00
Peter Wielander eb54dd8544 [backport] Split tarball hosting out of docs into its own project (#1893) (#1899) 2026-05-04 12:33:00 +09:00
Peter Wielander 8389bce6c3 [docs] Build packages before packing preview tarballs on stable (#1793) 2026-04-16 17:54:23 -07:00
Peter Wielander 47aa68534f [docs] Restore minimal Next.js placeholder on stable (#1786) 2026-04-16 16:45:24 -07:00
Nathan Rajlich 543216060b Remove docs app from stable branch, keep docs/content/ for npm releases (#1771)
The docs Next.js app is deployed only from main. Remove the app code
(components, layouts, configs, styles) from stable to eliminate
cherry-pick conflicts during backports. Keep docs/content/ which
contains the markdown files that are bundled into npm packages via
prepack scripts for AI agent consumption.
2026-04-16 13:13:09 -07:00
John Lindquist 5b6d0779c0 docs: March docs audit and alignment (#1466)
* docs: clarify Next monorepo setup

Prevent confusion when Next.js apps live below the repository root and workflow code imports sibling workspace packages.

This documents the output tracing root requirement at the point where users configure withWorkflow, so monorepo setups follow the same working patterns as the shipped Next.js integration instead of failing due to unresolved workspace imports.

Ploop-Iter: 1

* ploop: iteration 2 checkpoint

Automated checkpoint commit.

Ploop-Iter: 2

* ploop: iteration 3 checkpoint

Automated checkpoint commit.

Ploop-Iter: 3

* docs: audit recent documentation coverage

Capture recent workflow documentation updates so the public docs and package guidance stay aligned with the implementation and current docs-typecheck behavior.

Ploop-Iter: 1

* docs: align docs-typecheck docs

Document the current docs verification contract so contributors do not assume JavaScript examples are type-checked when only TypeScript snippets are enforced today.

Add regression coverage around the README language and framework integration guidance to keep those docs aligned with the implemented Next.js and docs-typecheck behavior as future changes land.

Ploop-Iter: 2

* docs: add start() troubleshooting guidance

Document the most common causes of the invalid workflow function error so users can resolve start() failures from the API docs and Next.js setup flow without having to infer build-time requirements from runtime behavior.

Keep the new troubleshooting page aligned with the shipped runtime message and add regression coverage so future wording or cross-link changes do not silently break that guidance.

Ploop-Iter: 3

* docs: align NestJS setup docs

Document both supported NestJS module formats and add a regression check so the getting-started guide stays aligned with the package README as the integration evolves.

Ploop-Iter: 1

* docs: tighten NestJS CommonJS guidance

Keep the NestJS getting-started guide consistent across the ESM and CommonJS paths so readers do not mix module settings or import styles mid-setup.

Strengthen the docs regression coverage around the later guide sections so future edits are more likely to preserve the supported CommonJS path documented in the package README.

Ploop-Iter: 2

* docs: align docs with recent workflow guidance

Document the recently added troubleshooting and observability patterns so the public docs stay aligned with the behavior users now encounter in practice.

This keeps the NestJS guide, workflow API reference, and docs regression coverage in sync with the runtime-facing guidance from recent changes.

Ploop-Iter: 3

* docs: audit docs coverage

Why: keep the docs aligned with recent API and runtime behavior changes so examples and reference pages don’t drift from the supported surface.

Ploop-Iter: 1

* test: add docs audit guards

Add regression coverage for doc surfaces that are easy to drift from implementation so docs audits catch mismatches early and keep published guidance aligned with the supported API surface.

Ploop-Iter: 2

* docs: add docs audit guards

Keep new observability and server-testing guidance anchored to machine-readable interfaces so follow-up implementation changes do not silently drift away from the documented agent and automation patterns.

Ploop-Iter: 3

* docs: align observability troubleshooting guidance

Keep the docs consistent so users get the same guidance when debugging hook token collisions and correlating workflow events with platform logs.

This prevents the event-sourcing reference from drifting away from the observability and error docs, and adds guard tests to catch regressions.

Ploop-Iter: 1

* Remove the unreferenced image file img-a-clean-minimal-technical-architecture-d-2026-02-27T14-07-52-1.png from the repo root, workbench/fastify/public/index.html (a Nitro example mistakenly placed in the fastify workbench by a ploop checkpoint), all .claude/worktrees/* submodule references, and all 15 string-presence audit guard tests in packages/docs-typecheck/src/__tests__/ (they only assert keyword presence, not semantic correctness). None of these belong in the docs audit PR.

* Address all PR #1466 review feedback from VaguelySerious, pranaygp, and ijjk:

1. Remove the "Machine-Readable Surfaces" section from docs/content/docs/observability/index.mdx (reviewers say it's unnecessary and already in world docs)
2. Remove all @skip-typecheck annotations from durable-agent.mdx (8) and server-based.mdx (1) — types exist in built packages/ai/dist after pnpm build
3. In durable-agent.mdx, change "machine-readable tool activity" to "tool call details" in the stream() return description
4. In durable-agent.mdx "Aborting Long-Running Streams" section, add a warning callout that abortSignal is not yet supported (blocked by #1301), recommend timeout instead
5. In event-sourcing.mdx, update requestId description: "On Vercel, requestId is the platform request ID when available. Other worlds are not expected to provide a requestId."
6. In get-world.mdx, change "user-friendly names from the machine-readable workflowName field" to "human-readable names from the workflowName field"
7. In start-invalid-workflow-function.mdx, add "// Does NOT work" comment above the bad example line
8. In with-workflow.mdx: reframe outputFileTracingRoot as a workaround (Next.js auto-detects by default per ijjk); change options description from "control local development behavior" to "configure the Next.js integration"; scope the callout to "workflows.local options only affect local development"
9. Drop the withWorkflow() options callout from docs/content/docs/getting-started/next.mdx
10. Remove the Next.js-specific outputFileTracingRoot callout from framework-integrations.mdx
11. Add a Troubleshooting section with the start() invalid-workflow-function error to all 9 non-Next getting-started guides (astro, express, fastify, hono, nestjs, nitro, nuxt, sveltekit, vite), each with framework-appropriate config check in point 2

* docs: absorb unique accuracy fixes from PR #1200

Cherry-picked 6 still-needed fixes from #1200 that aren't covered by
this audit PR or #1516:
- Fix npx workflow description (observability)
- Remove fetch from restricted modules list (errors)
- Fix package name @workflow-worlds/postgres → @workflow/world-postgres (deploying)
- Fix stream wording (foundations/starting-workflows)
- Fix import path simple → simple-streaming (foundations/streaming)
- Add close(), getEncryptionKeyForRun(), writeToStreamMulti() to World interface,
  update create() and streamer signatures (deploying/building-a-world)

* docs: address review feedback on March docs audit

- durable-agent.mdx: "structured tool activity" → "tool call information"
  per VaguelySerious's suggestion
- next.mdx: drop monorepo callout from getting-started per pranaygp
  (too much context too early; info is in withWorkflow API ref)

* docs: fix 2 typecheck failures in encryption and nestjs guides

- encryption.mdx: add skip-typecheck for interface signature block
  (getEncryptionKeyForRun overloads are not runnable code)
- nestjs.mdx: add skip-typecheck for WorkflowModule.forRoot config
  snippet (fragment inside callout, full import shown above)

Verified: pnpm vitest run passes 300/300 in docs-typecheck.
2026-04-07 11:18:42 -07:00
Pranay Prakash 125c38708e [changeset] Exit pre-release mode (to release 4.2 stable) (#1508) 2026-04-06 13:52:46 -07:00
Peter Wielander c8dce52606 [core] [world] Lazy run creation on start (#1537) 2026-04-06 12:25:23 -07:00
Karthik Kalyan ce8a80eb82 [docs] Add vercel world consumer function security documentation (#1543) 2026-04-03 09:57:01 -07:00
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>
2026-04-02 19:52:47 -07:00
Peter Wielander 136c1f4e97 [docs] Tidy world API docs and document new stream helpers (#1581) 2026-04-02 20:08:51 +00:00
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 cdf90d5a38 (#1541)

* Fix missing </h1> closing tag and add article 'the' before 'Workflow SDK' in docs
2026-04-02 19:39:02 +00:00
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.
2026-04-02 17:04:03 +00:00
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>
2026-04-01 09:39:22 -07:00
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>
2026-03-31 18:28:30 -07:00
Peter Wielander 5ca55af2bd [docs] Link to Vercel World pricing and limits pages (#1559) 2026-03-30 19:52:15 +00:00
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
2026-03-30 19:50:08 +00:00
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>
2026-03-29 16:05:39 -07:00
Nathan Rajlich 7db491b89c Add Workflow Globals reference page documenting available workflow VM APIs (#1548) 2026-03-29 22:14:41 +00:00
Nathan Rajlich 55c821ee85 Add missing workflow/errors card to API Reference index (#1549) 2026-03-29 14:57:12 -07:00
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>
2026-03-27 11:20:44 -07:00
Nathan Colosimo e045b59dc4 [world-postgres] Add maxPoolSize config for graphile (#1527)
Co-authored-by: Peter Wielander <mittgfu@gmail.com>
2026-03-26 16:09:08 -07:00
Matan Kushner 52db376c39 Support projects with Node.js step dependencies in vitest plugin (#1524)
Co-authored-by: Peter Wielander <mittgfu@gmail.com>
2026-03-26 23:05:05 +00:00
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."
2026-03-26 16:01:14 -07:00
Peter Wielander 9705acde3b Fix tarballing and ensure we don't regress (#1510)
Signed-off-by: Peter Wielander <mittgfu@gmail.com>
2026-03-24 14:47:45 -07:00
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>
2026-03-24 10:04:42 -07:00
Pranay Prakash ef4ca00b77 chore: bump next to 16.2.1 and fix deferred build (#1496)
* chore: bump next to 16.2.1

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* test: run deferred Next dev e2e assertions on stable

Bump Next.js to 16.2.1 in docs and swc-playground and update lockfile.

* fix(next): copy all deferred step sources for step-mode transforms

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: JJ Kasper <jj@jjsweb.site>
Co-authored-by: Peter Wielander <mittgfu@gmail.com>
2026-03-23 21:25:28 -07:00
Peter Wielander 01bbe66d5a [world] Add stream pagination and metadata endpoints (#1470) 2026-03-23 17:39:39 -07:00
Peter Wielander c1389ddf3f Remove NestJS Vercel integration while in experimental phase (#1485) 2026-03-23 17:04:31 -07:00
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>
2026-03-24 00:01:36 +00:00
Peter Wielander 823f58e5c6 Revert "Add support for calling start() inside workflow functions (#1133)" (#1475)
This reverts commit e889860984.
2026-03-20 17:04:28 -07:00
Peter Wielander 78f1b0e19f [core] Support negative startIndex for streaming (#1460) 2026-03-20 13:29:42 -07:00
Peter Wielander 2b07294313 [core] Ensure open stream flush is await-able in pendingOps (#1446) 2026-03-20 13:28:05 -07:00
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>
2026-03-20 13:00:17 -07:00
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>
2026-03-19 13:41:23 -07:00
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>
2026-03-19 11:18:09 -07:00
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>
2026-03-19 10:56:01 -07:00
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
2026-03-18 07:22:42 +00:00
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 */}).
2026-03-18 00:18:43 +00:00
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
2026-03-16 22:58:27 +00:00
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>
2026-03-13 15:20:06 -07:00