@sanity/workflow-mcp 0.3.0 → 0.5.0

package/README.md

@@ -15,7 +15,7 @@ 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, tasks, available actions, recent history.                                          |
+| `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, and — when stuck — the cause plus suggested remediations. |
 | `fire_action`             | write         | Advance state. The only write. Mirrors the engine's universal "something happened" entry point.                                           |
 

package/dist/index.cjs

@@ -3,16 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: !0 });
 var workflowEngine = require("@sanity/workflow-engine"), define = require("@sanity/workflow-engine/define");
 const minimalExample = {
   name: "quick-approval",
-  version: 1,
   title: "Quick approval",
   description: "One review stage with a single approve action, then a terminal stage.",
   initialStage: "review",
-  fields: [{ type: "doc.ref", name: "subject", title: "Document", source: { type: "init" } }],
+  fields: [{ type: "doc.ref", name: "subject", title: "Document", initialValue: { type: "input" } }],
   stages: [
     {
       name: "review",
       title: "Review",
-      tasks: [
+      activities: [
         {
           name: "decide",
           title: "Decide",
@@ -26,16 +25,15 @@ const minimalExample = {
   ]
 }, reviewLoopExample = {
   name: "doc-review",
-  version: 1,
   title: "Document review",
   description: "Draft, then editorial review that approves or rejects back to drafting.",
   initialStage: "drafting",
-  fields: [{ type: "doc.ref", name: "subject", title: "Document", source: { type: "init" } }],
+  fields: [{ type: "doc.ref", name: "subject", title: "Document", initialValue: { type: "input" } }],
   stages: [
     {
       name: "drafting",
       title: "Drafting",
-      tasks: [
+      activities: [
         {
           name: "write",
           title: "Write the draft",
@@ -48,7 +46,7 @@ const minimalExample = {
     {
       name: "review",
       title: "Editorial review",
-      tasks: [
+      activities: [
         {
           name: "review",
           title: "Review the draft",
@@ -61,18 +59,18 @@ const minimalExample = {
       ],
       transitions: [
         { name: "to-approved", title: "Approve and finish", to: "approved" },
-        // Reject flips the task to `failed`; this routes the instance back.
+        // Reject flips the activity to `failed`; this routes the instance back.
         {
           name: "to-drafting",
           title: "Send back to drafting",
           to: "drafting",
-          filter: "$anyTaskFailed"
+          filter: "$anyActivityFailed"
         }
       ]
     },
     { name: "approved", title: "Approved", description: "Terminal \u2014 no transitions out." }
   ]
-}, ORIENTATION = "# Authoring a workflow definition\n\nA workflow definition is a plain JSON object. There is no code in it \u2014 every\ncondition (filters, predicates, guards) is a GROQ *string*. Generate the JSON,\nthen call `validate_workflow_definition` to check it; fix the reported errors\nand re-validate until it returns `valid: true`. The validator returns the\n*desugared* definition under `definition` \u2014 that is exactly what would deploy.\n\n## Shape\n\n- **Workflow**: `{ name, version (positive int), title, description?, initialStage, fields?, stages[], predicates? }`.\n  `initialStage` must be the `name` of a declared stage.\n- **Stage**: `{ name, title?, description?, tasks?, transitions? }`. A stage with\n  no transitions is terminal. Reaching a terminal stage ends the workflow.\n- **Task**: `{ name, title?, activation?, actions? }`. `activation` is `'auto'`\n  (starts when the stage is entered) or `'manual'` (default \u2014 a human starts it).\n- **Action**: `{ name, title?, status?, params?, ops? }`.\n  `status: 'done' | 'skipped' | 'failed'` is sugar that flips the *firing task* to\n  that status when the action fires. `ops` are mutations applied when the action\n  fires (e.g. `{type:'field.set', target:{field:'x'}, value:{type:'param', param:'p'}}`).\n  `params` are values the action collects from the caller (referenced by\n  `{type:'param', param:'<name>'}` sources).\n- **Transition**: `{ name, title?, to, filter? }`. `to` must name a declared\n  stage. `filter` is a GROQ condition gating the exit; omit it and it defaults\n  to `$allTasksDone`.\n- **Field** (workflow- or stage-scoped persistent state): `{ type, name, title?, source }`.\n  Common `type`s: `doc.ref`, `doc.refs`, `value.string`, `value.url`,\n  `value.number`, `value.boolean`. `source` is where the value comes from:\n  `{type:'init'}` (supplied when the instance starts), `{type:'write'}` (a user\n  edits it), `{type:'param', param:'<actionParamName>'}`, `{type:'now'}`, `{type:'actor'}`.\n  By convention a workflow has an `init`-sourced `doc.ref` named `subject` \u2014 the\n  headline document it is about.\n\n## GROQ in conditions\n\nBuilt-in variables available in filters/predicates: `$allTasksDone`,\n`$anyTaskFailed` (booleans over the current stage's tasks), `$tasks` (the task\nlist), `$fields` (field values), `$now`, and the caller-scoped vars `$actor`\n(the acting user), `$assigned` (whether the caller is the task's assignee \u2014 the\nidiomatic permission gate, used as `filter: '$assigned'`), and `$can`. Define\nreusable named conditions under top-level `predicates: { name: '<groq>' }` and\nreference them as `$name` (e.g.\n`predicates: { ready: \"count($tasks[status != 'done']) == 0\" }` \u2192 `$ready`).\n\nConditions evaluate against an in-memory snapshot (the instance + its subject +\nfield-declared docs) \u2014 **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## Sugars worth knowing\n\n- Action `status: 'done' | 'skipped' | 'failed'` \u2014 flips the firing task (shown above).\n- Omitted transition `filter` \u2014 defaults to `$allTasksDone`.\n- Omitted task `activation` \u2014 defaults to `'manual'`.\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 \u2192 drafting` gated\n  on `$anyTaskFailed`), not to a terminal stage. Reserve terminal stages for\n  completion and for explicit cancellation/abandonment \u2014 a workflow should not\n  dead-end just because something was declined.\n- **Prefer draft \u2192 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, task names (per stage) and transition names are unique.\n- Every transition `to` and `initialStage` names a declared stage.\n- Custom `predicates` must not shadow a built-in (e.g. `allTasksDone`).\n- Every GROQ string must parse and must not be a `_type` discovery scan.", AUTHORING_GUIDE = `${ORIENTATION}
+}, ORIENTATION = "# Authoring a workflow definition\n\nA workflow definition is a plain JSON object. There is no code in it \u2014 every\ncondition (filters, predicates, guards) is a GROQ *string*. Generate the JSON,\nthen call `validate_workflow_definition` to check it; fix the reported errors\nand re-validate until it returns `valid: true`. The validator returns the\n*desugared* definition under `definition` \u2014 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` \u2014 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?, activation?, actions? }`. `activation` is `'auto'`\n  (starts when the stage is entered) or `'manual'` (default \u2014 a human starts it).\n- **Action**: `{ name, title?, status?, params?, ops? }`.\n  `status: 'done' | 'skipped' | 'failed'` is sugar that flips the *firing activity* to\n  that status when the action fires. `ops` are mutations applied when the action\n  fires (e.g. `{type:'field.set', target:{field:'x'}, value:{type:'param', param:'p'}}`).\n  `params` are values the action collects from the caller (referenced by\n  `{type:'param', param:'<name>'}` sources).\n- **Transition**: `{ name, title?, to, filter? }`. `to` must name a declared\n  stage. `filter` is a GROQ condition gating the exit; omit it and it defaults\n  to `$allActivitiesDone`.\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` \u2014 one concrete\n  principal; `assignee` / `assignees` \u2014 one or many user-or-role assignees), and\n  the compositional kinds `object` (`{ type:'object', name, fields: [...] }`) and\n  `array` (`{ type:'array', name, of: [...] }`) \u2014 `fields`/`of` are themselves\n  field shapes, so any structure composes. `initialValue` seeds the slot once at\n  materialisation and is **optional** \u2014 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` \u2014 the\n  headline document it is about.\n  Two list sugars desugar to `array`: `{type:'todoList', name}` (ad-hoc\n  status-tracked work \u2014 rows `{ label, status, assignee?, dueDate? }`) and\n  `{type:'notes', name}` (an append-only audit/comment log \u2014 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 filters/predicates: `$allActivitiesDone`,\n`$anyActivityFailed` (booleans over the current stage's activities), `$activities` (the activity\nlist), `$fields` (field values), `$now`, and the caller-scoped vars `$actor`\n(the acting user), `$assigned` (whether the caller is the activity's assignee \u2014 the\nidiomatic permission gate, used as `filter: '$assigned'`), and `$can`. Define\nreusable named conditions under top-level `predicates: { name: '<groq>' }` and\nreference them as `$name` (e.g.\n`predicates: { ready: \"count($activities[status != 'done']) == 0\" }` \u2192 `$ready`).\n\nConditions evaluate against an in-memory snapshot (the instance + its subject +\nfield-declared docs) \u2014 **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## Sugars worth knowing\n\n- Action `status: 'done' | 'skipped' | 'failed'` \u2014 flips the firing activity (shown above).\n- Omitted transition `filter` \u2014 defaults to `$allActivitiesDone`.\n- Omitted activity `activation` \u2014 defaults to `'manual'`.\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 \u2192 drafting` gated\n  on `$anyActivityFailed`), not to a terminal stage. Reserve terminal stages for\n  completion and for explicit cancellation/abandonment \u2014 a workflow should not\n  dead-end just because something was declined.\n- **Prefer draft \u2192 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- 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}
 
 ## Examples
 
@@ -107,7 +105,7 @@ ${JSON.stringify(reviewLoopExample, null, 2)}
   },
   {
     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 \u2014 its ref and title), every task on the current stage with its available actions (and whether each action is currently allowed), and the most recent history entries. Use this whenever you need to understand what's possible on an instance before deciding to act. This is a pure read \u2014 it does not change anything. 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 \u2014 its ref and title), every activity on the current stage with its available actions (and whether each action is currently allowed), and the most recent history entries. Use this whenever you need to understand what's possible on an instance before deciding to act. This is a pure read \u2014 it does not change anything. 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.",
     input_schema: {
       type: "object",
       properties: {
@@ -122,7 +120,7 @@ ${JSON.stringify(reviewLoopExample, null, 2)}
   },
   {
     name: "diagnose_workflow",
-    description: "Explain why a single workflow instance is or isn't progressing. Returns a verdict (`state`: progressing, waiting, blocked, completed, aborted, or stuck), a one-line `summary`, and \u2014 when stuck \u2014 a structured `cause` plus the `remediations` that would unstick it. Use this when an instance seems stalled or the user asks \"why isn't this moving?\": it distinguishes a healthy instance (waiting on a human, or will advance on its own) from a genuinely stuck one (a failed effect or task, a dead-end transition). This is a pure read \u2014 it changes nothing, and the remediations it names are advisory: none can be executed through this server. To actually advance a healthy waiting instance use fire_action; for per-task action detail use get_workflow_state.",
+    description: "Explain why a single workflow instance is or isn't progressing. Returns a verdict (`state`: progressing, waiting, blocked, completed, aborted, or stuck), a one-line `summary`, and \u2014 when stuck \u2014 a structured `cause` plus the `remediations` that would unstick it. Use this when an instance seems stalled or the user asks \"why isn't this moving?\": it distinguishes a healthy instance (waiting on a human, or will advance on its own) from a genuinely stuck one (a failed effect or activity, a dead-end transition). This is a pure read \u2014 it changes nothing, and the remediations it names are advisory: none can be executed through this server. To actually advance a healthy waiting instance use fire_action; for per-activity action detail use get_workflow_state.",
     input_schema: {
       type: "object",
       properties: {
@@ -137,7 +135,7 @@ ${JSON.stringify(reviewLoopExample, null, 2)}
   },
   {
     name: "fire_action",
-    description: "Advance a workflow instance by firing an action on one of its tasks. This is the only way to advance workflow state from the outside \u2014 there is no separate 'complete task' or 'transition stage' tool. To find the right (task, action) pair, call get_workflow_state first and pick from the allowed actions listed on the current stage's tasks. After firing, the engine cascades any auto-transitions that become eligible (so an 'approve' action on a review task may transition the workflow to a terminal stage in one shot). Returns the resulting state, same shape as get_workflow_state. If the action is not currently allowed (e.g. the task is already done, or a guard fails), this returns an error describing why.",
+    description: "Advance a workflow instance by firing an action on one of its activities. This is the only way to advance workflow state from the outside \u2014 there is no separate 'complete activity' or 'transition stage' tool. To find the right (activity, action) pair, call get_workflow_state first and pick from the allowed actions listed on the current stage's activities. After firing, the engine cascades any auto-transitions that become eligible (so an 'approve' action on a review activity may transition the workflow to a terminal stage in one shot). Returns the resulting state, same shape as get_workflow_state. If the action is not currently allowed (e.g. the activity is already done, or a guard fails), this returns an error describing why.",
     input_schema: {
       type: "object",
       properties: {
@@ -145,16 +143,21 @@ ${JSON.stringify(reviewLoopExample, null, 2)}
           type: "string",
           description: "The workflow instance id."
         },
-        task: {
+        activity: {
           type: "string",
-          description: "The id of the task on the current stage. Must be one of the tasks returned by get_workflow_state."
+          description: "The id of the activity on the current stage. Must be one of the activities returned by get_workflow_state."
         },
         action: {
           type: "string",
-          description: "The id of the action on that task. Must be one of the actions listed as allowed=true on the task."
+          description: "The id of the action on that activity. Must be one of the actions listed as allowed=true on the activity."
+        },
+        params: {
+          type: "object",
+          description: `Optional. Values for the action's declared params, keyed by param name (e.g. {"note": "Unsupported claim in paragraph 3."}). Required when the action declares a required param \u2014 get_workflow_state lists each action's params and whether they are required. The shape is per-action, so this is a free-form object; the engine validates the supplied values against the action's declared params and rejects the call if a required one is missing.`,
+          additionalProperties: !0
         }
       },
-      required: ["instance_id", "task", "action"],
+      required: ["instance_id", "activity", "action"],
       additionalProperties: !1
     }
   },
@@ -237,8 +240,12 @@ function projectSummary(doc, subjectTitles) {
     ...subject !== void 0 ? { subject } : {}
   };
 }
-function projectState(instance, evaluation, subjectTitles) {
-  const workflowTitle = JSON.parse(instance.definitionSnapshot).title, stageTitle = evaluation.currentStage.stage.title, tasks = evaluation.currentStage.tasks.map((te) => {
+function projectState({
+  instance,
+  evaluation,
+  subjectTitles
+}) {
+  const workflowTitle = JSON.parse(instance.definitionSnapshot).title, stageTitle = evaluation.currentStage.stage.title, activities = evaluation.currentStage.activities.map((te) => {
     const actions = te.actions.map((ae) => {
       const verdict = workflowEngine.actionVerdict(te, ae);
       return {
@@ -249,9 +256,9 @@ function projectState(instance, evaluation, subjectTitles) {
       };
     });
     return {
-      task: te.task.name,
-      ...te.task.title !== void 0 ? { title: te.task.title } : {},
-      ...te.task.description !== void 0 ? { description: te.task.description } : {},
+      activity: te.activity.name,
+      ...te.activity.title !== void 0 ? { title: te.activity.title } : {},
+      ...te.activity.description !== void 0 ? { description: te.activity.description } : {},
       status: te.status,
       actions
     };
@@ -268,7 +275,7 @@ function projectState(instance, evaluation, subjectTitles) {
     ...stageTitle !== void 0 ? { currentStageTitle: stageTitle } : {},
     done: isInstanceDone(instance),
     ...subject !== void 0 ? { subject } : {},
-    tasks,
+    activities,
     recentHistory
   };
 }
@@ -281,15 +288,21 @@ function isInstanceDone(instance) {
     return !1;
   }
 }
-const DISABLED_REASON_TEXT = {
-  "filter-failed": "action's filter condition did not hold for this actor",
-  "task-not-active": "task is not currently active",
-  "stage-terminal": "stage is terminal \u2014 no further actions possible",
-  "instance-completed": "instance has already completed",
-  "requirements-unmet": "task's declared requirements are not yet satisfied"
-};
 function formatDisabledReason(reason) {
-  return DISABLED_REASON_TEXT[reason.kind] ?? reason.kind.replace(/-/g, " ");
+  switch (reason.kind) {
+    case "filter-failed":
+      return "action's filter condition did not hold for this actor";
+    case "activity-not-active":
+      return "activity is not currently active";
+    case "stage-terminal":
+      return "stage is terminal \u2014 no further actions possible";
+    case "mutation-guard-denied":
+      return `blocked by mutation guard(s): ${reason.guardIds.join(", ")}`;
+    case "instance-completed":
+      return "instance has already completed";
+    case "requirements-unmet":
+      return "activity's declared requirements are not yet satisfied";
+  }
 }
 function summariseHistoryEntry(entry) {
   switch (entry._type) {
@@ -297,12 +310,12 @@ function summariseHistoryEntry(entry) {
       return `entered stage "${String(entry.stage)}"`;
     case "stageExited":
       return `exited stage "${String(entry.stage)}" \u2192 "${String(entry.toStage)}"`;
-    case "taskActivated":
-      return `task "${String(entry.task)}" activated`;
-    case "taskStatusChanged":
-      return `task "${String(entry.task)}" status: ${String(entry.from)} \u2192 ${String(entry.to)}`;
+    case "activityActivated":
+      return `activity "${String(entry.activity)}" activated`;
+    case "activityStatusChanged":
+      return `activity "${String(entry.activity)}" status: ${String(entry.from)} \u2192 ${String(entry.to)}`;
     case "actionFired":
-      return `action "${String(entry.action)}" fired on task "${String(entry.task)}"`;
+      return `action "${String(entry.action)}" fired on activity "${String(entry.activity)}"`;
     case "transitionFired":
       return `transition fired: "${String(entry.fromStage)}" \u2192 "${String(entry.toStage)}"`;
     case "effectQueued":
@@ -310,7 +323,7 @@ function summariseHistoryEntry(entry) {
     case "effectCompleted":
       return `effect "${String(entry.effect)}" completed (${String(entry.status)})`;
     case "spawned":
-      return `spawned child workflow from task "${String(entry.task)}"`;
+      return `spawned child workflow from activity "${String(entry.activity)}"`;
     default:
       return entry._type;
   }
@@ -320,9 +333,9 @@ function diagnosisSummary(diagnosis) {
     case "progressing":
       return "This instance will advance on its own.";
     case "waiting":
-      return `Waiting for action on task "${diagnosis.task}": ${diagnosis.actions.join(" or ")}. This is the normal in-flight state \u2014 it advances when someone acts.`;
+      return `Waiting for action on activity "${diagnosis.activity}": ${diagnosis.actions.join(" or ")}. This is the normal in-flight state \u2014 it advances when someone acts.`;
     case "blocked":
-      return `Task "${diagnosis.task}" is visible but not yet executable \u2014 unmet requirement(s): ${diagnosis.requirements.join(", ")}. It will not advance until those are satisfied.`;
+      return `Activity "${diagnosis.activity}" is visible but not yet executable \u2014 unmet requirement(s): ${diagnosis.requirements.join(", ")}. It will not advance until those are satisfied.`;
     case "completed":
       return `Completed at ${diagnosis.at}.`;
     case "aborted":
@@ -334,13 +347,13 @@ function diagnosisSummary(diagnosis) {
 function stuckSummary(cause) {
   switch (cause.kind) {
     case "failed-effect":
-      return `Stuck: a failed effect "${cause.effect.name}" is blocking task "${cause.effect.origin.name}", which can't complete until the effect succeeds.`;
+      return `Stuck: a failed effect "${cause.effect.name}" is blocking activity "${cause.effect.origin.name}", which can't complete until the effect succeeds.`;
     case "hung-effect":
       return `Stuck: effect "${cause.effect.name}" was claimed but never completed \u2014 the drainer likely died mid-dispatch, so it won't drain on its own.`;
-    case "failed-task":
-      return `Stuck: task "${cause.task}" is in a terminal failed state, so any exit transition gated on it can never fire.`;
+    case "failed-activity":
+      return `Stuck: activity "${cause.activity}" is in a terminal failed state, so any exit transition gated on it can never fire.`;
     case "no-transition-fires":
-      return "Stuck: every task is resolved but no exit transition's filter is satisfied \u2014 likely a routing state value a filter reads was never written.";
+      return "Stuck: every activity is resolved but no exit transition's filter is satisfied \u2014 likely a routing state value a filter reads was never written.";
     case "transition-unevaluable":
       return `Stuck (recoverable): exit transition(s) ${cause.transitions.join(", ")} read an operand that is missing or unreadable (GROQ null). It advances on its own once that data becomes readable \u2014 no manual fix needed.`;
   }
@@ -354,20 +367,21 @@ function buildTools(engine, options = {}) {
     },
     get_workflow_state: async (rawInput) => {
       const input = parseInstanceIdInput(rawInput, "get_workflow_state");
-      return getInstanceState(engine, input.instance_id, accessOverride);
+      return getInstanceState({ engine, instanceId: input.instance_id, accessOverride });
     },
     diagnose_workflow: async (rawInput) => {
       const input = parseInstanceIdInput(rawInput, "diagnose_workflow");
-      return getInstanceDiagnosis(engine, input.instance_id, accessOverride);
+      return getInstanceDiagnosis({ engine, instanceId: input.instance_id, accessOverride });
     },
     fire_action: async (rawInput) => {
       const input = parseFireActionInput(rawInput);
       return await engine.fireAction({
         instanceId: input.instance_id,
-        task: input.task,
+        activity: input.activity,
         action: input.action,
+        ...input.params !== void 0 ? { params: input.params } : {},
         ...accessOverride !== void 0 ? { access: accessOverride } : {}
-      }), getInstanceState(engine, input.instance_id, accessOverride);
+      }), getInstanceState({ engine, instanceId: input.instance_id, accessOverride });
     },
     // Authoring tools — engine-independent: they teach and check the DSL, they
     // don't touch the lake or an instance.
@@ -389,33 +403,44 @@ function parseListInput(raw) {
   const obj = raw, status = obj.status === "done" || obj.status === "any" ? obj.status : "in_flight", definition = typeof obj.definition == "string" ? obj.definition : void 0;
   return definition !== void 0 ? { definition, status } : { status };
 }
-function parseValidateInput(raw) {
+function asObject(raw, tool) {
   if (raw === null || typeof raw != "object")
-    throw new Error("validate_workflow_definition: input must be an object");
-  const obj = raw;
+    throw new Error(`${tool}: input must be an object`);
+  return raw;
+}
+function requireString({
+  obj,
+  key,
+  tool
+}) {
+  const value = obj[key];
+  if (typeof value != "string" || value === "")
+    throw new Error(`${tool}: ${key} is required`);
+  return value;
+}
+function parseValidateInput(raw) {
+  const obj = asObject(raw, "validate_workflow_definition");
   if (obj.definition === null || typeof obj.definition != "object")
     throw new Error("validate_workflow_definition: `definition` is required and must be an object");
   return { definition: obj.definition };
 }
 function parseInstanceIdInput(raw, tool) {
-  if (raw === null || typeof raw != "object")
-    throw new Error(`${tool}: input must be an object`);
-  const obj = raw;
-  if (typeof obj.instance_id != "string" || obj.instance_id === "")
-    throw new Error(`${tool}: instance_id is required`);
-  return { instance_id: obj.instance_id };
+  const obj = asObject(raw, tool);
+  return { instance_id: requireString({ obj, key: "instance_id", tool }) };
 }
 function parseFireActionInput(raw) {
-  if (raw === null || typeof raw != "object")
-    throw new Error("fire_action: input must be an object");
-  const obj = raw;
-  for (const key of ["instance_id", "task", "action"])
-    if (typeof obj[key] != "string" || obj[key] === "")
-      throw new Error(`fire_action: ${key} is required`);
+  const obj = asObject(raw, "fire_action");
+  let params;
+  if (obj.params !== void 0) {
+    if (obj.params === null || typeof obj.params != "object" || Array.isArray(obj.params))
+      throw new Error("fire_action: params must be an object");
+    params = obj.params;
+  }
   return {
-    instance_id: obj.instance_id,
-    task: obj.task,
-    action: obj.action
+    instance_id: requireString({ obj, key: "instance_id", tool: "fire_action" }),
+    activity: requireString({ obj, key: "activity", tool: "fire_action" }),
+    action: requireString({ obj, key: "action", tool: "fire_action" }),
+    ...params !== void 0 ? { params } : {}
   };
 }
 async function listInstances(engine, input) {
@@ -431,14 +456,22 @@ async function listInstances(engine, input) {
     instances: filtered.map((doc) => projectSummary(doc, subjectTitles))
   };
 }
-async function getInstanceState(engine, instanceId, accessOverride) {
+async function getInstanceState({
+  engine,
+  instanceId,
+  accessOverride
+}) {
   const evaluation = await engine.evaluateInstance({
     instanceId,
     ...accessOverride !== void 0 ? { access: accessOverride } : {}
   }), instance = await engine.getInstance({ instanceId }), subjectTitles = await fetchSubjectTitles(engine, [instance]);
-  return projectState(instance, evaluation, subjectTitles);
+  return projectState({ instance, evaluation, subjectTitles });
 }
-async function getInstanceDiagnosis(engine, instanceId, accessOverride) {
+async function getInstanceDiagnosis({
+  engine,
+  instanceId,
+  accessOverride
+}) {
   const { diagnosis, remediations } = await engine.diagnose({
     instanceId,
     ...accessOverride !== void 0 ? { access: accessOverride } : {}