@sanity/workflow-mcp 0.4.0 → 0.5.1

package/README.md

@@ -3,10 +3,9 @@
 MCP tool surface for the workflows engine. Two jobs, no fluff: operate running
 instances, and author new definitions.
 
-> [!WARNING]
-> POC. The eval harness in [`@sanity/workflow-mcp-evals`](../workflow-mcp-evals)
-> is the load-bearing artifact for now — this package exposes the tools
-> the evals drive, plus a stdio MCP entry point for real MCP clients.
+The tool surface is developed against the eval harness in
+[`@sanity/workflow-mcp-evals`](../workflow-mcp-evals) — this package exposes
+the tools the evals drive, plus a stdio MCP entry point for real MCP clients.
 
 ## What the tools do
 
@@ -57,11 +56,13 @@ it's `bin/run.js`, and once the package is published this is what
 node packages/workflow-mcp/bin/run.js
 ```
 
-Both share the one boot path in `src/stdio.ts` and read the same
-`SANITY_*` and `WORKFLOW_*` env vars as
-[`@sanity/workflow-cli`](../workflow-cli) (which loads them
-from the root `.env`). Copy `.env.example` to `.env` at the repo root
-to get started — note the MCP _requires_ `SANITY_DATASET`.
+Both share the one boot path in `src/stdio.ts`, which reads its
+configuration from the environment: `SANITY_PROJECT_ID`, `SANITY_DATASET`,
+`SANITY_AUTH_TOKEN`, and `WORKFLOW_TAG` are required; `SANITY_API_HOST`,
+`WORKFLOW_RESOURCE_TYPE`, and `WORKFLOW_RESOURCE_ID` are optional. The `dev`
+script loads them from the repo-root `.env`, so copy `.env.example` to `.env`
+to get started. (The CLI has since moved to a `sanity.workflow.ts` config; the
+MCP still takes plain env vars.)
 
 ## API
 
@@ -69,7 +70,7 @@ to get started — note the MCP _requires_ `SANITY_DATASET`.
 import {createEngine} from '@sanity/workflow-engine'
 import {buildTools} from '@sanity/workflow-mcp'
 
-const engine = createEngine({client, workflowResource, tags})
+const engine = createEngine({client, workflowResource, tag})
 const {descriptors, impls} = buildTools(engine)
 
 // descriptors → feed to Anthropic API's `tools:` param, or to an MCP
@@ -84,8 +85,9 @@ const {descriptors, impls} = buildTools(engine)
   the LLM surface until we have an eval case that needs it (and a
   story for the actor identity that would authorise the override).
 - **No `start_instance` tool.** Starting an instance is an operator
-  action that needs context the LLM doesn't have (subject doc id,
-  initial state). Out of scope for v0.1.
+  action that needs context the LLM doesn't have (subject doc ref,
+  initial field values); operators start instances with the workflow
+  CLI's `start` command.
 - **No effect completion.** Same logic — effects are queued by the
   engine and drained by the runtime, not by a human or LLM.
 - **No subscription / streaming.** MCP supports it; we haven't needed

package/dist/index.cjs

@@ -46,31 +46,62 @@ const minimalExample = {
     {
       name: "review",
       title: "Editorial review",
+      // The decision is data: each action writes it, the transition filters
+      // read it. Stage-scoped so a later review round starts with a clean slate.
+      fields: [{ type: "string", name: "decision", title: "Review decision" }],
       activities: [
         {
           name: "review",
           title: "Review the draft",
           activation: "auto",
           actions: [
-            { name: "approve", title: "Approve", status: "done" },
-            { name: "reject", title: "Reject", status: "failed" }
+            {
+              name: "approve",
+              title: "Approve",
+              status: "done",
+              ops: [
+                {
+                  type: "field.set",
+                  target: { field: "decision" },
+                  value: { type: "literal", value: "approve" }
+                }
+              ]
+            },
+            // Rejecting is the reviewer DOING their job — a decision, not a
+            // failure — so it resolves `done` and routes via the field.
+            {
+              name: "reject",
+              title: "Reject",
+              status: "done",
+              ops: [
+                {
+                  type: "field.set",
+                  target: { field: "decision" },
+                  value: { type: "literal", value: "reject" }
+                }
+              ]
+            }
           ]
         }
       ],
       transitions: [
-        { name: "to-approved", title: "Approve and finish", to: "approved" },
-        // Reject flips the activity to `failed`; this routes the instance back.
+        {
+          name: "to-approved",
+          title: "Approve and finish",
+          to: "approved",
+          filter: "$allActivitiesDone && $fields.decision == 'approve'"
+        },
         {
           name: "to-drafting",
           title: "Send back to drafting",
           to: "drafting",
-          filter: "$anyActivityFailed"
+          filter: "$allActivitiesDone && $fields.decision == 'reject'"
         }
       ]
     },
     { 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, 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}
+}, 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. Status is a health axis, not a decision:\n  a routine decision (reject, send back, decline, hold) resolves `'done'` and\n  writes the decision into a field the transition filters read \u2014 reserve\n  `'failed'` for work that genuinely could not complete (e.g. a missed\n  deadline via `failWhen`). `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 field 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 (the engine's exported\n`CONDITION_VARS` inventory is the source of truth): `$allActivitiesDone`,\n`$anyActivityFailed` (booleans over the current stage's activities), `$activities` (the activity\nlist), `$fields` (field values), `$now`, `$self`/`$stage`/`$parent`/`$ancestors`\n(instance identity + position), `$effectStatus` (effect name \u2192 `'done'`/`'failed'`\nof the run queued during the CURRENT stage entry \u2014 the re-entry-safe way to gate\non an effect having drained, e.g.\n`completeWhen: \"defined($effectStatus['my.effect'])\"`), and the caller-scoped\nvars `$actor` (the acting user), `$assigned` (whether the caller is the\nactivity's assignee \u2014 the idiomatic permission gate, used as\n`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 a `decision` field the reject action wrote), not to a terminal stage.\n  Reserve terminal stages for completion and for explicit\n  cancellation/abandonment \u2014 a workflow should not dead-end just because\n  something was declined.\n- **Decisions are fields, not failures.** When a stage branches on a human\n  decision, declare a stage-scoped `string` field (stage scope resets on\n  re-entry, so loop-backs start clean), have each deciding action `field.set`\n  it, and gate every outbound transition on its value (Example 2). Do not\n  encode a decision as `status: 'failed'` + `$anyActivityFailed` \u2014 reporting\n  would count healthy loops as failures.\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
 
@@ -86,13 +117,13 @@ ${JSON.stringify(reviewLoopExample, null, 2)}
 `, LIST_CAP = 25, TOOL_DESCRIPTORS = [
   {
     name: "list_workflow_instances",
-    description: "List workflow instances in the configured workspace. 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 \u2014 id, workflow type id and human-readable `workflowTitle`, current stage, whether the instance is done, and (when the workflow has a conventional 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 " + String(25) + " results. Do NOT use this to inspect a single known instance \u2014 use get_workflow_state for that, the response will be richer.",
+    description: "List workflow instances in the configured workspace. 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 \u2014 id, `definition` (the workflow definition's `name`) and human-readable `workflowTitle`, current stage, whether the instance is done, and (when the workflow has a conventional 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 " + String(25) + " results. Do NOT use this to inspect a single known instance \u2014 use get_workflow_state for that, the response will be richer.",
     input_schema: {
       type: "object",
       properties: {
         definition: {
           type: "string",
-          description: "Optional. Restrict to instances of this workflow definition (e.g. 'article-review')."
+          description: "Optional. Restrict to instances of this workflow definition, by its `name` (e.g. 'article-review')."
         },
         status: {
           type: "string",
@@ -150,6 +181,11 @@ ${JSON.stringify(reviewLoopExample, null, 2)}
         action: {
           type: "string",
           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", "activity", "action"],
@@ -235,7 +271,11 @@ function projectSummary(doc, subjectTitles) {
     ...subject !== void 0 ? { subject } : {}
   };
 }
-function projectState(instance, evaluation, subjectTitles) {
+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);
@@ -279,15 +319,21 @@ function isInstanceDone(instance) {
     return !1;
   }
 }
-const DISABLED_REASON_TEXT = {
-  "filter-failed": "action's filter condition did not hold for this actor",
-  "activity-not-active": "activity is not currently active",
-  "stage-terminal": "stage is terminal \u2014 no further actions possible",
-  "instance-completed": "instance has already completed",
-  "requirements-unmet": "activity'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): ${workflowEngine.deniedGuardLabels(reason.denied).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) {
@@ -352,11 +398,11 @@ 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);
@@ -364,8 +410,9 @@ function buildTools(engine, options = {}) {
         instanceId: input.instance_id,
         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.
@@ -387,33 +434,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", "activity", "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,
-    activity: obj.activity,
-    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) {
@@ -429,14 +487,22 @@ async function listInstances(engine, input) {
     instances: filtered.map((doc) => projectSummary(doc, subjectTitles))
   };
 }
-async function getInstanceState(engine, instanceId, accessOverride) {
-  const evaluation = await engine.evaluateInstance({
+async function getInstanceState({
+  engine,
+  instanceId,
+  accessOverride
+}) {
+  const evaluation = await engine.evaluate({
     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 } : {}