@sanity/workflow-mcp 0.9.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @sanity/workflow-mcp
 
+## 0.20.0
+
+### Minor Changes
+
+- e860898: **BREAKING:** Published Editorial Workflows packages now ship as one fixed release stack and require exact-version peers for every shared runtime package. Install the matching stack so the engine, reactive core, adapters, tools, and UI cannot silently load private or version-skewed copies.
+
+### Patch Changes
+
+- Updated dependencies [bce09fc]
+- Updated dependencies [efb4cd9]
+- Updated dependencies [46b0285]
+- Updated dependencies [ab5e454]
+- Updated dependencies [8a76c67]
+- Updated dependencies [e3122cc]
+- Updated dependencies [7e8f459]
+- Updated dependencies [98e488e]
+- Updated dependencies [7c4dd86]
+  - @sanity/workflow-engine@0.20.0
+
+## 0.9.1
+
+### Patch Changes
+
+- 24b11dd: Surface the `progress` field kind: a progress field's pill wears its value as a tweened background fill with a whole-number percent caption in a reserved-width slot (at-a-glance progress that never resizes as it ticks), the tweened `ProgressBar` (from `@sanity/workflow-components`) renders on every field-value display surface — pill popovers, field rows, the activity dialog — and edits go through native 0–100 number inputs honoring declared validation bounds; the MCP authoring guide documents the kind.
+- Updated dependencies [24b11dd]
+- Updated dependencies [2005ab7]
+- Updated dependencies [24b11dd]
+- Updated dependencies [59b40fd]
+  - @sanity/workflow-engine@0.19.0
+
 ## 0.9.0
 
 ### Minor Changes

package/dist/_chunks-es/index.js

@@ -657,7 +657,7 @@ const instanceIdField = z.string().min(1).describe("The workflow instance id."),
         title: "Approved",
         description: "Terminal — no transitions out."
     } ]
-}, ORIENTATION = "# Authoring a workflow definition\n\nA workflow definition is a plain JSON object. There is no code in it — every\ncondition (triggers, filters, predicates, guards) is a GROQ *string*. Generate\nthe JSON, then call `validate_workflow_definition` (it takes a `definitions`\narray — validate a parent and its child workflows together) to check it; fix\nthe reported errors and re-validate until it returns `valid: true`. Each\n`results` entry pairs with your input and carries the *desugared* definition\nunder `definition` — that is exactly what would deploy.\n\n## Shape\n\n- **Workflow**: `{ name, title, description?, initialStage, fields?, stages[], predicates? }`.\n  `name` must match `^[a-z0-9][a-z0-9-]*$` (lowercase + digits + dashes — it\n  interpolates into every deployed document id, so spaces, uppercase, dots,\n  and underscores are rejected). `initialStage` must be the `name` of a\n  declared stage. Do NOT include a `version` — definitions are immutable and\n  content-addressed; deploy assigns the version from the content, the author\n  never writes one.\n- **Stage**: `{ name, title?, description?, activities?, transitions? }`. A stage with\n  no transitions is terminal. Reaching a terminal stage ends the workflow.\n- **Activity**: `{ name, title?, filter?, actions?, fields? }` — a unit of work\n  that carries NO payload of its own; everything that DOES anything lives on\n  its actions. Every in-scope activity is **active from the moment its stage\n  is entered** (there is no activation step) and stays active until an action\n  resolves it `done`/`skipped`/`failed`. `filter` is existence, evaluated\n  once at stage entry: a definite `false` skips the activity for this visit.\n- **Action**: `{ name, title?, when?, status?, params?, ops? }` — actions are\n  the ONLY payload mechanism. Two firing modes:\n    - **No `when`** — invoked by a caller (a person or agent calling\n      `fire_action`).\n    - **With `when`** — CASCADE-FIRED: the engine fires it on its own the\n      moment the GROQ trigger is true (at most once per stage visit), and no\n      caller can ever invoke it. Fires-on-entry work is `when: 'true'`.\n  `status: 'done' | 'skipped' | 'failed'` is sugar that resolves the *firing\n  activity* to that status when the action fires. Status is a health axis, not\n  a decision: a routine decision (reject, send back, decline, hold) resolves\n  `'done'` and writes the decision into a field the transition triggers read —\n  reserve `'failed'` for work that genuinely could not complete (e.g. a missed\n  deadline via `{name: 'deadline', when: '$now > $fields.dueBy', status: 'failed'}`).\n  `ops` are mutations applied when the action fires (e.g.\n  `{type:'field.set', target:{field:'x'}, value:{type:'param', param:'p'}}`).\n  `params` are values a caller-fired action collects from the caller\n  (referenced by `{type:'param', param:'<name>'}` sources); a `when` action\n  has no caller, so `params` is rejected there. Scalar params may constrain\n  callers to titled choices with\n  `options:{list:[{title:'Approve', value:'approve'}]}`, and string/text or\n  number params may declare inclusive `validation:{min,max}` bounds.\n- **Transition**: `{ name, title?, to, when? }` — a pure edge; transitions\n  carry no ops or effects (only actions do). `to` must name a declared stage.\n  `when` is the GROQ trigger gating the exit; omit it and it defaults to\n  `$allActivitiesDone`. The first transition whose `when` is true (in\n  declaration order) fires.\n- **Field** (workflow- or stage-scoped persistent state): `{ type, name, title?, initialValue?, options?, validation? }`.\n  Scalar `type`s mirror Sanity: `string`, `text` (multiline), `number`,\n  `boolean`, `date` (YYYY-MM-DD), `datetime` (ISO), `url`. Plus references\n  (`doc.ref`, `doc.refs`, `release.ref`, and `subject` — a single `doc.ref`\n  elevated to name THE document the workflow is about; workflow scope only, at\n  most one, and what document pickers match against), identities (`actor` — one\n  concrete principal; `assignee` / `assignees` — one or many user-or-role\n  assignees), and\n  the compositional kinds `object` (`{ type:'object', name, fields: [...] }`) and\n  `array` (`{ type:'array', name, of: [...] }`) — `fields`/`of` are themselves\n  field shapes, so any structure composes. `initialValue` seeds the field once at\n  materialisation and is **optional** — omit it for op-filled working memory\n  (the common default). Arms: `{type:'input'}` (the caller supplies it when the\n  instance starts), `{type:'query', query:'<groq>'}` (computed from the lake),\n  `{type:'literal', value:<json>}`, or `{type:'fieldRead', field:'<name>'}`.\n  String/text, number, URL, date, and datetime fields may declare a non-empty\n  `options.list` of `{title, value}` choices. Values must match the field kind,\n  be unique, and every non-null runtime value must be listed. The same syntax\n  works on nested field shapes, effect outputs, and action params (where datetime\n  is spelled `dateTime`).\n  String/text and number declarations may also use inclusive\n  `validation:{min,max}` bounds. String/text bounds measure character length\n  and must be non-negative integers; number bounds measure the numeric value.\n  Choices must satisfy any bounds. The same syntax works on nested field shapes,\n  effect outputs, and action params.\n  A workflow about a document declares an `input`-sourced `subject` entry — the\n  runtime and every surface identify the subject by that kind.\n  Two list sugars desugar to `array`: `{type:'todoList', name}` (ad-hoc\n  status-tracked work — rows `{ label, status, assignee?, dueDate? }`) and\n  `{type:'notes', name}` (an append-only audit/comment log — rows\n  `{ body, actor, at }`; pairs with the `audit` op, which stamps `actor`/`at`).\n\n## GROQ in conditions\n\nBuilt-in variables available in triggers/filters/predicates (the engine's\nexported `CONDITION_VARS` inventory is the source of truth):\n`$allActivitiesDone`, `$anyActivityFailed` (booleans over the current stage's\nactivities), `$activities` (the activity list), `$fields` (field values),\n`$context` (the start-time context bag — values seeded when the instance\nstarted; written once, never mutated), `$now`,\n`$self`/`$stage`/`$parent`/`$ancestors` (instance identity + position),\n`$effectStatus` (effect name → `'done'`/`'failed'` of the run queued during\nthe CURRENT stage entry — the re-entry-safe way to gate on an effect having\ndrained, e.g. a trigger action\n`{name: 'settled', when: \"defined($effectStatus['my.effect'])\", status: 'done'}`),\nand the caller-scoped vars `$actor` (the acting user), `$assigned` (whether\nthe caller is the activity's assignee — the idiomatic permission gate, used as\nan action `filter: '$assigned'`), and `$can`. `$actor`/`$assigned`/`$can`\nbelong in **caller-fired action filters only**. The cascade is deliberately\ncaller-blind: transition `when`s, activity `filter`s, and a cascade-fired\naction's `when`/`filter` re-evaluate on every trigger (another editor's\naction, an effect draining, a tick) and must resolve the same way regardless\nof whose token that is, so deploy rejects `$actor`/`$assigned`/`$can`/`$params`\nthere — route on instance state an action wrote instead. `$params` (the firing\naction's args) is not usable in **any** filter — action filters included: a\nfilter decides whether the action is enabled before the caller supplies args,\nso deploy rejects it there too. Collect caller input with the action's\n`params` and consume it in the action's `ops` (a `{type:'param'}` value).\n(Identity still gates every move: the commit rides the caller's token, and the\nlake's ACL accepts or rejects the write wholesale.) Define reusable named\nconditions under top-level `predicates: { name: '<groq>' }` and reference\nthem as `$name` (e.g.\n`predicates: { ready: \"count($activities[status != 'done']) == 0\" }` → `$ready`).\n\nConditions evaluate against an in-memory snapshot (the instance + its subject +\nfield-declared docs) — **never** scan by `_type` (e.g. `*[_type==\"article\"]`);\nthat is a discovery query and the validator rejects it. To bring a document into\nscope, declare a `doc.ref` field for it.\n\n`$fields.<name>` must name a declared field entry visible at the reading\nsite: workflow fields everywhere, plus the enclosing stage's fields at that\nstage's sites, plus the enclosing activity's fields inside that activity.\nTransition triggers cannot see activity fields — put a decision a transition\nroutes on at stage scope (Example 2). A read's dot-path must also fit the\nentry's declared value shape — reference envelopes especially: a\n`release.ref` value carries `id`/`type`/`releaseName` (never `_id`), a\n`doc.refs` element `id`/`type`. The validator rejects reads of\nundeclared names, condition dot-paths that don't fit the declared shape,\nstages no transition path reaches, and `fieldRead` value sources whose\ntarget entry or dot-path doesn't resolve.\n\n## Sugars worth knowing\n\n- Action `status: 'done' | 'skipped' | 'failed'` — resolves the firing activity (shown above).\n- Omitted transition `when` — defaults to `$allActivitiesDone`.\n- Action `roles: ['editor', ...]` — on a caller-fired action, folds a\n  role-membership check into its `filter`.\n\n## Modeling defaults\n\nValid is not the same as good. Prefer these unless the request says otherwise:\n\n- **A decline/reject loops back.** Route a rejected / changes-requested\n  transition to an *earlier* stage for revision (e.g. `review → drafting` gated\n  on a `decision` field the reject action wrote), not to a terminal stage.\n  Reserve terminal stages for completion and for explicit\n  cancellation/abandonment — a workflow should not dead-end just because\n  something was declined.\n- **Decisions are fields, not failures.** When a stage branches on a human\n  decision, declare a stage-scoped `string` field (stage scope resets on\n  re-entry, so loop-backs start clean), have each deciding action `field.set`\n  it, and gate every outbound transition on its value (Example 2). Do not\n  encode a decision as `status: 'failed'` + `$anyActivityFailed` — reporting\n  would count healthy loops as failures.\n- **Prefer draft → review.** Model an author working in a drafting stage who\n  submits, then a review stage that gates. Don't add more review stages unless\n  the request asks for multiple approvers or rounds.\n- **When the shape is ambiguous, pick the conventional one and confirm** with the\n  user rather than inventing extra stages.\n\n## Rules the validator enforces\n\n- Stage names, activity names (per stage) and transition names are unique.\n- Every transition `to` and `initialStage` names a declared stage.\n- Every activity must have a path to a terminal status — some action in the\n  stage (its own, or a sibling's via a `status.set` op) resolves it\n  `done`/`skipped`/`failed`; an activity nothing can ever resolve is rejected.\n- A terminal stage (no transitions) declares no activities — entering it\n  completes the instance, so they could never run.\n- Custom `predicates` must not shadow a built-in (e.g. `allActivitiesDone`).\n- Every GROQ string must parse and must not be a `_type` discovery scan.", AUTHORING_GUIDE = `${ORIENTATION}\n\n## Examples\n\n### Example 1 — ${minimalExample.title} (minimal: one stage, one action)\n\`\`\`json\n${JSON.stringify(minimalExample, null, 2)}\n\`\`\`\n\n### Example 2 — ${reviewLoopExample.title} (review loop: reject routes back)\n\`\`\`json\n${JSON.stringify(reviewLoopExample, null, 2)}\n\`\`\`\n`, getWorkflowAuthoringGuideTool = defineWorkflowTool({
+}, ORIENTATION = "# Authoring a workflow definition\n\nA workflow definition is a plain JSON object. There is no code in it — every\ncondition (triggers, filters, predicates, guards) is a GROQ *string*. Generate\nthe JSON, then call `validate_workflow_definition` (it takes a `definitions`\narray — validate a parent and its child workflows together) to check it; fix\nthe reported errors and re-validate until it returns `valid: true`. Each\n`results` entry pairs with your input and carries the *desugared* definition\nunder `definition` — that is exactly what would deploy.\n\n## Shape\n\n- **Workflow**: `{ name, title, description?, initialStage, fields?, stages[], predicates? }`.\n  `name` must match `^[a-z0-9][a-z0-9-]*$` (lowercase + digits + dashes — it\n  interpolates into every deployed document id, so spaces, uppercase, dots,\n  and underscores are rejected). `initialStage` must be the `name` of a\n  declared stage. Do NOT include a `version` — definitions are immutable and\n  content-addressed; deploy assigns the version from the content, the author\n  never writes one.\n- **Stage**: `{ name, title?, description?, activities?, transitions? }`. A stage with\n  no transitions is terminal. Reaching a terminal stage ends the workflow.\n- **Activity**: `{ name, title?, filter?, actions?, fields? }` — a unit of work\n  that carries NO payload of its own; everything that DOES anything lives on\n  its actions. Every in-scope activity is **active from the moment its stage\n  is entered** (there is no activation step) and stays active until an action\n  resolves it `done`/`skipped`/`failed`. `filter` is existence, evaluated\n  once at stage entry: a definite `false` skips the activity for this visit.\n- **Action**: `{ name, title?, when?, status?, params?, ops? }` — actions are\n  the ONLY payload mechanism. Two firing modes:\n    - **No `when`** — invoked by a caller (a person or agent calling\n      `fire_action`).\n    - **With `when`** — CASCADE-FIRED: the engine fires it on its own the\n      moment the GROQ trigger is true (at most once per stage visit), and no\n      caller can ever invoke it. Fires-on-entry work is `when: 'true'`.\n  `status: 'done' | 'skipped' | 'failed'` is sugar that resolves the *firing\n  activity* to that status when the action fires. Status is a health axis, not\n  a decision: a routine decision (reject, send back, decline, hold) resolves\n  `'done'` and writes the decision into a field the transition triggers read —\n  reserve `'failed'` for work that genuinely could not complete (e.g. a missed\n  deadline via `{name: 'deadline', when: '$now > $fields.dueBy', status: 'failed'}`).\n  `ops` are mutations applied when the action fires (e.g.\n  `{type:'field.set', target:{field:'x'}, value:{type:'param', param:'p'}}`).\n  `params` are values a caller-fired action collects from the caller\n  (referenced by `{type:'param', param:'<name>'}` sources); a `when` action\n  has no caller, so `params` is rejected there. Scalar params may constrain\n  callers to titled choices with\n  `options:{list:[{title:'Approve', value:'approve'}]}`, and string/text or\n  number params may declare inclusive `validation:{min,max}` bounds.\n- **Transition**: `{ name, title?, to, when? }` — a pure edge; transitions\n  carry no ops or effects (only actions do). `to` must name a declared stage.\n  `when` is the GROQ trigger gating the exit; omit it and it defaults to\n  `$allActivitiesDone`. The first transition whose `when` is true (in\n  declaration order) fires.\n- **Field** (workflow- or stage-scoped persistent state): `{ type, name, title?, initialValue?, options?, validation? }`.\n  Scalar `type`s mirror Sanity: `string`, `text` (multiline), `number`,\n  `progress` (a number elevated to mean 0–100 completion; always finite and\n  within 0–100 inclusive, fractions allowed), `boolean`, `date` (YYYY-MM-DD),\n  `datetime` (ISO), `url`. Plus references\n  (`doc.ref`, `doc.refs`, `release.ref`, and `subject` — a single `doc.ref`\n  elevated to name THE document the workflow is about; workflow scope only, at\n  most one, and what document pickers match against), identities (`actor` — one\n  concrete principal; `assignee` / `assignees` — one or many user-or-role\n  assignees), and\n  the compositional kinds `object` (`{ type:'object', name, fields: [...] }`) and\n  `array` (`{ type:'array', name, of: [...] }`) — `fields`/`of` are themselves\n  field shapes, so any structure composes. `initialValue` seeds the field once at\n  materialisation and is **optional** — omit it for op-filled working memory\n  (the common default). Arms: `{type:'input'}` (the caller supplies it when the\n  instance starts), `{type:'query', query:'<groq>'}` (computed from the lake),\n  `{type:'literal', value:<json>}`, or `{type:'fieldRead', field:'<name>'}`.\n  String/text, number, URL, date, and datetime fields may declare a non-empty\n  `options.list` of `{title, value}` choices. Values must match the field kind,\n  be unique, and every non-null runtime value must be listed. The same syntax\n  works on nested field shapes, effect outputs, and action params (where datetime\n  is spelled `dateTime`).\n  String/text, number, and progress declarations may also use inclusive\n  `validation:{min,max}` bounds. String/text bounds measure character length\n  and must be non-negative integers; number bounds measure the numeric value;\n  progress bounds may only narrow the kind's intrinsic 0–100 (each declared\n  bound must itself sit within 0–100). Choices must satisfy any bounds. The\n  same syntax works on nested field shapes, effect outputs, and action params.\n  A workflow about a document declares an `input`-sourced `subject` entry — the\n  runtime and every surface identify the subject by that kind.\n  Two list sugars desugar to `array`: `{type:'todoList', name}` (ad-hoc\n  status-tracked work — rows `{ label, status, assignee?, dueDate? }`) and\n  `{type:'notes', name}` (an append-only audit/comment log — rows\n  `{ body, actor, at }`; pairs with the `audit` op, which stamps `actor`/`at`).\n\n## GROQ in conditions\n\nBuilt-in variables available in triggers/filters/predicates (the engine's\nexported `CONDITION_VARS` inventory is the source of truth):\n`$allActivitiesDone`, `$anyActivityFailed` (booleans over the current stage's\nactivities), `$activities` (the activity list), `$fields` (field values),\n`$context` (the start-time context bag — values seeded when the instance\nstarted; written once, never mutated), `$now`,\n`$self`/`$stage`/`$parent`/`$ancestors` (instance identity + position),\n`$effectStatus` (effect name → `'done'`/`'failed'` of the run queued during\nthe CURRENT stage entry — the re-entry-safe way to gate on an effect having\ndrained, e.g. a trigger action\n`{name: 'settled', when: \"defined($effectStatus['my.effect'])\", status: 'done'}`),\nand the caller-scoped vars `$actor` (the acting user), `$assigned` (whether\nthe caller is the activity's assignee — the idiomatic permission gate, used as\nan action `filter: '$assigned'`), and `$can`. `$actor`/`$assigned`/`$can`\nbelong in **caller-fired action filters only**. The cascade is deliberately\ncaller-blind: transition `when`s, activity `filter`s, and a cascade-fired\naction's `when`/`filter` re-evaluate on every trigger (another editor's\naction, an effect draining, a tick) and must resolve the same way regardless\nof whose token that is, so deploy rejects `$actor`/`$assigned`/`$can`/`$params`\nthere — route on instance state an action wrote instead. `$params` (the firing\naction's args) is not usable in **any** filter — action filters included: a\nfilter decides whether the action is enabled before the caller supplies args,\nso deploy rejects it there too. Collect caller input with the action's\n`params` and consume it in the action's `ops` (a `{type:'param'}` value).\n(Identity still gates every move: the commit rides the caller's token, and the\nlake's ACL accepts or rejects the write wholesale.) Define reusable named\nconditions under top-level `predicates: { name: '<groq>' }` and reference\nthem as `$name` (e.g.\n`predicates: { ready: \"count($activities[status != 'done']) == 0\" }` → `$ready`).\n\nConditions evaluate against an in-memory snapshot (the instance + its subject +\nfield-declared docs) — **never** scan by `_type` (e.g. `*[_type==\"article\"]`);\nthat is a discovery query and the validator rejects it. To bring a document into\nscope, declare a `doc.ref` field for it.\n\n`$fields.<name>` must name a declared field entry visible at the reading\nsite: workflow fields everywhere, plus the enclosing stage's fields at that\nstage's sites, plus the enclosing activity's fields inside that activity.\nTransition triggers cannot see activity fields — put a decision a transition\nroutes on at stage scope (Example 2). A read's dot-path must also fit the\nentry's declared value shape — reference envelopes especially: a\n`release.ref` value carries `id`/`type`/`releaseName` (never `_id`), a\n`doc.refs` element `id`/`type`. The validator rejects reads of\nundeclared names, condition dot-paths that don't fit the declared shape,\nstages no transition path reaches, and `fieldRead` value sources whose\ntarget entry or dot-path doesn't resolve.\n\n## Sugars worth knowing\n\n- Action `status: 'done' | 'skipped' | 'failed'` — resolves the firing activity (shown above).\n- Omitted transition `when` — defaults to `$allActivitiesDone`.\n- Action `roles: ['editor', ...]` — on a caller-fired action, folds a\n  role-membership check into its `filter`.\n\n## Modeling defaults\n\nValid is not the same as good. Prefer these unless the request says otherwise:\n\n- **A decline/reject loops back.** Route a rejected / changes-requested\n  transition to an *earlier* stage for revision (e.g. `review → drafting` gated\n  on a `decision` field the reject action wrote), not to a terminal stage.\n  Reserve terminal stages for completion and for explicit\n  cancellation/abandonment — a workflow should not dead-end just because\n  something was declined.\n- **Decisions are fields, not failures.** When a stage branches on a human\n  decision, declare a stage-scoped `string` field (stage scope resets on\n  re-entry, so loop-backs start clean), have each deciding action `field.set`\n  it, and gate every outbound transition on its value (Example 2). Do not\n  encode a decision as `status: 'failed'` + `$anyActivityFailed` — reporting\n  would count healthy loops as failures.\n- **Prefer draft → review.** Model an author working in a drafting stage who\n  submits, then a review stage that gates. Don't add more review stages unless\n  the request asks for multiple approvers or rounds.\n- **When the shape is ambiguous, pick the conventional one and confirm** with the\n  user rather than inventing extra stages.\n\n## Rules the validator enforces\n\n- Stage names, activity names (per stage) and transition names are unique.\n- Every transition `to` and `initialStage` names a declared stage.\n- Every activity must have a path to a terminal status — some action in the\n  stage (its own, or a sibling's via a `status.set` op) resolves it\n  `done`/`skipped`/`failed`; an activity nothing can ever resolve is rejected.\n- A terminal stage (no transitions) declares no activities — entering it\n  completes the instance, so they could never run.\n- Custom `predicates` must not shadow a built-in (e.g. `allActivitiesDone`).\n- Every GROQ string must parse and must not be a `_type` discovery scan.", AUTHORING_GUIDE = `${ORIENTATION}\n\n## Examples\n\n### Example 1 — ${minimalExample.title} (minimal: one stage, one action)\n\`\`\`json\n${JSON.stringify(minimalExample, null, 2)}\n\`\`\`\n\n### Example 2 — ${reviewLoopExample.title} (review loop: reject routes back)\n\`\`\`json\n${JSON.stringify(reviewLoopExample, null, 2)}\n\`\`\`\n`, getWorkflowAuthoringGuideTool = defineWorkflowTool({
     name: "get_workflow_authoring_guide",
     description: "Get the guide for authoring a workflow definition: the DSL shape, the GROQ condition built-ins, the sugars, the rules the validator enforces, and two worked JSON examples. Call this BEFORE writing a definition from a description, then generate the JSON and check it with validate_workflow_definition. Pure read; takes no arguments.",
     inputSchema: {},

package/dist/index.cjs

@@ -640,7 +640,7 @@ const instanceIdField = zod.z.string().min(1).describe("The workflow instance id
         title: "Approved",
         description: "Terminal — no transitions out."
     } ]
-}, ORIENTATION = "# Authoring a workflow definition\n\nA workflow definition is a plain JSON object. There is no code in it — every\ncondition (triggers, filters, predicates, guards) is a GROQ *string*. Generate\nthe JSON, then call `validate_workflow_definition` (it takes a `definitions`\narray — validate a parent and its child workflows together) to check it; fix\nthe reported errors and re-validate until it returns `valid: true`. Each\n`results` entry pairs with your input and carries the *desugared* definition\nunder `definition` — that is exactly what would deploy.\n\n## Shape\n\n- **Workflow**: `{ name, title, description?, initialStage, fields?, stages[], predicates? }`.\n  `name` must match `^[a-z0-9][a-z0-9-]*$` (lowercase + digits + dashes — it\n  interpolates into every deployed document id, so spaces, uppercase, dots,\n  and underscores are rejected). `initialStage` must be the `name` of a\n  declared stage. Do NOT include a `version` — definitions are immutable and\n  content-addressed; deploy assigns the version from the content, the author\n  never writes one.\n- **Stage**: `{ name, title?, description?, activities?, transitions? }`. A stage with\n  no transitions is terminal. Reaching a terminal stage ends the workflow.\n- **Activity**: `{ name, title?, filter?, actions?, fields? }` — a unit of work\n  that carries NO payload of its own; everything that DOES anything lives on\n  its actions. Every in-scope activity is **active from the moment its stage\n  is entered** (there is no activation step) and stays active until an action\n  resolves it `done`/`skipped`/`failed`. `filter` is existence, evaluated\n  once at stage entry: a definite `false` skips the activity for this visit.\n- **Action**: `{ name, title?, when?, status?, params?, ops? }` — actions are\n  the ONLY payload mechanism. Two firing modes:\n    - **No `when`** — invoked by a caller (a person or agent calling\n      `fire_action`).\n    - **With `when`** — CASCADE-FIRED: the engine fires it on its own the\n      moment the GROQ trigger is true (at most once per stage visit), and no\n      caller can ever invoke it. Fires-on-entry work is `when: 'true'`.\n  `status: 'done' | 'skipped' | 'failed'` is sugar that resolves the *firing\n  activity* to that status when the action fires. Status is a health axis, not\n  a decision: a routine decision (reject, send back, decline, hold) resolves\n  `'done'` and writes the decision into a field the transition triggers read —\n  reserve `'failed'` for work that genuinely could not complete (e.g. a missed\n  deadline via `{name: 'deadline', when: '$now > $fields.dueBy', status: 'failed'}`).\n  `ops` are mutations applied when the action fires (e.g.\n  `{type:'field.set', target:{field:'x'}, value:{type:'param', param:'p'}}`).\n  `params` are values a caller-fired action collects from the caller\n  (referenced by `{type:'param', param:'<name>'}` sources); a `when` action\n  has no caller, so `params` is rejected there. Scalar params may constrain\n  callers to titled choices with\n  `options:{list:[{title:'Approve', value:'approve'}]}`, and string/text or\n  number params may declare inclusive `validation:{min,max}` bounds.\n- **Transition**: `{ name, title?, to, when? }` — a pure edge; transitions\n  carry no ops or effects (only actions do). `to` must name a declared stage.\n  `when` is the GROQ trigger gating the exit; omit it and it defaults to\n  `$allActivitiesDone`. The first transition whose `when` is true (in\n  declaration order) fires.\n- **Field** (workflow- or stage-scoped persistent state): `{ type, name, title?, initialValue?, options?, validation? }`.\n  Scalar `type`s mirror Sanity: `string`, `text` (multiline), `number`,\n  `boolean`, `date` (YYYY-MM-DD), `datetime` (ISO), `url`. Plus references\n  (`doc.ref`, `doc.refs`, `release.ref`, and `subject` — a single `doc.ref`\n  elevated to name THE document the workflow is about; workflow scope only, at\n  most one, and what document pickers match against), identities (`actor` — one\n  concrete principal; `assignee` / `assignees` — one or many user-or-role\n  assignees), and\n  the compositional kinds `object` (`{ type:'object', name, fields: [...] }`) and\n  `array` (`{ type:'array', name, of: [...] }`) — `fields`/`of` are themselves\n  field shapes, so any structure composes. `initialValue` seeds the field once at\n  materialisation and is **optional** — omit it for op-filled working memory\n  (the common default). Arms: `{type:'input'}` (the caller supplies it when the\n  instance starts), `{type:'query', query:'<groq>'}` (computed from the lake),\n  `{type:'literal', value:<json>}`, or `{type:'fieldRead', field:'<name>'}`.\n  String/text, number, URL, date, and datetime fields may declare a non-empty\n  `options.list` of `{title, value}` choices. Values must match the field kind,\n  be unique, and every non-null runtime value must be listed. The same syntax\n  works on nested field shapes, effect outputs, and action params (where datetime\n  is spelled `dateTime`).\n  String/text and number declarations may also use inclusive\n  `validation:{min,max}` bounds. String/text bounds measure character length\n  and must be non-negative integers; number bounds measure the numeric value.\n  Choices must satisfy any bounds. The same syntax works on nested field shapes,\n  effect outputs, and action params.\n  A workflow about a document declares an `input`-sourced `subject` entry — the\n  runtime and every surface identify the subject by that kind.\n  Two list sugars desugar to `array`: `{type:'todoList', name}` (ad-hoc\n  status-tracked work — rows `{ label, status, assignee?, dueDate? }`) and\n  `{type:'notes', name}` (an append-only audit/comment log — rows\n  `{ body, actor, at }`; pairs with the `audit` op, which stamps `actor`/`at`).\n\n## GROQ in conditions\n\nBuilt-in variables available in triggers/filters/predicates (the engine's\nexported `CONDITION_VARS` inventory is the source of truth):\n`$allActivitiesDone`, `$anyActivityFailed` (booleans over the current stage's\nactivities), `$activities` (the activity list), `$fields` (field values),\n`$context` (the start-time context bag — values seeded when the instance\nstarted; written once, never mutated), `$now`,\n`$self`/`$stage`/`$parent`/`$ancestors` (instance identity + position),\n`$effectStatus` (effect name → `'done'`/`'failed'` of the run queued during\nthe CURRENT stage entry — the re-entry-safe way to gate on an effect having\ndrained, e.g. a trigger action\n`{name: 'settled', when: \"defined($effectStatus['my.effect'])\", status: 'done'}`),\nand the caller-scoped vars `$actor` (the acting user), `$assigned` (whether\nthe caller is the activity's assignee — the idiomatic permission gate, used as\nan action `filter: '$assigned'`), and `$can`. `$actor`/`$assigned`/`$can`\nbelong in **caller-fired action filters only**. The cascade is deliberately\ncaller-blind: transition `when`s, activity `filter`s, and a cascade-fired\naction's `when`/`filter` re-evaluate on every trigger (another editor's\naction, an effect draining, a tick) and must resolve the same way regardless\nof whose token that is, so deploy rejects `$actor`/`$assigned`/`$can`/`$params`\nthere — route on instance state an action wrote instead. `$params` (the firing\naction's args) is not usable in **any** filter — action filters included: a\nfilter decides whether the action is enabled before the caller supplies args,\nso deploy rejects it there too. Collect caller input with the action's\n`params` and consume it in the action's `ops` (a `{type:'param'}` value).\n(Identity still gates every move: the commit rides the caller's token, and the\nlake's ACL accepts or rejects the write wholesale.) Define reusable named\nconditions under top-level `predicates: { name: '<groq>' }` and reference\nthem as `$name` (e.g.\n`predicates: { ready: \"count($activities[status != 'done']) == 0\" }` → `$ready`).\n\nConditions evaluate against an in-memory snapshot (the instance + its subject +\nfield-declared docs) — **never** scan by `_type` (e.g. `*[_type==\"article\"]`);\nthat is a discovery query and the validator rejects it. To bring a document into\nscope, declare a `doc.ref` field for it.\n\n`$fields.<name>` must name a declared field entry visible at the reading\nsite: workflow fields everywhere, plus the enclosing stage's fields at that\nstage's sites, plus the enclosing activity's fields inside that activity.\nTransition triggers cannot see activity fields — put a decision a transition\nroutes on at stage scope (Example 2). A read's dot-path must also fit the\nentry's declared value shape — reference envelopes especially: a\n`release.ref` value carries `id`/`type`/`releaseName` (never `_id`), a\n`doc.refs` element `id`/`type`. The validator rejects reads of\nundeclared names, condition dot-paths that don't fit the declared shape,\nstages no transition path reaches, and `fieldRead` value sources whose\ntarget entry or dot-path doesn't resolve.\n\n## Sugars worth knowing\n\n- Action `status: 'done' | 'skipped' | 'failed'` — resolves the firing activity (shown above).\n- Omitted transition `when` — defaults to `$allActivitiesDone`.\n- Action `roles: ['editor', ...]` — on a caller-fired action, folds a\n  role-membership check into its `filter`.\n\n## Modeling defaults\n\nValid is not the same as good. Prefer these unless the request says otherwise:\n\n- **A decline/reject loops back.** Route a rejected / changes-requested\n  transition to an *earlier* stage for revision (e.g. `review → drafting` gated\n  on a `decision` field the reject action wrote), not to a terminal stage.\n  Reserve terminal stages for completion and for explicit\n  cancellation/abandonment — a workflow should not dead-end just because\n  something was declined.\n- **Decisions are fields, not failures.** When a stage branches on a human\n  decision, declare a stage-scoped `string` field (stage scope resets on\n  re-entry, so loop-backs start clean), have each deciding action `field.set`\n  it, and gate every outbound transition on its value (Example 2). Do not\n  encode a decision as `status: 'failed'` + `$anyActivityFailed` — reporting\n  would count healthy loops as failures.\n- **Prefer draft → review.** Model an author working in a drafting stage who\n  submits, then a review stage that gates. Don't add more review stages unless\n  the request asks for multiple approvers or rounds.\n- **When the shape is ambiguous, pick the conventional one and confirm** with the\n  user rather than inventing extra stages.\n\n## Rules the validator enforces\n\n- Stage names, activity names (per stage) and transition names are unique.\n- Every transition `to` and `initialStage` names a declared stage.\n- Every activity must have a path to a terminal status — some action in the\n  stage (its own, or a sibling's via a `status.set` op) resolves it\n  `done`/`skipped`/`failed`; an activity nothing can ever resolve is rejected.\n- A terminal stage (no transitions) declares no activities — entering it\n  completes the instance, so they could never run.\n- Custom `predicates` must not shadow a built-in (e.g. `allActivitiesDone`).\n- Every GROQ string must parse and must not be a `_type` discovery scan.", AUTHORING_GUIDE = `${ORIENTATION}\n\n## Examples\n\n### Example 1 — ${minimalExample.title} (minimal: one stage, one action)\n\`\`\`json\n${JSON.stringify(minimalExample, null, 2)}\n\`\`\`\n\n### Example 2 — ${reviewLoopExample.title} (review loop: reject routes back)\n\`\`\`json\n${JSON.stringify(reviewLoopExample, null, 2)}\n\`\`\`\n`, getWorkflowAuthoringGuideTool = defineWorkflowTool({
+}, ORIENTATION = "# Authoring a workflow definition\n\nA workflow definition is a plain JSON object. There is no code in it — every\ncondition (triggers, filters, predicates, guards) is a GROQ *string*. Generate\nthe JSON, then call `validate_workflow_definition` (it takes a `definitions`\narray — validate a parent and its child workflows together) to check it; fix\nthe reported errors and re-validate until it returns `valid: true`. Each\n`results` entry pairs with your input and carries the *desugared* definition\nunder `definition` — that is exactly what would deploy.\n\n## Shape\n\n- **Workflow**: `{ name, title, description?, initialStage, fields?, stages[], predicates? }`.\n  `name` must match `^[a-z0-9][a-z0-9-]*$` (lowercase + digits + dashes — it\n  interpolates into every deployed document id, so spaces, uppercase, dots,\n  and underscores are rejected). `initialStage` must be the `name` of a\n  declared stage. Do NOT include a `version` — definitions are immutable and\n  content-addressed; deploy assigns the version from the content, the author\n  never writes one.\n- **Stage**: `{ name, title?, description?, activities?, transitions? }`. A stage with\n  no transitions is terminal. Reaching a terminal stage ends the workflow.\n- **Activity**: `{ name, title?, filter?, actions?, fields? }` — a unit of work\n  that carries NO payload of its own; everything that DOES anything lives on\n  its actions. Every in-scope activity is **active from the moment its stage\n  is entered** (there is no activation step) and stays active until an action\n  resolves it `done`/`skipped`/`failed`. `filter` is existence, evaluated\n  once at stage entry: a definite `false` skips the activity for this visit.\n- **Action**: `{ name, title?, when?, status?, params?, ops? }` — actions are\n  the ONLY payload mechanism. Two firing modes:\n    - **No `when`** — invoked by a caller (a person or agent calling\n      `fire_action`).\n    - **With `when`** — CASCADE-FIRED: the engine fires it on its own the\n      moment the GROQ trigger is true (at most once per stage visit), and no\n      caller can ever invoke it. Fires-on-entry work is `when: 'true'`.\n  `status: 'done' | 'skipped' | 'failed'` is sugar that resolves the *firing\n  activity* to that status when the action fires. Status is a health axis, not\n  a decision: a routine decision (reject, send back, decline, hold) resolves\n  `'done'` and writes the decision into a field the transition triggers read —\n  reserve `'failed'` for work that genuinely could not complete (e.g. a missed\n  deadline via `{name: 'deadline', when: '$now > $fields.dueBy', status: 'failed'}`).\n  `ops` are mutations applied when the action fires (e.g.\n  `{type:'field.set', target:{field:'x'}, value:{type:'param', param:'p'}}`).\n  `params` are values a caller-fired action collects from the caller\n  (referenced by `{type:'param', param:'<name>'}` sources); a `when` action\n  has no caller, so `params` is rejected there. Scalar params may constrain\n  callers to titled choices with\n  `options:{list:[{title:'Approve', value:'approve'}]}`, and string/text or\n  number params may declare inclusive `validation:{min,max}` bounds.\n- **Transition**: `{ name, title?, to, when? }` — a pure edge; transitions\n  carry no ops or effects (only actions do). `to` must name a declared stage.\n  `when` is the GROQ trigger gating the exit; omit it and it defaults to\n  `$allActivitiesDone`. The first transition whose `when` is true (in\n  declaration order) fires.\n- **Field** (workflow- or stage-scoped persistent state): `{ type, name, title?, initialValue?, options?, validation? }`.\n  Scalar `type`s mirror Sanity: `string`, `text` (multiline), `number`,\n  `progress` (a number elevated to mean 0–100 completion; always finite and\n  within 0–100 inclusive, fractions allowed), `boolean`, `date` (YYYY-MM-DD),\n  `datetime` (ISO), `url`. Plus references\n  (`doc.ref`, `doc.refs`, `release.ref`, and `subject` — a single `doc.ref`\n  elevated to name THE document the workflow is about; workflow scope only, at\n  most one, and what document pickers match against), identities (`actor` — one\n  concrete principal; `assignee` / `assignees` — one or many user-or-role\n  assignees), and\n  the compositional kinds `object` (`{ type:'object', name, fields: [...] }`) and\n  `array` (`{ type:'array', name, of: [...] }`) — `fields`/`of` are themselves\n  field shapes, so any structure composes. `initialValue` seeds the field once at\n  materialisation and is **optional** — omit it for op-filled working memory\n  (the common default). Arms: `{type:'input'}` (the caller supplies it when the\n  instance starts), `{type:'query', query:'<groq>'}` (computed from the lake),\n  `{type:'literal', value:<json>}`, or `{type:'fieldRead', field:'<name>'}`.\n  String/text, number, URL, date, and datetime fields may declare a non-empty\n  `options.list` of `{title, value}` choices. Values must match the field kind,\n  be unique, and every non-null runtime value must be listed. The same syntax\n  works on nested field shapes, effect outputs, and action params (where datetime\n  is spelled `dateTime`).\n  String/text, number, and progress declarations may also use inclusive\n  `validation:{min,max}` bounds. String/text bounds measure character length\n  and must be non-negative integers; number bounds measure the numeric value;\n  progress bounds may only narrow the kind's intrinsic 0–100 (each declared\n  bound must itself sit within 0–100). Choices must satisfy any bounds. The\n  same syntax works on nested field shapes, effect outputs, and action params.\n  A workflow about a document declares an `input`-sourced `subject` entry — the\n  runtime and every surface identify the subject by that kind.\n  Two list sugars desugar to `array`: `{type:'todoList', name}` (ad-hoc\n  status-tracked work — rows `{ label, status, assignee?, dueDate? }`) and\n  `{type:'notes', name}` (an append-only audit/comment log — rows\n  `{ body, actor, at }`; pairs with the `audit` op, which stamps `actor`/`at`).\n\n## GROQ in conditions\n\nBuilt-in variables available in triggers/filters/predicates (the engine's\nexported `CONDITION_VARS` inventory is the source of truth):\n`$allActivitiesDone`, `$anyActivityFailed` (booleans over the current stage's\nactivities), `$activities` (the activity list), `$fields` (field values),\n`$context` (the start-time context bag — values seeded when the instance\nstarted; written once, never mutated), `$now`,\n`$self`/`$stage`/`$parent`/`$ancestors` (instance identity + position),\n`$effectStatus` (effect name → `'done'`/`'failed'` of the run queued during\nthe CURRENT stage entry — the re-entry-safe way to gate on an effect having\ndrained, e.g. a trigger action\n`{name: 'settled', when: \"defined($effectStatus['my.effect'])\", status: 'done'}`),\nand the caller-scoped vars `$actor` (the acting user), `$assigned` (whether\nthe caller is the activity's assignee — the idiomatic permission gate, used as\nan action `filter: '$assigned'`), and `$can`. `$actor`/`$assigned`/`$can`\nbelong in **caller-fired action filters only**. The cascade is deliberately\ncaller-blind: transition `when`s, activity `filter`s, and a cascade-fired\naction's `when`/`filter` re-evaluate on every trigger (another editor's\naction, an effect draining, a tick) and must resolve the same way regardless\nof whose token that is, so deploy rejects `$actor`/`$assigned`/`$can`/`$params`\nthere — route on instance state an action wrote instead. `$params` (the firing\naction's args) is not usable in **any** filter — action filters included: a\nfilter decides whether the action is enabled before the caller supplies args,\nso deploy rejects it there too. Collect caller input with the action's\n`params` and consume it in the action's `ops` (a `{type:'param'}` value).\n(Identity still gates every move: the commit rides the caller's token, and the\nlake's ACL accepts or rejects the write wholesale.) Define reusable named\nconditions under top-level `predicates: { name: '<groq>' }` and reference\nthem as `$name` (e.g.\n`predicates: { ready: \"count($activities[status != 'done']) == 0\" }` → `$ready`).\n\nConditions evaluate against an in-memory snapshot (the instance + its subject +\nfield-declared docs) — **never** scan by `_type` (e.g. `*[_type==\"article\"]`);\nthat is a discovery query and the validator rejects it. To bring a document into\nscope, declare a `doc.ref` field for it.\n\n`$fields.<name>` must name a declared field entry visible at the reading\nsite: workflow fields everywhere, plus the enclosing stage's fields at that\nstage's sites, plus the enclosing activity's fields inside that activity.\nTransition triggers cannot see activity fields — put a decision a transition\nroutes on at stage scope (Example 2). A read's dot-path must also fit the\nentry's declared value shape — reference envelopes especially: a\n`release.ref` value carries `id`/`type`/`releaseName` (never `_id`), a\n`doc.refs` element `id`/`type`. The validator rejects reads of\nundeclared names, condition dot-paths that don't fit the declared shape,\nstages no transition path reaches, and `fieldRead` value sources whose\ntarget entry or dot-path doesn't resolve.\n\n## Sugars worth knowing\n\n- Action `status: 'done' | 'skipped' | 'failed'` — resolves the firing activity (shown above).\n- Omitted transition `when` — defaults to `$allActivitiesDone`.\n- Action `roles: ['editor', ...]` — on a caller-fired action, folds a\n  role-membership check into its `filter`.\n\n## Modeling defaults\n\nValid is not the same as good. Prefer these unless the request says otherwise:\n\n- **A decline/reject loops back.** Route a rejected / changes-requested\n  transition to an *earlier* stage for revision (e.g. `review → drafting` gated\n  on a `decision` field the reject action wrote), not to a terminal stage.\n  Reserve terminal stages for completion and for explicit\n  cancellation/abandonment — a workflow should not dead-end just because\n  something was declined.\n- **Decisions are fields, not failures.** When a stage branches on a human\n  decision, declare a stage-scoped `string` field (stage scope resets on\n  re-entry, so loop-backs start clean), have each deciding action `field.set`\n  it, and gate every outbound transition on its value (Example 2). Do not\n  encode a decision as `status: 'failed'` + `$anyActivityFailed` — reporting\n  would count healthy loops as failures.\n- **Prefer draft → review.** Model an author working in a drafting stage who\n  submits, then a review stage that gates. Don't add more review stages unless\n  the request asks for multiple approvers or rounds.\n- **When the shape is ambiguous, pick the conventional one and confirm** with the\n  user rather than inventing extra stages.\n\n## Rules the validator enforces\n\n- Stage names, activity names (per stage) and transition names are unique.\n- Every transition `to` and `initialStage` names a declared stage.\n- Every activity must have a path to a terminal status — some action in the\n  stage (its own, or a sibling's via a `status.set` op) resolves it\n  `done`/`skipped`/`failed`; an activity nothing can ever resolve is rejected.\n- A terminal stage (no transitions) declares no activities — entering it\n  completes the instance, so they could never run.\n- Custom `predicates` must not shadow a built-in (e.g. `allActivitiesDone`).\n- Every GROQ string must parse and must not be a `_type` discovery scan.", AUTHORING_GUIDE = `${ORIENTATION}\n\n## Examples\n\n### Example 1 — ${minimalExample.title} (minimal: one stage, one action)\n\`\`\`json\n${JSON.stringify(minimalExample, null, 2)}\n\`\`\`\n\n### Example 2 — ${reviewLoopExample.title} (review loop: reject routes back)\n\`\`\`json\n${JSON.stringify(reviewLoopExample, null, 2)}\n\`\`\`\n`, getWorkflowAuthoringGuideTool = defineWorkflowTool({
     name: "get_workflow_authoring_guide",
     description: "Get the guide for authoring a workflow definition: the DSL shape, the GROQ condition built-ins, the sugars, the rules the validator enforces, and two worked JSON examples. Call this BEFORE writing a definition from a description, then generate the JSON and check it with validate_workflow_definition. Pure read; takes no arguments.",
     inputSchema: {},

package/dist/stdio.js

@@ -8,7 +8,7 @@ import { registerWorkflowTools, workflowAddressFromInput, createMcpTelemetry } f
 
 import { createClient } from "@sanity/client";
 
-var version = "0.9.0", packageJson = {
+var version = "0.20.0", packageJson = {
     version: version
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/workflow-mcp",
-  "version": "0.9.0",
+  "version": "0.20.0",
   "description": "MCP server exposing Sanity workflow tools to agents — operate running workflow instances and author new definitions.",
   "keywords": [
     "agent",
@@ -55,15 +55,18 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@sanity/client": "^7.22.1",
     "@sanity/telemetry": "^1.1.0",
-    "zod": "^4.4.3",
-    "@sanity/workflow-engine": "0.18.0"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@sanity/pkg-utils": "^10.5.2",
     "@types/node": "^24.12.4",
     "vitest": "^4.1.8",
-    "@sanity/workflow-engine-test": "0.13.0",
-    "@sanity/workflow-examples": "0.8.0"
+    "@sanity/workflow-engine": "0.20.0",
+    "@sanity/workflow-engine-test": "0.20.0",
+    "@sanity/workflow-examples": "0.9.0"
+  },
+  "peerDependencies": {
+    "@sanity/workflow-engine": "0.20.0"
   },
   "engines": {
     "node": ">=20"