Workflows release notes

Curated overviews of recent Workflows prerelease package waves.

Workflows 0.36 narrows generated document triggers and adds recovery for queued effects. The Workflows CLI also checks that generated runtime files match your definitions before deployment. Definition validation now catches hidden clock and document reads.

Teams using the generated runtime: upgrade your Workflows packages together to 0.36.0, regenerate with npx @sanity/workflow-cli blueprint generate, review your preserved effect handlers, deploy definitions, then redeploy Functions. When a generated Blueprint exists, file drift or missing handlers now stops definition deployment, including --check and --dry-run. The check covers the whole config even when deploying one definition or deployment. See generated runtime rollout.

Authors with effect budgets: runtime.memory is now whole GB from 1 through 10, and runtime.timeout is whole seconds from 1 through 900. Replace megabyte-style values such as memory: 512 with a supported allocation such as memory: 1, then regenerate and redeploy Functions. Values outside these ranges fail validation. See runtime settings.

Authors using clock functions in conditions, predicates, spawn expressions, or start rules: replace now() with $now and dateTime::now() with dateTime($now) before your next definition validation or deployment. Query-based initial values remain exempt. Existing stored definitions are not rewritten. See condition evaluation.

Authors with implicit document reads in start rules: a start.filter that reads the root document requires a subject field, and a GROQ start requirement cannot read a root document. Validation now also detects projection escapes and implicit reads through references(), sanity::versionOf(), and sanity::partOfRelease(). Rewrite affected requirements against supplied variables; $fields contains raw inputs, not hydrated documents. See start conditions.

Teams using reserved document types as subjects: discovery now excludes the sanity. and system. namespaces when a subject has no types, including when reading older definitions. Explicitly list the reserved type and, in Studio, add a mapping row. Listing an engine-owned instance, definition, or guard type now fails defineWorkflow and deploy validation. Remove those type names and use spawn to coordinate workflow instances. See subject fields and Studio configuration.

Teams relying on autonomous starts for existing documents: generated workflows with no start filter, or a filter that reads nothing beyond _type, now use creates-only watchers. Filters that read $now, other documents, or dynamic paths still observe every update. Regeneration does not backfill existing documents. Start their workflow instances explicitly where needed. See generated document triggers.

Custom telemetry consumers: event names now identify the package, such as Workflows Engine Instance Started, Workflows CLI Definition Shared, and Workflows React Session Started. Update logger filters and include both old and new names when querying historical data. CLI trace version 2 replaces payload fields command and flags with context fields commandArguments and extraArguments, alongside coreOptions; groupOrCommand is always workflows, and success remains the result. extraArguments now includes flag values such as --tag=prod, except redacted and undeclared inputs. Review your collection policy before upgrading.

Generated start watchers can respond only to updates of fields their start filter reads, and effect drains respond to pending-effect changes. This reduces Function invocations caused by unrelated edits. Dynamic or whole-document reads keep the broader update trigger. See generated document triggers.

The generated heartbeat periodically reevaluates function-hosted parent workflows and recovers function-hosted effects whose trigger was missed or whose lease expired. Recovery also covers effects on completed instances and workflows hosted elsewhere, and respects declared effect budgets. Recovery shares a bounded Function invocation, so it does not guarantee a completion deadline. See heartbeat recovery.

This release does not change stored document shapes or raise the reader-model floor. Generated runtimes remain experimental and are not ready for production use.

Workflows 0.35 fixes a CLI compatibility issue that prevented sanity.workflow.ts from loading in TypeScript 7 projects. Blueprint generation and its --check mode support TypeScript 6, TypeScript 7, and projects without TypeScript installed. Upgrade the Workflows packages you use together to 0.35.0; no configuration changes are required. See Configure and deploy workflow definitions.

Workflows 0.34 fixes compatibility with Sanity UI 4 for the Studio plugin and shared UI components.

For the Studio plugin, upgrade Sanity Studio to 6.15 or later in the 6.x line. Upgrade every @sanity/workflow-* package in your application to 0.34.0 together, reinstall dependencies, and commit the updated lockfile. Mixing Workflows releases can fail the studio build. See the upgrade instructions.

If you use @sanity/workflow-components or @sanity/workflow-diagram outside Studio, provide styled-components ^6.4.2. Both packages install Sanity UI 4. Use @sanity/ui ^4.2.1 for the theme provider around these Workflows components. See UI component installation.

Upgrading from 0.33 requires no changes to workflow definitions or stored workflow data. Keep your existing expectedMinReaderModel value.

Workflows 0.33 adds retry policies for external work and explains when a deleted document blocks an active workflow. The Workflows tool now marks overdue tasks individually.

If a document referenced by a required field is deleted while the workflow is active, normal actions and transitions stop. Abort and permitted direct field edits remain available.

Upgrade every studio, CLI, MCP server, Sanity Function, worker, and application sharing the workflow resource to Workflows 0.33.0. After verifying the rollout, set expectedMinReaderModel: 10 before deploying definitions with required content references or effect retry policies.

Existing workflow instances need no reset or backfill. Older runtimes can still advance some instances without the new checks, so upgrade every shared runtime before relying on them. Follow the model-10 rollout.

Studio and App SDK integrations require @sanity/sdk 3.1 or later in the 3.x line, with matching @sanity/sdk-react when used. Before reinstalling, configure SDK 3 to resolve @sanity/mutate 0.18.2; version 0.18.1 can leave document reads pending. Follow the installation instructions.

Custom implementations of Workflows client interfaces must read request targets from url instead of uri. The compatibility guidance names the affected interfaces.

An effect is external work queued by a workflow, such as sending a notification. Its retry policy can set the attempt count, fixed or exponential waits, and a window for starting another attempt. Retries run within one invocation, so the policy must fit its runtime. See bounded effect retries.

When a referenced document is deleted while a workflow is active, Sanity Studio identifies the affected field. A required reference blocks progress until you restore the document or select a readable replacement in an editable field. In the Workflows tool’s Overview and Board, an overdue dot identifies each late task. See Workflows in Sanity Studio.

The Workflows CLI can generate Sanity Functions from your workflow definitions with npx @sanity/workflow-cli blueprint generate. This command is experimental and not ready for production use. Its flags and generated output may change. See CLI command reference for options and current limitations.

Workflows 0.32 separates team responsibility from personal task ownership. A task can retain its project-role assignments while one person holds it. Sanity Studio distinguishes personal and role-routed work, with new controls for moving between tasks. Custom runtimes can discover when a workflow next needs a time-based check.

This is a breaking package release. Existing installations need coordinated runtime upgrades; claim declarations and custom effect configuration need code changes. Stored workflows need no reset or backfill.

Singular assignments now store a member list. Guards combining operations such as draft edits and publishing also need different document handling. Both require reader model 9, a stored-data compatibility level that older runtimes cannot handle.

Before allowing affected writes:

• Upgrade every studio, command-line tool, agent server, Sanity Function, worker, and application sharing the workflow data to runtime packages 0.32.0.
• After verifying every reader, set the deployment's reviewed expectedMinReaderModel to 9.
• Deploy revised definitions and verify their model. An unchanged redeployment can reuse the old definition.

An existing workflow instance, meaning one started workflow, keeps its original definition and assignment representation. The new lists apply to future instances started from a model-9 definition.

Existing instances with affected guards can require model 9 on their first new-engine commit, without redeployment. Older runtimes then refuse them; downgrading is not a rollback. The rollout guide identifies affected definitions. Others retain their existing reader requirement.

The claim shortcut for taking and releasing work is removed. Definitions containing type: 'claim' now fail validation.

Use ordinary fields and explicit actions. Preserve who can take, release, and act on the work. $assigned also matches an eligible role pool before anyone takes the task; it does not require a personal holder.

The assignment example shows routed work. The editorial review recipe preserves actor-based ownership instead.

Effects are queued work your application handles, such as sending email. Engine construction now groups their settings under effects:

• effectHandlers becomes effects.handlers.
• effectLeaseMs becomes effects.leaseMs.
• missingHandler becomes effects.missingHandler.

Use the same group in useWorkflowEngine and keep it stable between renders. The Studio plugin's own effectHandlers setting is unchanged.

Old TypeScript calls fail to compile. Old JavaScript settings are ignored, so draining can throw MissingHandlerError. Queued effects need no rewrite. See the handler configuration example.

Taking a task retains its role routes; releasing the person can return it to the role pool. In Sanity Studio, For me separates Tasks assigned to you from Tasks sent to your roles. See personal and role-routed tasks.

Expand a task's fields and actions without losing its selection. Previous/next controls and keyboard navigation move through the current list. A board navigator helps you reach stages on a wide board. See task and board navigation.

Custom runtimes can use nextEvaluationAt to schedule another tick, even when the last tick changed nothing. Your runtime still owns the timer and handles data changes. Some time conditions report no boundary, so a missing timestamp does not mean an active instance needs no further checks. See the scheduling example.

Instance lists gain viewer-assignment filters and counts in the CLI reference and MCP operations.

Custom integrations also have migration details for guard contracts, test-bench changes, and engine errors.

Workflows 0.31 makes Studio runs easier to scan and corrects MCP rollout guidance for role-constrained assignments. It also publishes Blueprint provider groundwork, but Blueprint deployment is not generally available yet.

Users of @sanity/workflow-blueprint must remove ownershipAction and unknown lifecycle keys. Lifecycle supports only deletionPolicy with retain or protect, plus dependsOn references that begin with $.resources.. Omit lifecycle to use the default retain policy. Code that constructs WorkflowsResource values directly must include lifecycle: {deletionPolicy: 'retain'} (or protect) or switch to defineWorkflows. Unsupported configuration now fails validation. Continue using sanity workflows deploy until the Blueprint integration is available.

MCP 0.30 reported reader model 6 for role-constrained assignment fields even though the engine requires model 8. Upgrade @sanity/workflow-mcp to 0.31, upgrade every reader sharing the workflow resource, then pass expectedMinReaderModel: 8 to workflows_deploy_definition. The stale guidance causes deployment rejection before any write. Definitions without assignment roles remain on reader model 4. Follow the role-constrained assignment rollout.

The Studio Overview groups the current stage’s human work by task in the Tasks column and on board cards, so separate assignments and unassigned work stay visible. Overdue marks show how late work is or how many tasks are overdue. Blocked marks name the task or automation that failed or did not finish. Applied filters now stay beside Add filter while the workflow and run-scope controls remain on the left. No Studio upgrade action is required beyond installing the 0.31 package stack.

Workflows 0.30 makes large sets of workflow instances easier to manage. A workflow instance is one started workflow. Studio brings all instances into one filterable view, custom interfaces gain paged live previews, and workflow authors can limit assignments to people or collective roles with specific project roles.

A workflow instance’s subject is the document it follows. Studio no longer offers bulk cleanup for active instances left behind when that document is deleted. Applications that delete subject documents must handle those instances explicitly. Use the deleted-subject Function to apply your lifecycle policy; otherwise the instances remain active. No action is needed if your application keeps subject documents.

Add roles to an assignee or assignees field to control who can be assigned. Workflows accepts people who hold a listed project role and collective roles that match a listed role. Existing values remain removable and reorderable even when they no longer qualify. See Assignments and role eligibility for the definition example and matching rules.

Fields without roles keep their current behavior. To enable role constraints, upgrade every runtime sharing the workflow resource, confirm access to the project member directory, then set expectedMinReaderModel: 8 and redeploy. Follow the model-8 rollout for the required order.

Overview brings workflow instances from every definition into one table or board, with filters, Open and Closed views, and a docked detail panel. The list continues loading until every matching instance is available instead of stopping at 200. For me isolates the current user’s open work, while Definitions contains the deployed workflow catalog and setup details. See the Workflows tool.

instancePreviewsQuery returns lightweight, cursor-paged instance summaries, while instanceChangesQuery keeps the list current. React applications can use useInstancePreviews, while Studio integrations can use useWorkflowInstancePreviews. These APIs replace full instance reads and integration-specific paging. See Read instance previews and List instance previews.

0.29 adds advisory node semantics, field arithmetic, Enterprise caller attributes, and clearer stuck-work signals in Studio.

ActionSemantic now includes signal.* and custom.* values as well as decisions. Update exhaustive maps, or narrow their input to DecisionSemantic. See action semantics.

attributes is now reserved by the synthetic $attributes. Definitions deployed under model 6 or earlier with predicates.attributes must rename it and redeploy; otherwise references resolve to the caller attribute bag. See named predicates.

Workflows, stages, and activities accept Semantic[]; actions accept ActionSemantic[]. Integrations can render these labels without changing execution. See definition properties.

field.inc, field.dec, and field.setIfMissing are available from actions and effect completion. Upgrade every runtime before using them, then follow the bounded retry pattern.

$attributes brings Enterprise User Attributes into caller-bound soft gates. Missing attributes fail closed, and values are not persisted. See context-specific variables.

Landing and workflow pages now surface active, overdue, and snapshot-detectable stuck work. Workflow details adds transition-aware diagnosis and recovery guidance. See the Workflows tool.

Use these notes to upgrade Workflows safely. Each release lists required migrations before new capabilities. Package changelogs remain the exhaustive API record.

This release tightens deployment authoring, adds project role catalogs to assignment controls, and clarifies role-assigned work.

Authored configs now require WorkflowDeploymentInput with the current literal expectedMinReaderModel: 4. Reuse the authored object across config and Blueprint entry points; a parsed WorkflowDeployment is not an authoring input. Missing this migration produces TypeScript errors. See Reader-model rollout.

Add roles to ProjectMembersState, add roles to hand-built StudioProjectUsersState values, pass RoleVocabulary to role resolvers, and replace AssigneeBadge(s).members with vocabulary. Use roles: [] to retain member-derived role choices. See Reusable UI components.

Direct RoleAvatar hosts must provide their own tooltip and accessible name. AssigneeStack users need no change.

Standalone sanity-workflows users need no action. Embedded oclif hosts must replace editorial-workflows:* and removed root aliases with workflows:* topic IDs. Otherwise a command can fail or resolve a host-owned command. The official sanity workflows mount is not shipped yet. See Configure and deploy workflow definitions.

Pickers can offer project roles with no current holders. An empty or unavailable catalog falls back to member-held roles, and an already-stored unknown role stays visible and removable.

The document view and Workflows tool show a notice when visible work is included through a role the current editor holds. Role aliases do not add work to this queue.

The engine now exports isRevisionConflict(error) for a known revision-guarded write. Do not use it to classify a whole cascade or every 409. The Studio plugin also avoids a false warning when another client completes the same start. See isRevisionConflict.

Workflows 0.27 makes agent tools easier to discover, makes project roles legible throughout assignment controls, and moves document-editor workflow controls onto self-contained instance cards. Custom reactive integrations can now distinguish an evaluation failure from loading.

Every MCP wire name now uses the plural resource_verb form. Update prompts, approval lists, scripts, literal tools/call requests, telemetry queries, and embedded registrations that hard-code a name before upgrading. Calls made with an old name fail as unknown tools. Parameters and response shapes are unchanged.

See the MCP tool reference.

ProjectMember.roles is now readonly {name: string; title?: string}[] instead of readonly string[]. Read role.name wherever an integration previously read a role string. Adapters such as useProjectMembers return the new shape automatically, but downstream readers must migrate or TypeScript fails. Stored assignee values still use the machine role name, so no stored-data migration is required.

See Supply project members.

WorkflowSession adds the required evaluationError field. Hook consumers receive it automatically. Tests or adapters that construct a complete session object must add evaluationError: undefined or supply the current evaluation failure.

See Render every session state.

The document editor's Workflows view now gives each run its own card. The header shows the run, stage, and status while collapsed; one click expands it. The card's overflow menu opens workflow history or aborts an in-flight run with a required reason.

See See where your work stands.

Every Studio assignee control accepts people and project roles. Roles use square avatars and their project titles for display while stored assignments retain machine names. Shared pickers sort members by display name, search names, email addresses, and roles, and show account details on hover. Pickers present choices; they do not infer assignment eligibility.

See Reusable UI components.

useWorkflowSession now exposes evaluationError. It identifies a failed evaluation attempt that would otherwise look like indefinite loading before the first successful evaluation. A later successful attempt or an instance change clears it; ready is unaffected.

See The reactive session.

Workflows 0.26 gives MCP embedding hosts a supported way to construct engine clients and keep model-facing behavior aligned with the bundled server.

No upgrade action required. All new exports are additive, and the bundled workflow-mcp stdio server keeps its existing behavior. Hosts that hand-built client configuration or engine construction can adopt the shared seams on their own schedule.

workflowClientConfig layers the engine's API version, request-tag family, published perspective, and resource address over a host's client configuration. createWorkflowEngine binds that client to one workflow environment, while workflowErrorText and the exported tag-description constants keep custom wrappers aligned with the bundled server.

See Embed the tools in another MCP server.

Workflows 0.25 reshapes the Studio tool around each workflow, lets agents discover deployed environment tags, and makes MCP tool definitions host-neutral.

The action tool is now fire_workflow_action. Replace fire_action in calls, prompts, allowlists, and telemetry filters. The old wire name is not registered.

Embedding hosts that consume raw WorkflowToolDef values must read requiresAddress and merge their own environment fields when it is true. A tool's inputSchema now contains only tool-owned parameters. Add requiresAddress to custom definitions.

Tool schemas use zod v3 through zod/v3. Build merged fields with the same major. zod and @modelcontextprotocol/sdk are peer dependencies. npm 7+ and pnpm install peers automatically; strict installers must add them explicitly.

See Connect an agent over MCP.

The top-level tabs are Workflows at /workflows/overview, All documents at /workflows/all-documents, and For me at /workflows/for-me. A workflow's Documents and Definition pages now live below /workflows/overview/<name>. Update bookmarks and links. A bare /workflows address and the retired /workflows/documents and /workflows/tasks pages return to the landing page. The old /workflows/documents/<name> and /workflows/definition/<name> deep links no longer match.

The Studio start dialog now gates only input fields declared required: true. Add that declaration to subject or any other input that every run must supply.

Activity rows now show an inline calendar only for dueDate and dueDatetime. If a plain date or datetime was intended to be the row's deadline, change its kind. Other date fields remain available in activity detail and the Date filter.

Engine 0.25 retains data model 5 and reader floor 4. Keep expectedMinReaderModel: 4. No stored-data migration is required.

The bundled MCP server adds list_workflow_tags, which takes a workflow resource and returns the sorted tags that currently contain deployed definitions. The engine also exports deployedTagsGroq() and definitionTagsGroq() for custom hosts. Discovery reports observed environments; confirm the tag instead of choosing one automatically.

See the MCP server and Reference.

The Workflows landing presents deployed workflows as cards. Each workflow has its own Documents board and Definition page. Selecting a run opens a resizable Workflow details panel with its document, stages, management controls, and recent history.

See Add Workflows to Sanity Studio.

Actor resolution now bridges project-scoped sessions, including SAML SSO sessions, through the project's user directory before persisting the account-global user ID. Standard sessions require no upgrade action.

Workflows 0.24 adds explicit deadline fields, a document board in Studio, focused instance cleanup, and clearer workflow diagrams.

WorkflowDiagram no longer accepts guardCount, selectedStage, or onSelectStage. Remove those props. Stage pills no longer provide host-defined selection behavior.

WS_CARD_TOKENS removes --ws-red and --ws-font. Replace --ws-positive with --ws-path. A custom wrapper that relies on explicit diagram typography must provide --ws-font and --ws-font-weight separately.

See Reusable UI components.

Engine 0.24 writes model 5 documents and retains reader floor 4. Keep expectedMinReaderModel: 4. No stored-data migration is required.

Before deploying a definition that uses dueDate or dueDatetime, upgrade every Studio, CLI, MCP server, Function, server, and application that reads the workflow resource. Older engines reject those field kinds.

See How early access works.

Use dueDate or dueDatetime to identify the single top-level deadline for a workflow, stage, or activity scope. Both kinds use the same values, validation, options, and Studio controls as date and datetime.

See Fields.

Use the Studio Documents tab to group the newest 200 runs of one selected workflow by stage, switch between horizontal columns and a stacked list, and share the selected workflow through the URL.

See Workflows tool.

Abort an in-flight workflow from instance detail with a recorded reason. Owners of editable to-do lists can remove rows immediately; assignment-only and read-only views cannot.

See Add Workflows to Sanity Studio.

sanity-workflows nuke --instance removes one terminal instance and its guards without resetting the deployment. It refuses in-flight instances and non-workflow documents.

See the nuke command reference.

Set fill to keep the diagram canvas at the parent’s full width while respecting the supplied height. The graph remains centered and is never enlarged beyond 1:1.

See Render the workflow diagram.

The Workflows tool now opens on Definitions and orders its tabs as Definitions, Documents, Tasks, and For me. Definition detail shows its deploy time, active-instance count, trigger, configuration issues, and a full-width stage diagram.

Required start inputs left by a valid mapping are collected in the start dialog instead of making the workflow unavailable. Mapping diagnostics remain on developer-facing definition surfaces.

Completed workflow stages now use a neutral face. Diagram paths distinguish the current stage, completed stages, traversed transitions, untraversed transitions, and branches the run can no longer reach. Hovering a dashed transition shows its direction, with animation disabled for reduced motion.

Studio feedback now distinguishes engine refusals, failed writes, and successful commits whose follow-up effects remain incomplete. Task lists wait briefly for document titles before appearing, unresolved document links show a loading face, and project-member controls remain loading until the directory settles.

The 0.23 release expands the Workflows tool with definition and history views, makes stage overrides easier from an interactive terminal, and restores Studio workflow actions and assignments.

None. Engine 0.23 keeps data model 4 and reader floor 4. Keep expectedMinReaderModel: 4; no stored workflow data or Studio configuration migration is required.

The Workflows tool adds a Definitions tab with deployed definition details and stage diagrams. Instance detail now carries the document-oriented workflow snapshot, an inline newest-first history feed, and pending-effect controls. The document view links to this detail instead of opening a separate debug event log.

See Workflows tool.

Reference fields, array items, and other Studio document previews no longer add workflow-stage decorations. Current stage remains visible in the form strip, document badge, and Workflows tool.

Run set-stage without --to on an interactive terminal to choose from every stage in the instance’s pinned definition. The current stage is marked and selected initially. Non-interactive use still requires --to.

See the set-stage command reference.

Studio can again fire workflow actions and save user assignees when its Sanity client is explicitly bound to a project API host. The fix restores account-global identity resolution for these Studio operations.

The 0.22 release makes CLI reads easier to automate, removes resource-selection friction for instance commands, and makes deployment targets clearer.

None. Engine 0.22 still writes model 4 documents and keeps the reader floor at 4. Keep expectedMinReaderModel: 4; no stored workflow data migration is required.

A stale numeric acknowledgement now reaches the runtime compatibility check, which rejects it with readers-first rollout guidance. The check still accepts only 4.

Review Reader-model rollout.

Use --json with list, show, definition list, and definition show. Show commands return stored documents; list commands return structured row data with resource provenance and a truncated flag. Multi-resource JSON reads fail instead of returning partial results.

See Read the output as JSON.

diagnose, fire-action, set-stage, abort, and reset-activity now find an instance across every configured workflow resource from its ID alone. --deployment and --tag remain optional narrowers.

See Select a deployment, a tag, or an instance.

Deploy progress and completion lines now name the deployment, tag, and workflow resource.

See Deploy.

The 0.21 release changes the persisted reader floor, workflow readiness, identity storage, recovery, and integration APIs.

Engine 0.21 writes model 4 definitions and instances. Upgrade Studio, applications, Functions, servers, CLI processes, and MCP servers first. Then change every deployment acknowledgement to expectedMinReaderModel: 4.

// sanity.workflow.ts
{
  expectedMinReaderModel: 4,
  // workflowResource, definitions, ...
}

Follow Reader-model rollout.

Replace start.allowed with ordered start.requirements. Replace activity requirement records with ordered GROQ requirement arrays. Use singleSubject for one unfinished run of the same definition per subject.

start: {
  requirements: [
    {type: 'singleSubject', name: 'one-open-run'},
    {type: 'groq', name: 'ready', query: '$fields.ready == true'},
  ],
}

See Start conditions.

$actor.id, user assignees, and $assigned now use the account-global sanityUserId. The same user therefore matches across projects, datasets, Canvas, and Media Library.

On project datasets, guard predicates compare the project-local value returned by identity(). The engine localizes projected actor and assignee metadata automatically, so guard authors do not translate IDs.

Existing live identity values resolve through the project directory and converge on their next engine commit. Audit history remains unchanged.

The Studio plugin now requires Sanity 6.3 or later.

See Install the packages.

list_workflow_instances now returns one page with has_more and next_cursor. Keep the same filters and continue until has_more is false.

See The tools.

useProjectMembers(projectId) returns the ProjectMembersState used by the shared member and assignee controls. AssigneePicker is controlled through onChange(nextValue).

See Edit project-member assignments.

resetActivity reruns or skips a terminal activity in the current stage, then continues the cascade. The CLI exposes the same operation as reset-activity.

See Recover a terminal activity.

The Workflows tool can confirm a local subject is still deleted before aborting its orphaned workflow instances.

See Workflows tool.

A parent now reacts after every child created by one spawn commit has settled, rather than observing a partially settled cohort.

The 0.20 release aligns the public Workflows packages as one runtime stack and updates Studio integration.

Install every @sanity/workflow-* package used by one application at the same version. Shared runtime packages are now exact-version peer dependencies, so dependencies previously installed transitively must be installed explicitly.

npm install @sanity/workflow-engine@0.20.0 @sanity/workflow-react@0.20.0 @sanity/workflow-sdk@0.20.0

pnpm add @sanity/workflow-engine@0.20.0 @sanity/workflow-react@0.20.0 @sanity/workflow-sdk@0.20.0

yarn add @sanity/workflow-engine@0.20.0 @sanity/workflow-react@0.20.0 @sanity/workflow-sdk@0.20.0

bun add @sanity/workflow-engine@0.20.0 @sanity/workflow-react@0.20.0 @sanity/workflow-sdk@0.20.0

See Versions and breaking changes.

Call workflowDefaultDocumentNode() without mapping arguments.

See Add the plugin to your config.

Move autoStart onto each applicable mapping row.

See Start a workflow automatically.

Remove mappings used only for workflow discovery. Keep a mapping when it customizes a discovered workflow or binds a definition that uses doc.ref instead of a subject field.

See Discover workflows from subjects.

Remove WorkflowStagePreview and the _id projection added solely for workflow badges.

See See where your work stands.

The Studio plugin discovers deployed workflows whose caller-provided subject accepts a document type in the current Studio schema. Multiple workflows may target the same document type.

See Add the plugin to your config.

Documents with active workflows display their current stage in supported Studio previews.

Interactive commands ask which deployment to use when configuration is ambiguous. Non-interactive commands still require --deployment or --tag.

See Select a deployment, a tag, or an instance.

Engine 0.19 adds new runtime capabilities.

Deployment name is now the unique CLI identity. Rename any deployment whose name is duplicated or contains anything other than lowercase letters, digits, or dashes.

A tag may group deployments across resources. Each (workflowResource, tag) pair remains unique. Use --deployment <name> for one deployment. Use --tag <tag> for a tag group. See A deployment has two identities.

# Target one deployment by name
npx sanity-workflows deploy --deployment review-prod

# Target every deployment in a tag group
npx sanity-workflows deploy --tag prod

# Target one deployment by name
pnpm dlx sanity-workflows deploy --deployment review-prod

# Target every deployment in a tag group
pnpm dlx sanity-workflows deploy --tag prod

# Target one deployment by name
yarn dlx sanity-workflows deploy --deployment review-prod

# Target every deployment in a tag group
yarn dlx sanity-workflows deploy --tag prod

# Target one deployment by name
bunx sanity-workflows deploy --deployment review-prod

# Target every deployment in a tag group
bunx sanity-workflows deploy --tag prod

The new progress field requires engine 0.19 readers. Follow Reader-model acknowledgement before deploying it. Existing workflow data needs no migration. Keep expectedMinReaderModel: 2.

// sanity.workflow.ts
{
  name: 'production',
  expectedMinReaderModel: 2,
  // workflowResource, definitions, ...
}

// Direct engine deployment
await engine.deployDefinitions({
  expectedMinReaderModel: 2,
  definitions,
})

Use a progress field to store completion from 0 to 100.

See Fields.

Call ctx.setProgress(...) to update a progress field while an effect handler runs.

See the working handler example.

Call ctx.commitOps(...) to commit field operations while an effect handler runs.

See the working handler example.

Action evaluation can preview whether an action exits the current stage.

The preview identifies the selected transition.

See Activities and actions.

Upgrade every reader before deploying definitions with this release. Readers include Studio, applications, Functions, MCP servers, and CLI processes. Then add expectedMinReaderModel: 2 to every workflow deployment configuration and every direct deployDefinitions() call. Keep the value literal. Follow the reader-first rollout before changing it.

// sanity.workflow.ts
{
  name: 'production',
  expectedMinReaderModel: 2,
  // workflowResource, definitions, ...
}

// Direct engine deployment
await engine.deployDefinitions({
  expectedMinReaderModel: 2,
  definitions,
})

subject is now a field kind. Replace the former required doc.ref subject convention with one workflow-scoped subject field. Without this migration, an existing definition can still run but no longer appears in document pickers or satisfies subject-based start rules when redeployed. See Fields.

Audit start inputs and spawn mappings. Unknown, wrong-kind, non-input, self-filled, and duplicate initial fields now fail instead of being silently discarded.

Studio can automatically start configured workflows when an editor opens a fresh document. Configure autoStart by document type; see Turn on auto-start for fresh documents.

Definitions can use first-class subject fields, typed scalar choice lists, inclusive string/text/number validation bounds, and decision semantics on actions. Effect handlers preserve concrete Sanity client APIs, including Agent Actions. Studio v6, reusable workflow controls, shared project-user resolution, and the redesigned Workflows tool are also included.

Move permission expressions from start.filter to start.allowed. filter now controls browse-time visibility and cannot read $fields; allowed is enforced when an instance starts.

Treat a caller-supplied instanceId as the idempotency key. Retrying the same start resumes it; do not reuse the ID for a different definition or version.

Fix newly rejected definition traps before redeploying, including invalid workflow or guard names, unbound $row reads, out-of-scope spawn reads, and invalid static field paths.

Programmatic starts gain an enforced allowed gate and resumable retries. The dedicated Workflows tool, causal autonomy analysis, runtime persisted-document validation, resource-surface checks for supplied references, and the tag-scoped CLI nuke command are included.

Move every operation, effect, and spawn payload onto an action. Triggered actions are now the only payload mechanism; remove payloads attached directly to transitions or other structure.

Definitions that can be started directly must use the start block. Review start filters against the new start context before redeploying.

Definitions gain explicit start configuration and triggered actions. CLI, MCP, and condition descriptions use one filter vocabulary, while the test bench more closely mirrors guarded engine behavior.