@sanity/workflow-mcp 0.6.0 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +56 -0
- package/README.md +29 -18
- package/dist/_chunks-es/index.js +288 -84
- package/dist/index.cjs +287 -82
- package/dist/index.d.cts +94 -6
- package/dist/index.d.ts +94 -6
- package/dist/stdio.js +1 -1
- package/package.json +4 -4
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,61 @@
|
|
|
1
1
|
# @sanity/workflow-mcp
|
|
2
2
|
|
|
3
|
+
## 0.8.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 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 …").
|
|
8
|
+
- 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).
|
|
9
|
+
- 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.
|
|
10
|
+
|
|
11
|
+
### Patch Changes
|
|
12
|
+
|
|
13
|
+
- 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.
|
|
14
|
+
- Updated dependencies [f9389e5]
|
|
15
|
+
- Updated dependencies [d0c62ea]
|
|
16
|
+
- Updated dependencies [c3eed2e]
|
|
17
|
+
- Updated dependencies [df4bd80]
|
|
18
|
+
- Updated dependencies [092a0d4]
|
|
19
|
+
- Updated dependencies [5a1a9fe]
|
|
20
|
+
- Updated dependencies [e3a7ba2]
|
|
21
|
+
- Updated dependencies [30fed9e]
|
|
22
|
+
- Updated dependencies [1321ba5]
|
|
23
|
+
- Updated dependencies [e683875]
|
|
24
|
+
- Updated dependencies [a8ace4d]
|
|
25
|
+
- @sanity/workflow-engine@0.17.0
|
|
26
|
+
|
|
27
|
+
## 0.7.0
|
|
28
|
+
|
|
29
|
+
### Minor Changes
|
|
30
|
+
|
|
31
|
+
- 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.
|
|
32
|
+
|
|
33
|
+
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).
|
|
34
|
+
|
|
35
|
+
- e5f5b77: **BREAKING:** the projection follows the engine's actions-only payload model.
|
|
36
|
+
- `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.
|
|
37
|
+
- 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).
|
|
38
|
+
- Each projected activity carries the engine's derived executor `classification` (interactive / autonomous / off-system / hybrid).
|
|
39
|
+
- `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.
|
|
40
|
+
- 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.
|
|
41
|
+
|
|
42
|
+
- 6a46db1: Follow the engine's `start` block (`start.kind` classification + the read-side `start.filter` visibility predicate):
|
|
43
|
+
- workflow-mcp: `list_workflow_definitions` entries carry `startKind` (`'interactive' | 'autonomous'` — a classification, never a restriction).
|
|
44
|
+
- 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.
|
|
45
|
+
- 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).
|
|
46
|
+
|
|
47
|
+
### Patch Changes
|
|
48
|
+
|
|
49
|
+
- Updated dependencies [11e2d6f]
|
|
50
|
+
- Updated dependencies [7510fd5]
|
|
51
|
+
- Updated dependencies [01e8042]
|
|
52
|
+
- Updated dependencies [79c54db]
|
|
53
|
+
- Updated dependencies [6a46db1]
|
|
54
|
+
- Updated dependencies [35b9b85]
|
|
55
|
+
- Updated dependencies [e5f5b77]
|
|
56
|
+
- Updated dependencies [01e8042]
|
|
57
|
+
- @sanity/workflow-engine@0.16.0
|
|
58
|
+
|
|
3
59
|
## 0.6.0
|
|
4
60
|
|
|
5
61
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -11,21 +11,24 @@ the tools the evals drive, plus a stdio MCP entry point for real MCP clients.
|
|
|
11
11
|
|
|
12
12
|
Operate a running instance:
|
|
13
13
|
|
|
14
|
-
| Tool
|
|
15
|
-
|
|
|
16
|
-
| `
|
|
17
|
-
| `
|
|
18
|
-
| `
|
|
19
|
-
| `
|
|
14
|
+
| Tool | Read or write | What it's for |
|
|
15
|
+
| --------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
16
|
+
| `list_workflow_definitions` | read | The catalogue: which workflow types are deployed (latest version each), and whether they're startable. |
|
|
17
|
+
| `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). |
|
|
18
|
+
| `list_workflow_instances` | read | Discover what's running. Filterable (`definition`, `document`, `include_completed` — in-flight by default), capped. |
|
|
19
|
+
| `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. |
|
|
20
|
+
| `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. |
|
|
21
|
+
| `start_workflow` | write | The lifecycle entry point: start a startable deployed definition, seeding its input-sourced fields (e.g. the subject document). |
|
|
22
|
+
| `fire_action` | write | Advance state. The instance write. Mirrors the engine's universal "something happened" entry point. |
|
|
20
23
|
|
|
21
24
|
Author a definition (guide → validate → deploy; the first two are pure and
|
|
22
25
|
engine-independent):
|
|
23
26
|
|
|
24
|
-
| Tool | Read or write | What it's for
|
|
25
|
-
| ------------------------------ | ------------- |
|
|
26
|
-
| `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.
|
|
27
|
-
| `validate_workflow_definition` | read | Check
|
|
28
|
-
| `deploy_workflow_definition` | write | Publish
|
|
27
|
+
| Tool | Read or write | What it's for |
|
|
28
|
+
| ------------------------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
29
|
+
| `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. |
|
|
30
|
+
| `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. |
|
|
31
|
+
| `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. |
|
|
29
32
|
|
|
30
33
|
Each tool def's `description` is written for an LLM consumer — it says
|
|
31
34
|
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
|
|
|
41
44
|
the search space the LLM has to navigate. We stay narrow until the
|
|
42
45
|
evals tell us the LLM is reaching for something we don't expose. The
|
|
43
46
|
authoring trio earns its place because authoring-from-a-description is
|
|
44
|
-
eval-backed; the agent generates the
|
|
47
|
+
eval-backed; the agent generates the definitions, self-corrects against
|
|
45
48
|
`validate_workflow_definition`, then publishes with
|
|
46
49
|
`deploy_workflow_definition` — safe to hand an agent because deploy is
|
|
47
50
|
create-only: it can never patch or clobber what's already deployed, and
|
|
48
51
|
running instances keep the definition version they started under.
|
|
52
|
+
`get_workflow_definition` closes the loop that create-only would
|
|
53
|
+
otherwise leave open — iterating on a deployed workflow means reading
|
|
54
|
+
it back, modifying, and deploying the next version — and
|
|
55
|
+
`start_workflow` is the lifecycle entry point the catalogue's
|
|
56
|
+
`startable` flag advertises.
|
|
49
57
|
|
|
50
58
|
## Run the stdio server
|
|
51
59
|
|
|
@@ -75,6 +83,13 @@ distinct `(resource, tag)`, cached for the life of the process. The `dev`
|
|
|
75
83
|
script loads the env from the repo-root `.env`, so copy `.env.example` to
|
|
76
84
|
`.env` to get started.
|
|
77
85
|
|
|
86
|
+
MCP-built engines declare no foreign resources, so a runtime-supplied
|
|
87
|
+
`doc.ref` to any resource other than the addressed workflow resource is
|
|
88
|
+
rejected at the write (`RefResourceUndeclaredError`) — deliberate: an
|
|
89
|
+
agent-driven write pointing a workflow at an undeclared resource is
|
|
90
|
+
exactly the misdirection the engine's written-ref gate exists to catch.
|
|
91
|
+
Definition content is unaffected (deploy expands and vets it).
|
|
92
|
+
|
|
78
93
|
### Telemetry
|
|
79
94
|
|
|
80
95
|
The stdio server reports adoption telemetry to Sanity: one
|
|
@@ -153,12 +168,8 @@ never builds an engine for them.
|
|
|
153
168
|
- **No `set_stage` tool.** Admin override; intentionally omitted from
|
|
154
169
|
the LLM surface until we have an eval case that needs it (and a
|
|
155
170
|
story for the actor identity that would authorise the override).
|
|
156
|
-
- **No
|
|
157
|
-
|
|
158
|
-
initial field values); operators start instances with the workflow
|
|
159
|
-
CLI's `start` command.
|
|
160
|
-
- **No effect completion.** Same logic — effects are queued by the
|
|
161
|
-
engine and drained by the runtime, not by a human or LLM.
|
|
171
|
+
- **No effect completion.** Effects are queued by the engine and
|
|
172
|
+
drained by the runtime, not by a human or LLM.
|
|
162
173
|
- **No subscription / streaming.** MCP supports it; we haven't needed
|
|
163
174
|
it yet. Pull-based polling via `get_workflow_state` covers the eval
|
|
164
175
|
cases.
|