@sanity/workflow-mcp 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,105 @@
 # @sanity/workflow-mcp
 
+## 0.22.0
+
+### Patch Changes
+
+- Updated dependencies [88ba4ba]
+  - @sanity/workflow-engine@0.22.0
+
+## 0.21.0
+
+### Minor Changes
+
+- f4bc057: **BREAKING:** `list_workflow_instances` now returns one page with `has_more` and an optional `next_cursor`; callers that need every match must continue with the cursor. The optional `limit` accepts 1–100 rows and defaults to 25.
+
+  Bound instance and definition list reads with lake-side filtering and consumer-specific projections.
+
+  Document filtering now excludes exited-stage references and includes live unresolved child-workflow references. Definition discovery selects and model-gates only the latest deployed version of each workflow name; historical versions remain stored and available to history-oriented APIs.
+
+  The MCP eval suite now verifies that agents follow list cursors to find a target beyond the first default page, including in persisted Braintrust runs.
+
+  MCP tool telemetry reports a `cursorUsed` boolean so continued list-page adoption is measurable without sending cursor values, arguments, or results.
+
+- bcc30fe: **BREAKING:** Definition deploys through the MCP tool acknowledge data model 4
+  (`expectedMinReaderModel: 4`): deploys assert a model-4-capable reader fleet
+  and require the model-4 engine.
+- fa9c796: **BREAKING:** Replace the singular `start.allowed` and activity requirement record with ordered, named requirement arrays.
+
+  Start readiness now accepts polymorphic `groq` and `singleSubject` nodes:
+
+  ```ts
+  // Before
+  start: {allowed: '$fields.approved == true'}
+
+  // After
+  start: {
+    requirements: [
+      {type: 'groq', name: 'approved', title: 'Approval required', query: '$fields.approved == true'},
+    ],
+  }
+  ```
+
+  Use `singleSubject` instead of `$subjectHasInFlightInstance` to allow at most one in-flight run of the same definition for a subject. The requirement is definition-scoped and version-blind across deployments:
+
+  ```ts
+  // Before
+  start: {allowed: '!$subjectHasInFlightInstance'}
+
+  // After
+  start: {
+    requirements: [
+      {type: 'singleSubject', name: 'single-subject', description: 'Finish the existing run first.'},
+    ],
+  }
+  ```
+
+  Activity readiness uses the same ordered descriptor model with `groq` nodes:
+
+  ```ts
+  // Before
+  requirements: {
+    approved: 'defined($fields.approval)'
+  }
+
+  // After
+  requirements: [{type: 'groq', name: 'approved', query: 'defined($fields.approval)'}]
+  ```
+
+  Requirement names must be unique within their owning array. Evaluation preserves author order and reports every unmet requirement with its `name` and optional editor-facing `title` and `description`. Fresh standalone starts enforce the requirements after validating inputs. Resuming an unfinished start and parent-owned spawning continue to bypass start requirements.
+
+  `evaluateStart()` now returns ordered `requirements` entries containing each descriptor, outcome, and GROQ insight where applicable. Its singular top-level `insight` is removed. `StartNotAllowedError.insight` is replaced by `StartNotAllowedError.unmetRequirements`. Activity evaluation likewise reports unmet requirement descriptors instead of names alone.
+
+  Rename the public start-requirement analysis helpers and constants:
+
+  ```ts
+  // Before
+  explainStartAllowed(args)
+  unboundAllowedReads(query, fields)
+  START_ALLOWED_VARS
+
+  // After
+  explainStartRequirement(args)
+  unboundRequirementReads(query, fields)
+  START_REQUIREMENT_VARS
+  ```
+
+  `definitionsForDocument({document, subject})` becomes `definitionsForDocument({document})`. Start applicability no longer needs a separately supplied subject. The engine-owned start dataset projection exposes only `definition`, `subject`, and `completedAt`; authors no longer query raw instance storage for deduplication.
+
+  Studio pre-flights both requirement kinds against the live document session, disables starts whose requirements are unmet, and renders the authored description or title with a humanized requirement-name fallback. Controls re-enable on the same mount when a blocking run completes.
+
+  Persisted data model 4 unconditionally raises `minReaderModel` to 4 for new definitions and instances because older readers would ignore readiness arrays and could commit invalid transitions. Upgrade every reader and Function before deploying model-4 writers. Legacy deployed definitions are not normalized; prerelease environments with incompatible definitions may use `sanity-workflows nuke` before redeploying.
+
+### Patch Changes
+
+- Updated dependencies [d9394e5]
+- Updated dependencies [92e28bd]
+- Updated dependencies [f4bc057]
+- Updated dependencies [bcc30fe]
+- Updated dependencies [e7392af]
+- Updated dependencies [fa9c796]
+  - @sanity/workflow-engine@0.21.0
+
 ## 0.20.0
 
 ### Minor Changes

package/README.md

@@ -15,7 +15,7 @@ Operate a running instance:
 | --------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `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.                                                                                                                                                                          |
+| `list_workflow_instances`   | read          | Discover what's running. Filterable (`definition`, `document`, `include_completed` — in-flight by default), with configurable cursor pagination.                                                                                                                                             |
 | `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).                                                                                                                                                              |
@@ -94,8 +94,10 @@ Definition content is unaffected (deploy expands and vets it).
 
 The stdio server reports adoption telemetry to Sanity: one
 `Editorial Workflows MCP Tool Called` event per tool invocation carrying the
-tool name and a success
-flag — never tool arguments or results — plus the engine's own adoption
+tool name, a success flag, and whether a list cursor was supplied. Cursor
+values, other tool arguments, and results are never sent. This makes continued
+page usage measurable without collecting customer content. The server also
+reports the engine's own adoption
 events. Nothing is sent unless the account's telemetry consent resolves to
 granted (the account-wide status `sanity telemetry status` shows). Set
 `DO_NOT_TRACK=1` to opt a process out; CI environments (`CI` set) never

package/dist/_chunks-es/index.js

@@ -1,4 +1,4 @@
-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 { createTelemetryIntake, isTelemetryEnvDenied, processShellUserProperties, errorMessage, validateTag, parseResourceGdr, parseDefinitionInput, extractDocumentId, parseDefinitionSnapshot, displayTitle, autonomySummary, actionRendering, isTerminalStage, describeCondition, actionVerdict, narrateAutonomyWaits, subjectDenialLabels, deniedGuardLabels, definitionLookupGroq, assertReadableModel, unsatisfiedTransitionSummaries, describeSite, latestDefinitionsGroq, startKindOf, isStartableDefinition, instancesQuery, instanceWatchesDocument, parseGdr, startRefusal, buildInitialFields, StartNotPrimedError, StartNotSettledError, validateDefinition, WorkflowError } from "@sanity/workflow-engine";
 
 import { defineEvent, createBatchedStore, createSessionId } from "@sanity/telemetry";
 
@@ -6,10 +6,12 @@ import { z } from "zod";
 
 import { defineWorkflow } from "@sanity/workflow-engine/define";
 
+import { Buffer } from "node:buffer";
+
 const WorkflowMcpToolCalled = defineEvent({
     name: "Editorial Workflows MCP Tool Called",
-    version: 1,
-    description: "An MCP tool was invoked — payload is the tool name and a success flag only, never tool arguments or results"
+    version: 2,
+    description: "An MCP tool was invoked — payload is the tool name, success, and list-cursor usage; never arguments, cursor values, or results"
 });
 
 function createMcpTelemetry(args) {
@@ -120,7 +122,7 @@ const deployWorkflowDefinitionTool = defineWorkflowTool({
         if (problems.length > 0) throw new Error(problems.join(`\n`));
         const {engine: engine} = await context();
         return engine.deployDefinitions({
-            expectedMinReaderModel: 2,
+            expectedMinReaderModel: 4,
             definitions: stored
         });
     }
@@ -332,7 +334,7 @@ async function fetchDeployedDefinition({engine: engine, definition: definition,
 }
 
 function isInstanceDone(instance) {
-    if (instance.completedAt !== void 0) return !0;
+    if (instance.completedAt != null) return !0;
     try {
         const stage = parseDefinitionSnapshot(instance).stages.find(s => s.name === instance.currentStage);
         return stage !== void 0 && isTerminalStage(stage);
@@ -717,11 +719,11 @@ 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({
-            groq: definitionsListGroq("desc")
-        })).map(assertReadableModel);
+        const {engine: engine} = await context();
         return {
-            definitions: latestDeployedDefinitions(deployed).map(def => ({
+            definitions: (await engine.query({
+                groq: latestDefinitionsGroq()
+            })).map(assertReadableModel).map(def => ({
                 name: def.name,
                 title: def.title,
                 ...def.description !== void 0 ? {
@@ -733,14 +735,44 @@ const instanceIdField = z.string().min(1).describe("The workflow instance id."),
             }))
         };
     }
-}), LIST_CAP = 25, listWorkflowInstancesTool = defineWorkflowTool({
+}), DEFAULT_LIST_LIMIT = 25, MAX_LIST_LIMIT = 100, cursorPayloadSchema = z.object({
+    version: z.literal(1),
+    lastChangedAt: z.string(),
+    instanceId: z.string(),
+    scope: z.string()
+});
+
+function cursorScope(input) {
+    return JSON.stringify([ input.workflow_resource, input.tag, input.definition ?? null, input.document ?? null, input.include_completed ]);
+}
+
+function encodeCursor(payload) {
+    return Buffer.from(JSON.stringify(payload)).toString("base64url");
+}
+
+function decodeCursor(cursor, expectedScope) {
+    let decoded;
+    try {
+        decoded = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+    } catch {
+        throw new Error("list_workflow_instances: invalid cursor");
+    }
+    const parsed = cursorPayloadSchema.safeParse(decoded);
+    if (!parsed.success) throw new Error("list_workflow_instances: invalid cursor");
+    if (parsed.data.scope !== expectedScope) throw new Error("list_workflow_instances: cursor does not match the current filters");
+    return parsed.data;
+}
+
+const SUMMARY_PROJECTION = `{\n  _type,\n  _id,\n  modelVersion,\n  minReaderModel,\n  workflowResource,\n  definition,\n  definitionSnapshot,\n  fields,\n  ancestors,\n  subworkflows,\n  stages,\n  currentStage,\n  lastChangedAt,\n  completedAt,\n  abortedAt\n}`, listWorkflowInstancesTool = defineWorkflowTool({
     name: "list_workflow_instances",
-    description: `List workflow instances in one workflow environment. Use this when you need to find a workflow but don't already know its instance id, or to survey what's in flight. Returns a compact summary — id, \`definition\` (the workflow definition's \`name\`) and human-readable \`workflowTitle\`, current stage, whether the instance is done, and (when the workflow declares a subject document) a \`subject\` field with the subject doc's ref and title. Use \`workflowTitle\` when the user names the workflow by type (e.g. "article reviews") and \`subject.title\` when they name a specific in-flight instance by what it's about (e.g. "the article-review about pricing"). Capped at ${LIST_CAP} results — the most recently changed matches; every filter applies before the cap. Do NOT use this to inspect a single known instance — use get_workflow_state for that, the response will be richer. ` + UNTRUSTED_AUTHORED_DATA_NOTE,
+    description: `List workflow instances in one workflow environment. Use this when you need to find a workflow but don't already know its instance id, or to survey what's in flight. Returns a compact summary — id, \`definition\` (the workflow definition's \`name\`) and human-readable \`workflowTitle\`, current stage, whether the instance is done, and (when the workflow declares a subject document) a \`subject\` field with the subject doc's ref and title. Use \`workflowTitle\` when the user names the workflow by type (e.g. "article reviews") and \`subject.title\` when they name a specific in-flight instance by what it's about (e.g. "the article-review about pricing"). Returns up to ${DEFAULT_LIST_LIMIT} results per page by default, ordered by most recently changed; set \`limit\` up to ${MAX_LIST_LIMIT}. Defensive document verification can leave a page underfilled. When \`has_more\` is true, call this tool again with the same filters and \`next_cursor\` as \`cursor\`; never claim the list is complete until \`has_more\` is false. Do NOT use this to inspect a single known instance — use get_workflow_state for that, the response will be richer. ` + UNTRUSTED_AUTHORED_DATA_NOTE,
     inputSchema: {
         ...workflowAddressFields,
         definition: z.string().describe("Optional. Restrict to instances of this workflow definition, by its `name` (e.g. 'article-review').").optional(),
         document: z.string().describe(`Optional. Only instances that reference this document — the workflow's subject or any other doc its fields point at — as a resource-qualified GDR URI (e.g. "dataset:proj:ds:article-1"). Use this to answer "which workflows are about this document?".`).superRefine(zodCheck(parseGdr)).optional(),
-        include_completed: z.boolean().describe("Optional. `true` includes completed/aborted instances. Defaults to false — in-flight instances only.").default(!1)
+        include_completed: z.boolean().describe("Optional. `true` includes completed/aborted instances. Defaults to false — in-flight instances only.").default(!1),
+        limit: z.number().int().min(1).max(MAX_LIST_LIMIT).describe(`Optional. Results per page, from 1 to ${MAX_LIST_LIMIT}. Defaults to ${DEFAULT_LIST_LIMIT}.`).default(DEFAULT_LIST_LIMIT),
+        cursor: z.string().describe("Optional. Opaque `next_cursor` from the previous response. Reuse the same address and filters when continuing.").optional()
     },
     annotations: {
         readOnlyHint: !0
@@ -757,12 +789,28 @@ 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({
-            groq: document === void 0 ? `${recency}[0...${LIST_CAP}]` : recency,
-            params: params
-        })).map(assertReadableModel), capped = (document === void 0 ? docs : docs.filter(doc => instanceWatchesDocument(doc, document))).slice(0, LIST_CAP), subjectTitles = await fetchSubjectTitles(engine, capped);
+        }), scope = cursorScope(input), cursor = input.cursor === void 0 ? void 0 : decodeCursor(input.cursor, scope), recency = `${query}${cursor === void 0 ? "" : "[lastChangedAt < $cursorLastChangedAt || (lastChangedAt == $cursorLastChangedAt && _id > $cursorInstanceId)]"} | order(lastChangedAt desc, _id asc)`, docs = (await engine.query({
+            groq: `${recency}[0...$pageSize]${SUMMARY_PROJECTION}`,
+            params: {
+                ...params,
+                pageSize: input.limit + 1,
+                ...cursor === void 0 ? {} : {
+                    cursorLastChangedAt: cursor.lastChangedAt,
+                    cursorInstanceId: cursor.instanceId
+                }
+            }
+        })).map(assertReadableModel), rawPage = docs.slice(0, input.limit), page = document === void 0 ? rawPage : rawPage.filter(doc => instanceWatchesDocument(doc, document)), hasMore = docs.length > input.limit, subjectTitles = await fetchSubjectTitles(engine, page), boundary = rawPage.at(-1);
         return {
-            instances: capped.map(doc => projectSummary(doc, subjectTitles))
+            instances: page.map(doc => projectSummary(doc, subjectTitles)),
+            has_more: hasMore,
+            ...hasMore && boundary !== void 0 ? {
+                next_cursor: encodeCursor({
+                    version: 1,
+                    lastChangedAt: boundary.lastChangedAt,
+                    instanceId: boundary._id,
+                    scope: scope
+                })
+            } : {}
         };
     }
 });
@@ -884,10 +932,11 @@ function registerWorkflowTools(server, getContext, options) {
 }
 
 async function runToolHandler({def: def, context: context, input: input, telemetry: telemetry}) {
-    const logCalled = success => {
+    const cursorUsed = listCursorWasSupplied(def.name, input), logCalled = success => {
         telemetry?.log(WorkflowMcpToolCalled, {
             tool: def.name,
-            success: success
+            success: success,
+            cursorUsed: cursorUsed
         });
     };
     try {
@@ -911,4 +960,8 @@ async function runToolHandler({def: def, context: context, input: input, telemet
     }
 }
 
+function listCursorWasSupplied(toolName, input) {
+    return toolName !== "list_workflow_instances" || typeof input != "object" || input === null ? !1 : "cursor" in input && typeof input.cursor == "string" && input.cursor.length > 0;
+}
+
 export { WORKFLOW_TOOLS, createMcpTelemetry, registerWorkflowTools, toolInputJsonSchema, workflowAddressFromInput };

package/dist/index.cjs

@@ -4,12 +4,12 @@ Object.defineProperty(exports, "__esModule", {
     value: !0
 });
 
-var workflowEngine = require("@sanity/workflow-engine"), telemetry = require("@sanity/telemetry"), zod = require("zod"), define = require("@sanity/workflow-engine/define");
+var workflowEngine = require("@sanity/workflow-engine"), telemetry = require("@sanity/telemetry"), zod = require("zod"), define = require("@sanity/workflow-engine/define"), node_buffer = require("node:buffer");
 
 const WorkflowMcpToolCalled = telemetry.defineEvent({
     name: "Editorial Workflows MCP Tool Called",
-    version: 1,
-    description: "An MCP tool was invoked — payload is the tool name and a success flag only, never tool arguments or results"
+    version: 2,
+    description: "An MCP tool was invoked — payload is the tool name, success, and list-cursor usage; never arguments, cursor values, or results"
 });
 
 function zodCheck(validate) {
@@ -103,7 +103,7 @@ const deployWorkflowDefinitionTool = defineWorkflowTool({
         if (problems.length > 0) throw new Error(problems.join(`\n`));
         const {engine: engine} = await context();
         return engine.deployDefinitions({
-            expectedMinReaderModel: 2,
+            expectedMinReaderModel: 4,
             definitions: stored
         });
     }
@@ -315,7 +315,7 @@ async function fetchDeployedDefinition({engine: engine, definition: definition,
 }
 
 function isInstanceDone(instance) {
-    if (instance.completedAt !== void 0) return !0;
+    if (instance.completedAt != null) return !0;
     try {
         const stage = workflowEngine.parseDefinitionSnapshot(instance).stages.find(s => s.name === instance.currentStage);
         return stage !== void 0 && workflowEngine.isTerminalStage(stage);
@@ -700,11 +700,11 @@ 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({
-            groq: workflowEngine.definitionsListGroq("desc")
-        })).map(workflowEngine.assertReadableModel);
+        const {engine: engine} = await context();
         return {
-            definitions: workflowEngine.latestDeployedDefinitions(deployed).map(def => ({
+            definitions: (await engine.query({
+                groq: workflowEngine.latestDefinitionsGroq()
+            })).map(workflowEngine.assertReadableModel).map(def => ({
                 name: def.name,
                 title: def.title,
                 ...def.description !== void 0 ? {
@@ -716,14 +716,44 @@ const instanceIdField = zod.z.string().min(1).describe("The workflow instance id
             }))
         };
     }
-}), LIST_CAP = 25, listWorkflowInstancesTool = defineWorkflowTool({
+}), DEFAULT_LIST_LIMIT = 25, MAX_LIST_LIMIT = 100, cursorPayloadSchema = zod.z.object({
+    version: zod.z.literal(1),
+    lastChangedAt: zod.z.string(),
+    instanceId: zod.z.string(),
+    scope: zod.z.string()
+});
+
+function cursorScope(input) {
+    return JSON.stringify([ input.workflow_resource, input.tag, input.definition ?? null, input.document ?? null, input.include_completed ]);
+}
+
+function encodeCursor(payload) {
+    return node_buffer.Buffer.from(JSON.stringify(payload)).toString("base64url");
+}
+
+function decodeCursor(cursor, expectedScope) {
+    let decoded;
+    try {
+        decoded = JSON.parse(node_buffer.Buffer.from(cursor, "base64url").toString("utf8"));
+    } catch {
+        throw new Error("list_workflow_instances: invalid cursor");
+    }
+    const parsed = cursorPayloadSchema.safeParse(decoded);
+    if (!parsed.success) throw new Error("list_workflow_instances: invalid cursor");
+    if (parsed.data.scope !== expectedScope) throw new Error("list_workflow_instances: cursor does not match the current filters");
+    return parsed.data;
+}
+
+const SUMMARY_PROJECTION = `{\n  _type,\n  _id,\n  modelVersion,\n  minReaderModel,\n  workflowResource,\n  definition,\n  definitionSnapshot,\n  fields,\n  ancestors,\n  subworkflows,\n  stages,\n  currentStage,\n  lastChangedAt,\n  completedAt,\n  abortedAt\n}`, listWorkflowInstancesTool = defineWorkflowTool({
     name: "list_workflow_instances",
-    description: `List workflow instances in one workflow environment. Use this when you need to find a workflow but don't already know its instance id, or to survey what's in flight. Returns a compact summary — id, \`definition\` (the workflow definition's \`name\`) and human-readable \`workflowTitle\`, current stage, whether the instance is done, and (when the workflow declares a subject document) a \`subject\` field with the subject doc's ref and title. Use \`workflowTitle\` when the user names the workflow by type (e.g. "article reviews") and \`subject.title\` when they name a specific in-flight instance by what it's about (e.g. "the article-review about pricing"). Capped at ${LIST_CAP} results — the most recently changed matches; every filter applies before the cap. Do NOT use this to inspect a single known instance — use get_workflow_state for that, the response will be richer. ` + UNTRUSTED_AUTHORED_DATA_NOTE,
+    description: `List workflow instances in one workflow environment. Use this when you need to find a workflow but don't already know its instance id, or to survey what's in flight. Returns a compact summary — id, \`definition\` (the workflow definition's \`name\`) and human-readable \`workflowTitle\`, current stage, whether the instance is done, and (when the workflow declares a subject document) a \`subject\` field with the subject doc's ref and title. Use \`workflowTitle\` when the user names the workflow by type (e.g. "article reviews") and \`subject.title\` when they name a specific in-flight instance by what it's about (e.g. "the article-review about pricing"). Returns up to ${DEFAULT_LIST_LIMIT} results per page by default, ordered by most recently changed; set \`limit\` up to ${MAX_LIST_LIMIT}. Defensive document verification can leave a page underfilled. When \`has_more\` is true, call this tool again with the same filters and \`next_cursor\` as \`cursor\`; never claim the list is complete until \`has_more\` is false. Do NOT use this to inspect a single known instance — use get_workflow_state for that, the response will be richer. ` + UNTRUSTED_AUTHORED_DATA_NOTE,
     inputSchema: {
         ...workflowAddressFields,
         definition: zod.z.string().describe("Optional. Restrict to instances of this workflow definition, by its `name` (e.g. 'article-review').").optional(),
         document: zod.z.string().describe(`Optional. Only instances that reference this document — the workflow's subject or any other doc its fields point at — as a resource-qualified GDR URI (e.g. "dataset:proj:ds:article-1"). Use this to answer "which workflows are about this document?".`).superRefine(zodCheck(workflowEngine.parseGdr)).optional(),
-        include_completed: zod.z.boolean().describe("Optional. `true` includes completed/aborted instances. Defaults to false — in-flight instances only.").default(!1)
+        include_completed: zod.z.boolean().describe("Optional. `true` includes completed/aborted instances. Defaults to false — in-flight instances only.").default(!1),
+        limit: zod.z.number().int().min(1).max(MAX_LIST_LIMIT).describe(`Optional. Results per page, from 1 to ${MAX_LIST_LIMIT}. Defaults to ${DEFAULT_LIST_LIMIT}.`).default(DEFAULT_LIST_LIMIT),
+        cursor: zod.z.string().describe("Optional. Opaque `next_cursor` from the previous response. Reuse the same address and filters when continuing.").optional()
     },
     annotations: {
         readOnlyHint: !0
@@ -740,12 +770,28 @@ 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({
-            groq: document === void 0 ? `${recency}[0...${LIST_CAP}]` : recency,
-            params: params
-        })).map(workflowEngine.assertReadableModel), capped = (document === void 0 ? docs : docs.filter(doc => workflowEngine.instanceWatchesDocument(doc, document))).slice(0, LIST_CAP), subjectTitles = await fetchSubjectTitles(engine, capped);
+        }), scope = cursorScope(input), cursor = input.cursor === void 0 ? void 0 : decodeCursor(input.cursor, scope), recency = `${query}${cursor === void 0 ? "" : "[lastChangedAt < $cursorLastChangedAt || (lastChangedAt == $cursorLastChangedAt && _id > $cursorInstanceId)]"} | order(lastChangedAt desc, _id asc)`, docs = (await engine.query({
+            groq: `${recency}[0...$pageSize]${SUMMARY_PROJECTION}`,
+            params: {
+                ...params,
+                pageSize: input.limit + 1,
+                ...cursor === void 0 ? {} : {
+                    cursorLastChangedAt: cursor.lastChangedAt,
+                    cursorInstanceId: cursor.instanceId
+                }
+            }
+        })).map(workflowEngine.assertReadableModel), rawPage = docs.slice(0, input.limit), page = document === void 0 ? rawPage : rawPage.filter(doc => workflowEngine.instanceWatchesDocument(doc, document)), hasMore = docs.length > input.limit, subjectTitles = await fetchSubjectTitles(engine, page), boundary = rawPage.at(-1);
         return {
-            instances: capped.map(doc => projectSummary(doc, subjectTitles))
+            instances: page.map(doc => projectSummary(doc, subjectTitles)),
+            has_more: hasMore,
+            ...hasMore && boundary !== void 0 ? {
+                next_cursor: encodeCursor({
+                    version: 1,
+                    lastChangedAt: boundary.lastChangedAt,
+                    instanceId: boundary._id,
+                    scope: scope
+                })
+            } : {}
         };
     }
 });
@@ -867,10 +913,11 @@ function registerWorkflowTools(server, getContext, options) {
 }
 
 async function runToolHandler({def: def, context: context, input: input, telemetry: telemetry2}) {
-    const logCalled = success => {
+    const cursorUsed = listCursorWasSupplied(def.name, input), logCalled = success => {
         telemetry2?.log(WorkflowMcpToolCalled, {
             tool: def.name,
-            success: success
+            success: success,
+            cursorUsed: cursorUsed
         });
     };
     try {
@@ -894,6 +941,10 @@ async function runToolHandler({def: def, context: context, input: input, telemet
     }
 }
 
+function listCursorWasSupplied(toolName, input) {
+    return toolName !== "list_workflow_instances" || typeof input != "object" || input === null ? !1 : "cursor" in input && typeof input.cursor == "string" && input.cursor.length > 0;
+}
+
 exports.WORKFLOW_TOOLS = WORKFLOW_TOOLS;
 
 exports.registerWorkflowTools = registerWorkflowTools;

package/dist/stdio.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/workflow-mcp",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "MCP server exposing Sanity workflow tools to agents — operate running workflow instances and author new definitions.",
   "keywords": [
     "agent",
@@ -61,12 +61,12 @@
     "@sanity/pkg-utils": "^10.5.2",
     "@types/node": "^24.12.4",
     "vitest": "^4.1.8",
-    "@sanity/workflow-engine": "0.20.0",
-    "@sanity/workflow-engine-test": "0.20.0",
-    "@sanity/workflow-examples": "0.9.0"
+    "@sanity/workflow-engine": "0.22.0",
+    "@sanity/workflow-engine-test": "0.22.0",
+    "@sanity/workflow-examples": "0.10.1"
   },
   "peerDependencies": {
-    "@sanity/workflow-engine": "0.20.0"
+    "@sanity/workflow-engine": "0.22.0"
   },
   "engines": {
     "node": ">=20"