@sanity/workflow-mcp 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanity, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# @sanity/workflow-mcp
+
+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.
+
+## What the tools do
+
+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.                                          |
+| `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.                                           |
+
+Author a definition (both pure, engine-independent, neither deploys):
+
+| Tool                           | Read or write | What it's for                                                                                                                                     |
+| ------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `get_workflow_authoring_guide` | read          | Return the DSL guide an agent reads before authoring — shape, GROQ built-ins, sugars, modeling defaults, and two worked JSON examples.            |
+| `validate_workflow_definition` | read          | Check an authored definition the way deploy does (structure + invariants + GROQ). Returns the desugared definition or a path-prefixed error list. |
+
+Each descriptor's `description` field is written for an LLM consumer
+— it says what the tool does, when to use it, and what _not_ to use
+it for. See `src/tools.ts`.
+
+## Why this surface, why no more
+
+The CLI surface is shaped for a human at a terminal who already knows
+the verbs. An MCP is consumed by an LLM that figures out which tool
+to use from prose alone. Adding tools beyond the minimum increases
+the search space the LLM has to navigate. We stay narrow until the
+evals tell us the LLM is reaching for something we don't expose. The
+authoring pair earns its place because authoring-from-a-description is
+eval-backed; the agent generates the definition and self-corrects against
+`validate_workflow_definition` (deploy stays a deliberate human step).
+
+## Run the stdio server
+
+In development (TypeScript sources via `tsx`):
+
+```bash
+pnpm --filter @sanity/workflow-mcp dev
+```
+
+Or run the built bin — the entry an MCP client spawns. After `pnpm build`
+it's `bin/run.js`, and once the package is published this is what
+`npx @sanity/workflow-mcp` resolves to:
+
+```bash
+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`.
+
+## API
+
+```ts
+import {createEngine} from '@sanity/workflow-engine'
+import {buildTools} from '@sanity/workflow-mcp'
+
+const engine = createEngine({client, workflowResource, tags})
+const {descriptors, impls} = buildTools(engine)
+
+// descriptors → feed to Anthropic API's `tools:` param, or to an MCP
+//   `tools/list` handler.
+// impls       → call from a `tools/call` handler, or from the eval
+//   harness directly (in-process, no transport).
+```
+
+## Open gaps
+
+- **No `set_stage` tool.** Admin override; intentionally omitted from
+  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.
+- **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
+  it yet. Pull-based polling via `get_workflow_state` covers the eval
+  cases.
+- **No `deploy_workflow_definition`.** `validate_workflow_definition` is
+  the authoring tool; a human deploys the validated definition via the
+  CLI. Deploy is a Content Lake write that inherits the actor-identity
+  story, so it stays out of the LLM surface for now.

package/bin/run.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// Production entry for the published package: loads the compiled boot
+// path from ./dist/stdio.js (built by pkg-utils via the `./stdio`
+// export). The dev counterpart, bin/workflow-mcp.ts, loads the TS
+// source through tsx instead.
+
+import {runStdioServer} from '../dist/stdio.js'
+
+await runStdioServer()

package/dist/index.cjs

@@ -0,0 +1,455 @@
+"use strict";
+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" } }],
+  stages: [
+    {
+      name: "review",
+      title: "Review",
+      tasks: [
+        {
+          name: "decide",
+          title: "Decide",
+          activation: "auto",
+          actions: [{ name: "approve", title: "Approve", status: "done" }]
+        }
+      ],
+      transitions: [{ name: "to-approved", title: "Approve and finish", to: "approved" }]
+    },
+    { name: "approved", title: "Approved", description: "Terminal \u2014 no transitions out." }
+  ]
+}, 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" } }],
+  stages: [
+    {
+      name: "drafting",
+      title: "Drafting",
+      tasks: [
+        {
+          name: "write",
+          title: "Write the draft",
+          activation: "auto",
+          actions: [{ name: "submit", title: "Submit for review", status: "done" }]
+        }
+      ],
+      transitions: [{ name: "to-review", title: "Send to review", to: "review" }]
+    },
+    {
+      name: "review",
+      title: "Editorial review",
+      tasks: [
+        {
+          name: "review",
+          title: "Review the draft",
+          activation: "auto",
+          actions: [
+            { name: "approve", title: "Approve", status: "done" },
+            { name: "reject", title: "Reject", status: "failed" }
+          ]
+        }
+      ],
+      transitions: [
+        { name: "to-approved", title: "Approve and finish", to: "approved" },
+        // Reject flips the task to `failed`; this routes the instance back.
+        {
+          name: "to-drafting",
+          title: "Send back to drafting",
+          to: "drafting",
+          filter: "$anyTaskFailed"
+        }
+      ]
+    },
+    { 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}
+
+## Examples
+
+### Example 1 \u2014 ${minimalExample.title} (minimal: one stage, one action)
+\`\`\`json
+${JSON.stringify(minimalExample, null, 2)}
+\`\`\`
+
+### Example 2 \u2014 ${reviewLoopExample.title} (review loop: reject routes back)
+\`\`\`json
+${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.",
+    input_schema: {
+      type: "object",
+      properties: {
+        definition: {
+          type: "string",
+          description: "Optional. Restrict to instances of this workflow definition (e.g. 'article-review')."
+        },
+        status: {
+          type: "string",
+          enum: ["in_flight", "done", "any"],
+          description: "Optional. 'in_flight' returns instances not in a terminal stage; 'done' returns completed/aborted; 'any' returns both. Defaults to 'in_flight'."
+        }
+      },
+      additionalProperties: !1
+    }
+  },
+  {
+    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.",
+    input_schema: {
+      type: "object",
+      properties: {
+        instance_id: {
+          type: "string",
+          description: "The workflow instance id."
+        }
+      },
+      required: ["instance_id"],
+      additionalProperties: !1
+    }
+  },
+  {
+    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.",
+    input_schema: {
+      type: "object",
+      properties: {
+        instance_id: {
+          type: "string",
+          description: "The workflow instance id."
+        }
+      },
+      required: ["instance_id"],
+      additionalProperties: !1
+    }
+  },
+  {
+    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.",
+    input_schema: {
+      type: "object",
+      properties: {
+        instance_id: {
+          type: "string",
+          description: "The workflow instance id."
+        },
+        task: {
+          type: "string",
+          description: "The id of the task on the current stage. Must be one of the tasks 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."
+        }
+      },
+      required: ["instance_id", "task", "action"],
+      additionalProperties: !1
+    }
+  },
+  {
+    name: "get_workflow_authoring_guide",
+    description: "Get the guide for authoring a workflow definition: the DSL shape, the GROQ condition built-ins, the sugars, the rules the validator enforces, and two worked JSON examples. Call this BEFORE writing a definition from a description, then generate the JSON and check it with validate_workflow_definition. Pure read; takes no arguments.",
+    input_schema: {
+      type: "object",
+      properties: {},
+      additionalProperties: !1
+    }
+  },
+  {
+    name: "validate_workflow_definition",
+    description: "Validate a workflow definition you have authored. Runs the same checks as deploy \u2014 structural shape, cross-field invariants (e.g. every transition target is a declared stage), and GROQ syntax \u2014 without writing anything. Returns `{valid:true, definition}` where `definition` is the desugared form that would deploy, or `{valid:false, error}` with every problem listed and path-prefixed. This does NOT deploy \u2014 a human deploys the validated definition via the CLI. Call get_workflow_authoring_guide first for the shape; on `valid:false`, fix the reported problems and validate again.",
+    input_schema: {
+      type: "object",
+      properties: {
+        definition: {
+          type: "object",
+          description: "The workflow definition to validate, as a JSON object in authoring shape. See get_workflow_authoring_guide for the shape and examples."
+        }
+      },
+      required: ["definition"],
+      additionalProperties: !1
+    }
+  }
+], SUBJECT_ENTRY_NAME = "subject";
+function getSubjectGdr(instance) {
+  const entry = instance.fields.find((s) => s._type === "doc.ref" && s.name === SUBJECT_ENTRY_NAME);
+  if (!(entry === void 0 || entry._type !== "doc.ref"))
+    return entry.value?.id;
+}
+async function fetchSubjectTitles(engine, instances) {
+  const docIdToGdr = /* @__PURE__ */ new Map();
+  for (const inst of instances) {
+    const gdr = getSubjectGdr(inst);
+    if (gdr !== void 0)
+      try {
+        docIdToGdr.set(workflowEngine.extractDocumentId(gdr), gdr);
+      } catch {
+      }
+  }
+  if (docIdToGdr.size === 0) return /* @__PURE__ */ new Map();
+  let docs;
+  try {
+    docs = await engine.client.fetch(
+      "*[_id in $docIds]{_id, title}",
+      { docIds: Array.from(docIdToGdr.keys()) }
+    );
+  } catch (err) {
+    return process.stderr.write(
+      `workflow-mcp: subject-title lookup failed; returning refs without titles: ${err instanceof Error ? err.message : String(err)}
+`
+    ), /* @__PURE__ */ new Map();
+  }
+  const out = /* @__PURE__ */ new Map();
+  for (const doc of docs) {
+    const gdr = docIdToGdr.get(doc._id);
+    gdr !== void 0 && typeof doc.title == "string" && doc.title !== "" && out.set(gdr, doc.title);
+  }
+  return out;
+}
+function buildSubject(instance, subjectTitles) {
+  const gdr = getSubjectGdr(instance);
+  if (gdr === void 0) return;
+  const title = subjectTitles.get(gdr);
+  return title !== void 0 ? { ref: gdr, title } : { ref: gdr };
+}
+function projectSummary(doc, subjectTitles) {
+  const definition = JSON.parse(doc.definitionSnapshot), stageTitle = definition.stages.find((s) => s.name === doc.currentStage)?.title, workflowTitle = definition.title, subject = buildSubject(doc, subjectTitles);
+  return {
+    instanceId: doc._id,
+    definition: doc.definition,
+    ...workflowTitle !== void 0 ? { workflowTitle } : {},
+    currentStage: doc.currentStage,
+    ...stageTitle !== void 0 ? { currentStageTitle: stageTitle } : {},
+    lastChangedAt: doc.lastChangedAt,
+    done: isInstanceDone(doc),
+    ...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) => {
+    const actions = te.actions.map((ae) => {
+      const verdict = workflowEngine.actionVerdict(te, ae);
+      return {
+        action: verdict.action,
+        ...verdict.title !== void 0 ? { title: verdict.title } : {},
+        allowed: verdict.allowed,
+        ...verdict.allowed === !1 && verdict.disabledReason !== void 0 ? { disabledReason: formatDisabledReason(verdict.disabledReason) } : {}
+      };
+    });
+    return {
+      task: te.task.name,
+      ...te.task.title !== void 0 ? { title: te.task.title } : {},
+      ...te.task.description !== void 0 ? { description: te.task.description } : {},
+      status: te.status,
+      actions
+    };
+  }), recentHistory = instance.history.slice(-8).toReversed().map((entry) => ({
+    at: entry.at,
+    type: entry._type,
+    summary: summariseHistoryEntry(entry)
+  })), subject = buildSubject(instance, subjectTitles);
+  return {
+    instanceId: instance._id,
+    definition: instance.definition,
+    ...workflowTitle !== void 0 ? { workflowTitle } : {},
+    currentStage: instance.currentStage,
+    ...stageTitle !== void 0 ? { currentStageTitle: stageTitle } : {},
+    done: isInstanceDone(instance),
+    ...subject !== void 0 ? { subject } : {},
+    tasks,
+    recentHistory
+  };
+}
+function isInstanceDone(instance) {
+  if (instance.completedAt !== void 0) return !0;
+  try {
+    const stage = JSON.parse(instance.definitionSnapshot).stages.find((s) => s.name === instance.currentStage);
+    return stage !== void 0 && workflowEngine.isTerminalStage(stage);
+  } catch {
+    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, " ");
+}
+function summariseHistoryEntry(entry) {
+  switch (entry._type) {
+    case "stageEntered":
+      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 "actionFired":
+      return `action "${String(entry.action)}" fired on task "${String(entry.task)}"`;
+    case "transitionFired":
+      return `transition fired: "${String(entry.fromStage)}" \u2192 "${String(entry.toStage)}"`;
+    case "effectQueued":
+      return `effect "${String(entry.effect)}" queued`;
+    case "effectCompleted":
+      return `effect "${String(entry.effect)}" completed (${String(entry.status)})`;
+    case "spawned":
+      return `spawned child workflow from task "${String(entry.task)}"`;
+    default:
+      return entry._type;
+  }
+}
+function diagnosisSummary(diagnosis) {
+  switch (diagnosis.state) {
+    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.`;
+    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.`;
+    case "completed":
+      return `Completed at ${diagnosis.at}.`;
+    case "aborted":
+      return diagnosis.reason !== void 0 ? `Aborted at ${diagnosis.at}: ${diagnosis.reason}.` : `Aborted at ${diagnosis.at}.`;
+    case "stuck":
+      return stuckSummary(diagnosis.cause);
+  }
+}
+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.`;
+    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 "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.";
+    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.`;
+  }
+}
+function buildTools(engine, options = {}) {
+  const accessOverride = options.access;
+  return { descriptors: TOOL_DESCRIPTORS, impls: {
+    list_workflow_instances: async (rawInput) => {
+      const input = parseListInput(rawInput);
+      return listInstances(engine, input);
+    },
+    get_workflow_state: async (rawInput) => {
+      const input = parseInstanceIdInput(rawInput, "get_workflow_state");
+      return getInstanceState(engine, input.instance_id, accessOverride);
+    },
+    diagnose_workflow: async (rawInput) => {
+      const input = parseInstanceIdInput(rawInput, "diagnose_workflow");
+      return getInstanceDiagnosis(engine, input.instance_id, accessOverride);
+    },
+    fire_action: async (rawInput) => {
+      const input = parseFireActionInput(rawInput);
+      return await engine.fireAction({
+        instanceId: input.instance_id,
+        task: input.task,
+        action: input.action,
+        ...accessOverride !== void 0 ? { access: accessOverride } : {}
+      }), getInstanceState(engine, input.instance_id, accessOverride);
+    },
+    // Authoring tools — engine-independent: they teach and check the DSL, they
+    // don't touch the lake or an instance.
+    get_workflow_authoring_guide: async () => AUTHORING_GUIDE,
+    validate_workflow_definition: async (rawInput) => {
+      const { definition } = parseValidateInput(rawInput);
+      try {
+        const stored = define.defineWorkflow(definition);
+        return workflowEngine.validateDefinition(stored), { valid: !0, definition: stored };
+      } catch (err) {
+        return { valid: !1, error: err instanceof Error ? err.message : String(err) };
+      }
+    }
+  } };
+}
+function parseListInput(raw) {
+  if (raw === null || typeof raw != "object")
+    return { status: "in_flight" };
+  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) {
+  if (raw === null || typeof raw != "object")
+    throw new Error("validate_workflow_definition: input must be an object");
+  const obj = raw;
+  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 };
+}
+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`);
+  return {
+    instance_id: obj.instance_id,
+    task: obj.task,
+    action: obj.action
+  };
+}
+async function listInstances(engine, input) {
+  const groqParts = [`_type == "${workflowEngine.WORKFLOW_INSTANCE_TYPE}"`];
+  input.definition !== void 0 && groqParts.push("definition == $definition");
+  const groq = `*[${groqParts.join(" && ")} && ${workflowEngine.tagScopeFilter()}] | order(lastChangedAt desc)[0...${LIST_CAP}]`, params = {};
+  input.definition !== void 0 && (params.definition = input.definition);
+  const filtered = (await engine.query({ groq, params })).filter((doc) => {
+    const done = isInstanceDone(doc);
+    return input.status === "done" ? done : input.status === "in_flight" ? !done : !0;
+  }), subjectTitles = await fetchSubjectTitles(engine, filtered);
+  return {
+    instances: filtered.map((doc) => projectSummary(doc, subjectTitles))
+  };
+}
+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);
+}
+async function getInstanceDiagnosis(engine, instanceId, accessOverride) {
+  const { diagnosis, remediations } = await engine.diagnose({
+    instanceId,
+    ...accessOverride !== void 0 ? { access: accessOverride } : {}
+  });
+  return {
+    instanceId,
+    state: diagnosis.state,
+    summary: diagnosisSummary(diagnosis),
+    ...diagnosis.state === "stuck" ? { cause: diagnosis.cause.kind } : {},
+    remediations
+  };
+}
+exports.buildTools = buildTools;
+//# sourceMappingURL=index.cjs.map