Workflows release notes

Curated overviews of recent Workflows prerelease package waves.

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 Workflows dataset, 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 Set up the workflow CLI.

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 Work from a document.

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 Set up the MCP server.

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 Set up the Studio plugin.

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 the prerelease 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 Set up the Studio plugin.

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 Delete one terminal instance.

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 Choose an administrative stage override.

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 Automate read commands.

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 Pick what a command touches.

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 Configure auto-start.

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 Current stage in previews.

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 Pick what a command touches.

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 Deployment names and tags.

# 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 Automatically start workflows.

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.