@sanity/workflow-mcp 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @sanity/workflow-mcp
 
+## 0.7.0
+
+### Minor Changes
+
+- 7510fd5: **BREAKING:** One list-filter vocabulary and definition batches. `list_workflow_instances` replaces its `status` enum with `include_completed` (boolean, default false — the engine's `includeCompleted` name, polarity, and in-flight default), and `deploy_workflow_definition` / `validate_workflow_definition` replace their singular `definition` object with a `definitions` array (`definition` singular now always means a definition NAME string, everywhere on the surface; validate returns per-definition `results` plus a top-level `valid`). Deploy takes a parent and its child workflows in one call — the engine orders children first.
+
+  Also in this release: the list tool applies every filter BEFORE its 25-result cap (the default in-flight view could previously return `[]` while in-flight instances existed behind newer completed ones) and gains a `document` filter (resource-qualified GDR URI, matching the engine's `instancesForDocument` read); `get_workflow_state` / `fire_action` responses now carry each action's declared `params` with requiredness, as `fire_action`'s description always promised; and two new tools round out the lifecycle — `start_workflow` (start a startable definition, seeding `initial_fields`) and `get_workflow_definition` (read a deployed definition's content envelope-stripped, redeployable as-is).
+
+- e5f5b77: **BREAKING:** the projection follows the engine's actions-only payload model.
+  - `get_workflow_state` (and `fire_action`'s returned state) applies filter-existence semantics: an action whose `filter` fails for the actor is ABSENT from the projection (never listed as disabled), and an activity the stage-entry filter scoped out of the visit is absent too — `ProjectedActivity.status` drops `pending` (activities are active from stage entry) and a projected `skipped` always means an action resolved it so.
+  - Cascade-fired (`when`) actions project as `automations` per activity — `{action, title?, firesWhen, pending?}`, the trigger GROQ plus the insight's "Needs: …" line while unsatisfied — never as invocable actions (new `ProjectedAutomation` type; `fire_action` rejects them engine-side).
+  - Each projected activity carries the engine's derived executor `classification` (interactive / autonomous / off-system / hybrid).
+  - `diagnose_workflow`'s waiting summary narrates only caller-fireable actions; an activity waiting purely on automation says so instead of naming pseudo-commands. History summaries narrate a `triggered` action fire as automation, the deleted `activityActivated` entry is gone, and failed-effect wording follows the action-origin model.
+  - The authoring guide teaches the new DSL: actions as the only payload mechanism, `when` triggers (fires-on-entry as `when: 'true'`), transitions as pure `{name, when, to}` edges, no `activation`/`completeWhen`/`failWhen`, the `$context` start-time bag, and the terminal-status / terminal-stage deploy invariants.
+
+- 6a46db1: Follow the engine's `start` block (`start.kind` classification + the read-side `start.filter` visibility predicate):
+  - workflow-mcp: `list_workflow_definitions` entries carry `startKind` (`'interactive' | 'autonomous'` — a classification, never a restriction).
+  - workflow-studio-plugin: start controls adopt the start model — `start.kind: 'autonomous'` mappings render no start affordance (automation owns their genesis), and a `start.filter` that DEFINITIVELY evaluates false on what's known before the dialog opens hides/disables the row with the start-condition reason. The pre-flight is purely additive: it never blocks a start the engine would accept, so every uncertain case (still loading, a dialog-collected `$fields` read, an eval error) shows the row. A failed start surfaces through the dialog's normal error toast.
+  - workflow-examples: `expense-approval` demonstrates a `start.filter` — one open approval per expense, as a picker-visibility filter (the Start list won't offer a second; not a gate).
+
+### Patch Changes
+
+- Updated dependencies [11e2d6f]
+- Updated dependencies [7510fd5]
+- Updated dependencies [01e8042]
+- Updated dependencies [79c54db]
+- Updated dependencies [6a46db1]
+- Updated dependencies [35b9b85]
+- Updated dependencies [e5f5b77]
+- Updated dependencies [01e8042]
+  - @sanity/workflow-engine@0.16.0
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -11,21 +11,24 @@ 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_instances` | read          | Discover what's running. Filterable, capped.                                                                                                                                                                                                     |
-| `get_workflow_state`      | read          | Project one instance into a flat shape: current stage, activities, available actions, 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. |
-| `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, 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.                                                                                                                                              |
 
 Author a definition (guide → validate → deploy; the first two are pure and
 engine-independent):
 
-| Tool                           | Read or write | What it's for                                                                                                                                                                                                       |
-| ------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `get_workflow_authoring_guide` | read          | Return the DSL guide an agent reads before authoring — shape, GROQ built-ins, sugars, modeling defaults, and two worked JSON examples.                                                                              |
-| `validate_workflow_definition` | read          | Check an authored definition the way deploy does (structure + invariants + GROQ). Returns the desugared definition or a path-prefixed error list.                                                                   |
-| `deploy_workflow_definition`   | write         | Publish a validated definition into an addressed environment. Create-only and content-addressed: identical content is an `unchanged` no-op, any change mints the next version, no deployed version is ever patched. |
+| Tool                           | Read or write | What it's for                                                                                                                                                                                                                                                         |
+| ------------------------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `get_workflow_authoring_guide` | read          | Return the DSL guide an agent reads before authoring — shape, GROQ built-ins, sugars, modeling defaults, and two worked JSON examples.                                                                                                                                |
+| `validate_workflow_definition` | read          | Check authored definitions (a `definitions` batch) the way deploy does (structure + invariants + GROQ). Returns `{valid, results}` — per definition, the desugared form or a path-prefixed error list.                                                                |
+| `deploy_workflow_definition`   | write         | Publish validated definitions into an addressed environment — one `definitions` batch per call (children deploy before the parents that spawn them). Create-only and content-addressed: identical content is an `unchanged` no-op, any change mints the next version. |
 
 Each tool def's `description` is written for an LLM consumer — it says
 what the tool does, when to use it, and what _not_ to use it for. Each
@@ -41,11 +44,16 @@ to use from prose alone. Adding tools beyond the minimum increases
 the search space the LLM has to navigate. We stay narrow until the
 evals tell us the LLM is reaching for something we don't expose. The
 authoring trio earns its place because authoring-from-a-description is
-eval-backed; the agent generates the definition, self-corrects against
+eval-backed; the agent generates the definitions, self-corrects against
 `validate_workflow_definition`, then publishes with
 `deploy_workflow_definition` — safe to hand an agent because deploy is
 create-only: it can never patch or clobber what's already deployed, and
 running instances keep the definition version they started under.
+`get_workflow_definition` closes the loop that create-only would
+otherwise leave open — iterating on a deployed workflow means reading
+it back, modifying, and deploying the next version — and
+`start_workflow` is the lifecycle entry point the catalogue's
+`startable` flag advertises.
 
 ## Run the stdio server
 
@@ -153,12 +161,8 @@ never builds an engine for them.
 - **No `set_stage` tool.** Admin override; intentionally omitted from
   the LLM surface until we have an eval case that needs it (and a
   story for the actor identity that would authorise the override).
-- **No `start_instance` tool.** Starting an instance is an operator
-  action that needs context the LLM doesn't have (subject doc ref,
-  initial field values); operators start instances with the workflow
-  CLI's `start` command.
-- **No effect completion.** Same logic — effects are queued by the
-  engine and drained by the runtime, not by a human or LLM.
+- **No effect completion.** Effects are queued by the engine and
+  drained by the runtime, not by a human or LLM.
 - **No subscription / streaming.** MCP supports it; we haven't needed
   it yet. Pull-based polling via `get_workflow_state` covers the eval
   cases.