## Summary
Split the serialization/deserialization logic into environment-specific layers so data hydration can happen client-side in the browser. This is a prerequisite for e2e encryption where decryption keys are only available in the browser.
## Architecture
### Layer 1: `@workflow/core/serialization-format` (new, browser-safe)
- Format prefix encoding/decoding (`devl`, future `encr`, etc.)
- Generic `hydrateData()` dispatch — handles Uint8Array (v2 binary), legacy arrays (v1), and plain values
- `hydrateResourceIO(resource, revivers)` resource-type dispatcher (step/hook/event/workflow field mapping)
- `ClassInstanceRef` (plain data class, no `node:util` dependency)
- `StreamRef`, type guards (`isStreamRef`, `isStreamId`, `isClassInstanceRef`), utility functions (`extractStreamIds`, `truncateId`)
- Shared `observabilityRevivers` for stream/class/step display overrides
- 36 unit tests covering all of the above
### Layer 2: Environment-specific revivers
- **`@workflow/web-shared`** (`lib/hydration.ts`) — browser-safe revivers using `atob()` for base64, real `URLSearchParams`/`Headers`/`URL` instances, `ClassInstanceRef` for UI rendering
- **`@workflow/cli`** (`lib/inspect/hydration.ts`) — Node.js revivers using `Buffer.from()` for base64, `CLIClassInstanceRef` with `util.inspect.custom` for CLI output
Each module exports a pre-bound `hydrateResourceIO(resource)` that uses its environment's revivers.
### Removed: `@workflow/core/observability`
- Deleted `observability.ts` and `observability.test.ts` entirely (no remaining consumers)
- Removed `"./observability"` export from `@workflow/core/package.json`
- Removed the `workflow` package's `internal/observability.ts` re-export
- All functionality has been split between `serialization-format.ts` (shared types/utilities) and the environment-specific hydration modules
## Web package changes
- Server passes raw world data through without hydration (CBOR preserves `Uint8Array`)
- Client calls `hydrateResourceIO` from `@workflow/web-shared` after receiving CBOR-decoded data
- No Vite `node:*` stubs needed since `@workflow/core/serialization-format` is browser-safe
- Optimized: event hydration finds the matching event before hydrating (instead of hydrating all)
- Reduced server log noise from handled API errors (4xx errors no longer logged)
## Packages affected
- `@workflow/core` — new `serialization-format` export (with tests), removed `observability` export
- `@workflow/web-shared` — new `lib/hydration.ts` with browser-safe revivers
- `@workflow/cli` — new `lib/inspect/hydration.ts` with Node.js revivers, updated `output.ts` import
- `@workflow/web` — client-side hydration, removed server-side hydration
- `workflow` — removed `internal/observability.ts` re-export
* Add workflow skill for Claude Code
Add custom slash commands for Claude Code:
- /pr command for creating PRs following repo conventions
Add workflow skill with comprehensive documentation:
- Main SKILL.md with core concepts and quick reference
- Reference docs for frameworks, AI agents, patterns, errors, and API
Signed-off-by: johnlindquist <johnlindquist@gmail.com>
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
* Update SKILL.md serialization docs for custom class support
Add documentation for custom class serialization using @workflow/serde
symbols (WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE) and clarify what can
and cannot be serialized based on recent PR #762.
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
* Fix incorrect API property names in SKILL.md
- Update sleep() example date from 2025 to 2027 (future date)
- Fix getWorkflowMetadata() to use correct properties: workflowRunId,
workflowStartedAt, url (not runId, workflowName)
- Fix getStepMetadata() to use correct property: attempt (not attemptNumber)
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
* Move skills to skill/workflow directory structure
Reorganize skill files to support multiple skills under ./skill/<name>/
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
* Rename skill to skills (plural)
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
* Refactor skills to use bundled docs from node_modules
- Update SKILL.md to direct agents to search node_modules/workflow/docs/
- Remove manually-maintained reference docs (ai-agents, api-reference, frameworks, patterns)
- Keep common-errors.md for practical troubleshooting
- Add prepack/postpack hooks to bundle docs in npm packages:
- workflow: All docs from docs/content/docs/
- @workflow/ai: AI-specific docs
- @workflow/core: foundations, how-it-works, api-reference
- @workflow/next: Next.js setup docs
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
* Add AI SDK step function guidance to SKILL.md
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
* Update SKILL.md formatting and add ecosystem section
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
* Align postpack scripts with AI SDK conventions
Use del-cli for postpack cleanup to match the AI SDK's cross-platform
approach. This ensures consistent tooling across both projects.
- Add del-cli ^5.1.0 to root devDependencies
- Update postpack in @workflow/core, @workflow/next, @workflow/ai, and
workflow packages from `rm -rf docs` to `del-cli docs`
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
* Add workflow health command to debugging documentation
Document the CLI health check command for verifying workflow/step
endpoint connectivity during local development and production.
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
* Address PR feedback: standardize on rm -rf and improve SKILL.md
- Remove del-cli dependency, use rm -rf consistently in postpack scripts
- Restructure SKILL.md to lead with "Prefer Step Functions" pattern
- Add sandbox limitations table for workflow-context workarounds
- Consolidate examples and remove duplication
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
* Consolidate common-errors.md into SKILL.md
Move useful tips (serialization, streaming, debugging) into main skill
file and remove the separate common-errors.md reference file.
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
---------
Signed-off-by: johnlindquist <johnlindquist@gmail.com>
Signed-off-by: John Lindquist <johnlindquist@gmail.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Pranay Prakash <pranay.gp@gmail.com>
Added support for serializing `this` context when invoking step functions.
### What changed?
- Modified the step function implementation to capture and serialize the `this` context when it's defined and not the global object
- Updated the step invocation queue item interface to include an optional `thisVal` property
- Enhanced the step handler to apply the hydrated `thisVal` when executing step functions
### Why make this change?
This enhancement allows step functions to be invoked with an explicit context object using standard JavaScript methods like `.call()` and `.apply()`. This is particularly useful for step functions that need to access properties from a specific context, enabling more flexible and idiomatic JavaScript patterns within workflows.
* feat: add queue-based health check to bypass Deployment Protection
- Add HealthCheckPayloadSchema and HEALTH_CHECK_STREAM_PREFIX to @workflow/world
- Add healthCheck() method to Queue interface
- Update workflow and step handlers to detect and respond to health check messages
- Implement healthCheck() in world-local, world-vercel, and world-postgres
The queue-based health check sends a message through the queue pipeline,
which bypasses Vercel's Deployment Protection. The handler writes a response
to a stream that the caller reads to confirm health.
This complements the existing HTTP-based ?__health approach which still works
for local development and when bypass headers are available.
* refactor: move healthCheck to core package as utility function
Instead of adding healthCheck to the World interface (which duplicated
the same implementation across all worlds), this is now a utility function
in @workflow/core that takes the World as a parameter.
Usage:
import { healthCheck } from '@workflow/core';
const result = await healthCheck(world, 'workflow');
This is cleaner because:
- Single implementation instead of 3 identical ones
- World implementations remain simple
- No changes needed to the World interface
* .
* refactor: move health check types from world to core
Health check types (HealthCheckPayloadSchema, HealthCheckResult, etc.)
are now defined in @workflow/core since that's where they're used.
The HealthCheckPayloadSchema is still part of QueuePayloadSchema in
world (so the queue accepts health check messages), but it's not
exported from the public API.
* .
* Refactor health check implementation based on code review feedback (#746)
* Initial plan
* Address PR review comments: export types, fix race condition, improve error handling
Co-authored-by: TooTallNate <71256+TooTallNate@users.noreply.github.com>
* Add queue-based health check test and document security considerations
Co-authored-by: TooTallNate <71256+TooTallNate@users.noreply.github.com>
* Replace 'any' type with proper type guards for health check response
Co-authored-by: TooTallNate <71256+TooTallNate@users.noreply.github.com>
* Extract health check queue names as constants and improve type guards
Co-authored-by: TooTallNate <71256+TooTallNate@users.noreply.github.com>
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: TooTallNate <71256+TooTallNate@users.noreply.github.com>
* .
* Fix e2e test
* .
* .
* .
* fix(ai): preserve providerMetadata as providerOptions in multi-turn tool calls (#733)
When tool calls are added to the conversation history, map providerMetadata
to providerOptions following the AI SDK convention. This fixes Gemini thinking
models that require thoughtSignature to be preserved across multi-turn tool calls,
preventing the error 'function call is missing a thought_signature'.
Fixes#727
* Local ui cli flag (#744)
* [web] Increase contrast on attribute items in sidebar (#736)
Signed-off-by: Peter Wielander <mittgfu@gmail.com>
* [world] Remove pause and resume events, actions and states (#751)
* Version Packages (beta) (#735)
* .
* .
* Update turbo inputs to include shared config (#752)
* Update turbo inputs to include shared config
* Apply suggestions from code review
Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
---------
Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
* feat(web): add self-hosted mode for world configuration (#747)
* feat(web): add self-hosted mode for world configuration
When WORKFLOW_TARGET_WORLD env var is set, the web UI operates in
self-hosted mode where the world configuration is locked to server-side
environment variables and cannot be changed via query params or UI.
- Add getHardcodedConfig server action to detect self-hosted mode
- Modify getWorldFromEnv to use server env vars in hardcoded mode
- Create WorldConfigContext to provide config state app-wide
- Update settings sidebar to show locked state with disabled inputs
- Update connection status to show PostgreSQL backend info
- Mask sensitive values (postgres URL) in hardcoded mode UI
* fix: address PR review feedback
- Remove unused ConfigMode type export
- Fix postgres substring to undefined (tooltip has details)
- Extract buildEnvMapFromProcessEnv helper to reduce duplication
- Remove unused EnvMap import from layout-client
- Import HardcodedConfig from web-shared/server instead of re-defining
* Fix: PostgreSQL URL parameter missing from configParsers, causing loss of postgres URL configuration on page reload in dynamic mode
* fix(cli): clear WORKFLOW_TARGET_WORLD when spawning web server
The CLI sets WORKFLOW_TARGET_WORLD as an env var, which the spawned
Next.js server inherits. This caused the web UI to enter self-hosted
mode even when launched via CLI.
Now we explicitly clear WORKFLOW_TARGET_WORLD from the server's
environment so it starts in dynamic mode where config comes from
query params as intended.
* refactor(web): use server-side env vars for world config
BREAKING CHANGE: The web UI no longer supports configuring the world
backend via URL query parameters. Configuration is now read exclusively
from server-side environment variables.
Changes:
- Remove query param parsing from @workflow/web config.ts
- Add ServerConfig interface with non-sensitive display info
- Update all components to use useServerConfig() hook
- Settings sidebar is now read-only
- CLI passes env vars to spawned web server instead of query params
- Server actions use process.env directly (envMap param reserved for future use)
This simplifies the architecture and improves security by never sending
sensitive data (connection strings, auth tokens) to the client.
* fix(web): fix settings sidebar overflow and shorten data dir path
- Add truncate/overflow handling to settings sidebar config values
- Add shortenPath() helper to abbreviate long file paths:
- Replaces home directory with ~
- Shows .../last-two-segments if still too long
- Add title attributes for full path on hover
* Update changeest
---------
Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>
* Version Packages (beta) (#755)
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
* Update packages/world/src/queue.ts
Co-authored-by: Pranay Prakash <pranay.gp@gmail.com>
* [web] Tidy wake-up and re-enqueue buttons (#737)
---------
Signed-off-by: Peter Wielander <mittgfu@gmail.com>
* [cli] Use dotenv to resolve .env and .env.local files on startup (#765)
* Use temporary workflow-server deployment URL
* feat: add queue-based health check to bypass Deployment Protection
- Add HealthCheckPayloadSchema and HEALTH_CHECK_STREAM_PREFIX to @workflow/world
- Add healthCheck() method to Queue interface
- Update workflow and step handlers to detect and respond to health check messages
- Implement healthCheck() in world-local, world-vercel, and world-postgres
The queue-based health check sends a message through the queue pipeline,
which bypasses Vercel's Deployment Protection. The handler writes a response
to a stream that the caller reads to confirm health.
This complements the existing HTTP-based ?__health approach which still works
for local development and when bypass headers are available.
* refactor: move healthCheck to core package as utility function
Instead of adding healthCheck to the World interface (which duplicated
the same implementation across all worlds), this is now a utility function
in @workflow/core that takes the World as a parameter.
Usage:
import { healthCheck } from '@workflow/core';
const result = await healthCheck(world, 'workflow');
This is cleaner because:
- Single implementation instead of 3 identical ones
- World implementations remain simple
- No changes needed to the World interface
* .
* refactor: move health check types from world to core
Health check types (HealthCheckPayloadSchema, HealthCheckResult, etc.)
are now defined in @workflow/core since that's where they're used.
The HealthCheckPayloadSchema is still part of QueuePayloadSchema in
world (so the queue accepts health check messages), but it's not
exported from the public API.
* .
* Refactor health check implementation based on code review feedback (#746)
* Initial plan
* Address PR review comments: export types, fix race condition, improve error handling
Co-authored-by: TooTallNate <71256+TooTallNate@users.noreply.github.com>
* Add queue-based health check test and document security considerations
Co-authored-by: TooTallNate <71256+TooTallNate@users.noreply.github.com>
* Replace 'any' type with proper type guards for health check response
Co-authored-by: TooTallNate <71256+TooTallNate@users.noreply.github.com>
* Extract health check queue names as constants and improve type guards
Co-authored-by: TooTallNate <71256+TooTallNate@users.noreply.github.com>
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: TooTallNate <71256+TooTallNate@users.noreply.github.com>
* .
* Fix e2e test
* .
* .
* .
* .
* .
* Update packages/world/src/queue.ts
Co-authored-by: Pranay Prakash <pranay.gp@gmail.com>
* Use temporary workflow-server deployment URL
* .
* .
---------
Signed-off-by: Peter Wielander <mittgfu@gmail.com>
Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: TooTallNate <71256+TooTallNate@users.noreply.github.com>
Co-authored-by: Pranay Prakash <pranay.gp@gmail.com>
Co-authored-by: Peter Wielander <mittgfu@gmail.com>
Co-authored-by: Vercel Release Bot <88769842+vercel-release-bot@users.noreply.github.com>
Co-authored-by: JJ Kasper <jj@jjsweb.site>
Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Vercel Release Bot