workflow 4.5.0 → 4.6.0

package/docs/ai/resumable-streams.mdx

@@ -194,6 +194,10 @@ This avoids replaying potentially thousands of chunks and lets the UI render fas
 When using a negative `initialStartIndex`, the reconnection endpoint **must** return the `x-workflow-stream-tail-index` header (as shown in [Step 2](#add-a-stream-reconnection-endpoint) above). The transport uses this header to compute absolute chunk positions so that retries after a disconnect resume from the correct position. If the header is missing, the transport falls back to `startIndex: 0` (replaying the entire stream) and logs a warning.
 </Callout>
 
+### Mid-part resumes
+
+A workflow stream is a flat sequence of chunks, but the AI SDK's UI protocol groups chunks into logical parts (`text-*`, `reasoning-*`, `tool-input-*`) that must be opened with a `*-start` before any `*-delta` or `*-end`. A non-zero `startIndex` can land in the middle of an open part. See [`WorkflowChatTransport` → Mid-part resumes](/docs/api-reference/workflow-ai/workflow-chat-transport#mid-part-resumes) for how this is handled and an example of rewinding to a step boundary on the server.
+
 ## Related Documentation
 
 - [`WorkflowChatTransport` API Reference](/docs/api-reference/workflow-ai/workflow-chat-transport) - Full configuration options

package/docs/api-reference/workflow/create-hook.mdx

@@ -65,7 +65,7 @@ export default Hook;`}
 
 The returned `Hook` object also implements `AsyncIterable<T>`, which allows you to iterate over incoming payloads using `for await...of` syntax.
 
-Use `hook.getConflict()` to check whether the hook token is already claimed by another active hook, without waiting for hook payload data. Calling `createHook()` on its own does not register the hook — registration is only committed when the workflow suspends. Awaiting `hook.getConflict()` suspends the workflow to commit the registration, then resolves with `null` once `hook_created` is recorded, or with `{ runId }` identifying the conflicting run if another active hook already owns the same token.
+Use `hook.getConflict()` (available starting in `workflow@4.5.0`) to check whether the hook token is already claimed by another active hook, without waiting for hook payload data. Calling `createHook()` on its own does not register the hook — registration is only committed when the workflow suspends. Awaiting `hook.getConflict()` suspends the workflow to commit the registration, then resolves with `null` once `hook_created` is recorded, or with `{ runId }` identifying the conflicting run if another active hook already owns the same token.
 
 ## Examples
 
@@ -116,7 +116,7 @@ export async function slackBotWorkflow(channelId: string) {
 
 ### Detecting Token Conflicts
 
-Use `hook.getConflict()` when the workflow needs to claim a hook token before doing other work, but does not need a payload yet:
+Use `hook.getConflict()` (available starting in `workflow@4.5.0`) when the workflow needs to claim a hook token before doing other work, but does not need a payload yet:
 
 ```typescript lineNumbers
 import { createHook } from "workflow";

package/docs/api-reference/workflow-ai/workflow-chat-transport.mdx

@@ -254,6 +254,45 @@ export default function ChatWithCustomConfig() {
 }
 ```
 
+## Mid-part resumes
+
+A workflow stream is a flat sequence of chunks, but the AI SDK's UI protocol groups chunks into logical parts: a `text-start` opens a text part that subsequent `text-delta`s extend and a `text-end` closes, and the same shape applies to `reasoning-*` and `tool-input-*`. The AI SDK client enforces that grammar — a `reasoning-delta` whose `reasoning-start` was never seen throws and breaks the chat.
+
+A non-zero `startIndex` (in particular a negative `initialStartIndex`) resolves to a chunk offset with no awareness of those part boundaries, so it can land in the middle of an open part. When that happens, `WorkflowChatTransport` will **drop chunks that reference a part it didn't see a start for** and log a one-time warning. The chat keeps working, but any partial part overlapping the resume cursor is discarded. Tool calls are an exception: `tool-input-available` / `tool-input-error` chunks are self-contained (they carry the full input), so a tool call is recovered as soon as one of those chunks appears in the resumed window — only its streamed input deltas are lost.
+
+To preserve those partial parts, rewind to a step boundary on the server before returning the readable. `start-step` / `finish-step` chunks are the natural seams — no UI part is ever open across them. Sketch:
+
+{/*@skip-typecheck: incomplete code sample*/}
+
+```typescript title="app/api/chat/[id]/stream/route.ts"
+const run = getRun(id);
+const tailIndex = await run.getReadable().getTailIndex();
+
+let resolved = startIndex < 0
+  ? Math.max(0, tailIndex + 1 + startIndex)
+  : startIndex;
+
+if (startIndex !== 0) {
+  // Walk back from `resolved` to the most recent start-step (or chunk 0),
+  // capping the lookback so a single huge step can't trigger an unbounded scan.
+  const LOOKBACK = 200;
+  const probe = run.getReadable({ startIndex: Math.max(0, resolved - LOOKBACK) });
+  let i = Math.max(0, resolved - LOOKBACK);
+  let lastBoundary = i;
+  for await (const chunk of probe as unknown as AsyncIterable<{ type: string }>) {
+    if (i >= resolved) break;
+    if (chunk.type === "start-step") lastBoundary = i;
+    i++;
+  }
+  resolved = lastBoundary;
+}
+
+return createUIMessageStreamResponse({
+  stream: run.getReadable({ startIndex: resolved }),
+  headers: { "x-workflow-stream-tail-index": String(tailIndex) },
+});
+```
+
 ## See Also
 
 - [DurableAgent](/docs/api-reference/workflow-ai/durable-agent) - Building durable AI agents within workflows

package/docs/api-reference/workflow-api/start.mdx

@@ -97,6 +97,8 @@ const run = await start(myWorkflow, ["arg1", "arg2"], { // [!code highlight]
 
 <Callout type="info">
 The `deploymentId` option is currently a Vercel-specific feature. Other Worlds may implement this option differently to match their own deployment runtimes, and the World spec may rename it from `deploymentId` to `version` in a future SDK version. On Vercel, `"latest"` resolves to the most recent deployment matching your current environment — the same production target for production deployments, or the same git branch for preview deployments.
+
+In Worlds without atomic, immutable deployments (such as local development or self-hosted Postgres), there is no notion of multiple deployments to resolve between, so `deploymentId: "latest"` has no effect: the SDK logs a warning and the run targets the current deployment. This means a workflow that opts into `"latest"` on Vercel still runs unchanged in local development.
 </Callout>
 
 <Callout type="warn">

package/docs/api-reference/workflow-next/with-workflow.mdx

@@ -31,11 +31,35 @@ export default withWorkflow(nextConfig, workflowConfig); // [!code highlight]
 If a package in `serverExternalPackages` contains workflow code (`"use step"`,
 `"use workflow"`, or serialization classes), `withWorkflow()` automatically
 removes it from `serverExternalPackages` for the current build and prints a
-warning. This ensures the package still gets transformed by the Workflow
-compiler. Remove that package from `serverExternalPackages` in your
+warning. Workflow still compiles the package so its directives are transformed.
+Remove that package from `serverExternalPackages` in your
 `next.config` to silence the warning.
 </Callout>
 
+### Workflow Discovery in Next.js
+
+`withWorkflow()` discovers workflows by scanning your Next.js entrypoints — App
+Router `route`, `page`, and `layout` files (under `app/` or `src/app/`) and any
+file under `pages/` or `src/pages/` — for `start()` calls imported from
+`workflow/api`. The workflow and step files themselves can live anywhere (for
+example `src/workflows/`); they are discovered transitively through imports, as
+long as a `start()` call in an entrypoint statically reaches them.
+
+<Callout type="info">
+Call `start()` from server-side entrypoints, including Route Handlers and Server
+Actions. Don't call workflow functions directly — that bypasses the workflow
+runtime.
+</Callout>
+
+### Next.js Server Actions and `"use server"`
+
+Don't put a top-level `"use server"` directive in modules imported by workflow
+or step functions. Workflow transformation wraps imported modules in synchronous
+initializers, and Next.js rejects a `"use server"` directive inside that wrapper
+with errors like `Server Actions must be async functions`. Keep `"use server"`
+on the files that define your Server Actions, and move shared logic into
+separate modules that don't carry the directive.
+
 ### Monorepos and Workspace Imports
 
 By default, Next.js detects the correct workspace root automatically. If your Next.js app lives in a subdirectory such as `apps/web` and workspace resolution is not working correctly, you can set `outputFileTracingRoot` as a workaround:
@@ -68,7 +92,6 @@ const nextConfig: NextConfig = {};
 
 export default withWorkflow(nextConfig, {
   workflows: {
-    lazyDiscovery: true,
     local: {
       port: 4000,
     },
@@ -78,7 +101,6 @@ export default withWorkflow(nextConfig, {
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `workflows.lazyDiscovery` | `boolean` | `false` | When `true`, defers workflow discovery until files are requested instead of scanning eagerly at startup. Useful for large projects where startup time matters. |
 | `workflows.local.port` | `number` | — | Overrides the `PORT` environment variable for local development. Has no effect when deployed to Vercel. |
 
 <Callout type="info">

package/docs/deploying/world/postgres-world.mdx

@@ -31,10 +31,42 @@ WORKFLOW_POSTGRES_URL="postgres://user:password@host:5432/database"
 
 Run the migration script to create the necessary tables in your database. Ensure `WORKFLOW_POSTGRES_URL` is set when running this command:
 
+<Tabs items={["npm", "pnpm", "Yarn", "Bun"]}>
+
+<Tab value="npm">
+
+```bash
+npx --package=@workflow/world-postgres bootstrap
+```
+
+</Tab>
+
+<Tab value="pnpm">
+
+```bash
+pnpm dlx --package @workflow/world-postgres bootstrap
+```
+
+</Tab>
+
+<Tab value="Yarn">
+
+```bash
+yarn dlx --package @workflow/world-postgres bootstrap
+```
+
+</Tab>
+
+<Tab value="Bun">
+
 ```bash
-npx workflow-postgres-setup
+bunx --package @workflow/world-postgres bootstrap
 ```
 
+</Tab>
+
+</Tabs>
+
 <Callout type="info">
 The migration is idempotent and can safely be run as a post-deployment lifecycle script.
 </Callout>

package/docs/foundations/hooks.mdx

@@ -87,7 +87,7 @@ The key points:
 
 ### Checking for Token Conflicts
 
-Sometimes you need to know that a hook token has been claimed, but you do not want to wait for external data yet. Await `hook.getConflict()` for that:
+Sometimes you need to know that a hook token has been claimed, but you do not want to wait for external data yet. Await `hook.getConflict()` (available starting in `workflow@4.5.0`) for that:
 
 ```typescript lineNumbers
 import { createHook } from "workflow";

package/docs/observability/index.mdx

@@ -42,6 +42,19 @@ npx workflow inspect runs --web
 
 ![Workflow SDK Web UI](/o11y-ui.png)
 
+To share a link to a specific run without opening a browser, use the `--url`
+flag. It prints the dashboard deep link to stdout and exits (no browser, no
+local server) — useful for scripts, PR comments, or automation. Add `--json` to
+get `{ "url": "..." }`.
+
+```bash
+# Print the deep-link URL for a run (no browser, no server)
+npx workflow inspect run <run_id> --url
+
+# Vercel runs: add the backend (and --env preview for preview deployments)
+npx workflow inspect run <run_id> --backend vercel --url
+```
+
 ## Backends
 
 The Workflow SDK CLI can inspect data from any [World](/docs/deploying). By default, it inspects data in your local development environment. For example, if you are using Next.js to develop workflows locally, the

package/docs/v4/api-reference/workflow-nitro/index.mdx

@@ -27,6 +27,7 @@ When enabled, the module:
 - Registers the workflow runtime routes under `/.well-known/workflow/v1/`.
 - Serves a redirect to the local observability dashboard at `/_workflow` in development.
 - Configures Vercel function rules (queue triggers and `maxDuration`) for the workflow routes when deploying to Vercel.
+- Uses Nitro's `workspaceDir` as the workflow project root so monorepo apps can import sibling workspace packages without extra workflow config.
 
 ## Module Options
 

package/docs/v4/api-reference/workflow-nuxt/index.mdx

@@ -25,6 +25,7 @@ When enabled, the module:
 - Registers the [`workflow/nitro`](/docs/api-reference/workflow-nitro) module on Nuxt's Nitro server, which transforms `"use workflow"` and `"use step"` directives, builds the workflow bundles, and registers the workflow runtime routes under `/.well-known/workflow/v1/`.
 - Configures Vite to bundle (rather than externalize) the Workflow SDK packages in SSR mode so workflow code is transformed correctly.
 - Enables the `workflow` TypeScript plugin by default for IDE IntelliSense.
+- Uses Nuxt/Nitro's detected `workspaceDir` so monorepo apps can import sibling workspace packages without extra workflow config.
 
 ## Module Options
 

package/docs/v5/api-reference/workflow-nitro/index.mdx

@@ -27,6 +27,7 @@ When enabled, the module:
 - Registers the workflow runtime routes under `/.well-known/workflow/v1/`.
 - Serves a redirect to the local observability dashboard at `/_workflow` in development.
 - Configures Vercel function rules (queue triggers and `maxDuration`) for the workflow routes when deploying to Vercel.
+- Uses Nitro's `workspaceDir` as the workflow project root so monorepo apps can import sibling workspace packages without extra workflow config.
 
 ## Module Options
 

package/docs/v5/api-reference/workflow-nuxt/index.mdx

@@ -25,6 +25,7 @@ When enabled, the module:
 - Registers the [`workflow/nitro`](/docs/api-reference/workflow-nitro) module on Nuxt's Nitro server, which transforms `"use workflow"` and `"use step"` directives, builds the workflow bundles, and registers the workflow runtime routes under `/.well-known/workflow/v1/`.
 - Configures Vite to bundle (rather than externalize) the Workflow SDK packages in SSR mode so workflow code is transformed correctly.
 - Enables the `workflow` TypeScript plugin by default for IDE IntelliSense.
+- Uses Nuxt/Nitro's detected `workspaceDir` so monorepo apps can import sibling workspace packages without extra workflow config.
 
 ## Module Options
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -57,18 +57,18 @@
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "4.0.10",
-    "@workflow/cli": "4.2.10",
-    "@workflow/core": "4.5.0",
+    "@workflow/astro": "4.0.11",
+    "@workflow/cli": "4.3.0",
+    "@workflow/core": "4.6.0",
     "@workflow/errors": "4.1.4",
     "@workflow/typescript-plugin": "4.0.3",
     "@workflow/utils": "4.1.3",
-    "@workflow/next": "4.0.11",
-    "@workflow/nest": "0.0.10",
-    "@workflow/nitro": "4.1.1",
-    "@workflow/nuxt": "4.0.11",
-    "@workflow/sveltekit": "4.0.10",
-    "@workflow/rollup": "4.0.10"
+    "@workflow/next": "4.1.0",
+    "@workflow/nest": "4.0.12",
+    "@workflow/nitro": "4.1.2",
+    "@workflow/nuxt": "4.0.12",
+    "@workflow/sveltekit": "4.0.11",
+    "@workflow/rollup": "4.0.11"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",