From ea66ca744a55ccce77017874c08fe2dd91d5f5af Mon Sep 17 00:00:00 2001 From: John Lindquist Date: Wed, 25 Feb 2026 21:16:30 -0700 Subject: [PATCH 1/5] docs(docs): correct workflow API snippets Update docs examples that referenced outdated or incorrect APIs. This fixes cancellation usage in get-world, stream import path and run return access in streaming, clarifies stream wording in starting-workflows, and removes fetch from Node.js core module examples. Verified: node -e '...docs snippet verification passed' (requested old/new snippets checked in 4 files) How to test: run the same node assertion command from repo root to confirm snippets. Swarm-Agent: codex-core-docs --- docs/content/docs/api-reference/workflow-api/get-world.mdx | 6 +++--- docs/content/docs/errors/node-js-module-in-workflow.mdx | 2 +- docs/content/docs/foundations/starting-workflows.mdx | 2 +- docs/content/docs/foundations/streaming.mdx | 4 ++-- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/content/docs/api-reference/workflow-api/get-world.mdx b/docs/content/docs/api-reference/workflow-api/get-world.mdx index 91812936b9..8b15fad9c2 100644 --- a/docs/content/docs/api-reference/workflow-api/get-world.mdx +++ b/docs/content/docs/api-reference/workflow-api/get-world.mdx @@ -68,7 +68,7 @@ export async function GET(req: Request) { Cancel a running workflow: ```typescript lineNumbers -import { getWorld } from "workflow/runtime"; +import { getWorld, cancelRun } from "@workflow/core/runtime"; export async function POST(req: Request) { const { runId } = await req.json(); @@ -79,9 +79,9 @@ export async function POST(req: Request) { try { const world = getWorld(); // [!code highlight] - const run = await world.runs.cancel(runId); // [!code highlight] + await cancelRun(world, runId); // [!code highlight] - return Response.json({ status: run.status }); + return Response.json({ status: "cancelled" }); } catch (error) { return Response.json( { error: "Failed to cancel workflow run" }, diff --git a/docs/content/docs/errors/node-js-module-in-workflow.mdx b/docs/content/docs/errors/node-js-module-in-workflow.mdx index de95f023df..d89f332673 100644 --- a/docs/content/docs/errors/node-js-module-in-workflow.mdx +++ b/docs/content/docs/errors/node-js-module-in-workflow.mdx @@ -69,7 +69,7 @@ async function read(filePath: string) { These common Node.js core modules cannot be used in workflow functions: - File system: `fs`, `path` -- Network: `http`, `https`, `net`, `dns`, `fetch` +- Network: `http`, `https`, `net`, `dns` - Process: `child_process`, `cluster` - Crypto: `crypto` (use Web Crypto API instead) - Operating system: `os` diff --git a/docs/content/docs/foundations/starting-workflows.mdx b/docs/content/docs/foundations/starting-workflows.mdx index 2dd41bc677..000a4d099c 100644 --- a/docs/content/docs/foundations/starting-workflows.mdx +++ b/docs/content/docs/foundations/starting-workflows.mdx @@ -144,7 +144,7 @@ export async function POST(request: Request) { } ``` -Your workflow can write to the stream using [`getWritable()`](/docs/api-reference/workflow/get-writable): +Your workflow can obtain a writable stream using [`getWritable()`](/docs/api-reference/workflow/get-writable): ```typescript lineNumbers import { getWritable } from "workflow"; diff --git a/docs/content/docs/foundations/streaming.mdx b/docs/content/docs/foundations/streaming.mdx index 475bb485e6..8625e4ba90 100644 --- a/docs/content/docs/foundations/streaming.mdx +++ b/docs/content/docs/foundations/streaming.mdx @@ -44,7 +44,7 @@ Use the `Run` object's `readable` property to consume the stream from your API r ```typescript title="app/api/stream/route.ts" lineNumbers import { start } from "workflow/api"; -import { simpleStreamingWorkflow } from "./workflows/simple"; +import { simpleStreamingWorkflow } from "./workflows/simple-streaming"; export async function POST() { const run = await start(simpleStreamingWorkflow); @@ -120,7 +120,7 @@ import { streamProcessingWorkflow } from "./workflows/streaming"; export async function POST(request: Request) { // Streams can be passed as workflow arguments const run = await start(streamProcessingWorkflow, [request.body]); // [!code highlight] - await run.result(); + await run.returnValue; return Response.json({ status: "complete" }); } From e380cfb41578765aaabcf94d2cf3e9be962e722e Mon Sep 17 00:00:00 2001 From: John Lindquist Date: Wed, 25 Feb 2026 21:18:05 -0700 Subject: [PATCH 2/5] docs(deploying): fix World and Streamer interface docs Correct World interface docs to include close() and getEncryptionKeyForRun() overloads, and clarify their runtime behavior. Update Streamer runId types to string, add writeToStreamMulti(), and document it as an optional batching optimization. Also fix package references from @workflow-worlds/postgres to @workflow/world-postgres. Verified: pnpm biome check docs/content/docs/deploying/building-a-world.mdx docs/content/docs/deploying/index.mdx (fails because Biome config ignores *.mdx paths) Verified: node <<'NODE' ... scoped assertions on docs/content/docs/deploying/building-a-world.mdx and docs/content/docs/deploying/index.mdx (pass) Swarm-Agent: codex-world-interface --- docs/content/docs/deploying/building-a-world.mdx | 16 +++++++++++++--- docs/content/docs/deploying/index.mdx | 4 ++-- 2 files changed, 15 insertions(+), 5 deletions(-) diff --git a/docs/content/docs/deploying/building-a-world.mdx b/docs/content/docs/deploying/building-a-world.mdx index c09589ef50..48f5b10918 100644 --- a/docs/content/docs/deploying/building-a-world.mdx +++ b/docs/content/docs/deploying/building-a-world.mdx @@ -34,10 +34,13 @@ A World connects workflows to the infrastructure that powers them. The World int ```typescript interface World extends Storage, Queue, Streamer { start?(): Promise; + close?(): Promise; + getEncryptionKeyForRun?(run: WorkflowRun): Promise; + getEncryptionKeyForRun?(runId: string, context?: Record): Promise; } ``` -The optional `start()` method initializes any background tasks needed by your World (e.g., queue polling). +The optional `start()` method initializes background tasks (for example, queue polling). The optional `close()` method releases resources like connection pools and listeners. The optional `getEncryptionKeyForRun()` method returns the AES-256 key used to encrypt data for a run; if it is not implemented, encryption is disabled. ## The Event Log Model @@ -165,13 +168,19 @@ The Streamer interface enables real-time data streaming: interface Streamer { writeToStream( name: string, - runId: string | Promise, + runId: string, chunk: string | Uint8Array ): Promise; + writeToStreamMulti?( + name: string, + runId: string, + chunks: (string | Uint8Array)[] + ): Promise; + closeStream( name: string, - runId: string | Promise + runId: string ): Promise; readFromStream( @@ -184,6 +193,7 @@ interface Streamer { ``` Streams are identified by a combination of `runId` and `name`. Each workflow run can have multiple named streams. +`writeToStreamMulti()` is an optional optimization for batching multiple writes. ## Reference Implementations diff --git a/docs/content/docs/deploying/index.mdx b/docs/content/docs/deploying/index.mdx index 632dcd69c7..c22ca7a787 100644 --- a/docs/content/docs/deploying/index.mdx +++ b/docs/content/docs/deploying/index.mdx @@ -71,7 +71,7 @@ For self-hosting or deploying to other cloud providers, you can use community-ma To use a different World implementation, set the `WORKFLOW_TARGET_WORLD` environment variable: ```bash -export WORKFLOW_TARGET_WORLD=@workflow-worlds/postgres +export WORKFLOW_TARGET_WORLD=@workflow/world-postgres # Plus any world-specific configuration export DATABASE_URL=postgres://... ``` @@ -87,7 +87,7 @@ The [Observability tools](/docs/observability) work with any World backend. By d npx workflow inspect runs # Inspect remote workflows -npx workflow inspect runs --backend @workflow-worlds/postgres +npx workflow inspect runs --backend @workflow/world-postgres ``` Learn more about [Observability](/docs/observability) tools. From cd4015d439827c3f57a85f0775b7395d91dd5287 Mon Sep 17 00:00:00 2001 From: John Lindquist Date: Wed, 25 Feb 2026 21:20:28 -0700 Subject: [PATCH 3/5] docs(ai): fix MDX code sample consistency issues Align code examples across AI docs by renaming the tools export, fixing import snippets, restoring a missing logical OR, adding missing RetryableError import context, and repairing a broken highlight annotation. Verified: git diff --check -- docs/content/docs/ai/index.mdx docs/content/docs/ai/sleep-and-delays.mdx docs/content/docs/ai/resumable-streams.mdx Verified: set -euo pipefail; rg -n "export const flightBookingTools = \\{" docs/content/docs/ai/index.mdx; rg -n "import \\{ flightBookingTools \\} from \"@/ai/tools\";" docs/content/docs/ai/index.mdx; rg -n "import \\{ sleep \\} from \"workflow\";" docs/content/docs/ai/sleep-and-delays.mdx; rg -n "tool-checkBaggageAllowance\" \\|\\|" docs/content/docs/ai/sleep-and-delays.mdx; rg -n "part.type === \"tool-sleep\"" docs/content/docs/ai/sleep-and-delays.mdx; rg -n "import \\{ RetryableError \\} from \"workflow\";" docs/content/docs/ai/sleep-and-delays.mdx; rg -n "headers: \\{ // \\[!code highlight\\]" docs/content/docs/ai/resumable-streams.mdx Swarm-Agent: codex-ai-docs --- docs/content/docs/ai/index.mdx | 4 ++-- docs/content/docs/ai/resumable-streams.mdx | 2 +- docs/content/docs/ai/sleep-and-delays.mdx | 6 ++++-- 3 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/content/docs/ai/index.mdx b/docs/content/docs/ai/index.mdx index fd9184631a..4c02da245d 100644 --- a/docs/content/docs/ai/index.mdx +++ b/docs/content/docs/ai/index.mdx @@ -148,7 +148,7 @@ Our tools are mostly mocked out for the sake of the example. We use AI SDK's `to import { tool } from "ai"; import { z } from "zod"; -export const tools = { +export const flightBookingTools = { searchFlights: tool({ description: "Search for flights", inputSchema: z.object({ query: z.string() }), @@ -256,7 +256,7 @@ Move the agent logic into a separate function, which will serve as our workflow ```typescript title="workflows/chat/workflow.ts" lineNumbers import { DurableAgent } from "@workflow/ai/agent"; // [!code highlight] import { getWritable } from "workflow"; // [!code highlight] -import { tools } from "@/ai/tools"; +import { flightBookingTools } from "@/ai/tools"; import { openai } from "@workflow/ai/openai"; import type { ModelMessage, UIMessageChunk } from "ai"; diff --git a/docs/content/docs/ai/resumable-streams.mdx b/docs/content/docs/ai/resumable-streams.mdx index 510c357c90..754a38b514 100644 --- a/docs/content/docs/ai/resumable-streams.mdx +++ b/docs/content/docs/ai/resumable-streams.mdx @@ -42,7 +42,7 @@ export async function POST(req: Request) { return createUIMessageStreamResponse({ stream: run.readable, - headers: { // [!code highlight + headers: { // [!code highlight] "x-workflow-run-id": run.runId, // [!code highlight] }, // [!code highlight] }); diff --git a/docs/content/docs/ai/sleep-and-delays.mdx b/docs/content/docs/ai/sleep-and-delays.mdx index f3eb33415d..ea18c2f58d 100644 --- a/docs/content/docs/ai/sleep-and-delays.mdx +++ b/docs/content/docs/ai/sleep-and-delays.mdx @@ -33,7 +33,7 @@ Sleep is a built-in function in Workflow DevKit, so exposing it as a tool is as Add a new "sleep" tool to the `tools` defined in `workflows/chat/steps/tools.ts`: ```typescript title="workflows/chat/steps/tools.ts" lineNumbers -import { getWritable, sleep } from "workflow"; // [!code highlight] +import { sleep } from "workflow"; // [!code highlight] // ... existing imports ... @@ -110,7 +110,7 @@ export default function ChatPage() { part.type === "tool-checkFlightStatus" || part.type === "tool-getAirportInfo" || part.type === "tool-bookFlight" || - part.type === "tool-checkBaggageAllowance" + part.type === "tool-checkBaggageAllowance" || part.type === "tool-sleep" // [!code highlight] ) { // ... @@ -162,6 +162,8 @@ Aside from providing `sleep()` as a tool, there are other use cases for Agents t When hitting API rate limits, use `RetryableError` with a delay: ```typescript lineNumbers +import { RetryableError } from "workflow"; + async function callRateLimitedAPI(endpoint: string) { "use step"; From d44750748961396bbeeabf1ed35ae33950f0420d Mon Sep 17 00:00:00 2001 From: John Lindquist Date: Wed, 25 Feb 2026 21:21:55 -0700 Subject: [PATCH 4/5] fix(docs): correct misc wording and annotation typos Update three docs files to fix a malformed code-highlight annotation,\nclarify Astro directory wording, and correct npx behavior wording.\n\nVerified: set -e; rg assertions for old/new strings in all 3 files (pass)\nVerified: git diff --check -- docs/content/docs/errors/start-invalid-workflow-function.mdx docs/content/docs/getting-started/astro.mdx docs/content/docs/observability/index.mdx (pass)\nVerified: npx -y prettier@3 --check docs/content/docs/errors/start-invalid-workflow-function.mdx docs/content/docs/getting-started/astro.mdx docs/content/docs/observability/index.mdx (fails: pre-existing formatting style mismatch in docs)\nSwarm-Agent: codex-misc-fixes --- docs/content/docs/errors/start-invalid-workflow-function.mdx | 2 +- docs/content/docs/getting-started/astro.mdx | 2 +- docs/content/docs/observability/index.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/content/docs/errors/start-invalid-workflow-function.mdx b/docs/content/docs/errors/start-invalid-workflow-function.mdx index d43fcbd7dd..7b8b90920e 100644 --- a/docs/content/docs/errors/start-invalid-workflow-function.mdx +++ b/docs/content/docs/errors/start-invalid-workflow-function.mdx @@ -96,7 +96,7 @@ export default nextConfig; ```typescript lineNumbers title="next.config.ts" // Fixed - includes withWorkflow -import { withWorkflow } from "workflow/next"; // [!code highlight} +import { withWorkflow } from "workflow/next"; // [!code highlight] import type { NextConfig } from "next"; const nextConfig: NextConfig = { diff --git a/docs/content/docs/getting-started/astro.mdx b/docs/content/docs/getting-started/astro.mdx index c2570a6a97..bbb3f8d390 100644 --- a/docs/content/docs/getting-started/astro.mdx +++ b/docs/content/docs/getting-started/astro.mdx @@ -196,7 +196,7 @@ Workflows can be triggered from API routes or any server-side code. ## Run in Development -To start your development server, run the following command in your terminal in the Vite root directory: +To start your development server, run the following command in your terminal in the Astro project root directory: ```bash npm run dev diff --git a/docs/content/docs/observability/index.mdx b/docs/content/docs/observability/index.mdx index dafaeb68c8..a1e758f49c 100644 --- a/docs/content/docs/observability/index.mdx +++ b/docs/content/docs/observability/index.mdx @@ -17,7 +17,7 @@ Workflow DevKit provides powerful tools to inspect, monitor, and debug your work npx workflow ``` -The CLI comes pre-installed with the Workflow DevKit and registers the `workflow` command. If the `workflow` package is not already installed, `npx workflow` will install it globally, or use the local installed version if available. +The CLI comes pre-installed with the Workflow DevKit and registers the `workflow` command. If the `workflow` package is not already installed, `npx workflow` will download and run the CLI temporarily, or use the local installed version if available. Get started inspecting your local workflows: From 9fe76fa2c25c6f502a6bdb6a11c6598709c44737 Mon Sep 17 00:00:00 2001 From: John Lindquist Date: Thu, 26 Feb 2026 08:55:31 -0700 Subject: [PATCH 5/5] fix(docs): correct events.create() runId type to string | null The first overload of events.create() accepts string | null, not just null. Clients can provide their own runId for run_created events. --- docs/content/docs/deploying/building-a-world.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/content/docs/deploying/building-a-world.mdx b/docs/content/docs/deploying/building-a-world.mdx index 48f5b10918..2a66d01e10 100644 --- a/docs/content/docs/deploying/building-a-world.mdx +++ b/docs/content/docs/deploying/building-a-world.mdx @@ -66,8 +66,8 @@ interface Storage { }; events: { - // Create a new workflow run (runId must be null - server generates it) - create(runId: null, data: RunCreatedEventRequest, params?: CreateEventParams): Promise; + // Create a new workflow run (runId may be client-provided or null for server generation) + create(runId: string | null, data: RunCreatedEventRequest, params?: CreateEventParams): Promise; // Create an event for an existing run create(runId: string, data: CreateEventRequest, params?: CreateEventParams): Promise; @@ -91,7 +91,7 @@ interface Storage { 2. Atomically update the affected entity (run, step, or hook) 3. Return both the created event and the updated entity -**Run Creation:** For `run_created` events, the `runId` parameter is `null`. Your World generates and returns a new `runId`. +**Run Creation:** For `run_created` events, the `runId` parameter may be a client-provided string or `null`. When `null`, your World generates and returns a new `runId`. **Hook Tokens:** Hook tokens must be unique. If a `hook_created` event conflicts with an existing token, return a `hook_conflict` event instead.