@sanity/workflow-mcp 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @sanity/workflow-mcp
 
+## 0.8.0
+
+### Minor Changes
+
+- f9389e5: `get_workflow_state` (and `fire_action`'s shared state projection) now carries the causal-autonomy insight: per activity a `completesWithoutCaller` verdict (`yes`/`no`/`conditional`) with narrated `waitsOn` lines when not `yes`, and a workflow-level `autonomy` one-liner ("this workflow runs itself except at …").
+- e3a7ba2: `start_workflow` gains `instance_id` — for retries: the id is the start's idempotency key, so an agent retrying a start that errored can pass the same id and resume it instead of minting a duplicate instance. A start whose first auto-advance fails after the instance was created and primed no longer surfaces as a failed tool call — the run exists, so the tool returns its projected state with a `startNotSettled` caveat naming the cause and the retry id. A start that fails before priming (`StartNotPrimedError`) stays a failed call, its message naming the `instance_id` to retry with (or `abort_workflow` to discard).
+- 5a1a9fe: Direct reads of engine-owned documents adopt the data-model gate (`assertReadableModel`): the CLI's instance and definition reads (`show`, `tail`, `list`, `definition show`, `definition list`, deploy lookups, the share read-back) and the MCP tools that interpret rows from the ungated `engine.query` escape hatch (`list_workflow_definitions`, `list_workflow_instances`, the definition lookup behind `start_workflow` / `get_workflow_definition`). A document written by a newer engine data model now fails with the governed "upgrade `@sanity/workflow-engine`" error instead of rendering unchecked; list projections carry the stamp pair so projected rows gate too.
+
+### Patch Changes
+
+- 30fed9e: The authoring guide states the definition-name grammar (`^[a-z0-9][a-z0-9-]*$`) and the condition dot-path shape rule (reference envelopes carry `id`/`type`/…, never `_id`), matching the engine's deploy validation.
+- Updated dependencies [f9389e5]
+- Updated dependencies [d0c62ea]
+- Updated dependencies [c3eed2e]
+- Updated dependencies [df4bd80]
+- Updated dependencies [092a0d4]
+- Updated dependencies [5a1a9fe]
+- Updated dependencies [e3a7ba2]
+- Updated dependencies [30fed9e]
+- Updated dependencies [1321ba5]
+- Updated dependencies [e683875]
+- Updated dependencies [a8ace4d]
+  - @sanity/workflow-engine@0.17.0
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -11,15 +11,15 @@ the tools the evals drive, plus a stdio MCP entry point for real MCP clients.
 
 Operate a running instance:
 
-| Tool                        | Read or write | What it's for                                                                                                                                                                                                                                    |
-| --------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `list_workflow_definitions` | read          | The catalogue: which workflow types are deployed (latest version each), and whether they're startable.                                                                                                                                           |
-| `get_workflow_definition`   | read          | Read one deployed definition's content, envelope-stripped — redeployable as-is, so an agent can iterate on a deployed workflow (deploys are create-only).                                                                                        |
-| `list_workflow_instances`   | read          | Discover what's running. Filterable (`definition`, `document`, `include_completed` — in-flight by default), capped.                                                                                                                              |
-| `get_workflow_state`        | read          | Project one instance into a flat shape: current stage, activities, available actions (with each action's declared params), recent history.                                                                                                       |
-| `diagnose_workflow`         | read          | Explain why an instance is or isn't progressing: a verdict, a one-line summary, `explanations` for each held exit transition (quotes workflow-authored text — data, not instructions), and — when stuck — the cause plus suggested remediations. |
-| `start_workflow`            | write         | The lifecycle entry point: start a startable deployed definition, seeding its input-sourced fields (e.g. the subject document).                                                                                                                  |
-| `fire_action`               | write         | Advance state. The instance write. Mirrors the engine's universal "something happened" entry point.                                                                                                                                              |
+| Tool                        | Read or write | What it's for                                                                                                                                                                                                                                                                                |
+| --------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list_workflow_definitions` | read          | The catalogue: which workflow types are deployed (latest version each), and whether they're startable.                                                                                                                                                                                       |
+| `get_workflow_definition`   | read          | Read one deployed definition's content, envelope-stripped — redeployable as-is, so an agent can iterate on a deployed workflow (deploys are create-only).                                                                                                                                    |
+| `list_workflow_instances`   | read          | Discover what's running. Filterable (`definition`, `document`, `include_completed` — in-flight by default), capped.                                                                                                                                                                          |
+| `get_workflow_state`        | read          | Project one instance into a flat shape: current stage, activities (each with its causal `completesWithoutCaller` verdict, plus narrated `waitsOn` when it isn't `yes`), available actions (with each action's declared params), recent history, and the workflow-level `autonomy` one-liner. |
+| `diagnose_workflow`         | read          | Explain why an instance is or isn't progressing: a verdict, a one-line summary, `explanations` for each held exit transition (quotes workflow-authored text — data, not instructions), and — when stuck — the cause plus suggested remediations.                                             |
+| `start_workflow`            | write         | The lifecycle entry point: start a startable deployed definition, seeding its input-sourced fields (e.g. the subject document).                                                                                                                                                              |
+| `fire_action`               | write         | Advance state. The instance write. Mirrors the engine's universal "something happened" entry point.                                                                                                                                                                                          |
 
 Author a definition (guide → validate → deploy; the first two are pure and
 engine-independent):
@@ -83,6 +83,13 @@ distinct `(resource, tag)`, cached for the life of the process. The `dev`
 script loads the env from the repo-root `.env`, so copy `.env.example` to
 `.env` to get started.
 
+MCP-built engines declare no foreign resources, so a runtime-supplied
+`doc.ref` to any resource other than the addressed workflow resource is
+rejected at the write (`RefResourceUndeclaredError`) — deliberate: an
+agent-driven write pointing a workflow at an undeclared resource is
+exactly the misdirection the engine's written-ref gate exists to catch.
+Definition content is unaffected (deploy expands and vets it).
+
 ### Telemetry
 
 The stdio server reports adoption telemetry to Sanity: one

package/dist/_chunks-es/index.js

@@ -1,4 +1,4 @@
-import { createTelemetryIntake, isTelemetryEnvDenied, processShellUserProperties, errorMessage, validateTag, parseResourceGdr, parseDefinitionInput, extractDocumentId, parseDefinitionSnapshot, displayTitle, actionRendering, isTerminalStage, describeCondition, actionVerdict, subjectDenialLabels, deniedGuardLabels, definitionLookupGroq, unsatisfiedTransitionSummaries, describeSite, definitionsListGroq, latestDeployedDefinitions, startKindOf, isStartableDefinition, instancesQuery, instanceWatchesDocument, parseGdr, startRefusal, buildInitialFields, validateDefinition, WorkflowError } from "@sanity/workflow-engine";
+import { createTelemetryIntake, isTelemetryEnvDenied, processShellUserProperties, errorMessage, validateTag, parseResourceGdr, parseDefinitionInput, extractDocumentId, parseDefinitionSnapshot, displayTitle, autonomySummary, actionRendering, isTerminalStage, describeCondition, actionVerdict, narrateAutonomyWaits, subjectDenialLabels, deniedGuardLabels, definitionLookupGroq, assertReadableModel, unsatisfiedTransitionSummaries, describeSite, definitionsListGroq, latestDeployedDefinitions, startKindOf, isStartableDefinition, instancesQuery, instanceWatchesDocument, parseGdr, startRefusal, buildInitialFields, StartNotPrimedError, StartNotSettledError, validateDefinition, WorkflowError } from "@sanity/workflow-engine";
 
 import { defineEvent, createBatchedStore, createSessionId } from "@sanity/telemetry";
 
@@ -211,6 +211,9 @@ function projectState({instance: instance, evaluation: evaluation, subjectTitles
             subject: subject
         } : {},
         activities: activities,
+        autonomy: autonomySummary(evaluation.autonomy, {
+            definition: definition
+        }).text,
         recentHistory: recentHistory
     };
 }
@@ -235,6 +238,7 @@ function projectActivity(te, definition) {
         } : {},
         status: te.status,
         classification: te.classification,
+        ...autonomyFields(te, definition),
         actions: actions,
         ...automations.length > 0 ? {
             automations: automations
@@ -242,6 +246,22 @@ function projectActivity(te, definition) {
     };
 }
 
+function autonomyFields(te, definition) {
+    const {completesWithoutCaller: completesWithoutCaller} = te.autonomy;
+    if (completesWithoutCaller === "yes") return {
+        completesWithoutCaller: completesWithoutCaller
+    };
+    const waitsOn = narrateAutonomyWaits(te.autonomy.waitsOn, {
+        definition: definition
+    });
+    return {
+        completesWithoutCaller: completesWithoutCaller,
+        ...waitsOn.length > 0 ? {
+            waitsOn: waitsOn
+        } : {}
+    };
+}
+
 function automationWhen(ae) {
     const when = ae.action.when;
     if (when === void 0) throw new Error(`action "${ae.action.name}" verdicts as automation but declares no \`when\` — the evaluation and the pinned definition disagree`);
@@ -308,7 +328,7 @@ async function fetchDeployedDefinition({engine: engine, definition: definition,
         const label = version !== void 0 ? ` v${version}` : "";
         throw new Error(`no deployed definition "${definition}"${label} in this workflow environment — list_workflow_definitions shows what is deployed`);
     }
-    return deployed;
+    return assertReadableModel(deployed);
 }
 
 function isInstanceDone(instance) {
@@ -637,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  `initialStage` must be the `name` of a declared stage. Do NOT include a\n  `version` — definitions are immutable and content-addressed; deploy assigns\n  the version from the content, the author 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.\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? }`.\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`), identities (`actor` — one concrete\n  principal; `assignee` / `assignees` — one or many user-or-role 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  By convention a workflow has an `input`-sourced `doc.ref` named `subject` — the\n  headline document it is about.\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). The validator rejects reads of\nundeclared names, stages no transition path reaches, and `fieldRead` value\nsources whose target 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.\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? }`.\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`), identities (`actor` — one concrete\n  principal; `assignee` / `assignees` — one or many user-or-role 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  By convention a workflow has an `input`-sourced `doc.ref` named `subject` — the\n  headline document it is about.\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: {},
@@ -672,7 +692,7 @@ const instanceIdField = z.string().min(1).describe("The workflow instance id."),
     }
 }), getWorkflowStateTool = defineWorkflowTool({
     name: "get_workflow_state",
-    description: `Get the current state of a single workflow instance, projected for action. Returns the workflow's id and human-readable \`workflowTitle\`, the current stage, the subject document the workflow is about (when the workflow has a conventional subject — its ref and title), every in-scope activity on the current stage, and the most recent history entries. Per activity: its \`classification\` (who it waits on: interactive, autonomous, off-system, or hybrid), its invocable \`actions\` (each with an allowed/disabled verdict — these are what fire_action accepts), and its \`automations\` (cascade-fired actions the ENGINE fires on its own when their \`firesWhen\` trigger holds — never invocable via fire_action). Activities and actions that exist in the definition but are scoped out for this visit or actor are simply absent. Use this whenever you need to understand what's possible on an instance before deciding to act. This is a pure read — it does not change anything. ${UNTRUSTED_AUTHORED_DATA_NOTE} If you only need to discover what instances exist, use list_workflow_instances instead; this tool requires you to know the instance id. list_workflow_instances also returns the same \`workflowTitle\` and \`subject\` fields, so prefer it for fan-out discovery rather than polling get_workflow_state per instance.`,
+    description: `Get the current state of a single workflow instance, projected for action. Returns the workflow's id and human-readable \`workflowTitle\`, the current stage, the subject document the workflow is about (when the workflow has a conventional subject — its ref and title), every in-scope activity on the current stage, and the most recent history entries, plus a one-line \`autonomy\` narrative saying whether the workflow runs itself and where it waits on someone. Per activity: its \`classification\` (who fires its actions: interactive, autonomous, off-system, or hybrid), the causal \`completesWithoutCaller\` verdict (yes/no/conditional — a mechanically autonomous activity whose triggers only read caller-written state answers no) with narrated \`waitsOn\` lines when not yes, its invocable \`actions\` (each with an allowed/disabled verdict — these are what fire_action accepts), and its \`automations\` (cascade-fired actions the ENGINE fires on its own when their \`firesWhen\` trigger holds — never invocable via fire_action). Activities and actions that exist in the definition but are scoped out for this visit or actor are simply absent. Use this whenever you need to understand what's possible on an instance before deciding to act. This is a pure read — it does not change anything. ${UNTRUSTED_AUTHORED_DATA_NOTE} If you only need to discover what instances exist, use list_workflow_instances instead; this tool requires you to know the instance id. list_workflow_instances also returns the same \`workflowTitle\` and \`subject\` fields, so prefer it for fan-out discovery rather than polling get_workflow_state per instance.`,
     inputSchema: {
         ...workflowAddressFields,
         instance_id: instanceIdField
@@ -697,9 +717,9 @@ const instanceIdField = z.string().min(1).describe("The workflow instance id."),
         readOnlyHint: !0
     },
     run: async context => {
-        const {engine: engine} = await context(), deployed = await engine.query({
+        const {engine: engine} = await context(), deployed = (await engine.query({
             groq: definitionsListGroq("desc")
-        });
+        })).map(assertReadableModel);
         return {
             definitions: latestDeployedDefinitions(deployed).map(def => ({
                 name: def.name,
@@ -737,22 +757,55 @@ const instanceIdField = z.string().min(1).describe("The workflow instance id."),
         }, {query: query, params: params} = instancesQuery({
             tag: engine.tag,
             filter: filter
-        }), recency = `${query} | order(lastChangedAt desc)`, docs = await engine.query({
+        }), recency = `${query} | order(lastChangedAt desc)`, docs = (await engine.query({
             groq: document === void 0 ? `${recency}[0...${LIST_CAP}]` : recency,
             params: params
-        }), capped = (document === void 0 ? docs : docs.filter(doc => instanceWatchesDocument(doc, document))).slice(0, LIST_CAP), subjectTitles = await fetchSubjectTitles(engine, capped);
+        })).map(assertReadableModel), capped = (document === void 0 ? docs : docs.filter(doc => instanceWatchesDocument(doc, document))).slice(0, LIST_CAP), subjectTitles = await fetchSubjectTitles(engine, capped);
         return {
             instances: capped.map(doc => projectSummary(doc, subjectTitles))
         };
     }
-}), startWorkflowTool = defineWorkflowTool({
+});
+
+async function startResolvingRetries(args) {
+    const {engine: engine, input: input, initialFields: initialFields} = args;
+    try {
+        const {instance: instance} = await engine.startInstance({
+            definition: input.definition,
+            ...input.version !== void 0 ? {
+                version: input.version
+            } : {},
+            ...initialFields.length > 0 ? {
+                initialFields: initialFields
+            } : {},
+            ...input.instance_id !== void 0 ? {
+                instanceId: input.instance_id
+            } : {}
+        });
+        return {
+            instanceId: instance._id
+        };
+    } catch (err) {
+        if (err instanceof StartNotPrimedError) throw new Error(`${errorMessage(err)} Retry start_workflow with instance_id "${err.instanceId}" to resume, or abort_workflow to discard it.`, {
+            cause: err
+        });
+        if (!(err instanceof StartNotSettledError)) throw err;
+        return {
+            instanceId: err.instanceId,
+            startNotSettled: `The workflow started (created and primed) but its first auto-advance failed: ${errorMessage(err.cause)}. It settles on the next engine tick, or retry start_workflow with instance_id "${err.instanceId}".`
+        };
+    }
+}
+
+const startWorkflowTool = defineWorkflowTool({
     name: "start_workflow",
     description: "Start a new workflow instance from a deployed definition — the lifecycle entry point. Use list_workflow_definitions first: `startable: true` marks what this tool can start (child workflows are spawn-only — a parent workflow's activity creates them, never this tool). Supply values for the workflow's input-sourced fields via `initial_fields` — e.g. the subject document the workflow is about. Returns the started instance, same shape as get_workflow_state; the engine's cascade (triggers and transitions) has already run, so it may land past the initial stage. Do NOT use this to advance an existing instance — that is fire_action. " + UNTRUSTED_AUTHORED_DATA_NOTE,
     inputSchema: {
         ...workflowAddressFields,
         definition: z.string().min(1).describe("The workflow definition `name` to start (as listed by list_workflow_definitions)."),
         version: z.number().int().min(1).describe("Optional. The deployed definition version to start from. Defaults to the highest.").optional(),
-        initial_fields: z.record(z.string(), z.unknown()).describe('Optional. Values for the workflow\'s input-sourced field entries, keyed by field name (e.g. {"subject": {"id": "dataset:proj:ds:article-1", "type": "article"}}). doc.ref values take an object with a GDR `id` and doc `type`. get_workflow_definition shows a workflow\'s declared fields; only input-sourced entries accept a value here.').optional()
+        initial_fields: z.record(z.string(), z.unknown()).describe('Optional. Values for the workflow\'s input-sourced field entries, keyed by field name (e.g. {"subject": {"id": "dataset:proj:ds:article-1", "type": "article"}}). doc.ref values take an object with a GDR `id` and doc `type`. get_workflow_definition shows a workflow\'s declared fields; only input-sourced entries accept a value here.').optional(),
+        instance_id: z.string().min(1).describe("Optional. Start under this instance id — for retries. The id is the start's idempotency key: pass the SAME id when retrying a start that errored and the engine resumes that start instead of creating a duplicate instance (an already-settled start replays as a no-op). A failed start names the id to retry with in its error message. Omit to mint a fresh id.").optional()
     },
     annotations: {
         readOnlyHint: !1,
@@ -771,19 +824,18 @@ const instanceIdField = z.string().min(1).describe("The workflow instance id."),
         const initialFields = buildInitialFields({
             declared: deployed.fields ?? [],
             values: input.initial_fields ?? {}
-        }), {instance: instance} = await engine.startInstance({
-            definition: input.definition,
-            ...input.version !== void 0 ? {
-                version: input.version
-            } : {},
-            ...initialFields.length > 0 ? {
-                initialFields: initialFields
-            } : {}
-        });
-        return getInstanceState({
+        }), {instanceId: instanceId, startNotSettled: startNotSettled} = await startResolvingRetries({
             engine: engine,
-            instanceId: instance._id
+            input: input,
+            initialFields: initialFields
+        }), state = await getInstanceState({
+            engine: engine,
+            instanceId: instanceId
         });
+        return startNotSettled !== void 0 ? {
+            ...state,
+            startNotSettled: startNotSettled
+        } : state;
     }
 }), validateWorkflowDefinitionTool = defineWorkflowTool({
     name: "validate_workflow_definition",

package/dist/index.cjs

@@ -194,6 +194,9 @@ function projectState({instance: instance, evaluation: evaluation, subjectTitles
             subject: subject
         } : {},
         activities: activities,
+        autonomy: workflowEngine.autonomySummary(evaluation.autonomy, {
+            definition: definition
+        }).text,
         recentHistory: recentHistory
     };
 }
@@ -218,6 +221,7 @@ function projectActivity(te, definition) {
         } : {},
         status: te.status,
         classification: te.classification,
+        ...autonomyFields(te, definition),
         actions: actions,
         ...automations.length > 0 ? {
             automations: automations
@@ -225,6 +229,22 @@ function projectActivity(te, definition) {
     };
 }
 
+function autonomyFields(te, definition) {
+    const {completesWithoutCaller: completesWithoutCaller} = te.autonomy;
+    if (completesWithoutCaller === "yes") return {
+        completesWithoutCaller: completesWithoutCaller
+    };
+    const waitsOn = workflowEngine.narrateAutonomyWaits(te.autonomy.waitsOn, {
+        definition: definition
+    });
+    return {
+        completesWithoutCaller: completesWithoutCaller,
+        ...waitsOn.length > 0 ? {
+            waitsOn: waitsOn
+        } : {}
+    };
+}
+
 function automationWhen(ae) {
     const when = ae.action.when;
     if (when === void 0) throw new Error(`action "${ae.action.name}" verdicts as automation but declares no \`when\` — the evaluation and the pinned definition disagree`);
@@ -291,7 +311,7 @@ async function fetchDeployedDefinition({engine: engine, definition: definition,
         const label = version !== void 0 ? ` v${version}` : "";
         throw new Error(`no deployed definition "${definition}"${label} in this workflow environment — list_workflow_definitions shows what is deployed`);
     }
-    return deployed;
+    return workflowEngine.assertReadableModel(deployed);
 }
 
 function isInstanceDone(instance) {
@@ -620,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  `initialStage` must be the `name` of a declared stage. Do NOT include a\n  `version` — definitions are immutable and content-addressed; deploy assigns\n  the version from the content, the author 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.\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? }`.\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`), identities (`actor` — one concrete\n  principal; `assignee` / `assignees` — one or many user-or-role 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  By convention a workflow has an `input`-sourced `doc.ref` named `subject` — the\n  headline document it is about.\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). The validator rejects reads of\nundeclared names, stages no transition path reaches, and `fieldRead` value\nsources whose target 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.\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? }`.\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`), identities (`actor` — one concrete\n  principal; `assignee` / `assignees` — one or many user-or-role 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  By convention a workflow has an `input`-sourced `doc.ref` named `subject` — the\n  headline document it is about.\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: {},
@@ -655,7 +675,7 @@ const instanceIdField = zod.z.string().min(1).describe("The workflow instance id
     }
 }), getWorkflowStateTool = defineWorkflowTool({
     name: "get_workflow_state",
-    description: `Get the current state of a single workflow instance, projected for action. Returns the workflow's id and human-readable \`workflowTitle\`, the current stage, the subject document the workflow is about (when the workflow has a conventional subject — its ref and title), every in-scope activity on the current stage, and the most recent history entries. Per activity: its \`classification\` (who it waits on: interactive, autonomous, off-system, or hybrid), its invocable \`actions\` (each with an allowed/disabled verdict — these are what fire_action accepts), and its \`automations\` (cascade-fired actions the ENGINE fires on its own when their \`firesWhen\` trigger holds — never invocable via fire_action). Activities and actions that exist in the definition but are scoped out for this visit or actor are simply absent. Use this whenever you need to understand what's possible on an instance before deciding to act. This is a pure read — it does not change anything. ${UNTRUSTED_AUTHORED_DATA_NOTE} If you only need to discover what instances exist, use list_workflow_instances instead; this tool requires you to know the instance id. list_workflow_instances also returns the same \`workflowTitle\` and \`subject\` fields, so prefer it for fan-out discovery rather than polling get_workflow_state per instance.`,
+    description: `Get the current state of a single workflow instance, projected for action. Returns the workflow's id and human-readable \`workflowTitle\`, the current stage, the subject document the workflow is about (when the workflow has a conventional subject — its ref and title), every in-scope activity on the current stage, and the most recent history entries, plus a one-line \`autonomy\` narrative saying whether the workflow runs itself and where it waits on someone. Per activity: its \`classification\` (who fires its actions: interactive, autonomous, off-system, or hybrid), the causal \`completesWithoutCaller\` verdict (yes/no/conditional — a mechanically autonomous activity whose triggers only read caller-written state answers no) with narrated \`waitsOn\` lines when not yes, its invocable \`actions\` (each with an allowed/disabled verdict — these are what fire_action accepts), and its \`automations\` (cascade-fired actions the ENGINE fires on its own when their \`firesWhen\` trigger holds — never invocable via fire_action). Activities and actions that exist in the definition but are scoped out for this visit or actor are simply absent. Use this whenever you need to understand what's possible on an instance before deciding to act. This is a pure read — it does not change anything. ${UNTRUSTED_AUTHORED_DATA_NOTE} If you only need to discover what instances exist, use list_workflow_instances instead; this tool requires you to know the instance id. list_workflow_instances also returns the same \`workflowTitle\` and \`subject\` fields, so prefer it for fan-out discovery rather than polling get_workflow_state per instance.`,
     inputSchema: {
         ...workflowAddressFields,
         instance_id: instanceIdField
@@ -680,9 +700,9 @@ const instanceIdField = zod.z.string().min(1).describe("The workflow instance id
         readOnlyHint: !0
     },
     run: async context => {
-        const {engine: engine} = await context(), deployed = await engine.query({
+        const {engine: engine} = await context(), deployed = (await engine.query({
             groq: workflowEngine.definitionsListGroq("desc")
-        });
+        })).map(workflowEngine.assertReadableModel);
         return {
             definitions: workflowEngine.latestDeployedDefinitions(deployed).map(def => ({
                 name: def.name,
@@ -720,22 +740,55 @@ const instanceIdField = zod.z.string().min(1).describe("The workflow instance id
         }, {query: query, params: params} = workflowEngine.instancesQuery({
             tag: engine.tag,
             filter: filter
-        }), recency = `${query} | order(lastChangedAt desc)`, docs = await engine.query({
+        }), recency = `${query} | order(lastChangedAt desc)`, docs = (await engine.query({
             groq: document === void 0 ? `${recency}[0...${LIST_CAP}]` : recency,
             params: params
-        }), capped = (document === void 0 ? docs : docs.filter(doc => workflowEngine.instanceWatchesDocument(doc, document))).slice(0, LIST_CAP), subjectTitles = await fetchSubjectTitles(engine, capped);
+        })).map(workflowEngine.assertReadableModel), capped = (document === void 0 ? docs : docs.filter(doc => workflowEngine.instanceWatchesDocument(doc, document))).slice(0, LIST_CAP), subjectTitles = await fetchSubjectTitles(engine, capped);
         return {
             instances: capped.map(doc => projectSummary(doc, subjectTitles))
         };
     }
-}), startWorkflowTool = defineWorkflowTool({
+});
+
+async function startResolvingRetries(args) {
+    const {engine: engine, input: input, initialFields: initialFields} = args;
+    try {
+        const {instance: instance} = await engine.startInstance({
+            definition: input.definition,
+            ...input.version !== void 0 ? {
+                version: input.version
+            } : {},
+            ...initialFields.length > 0 ? {
+                initialFields: initialFields
+            } : {},
+            ...input.instance_id !== void 0 ? {
+                instanceId: input.instance_id
+            } : {}
+        });
+        return {
+            instanceId: instance._id
+        };
+    } catch (err) {
+        if (err instanceof workflowEngine.StartNotPrimedError) throw new Error(`${workflowEngine.errorMessage(err)} Retry start_workflow with instance_id "${err.instanceId}" to resume, or abort_workflow to discard it.`, {
+            cause: err
+        });
+        if (!(err instanceof workflowEngine.StartNotSettledError)) throw err;
+        return {
+            instanceId: err.instanceId,
+            startNotSettled: `The workflow started (created and primed) but its first auto-advance failed: ${workflowEngine.errorMessage(err.cause)}. It settles on the next engine tick, or retry start_workflow with instance_id "${err.instanceId}".`
+        };
+    }
+}
+
+const startWorkflowTool = defineWorkflowTool({
     name: "start_workflow",
     description: "Start a new workflow instance from a deployed definition — the lifecycle entry point. Use list_workflow_definitions first: `startable: true` marks what this tool can start (child workflows are spawn-only — a parent workflow's activity creates them, never this tool). Supply values for the workflow's input-sourced fields via `initial_fields` — e.g. the subject document the workflow is about. Returns the started instance, same shape as get_workflow_state; the engine's cascade (triggers and transitions) has already run, so it may land past the initial stage. Do NOT use this to advance an existing instance — that is fire_action. " + UNTRUSTED_AUTHORED_DATA_NOTE,
     inputSchema: {
         ...workflowAddressFields,
         definition: zod.z.string().min(1).describe("The workflow definition `name` to start (as listed by list_workflow_definitions)."),
         version: zod.z.number().int().min(1).describe("Optional. The deployed definition version to start from. Defaults to the highest.").optional(),
-        initial_fields: zod.z.record(zod.z.string(), zod.z.unknown()).describe('Optional. Values for the workflow\'s input-sourced field entries, keyed by field name (e.g. {"subject": {"id": "dataset:proj:ds:article-1", "type": "article"}}). doc.ref values take an object with a GDR `id` and doc `type`. get_workflow_definition shows a workflow\'s declared fields; only input-sourced entries accept a value here.').optional()
+        initial_fields: zod.z.record(zod.z.string(), zod.z.unknown()).describe('Optional. Values for the workflow\'s input-sourced field entries, keyed by field name (e.g. {"subject": {"id": "dataset:proj:ds:article-1", "type": "article"}}). doc.ref values take an object with a GDR `id` and doc `type`. get_workflow_definition shows a workflow\'s declared fields; only input-sourced entries accept a value here.').optional(),
+        instance_id: zod.z.string().min(1).describe("Optional. Start under this instance id — for retries. The id is the start's idempotency key: pass the SAME id when retrying a start that errored and the engine resumes that start instead of creating a duplicate instance (an already-settled start replays as a no-op). A failed start names the id to retry with in its error message. Omit to mint a fresh id.").optional()
     },
     annotations: {
         readOnlyHint: !1,
@@ -754,19 +807,18 @@ const instanceIdField = zod.z.string().min(1).describe("The workflow instance id
         const initialFields = workflowEngine.buildInitialFields({
             declared: deployed.fields ?? [],
             values: input.initial_fields ?? {}
-        }), {instance: instance} = await engine.startInstance({
-            definition: input.definition,
-            ...input.version !== void 0 ? {
-                version: input.version
-            } : {},
-            ...initialFields.length > 0 ? {
-                initialFields: initialFields
-            } : {}
-        });
-        return getInstanceState({
+        }), {instanceId: instanceId, startNotSettled: startNotSettled} = await startResolvingRetries({
             engine: engine,
-            instanceId: instance._id
+            input: input,
+            initialFields: initialFields
+        }), state = await getInstanceState({
+            engine: engine,
+            instanceId: instanceId
         });
+        return startNotSettled !== void 0 ? {
+            ...state,
+            startNotSettled: startNotSettled
+        } : state;
     }
 }), validateWorkflowDefinitionTool = defineWorkflowTool({
     name: "validate_workflow_definition",

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import type { ActionParam } from "@sanity/workflow-engine";
+import type { AutonomyVerdict } from "@sanity/workflow-engine";
 import type { Diagnosis } from "@sanity/workflow-engine";
 import type { Engine } from "@sanity/workflow-engine";
 import type { ExecutorClassification } from "@sanity/workflow-engine";
@@ -63,11 +64,25 @@ export declare interface ProjectedActivity {
    *  projection, so `skipped` here always means an action resolved it so. */
   status: "active" | "done" | "skipped" | "failed";
   /**
-   * Who, if anyone, the activity waits on — `interactive` (only invocable
-   * actions), `autonomous` (only cascade-fired automation), `off-system`
-   * (work performed outside the system), or `hybrid` (both kinds).
+   * Who, if anyone, fires the activity's actions — `interactive` (only
+   * invocable actions), `autonomous` (only cascade-fired automation),
+   * `off-system` (work performed outside the system), or `hybrid` (both
+   * kinds). Shape-only; `completesWithoutCaller` is the causal answer.
    */
   classification: ExecutorClassification;
+  /**
+   * The causal refinement of `classification`: whether the activity resolves
+   * with no caller acting, following its triggers' reads to their producers
+   * (a mechanically autonomous trigger that only reads caller-written state
+   * still answers `no`). `conditional` means it depends on runtime values
+   * the static analysis can't see.
+   */
+  completesWithoutCaller: AutonomyVerdict;
+  /** What the activity waits on when it doesn't complete on its own
+   *  ("waits on caller action …"), narrated in the workflow's vocabulary.
+   *  Present only when `completesWithoutCaller` isn't `yes` AND something is
+   *  narratable (a bare `conditional`, e.g. a cyclic gate, carries none). */
+  waitsOn?: string[];
   /** Invocable actions on this activity, each with its allowed/disabled
    *  verdict. See {@link ProjectedActionVerdict} for what never appears. */
   actions: ProjectedActionVerdict[];
@@ -164,6 +179,9 @@ export declare interface ProjectedInstanceState {
   subject?: ProjectedSubject;
   /** Activities on the current stage, with available actions. */
   activities: ProjectedActivity[];
+  /** The workflow-level causal-autonomy narrative — "this workflow runs
+   *  itself", or the stages where a run waits on someone. */
+  autonomy: string;
   /** Most recent history entries (newest first), capped to keep payload tight. */
   recentHistory: ProjectedHistoryEntry[];
 }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import type { ActionParam } from "@sanity/workflow-engine";
+import type { AutonomyVerdict } from "@sanity/workflow-engine";
 import type { Diagnosis } from "@sanity/workflow-engine";
 import type { Engine } from "@sanity/workflow-engine";
 import type { ExecutorClassification } from "@sanity/workflow-engine";
@@ -63,11 +64,25 @@ export declare interface ProjectedActivity {
    *  projection, so `skipped` here always means an action resolved it so. */
   status: "active" | "done" | "skipped" | "failed";
   /**
-   * Who, if anyone, the activity waits on — `interactive` (only invocable
-   * actions), `autonomous` (only cascade-fired automation), `off-system`
-   * (work performed outside the system), or `hybrid` (both kinds).
+   * Who, if anyone, fires the activity's actions — `interactive` (only
+   * invocable actions), `autonomous` (only cascade-fired automation),
+   * `off-system` (work performed outside the system), or `hybrid` (both
+   * kinds). Shape-only; `completesWithoutCaller` is the causal answer.
    */
   classification: ExecutorClassification;
+  /**
+   * The causal refinement of `classification`: whether the activity resolves
+   * with no caller acting, following its triggers' reads to their producers
+   * (a mechanically autonomous trigger that only reads caller-written state
+   * still answers `no`). `conditional` means it depends on runtime values
+   * the static analysis can't see.
+   */
+  completesWithoutCaller: AutonomyVerdict;
+  /** What the activity waits on when it doesn't complete on its own
+   *  ("waits on caller action …"), narrated in the workflow's vocabulary.
+   *  Present only when `completesWithoutCaller` isn't `yes` AND something is
+   *  narratable (a bare `conditional`, e.g. a cyclic gate, carries none). */
+  waitsOn?: string[];
   /** Invocable actions on this activity, each with its allowed/disabled
    *  verdict. See {@link ProjectedActionVerdict} for what never appears. */
   actions: ProjectedActionVerdict[];
@@ -164,6 +179,9 @@ export declare interface ProjectedInstanceState {
   subject?: ProjectedSubject;
   /** Activities on the current stage, with available actions. */
   activities: ProjectedActivity[];
+  /** The workflow-level causal-autonomy narrative — "this workflow runs
+   *  itself", or the stages where a run waits on someone. */
+  autonomy: string;
   /** Most recent history entries (newest first), capped to keep payload tight. */
   recentHistory: ProjectedHistoryEntry[];
 }

package/dist/stdio.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/workflow-mcp",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "MCP server exposing Sanity workflow tools to agents — operate running workflow instances and author new definitions.",
   "keywords": [
     "agent",
@@ -56,14 +56,14 @@
     "@sanity/client": "^7.22.1",
     "@sanity/telemetry": "^1.1.0",
     "zod": "^4.4.3",
-    "@sanity/workflow-engine": "0.16.0"
+    "@sanity/workflow-engine": "0.17.0"
   },
   "devDependencies": {
     "@sanity/pkg-utils": "^10.5.2",
     "@types/node": "^24.12.4",
     "vitest": "^4.1.8",
-    "@sanity/workflow-engine-test": "0.11.0",
-    "@sanity/workflow-examples": "0.6.0"
+    "@sanity/workflow-engine-test": "0.12.0",
+    "@sanity/workflow-examples": "0.7.0"
   },
   "engines": {
     "node": ">=20"