@sanity/workflow-mcp 0.6.0 → 0.8.0

package/dist/index.d.cts

@@ -1,5 +1,8 @@
+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";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import type { ServerNotification } from "@modelcontextprotocol/sdk/types.js";
@@ -27,6 +30,13 @@ export declare type GetWorkflowToolContext = (
   input: unknown,
 ) => WorkflowToolContext | Promise<WorkflowToolContext>;
 
+/**
+ * One invocable (fireAction-fired) action. Two whole classes of action never
+ * appear here: an action whose `filter` scoped it out for this actor is
+ * ABSENT (filter is existence — it might as well not exist, never "disabled"),
+ * and a cascade-fired (`when`) action is projected as a
+ * {@link ProjectedAutomation} instead — the engine fires it, no caller can.
+ */
 export declare interface ProjectedActionVerdict {
   /** Action name — what to pass to `fire_action` as `action`. */
   action: string;
@@ -36,6 +46,10 @@ export declare interface ProjectedActionVerdict {
   allowed: boolean;
   /** When `allowed` is false, a short reason describing why. */
   disabledReason?: string;
+  /** The action's declared params — what `fire_action`'s `params` object must
+   *  satisfy (each entry names the param and whether it is required). Absent
+   *  when the action declares none. */
+  params?: ActionParam[];
 }
 
 export declare interface ProjectedActivity {
@@ -45,10 +59,71 @@ export declare interface ProjectedActivity {
   title?: string;
   /** Longer prose description, if provided. */
   description?: string;
-  /** Current activity status. */
-  status: "pending" | "active" | "done" | "skipped" | "failed";
-  /** Available actions on this activity, each with its allowed/disabled verdict. */
+  /** Current activity status. Activities are active from stage entry; an
+   *  activity whose `filter` scoped it out of this visit is absent from the
+   *  projection, so `skipped` here always means an action resolved it so. */
+  status: "active" | "done" | "skipped" | "failed";
+  /**
+   * 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[];
+  /** Cascade-fired actions, narrated as automation ("fires when …").
+   *  Present only when the activity declares any. */
+  automations?: ProjectedAutomation[];
+}
+
+/**
+ * One cascade-fired (`when`) action, narrated as automation: the engine fires
+ * it on its own the moment the trigger holds — it is never invocable via
+ * `fire_action`, so it must not read as a button.
+ */
+export declare interface ProjectedAutomation {
+  /** The cascade-fired action's name. Not accepted by `fire_action`. */
+  action: string;
+  /** Human label, if provided. */
+  title?: string;
+  /** The trigger — the GROQ condition whose truth makes the engine fire it. */
+  firesWhen: string;
+  /** What still stands between the current state and the trigger, as one
+   *  English line ("Needs: …"). Absent when the trigger is already satisfied
+   *  or already fired this stage visit. */
+  pending?: string;
+}
+
+/**
+ * Result of `get_workflow_definition` — one deployed version's content.
+ * `definition` is the stored (desugared) form with the document envelope
+ * stripped — valid input for the validate/deploy tools as-is (their parse
+ * accepts stored form; parts of it, e.g. resolved guard `idRefs`, are NOT
+ * valid authoring shape): modify it and redeploy via
+ * `deploy_workflow_definition` to mint the next version.
+ */
+export declare interface ProjectedDefinition {
+  /** Definition `name`. */
+  name: string;
+  /** The deployed version this content came from. */
+  version: number;
+  /** The envelope-stripped definition content. */
+  definition: WorkflowDefinition;
 }
 
 /**
@@ -104,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[];
 }
@@ -187,9 +265,10 @@ export declare function toolInputJsonSchema(
 ): ToolInputJsonSchema;
 
 /**
- * Result of `validate_workflow_definition`. On `valid: true`, `definition` is the
- * desugared form that would deploy (defaults filled, sugar expanded); on
- * `valid: false`, `error` is the aggregated, path-prefixed list of problems.
+ * Per-definition result inside {@link ValidateDefinitionsResult}. On
+ * `valid: true`, `definition` is the desugared form that would deploy
+ * (defaults filled, sugar expanded); on `valid: false`, `error` is the
+ * aggregated, path-prefixed list of problems.
  */
 export declare type ValidateDefinitionResult =
   | {
@@ -201,6 +280,15 @@ export declare type ValidateDefinitionResult =
       error: string;
     };
 
+/**
+ * Result of `validate_workflow_definition`. `results` pairs positionally with
+ * the input `definitions`; `valid` is true only when every definition passed.
+ */
+export declare interface ValidateDefinitionsResult {
+  valid: boolean;
+  results: ValidateDefinitionResult[];
+}
+
 export declare const WORKFLOW_TOOLS: readonly WorkflowToolDef[];
 
 /**

package/dist/index.d.ts

@@ -1,5 +1,8 @@
+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";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import type { ServerNotification } from "@modelcontextprotocol/sdk/types.js";
@@ -27,6 +30,13 @@ export declare type GetWorkflowToolContext = (
   input: unknown,
 ) => WorkflowToolContext | Promise<WorkflowToolContext>;
 
+/**
+ * One invocable (fireAction-fired) action. Two whole classes of action never
+ * appear here: an action whose `filter` scoped it out for this actor is
+ * ABSENT (filter is existence — it might as well not exist, never "disabled"),
+ * and a cascade-fired (`when`) action is projected as a
+ * {@link ProjectedAutomation} instead — the engine fires it, no caller can.
+ */
 export declare interface ProjectedActionVerdict {
   /** Action name — what to pass to `fire_action` as `action`. */
   action: string;
@@ -36,6 +46,10 @@ export declare interface ProjectedActionVerdict {
   allowed: boolean;
   /** When `allowed` is false, a short reason describing why. */
   disabledReason?: string;
+  /** The action's declared params — what `fire_action`'s `params` object must
+   *  satisfy (each entry names the param and whether it is required). Absent
+   *  when the action declares none. */
+  params?: ActionParam[];
 }
 
 export declare interface ProjectedActivity {
@@ -45,10 +59,71 @@ export declare interface ProjectedActivity {
   title?: string;
   /** Longer prose description, if provided. */
   description?: string;
-  /** Current activity status. */
-  status: "pending" | "active" | "done" | "skipped" | "failed";
-  /** Available actions on this activity, each with its allowed/disabled verdict. */
+  /** Current activity status. Activities are active from stage entry; an
+   *  activity whose `filter` scoped it out of this visit is absent from the
+   *  projection, so `skipped` here always means an action resolved it so. */
+  status: "active" | "done" | "skipped" | "failed";
+  /**
+   * 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[];
+  /** Cascade-fired actions, narrated as automation ("fires when …").
+   *  Present only when the activity declares any. */
+  automations?: ProjectedAutomation[];
+}
+
+/**
+ * One cascade-fired (`when`) action, narrated as automation: the engine fires
+ * it on its own the moment the trigger holds — it is never invocable via
+ * `fire_action`, so it must not read as a button.
+ */
+export declare interface ProjectedAutomation {
+  /** The cascade-fired action's name. Not accepted by `fire_action`. */
+  action: string;
+  /** Human label, if provided. */
+  title?: string;
+  /** The trigger — the GROQ condition whose truth makes the engine fire it. */
+  firesWhen: string;
+  /** What still stands between the current state and the trigger, as one
+   *  English line ("Needs: …"). Absent when the trigger is already satisfied
+   *  or already fired this stage visit. */
+  pending?: string;
+}
+
+/**
+ * Result of `get_workflow_definition` — one deployed version's content.
+ * `definition` is the stored (desugared) form with the document envelope
+ * stripped — valid input for the validate/deploy tools as-is (their parse
+ * accepts stored form; parts of it, e.g. resolved guard `idRefs`, are NOT
+ * valid authoring shape): modify it and redeploy via
+ * `deploy_workflow_definition` to mint the next version.
+ */
+export declare interface ProjectedDefinition {
+  /** Definition `name`. */
+  name: string;
+  /** The deployed version this content came from. */
+  version: number;
+  /** The envelope-stripped definition content. */
+  definition: WorkflowDefinition;
 }
 
 /**
@@ -104,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[];
 }
@@ -187,9 +265,10 @@ export declare function toolInputJsonSchema(
 ): ToolInputJsonSchema;
 
 /**
- * Result of `validate_workflow_definition`. On `valid: true`, `definition` is the
- * desugared form that would deploy (defaults filled, sugar expanded); on
- * `valid: false`, `error` is the aggregated, path-prefixed list of problems.
+ * Per-definition result inside {@link ValidateDefinitionsResult}. On
+ * `valid: true`, `definition` is the desugared form that would deploy
+ * (defaults filled, sugar expanded); on `valid: false`, `error` is the
+ * aggregated, path-prefixed list of problems.
  */
 export declare type ValidateDefinitionResult =
   | {
@@ -201,6 +280,15 @@ export declare type ValidateDefinitionResult =
       error: string;
     };
 
+/**
+ * Result of `validate_workflow_definition`. `results` pairs positionally with
+ * the input `definitions`; `valid` is true only when every definition passed.
+ */
+export declare interface ValidateDefinitionsResult {
+  valid: boolean;
+  results: ValidateDefinitionResult[];
+}
+
 export declare const WORKFLOW_TOOLS: readonly WorkflowToolDef[];
 
 /**

package/dist/stdio.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/workflow-mcp",
-  "version": "0.6.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.15.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.10.0",
-    "@sanity/workflow-examples": "0.5.0"
+    "@sanity/workflow-engine-test": "0.12.0",
+    "@sanity/workflow-examples": "0.7.0"
   },
   "engines": {
     "node": ">=20"