@ratifia/mcp 0.5.0 → 0.9.0

package/README.md

@@ -44,6 +44,12 @@ Point separate registrations at different environments by giving each its own `R
 Clone, then `npm install && npm run build` (rebuild after source changes). Use
 `npx tsx src/index.ts` instead of the built file to skip the build step while iterating.
 
+`npm run validate` checks the built server against the MCP protocol using the
+[Inspector CLI](https://modelcontextprotocol.io/docs/tools/inspector/cli) — the
+handshake, the advertised tool surface and schemas, and a full create → await →
+resolve cycle — driven against a stub API, so it needs no key and creates no
+real decisions. CI runs it on every push.
+
 ## Configuration (env)
 
 | Var | Required | Default | Purpose |
@@ -52,9 +58,26 @@ Clone, then `npm install && npm run build` (rebuild after source changes). Use
 | `RATIFIA_API_URL` | | `https://api.ratifia.com` | Ratifia API base. |
 | `RATIFIA_APP_URL` | | `https://app.ratifia.com` | Dashboard base for decision links. |
 | `RATIFIA_APPROVER_EMAIL` | | — | Who the decision is assigned to / notified. |
-| `RATIFIA_POLICY` | | — | Named policy whose route decides **how** you're notified (e.g. to your phone). |
+| `RATIFIA_POLICY` | | — | The **key** of a policy deciding **who** reviews and the quorum they need. It must exist in your org: an unknown key is a tool error, and the `gate` hook denies. |
+| `RATIFIA_WORKFLOW` | | `ratifia-mcp` (`ratifia-gate` for the hook) | The **workflow** decisions are filed under — the category the dashboard's Workflow filter groups by, e.g. `deploys` or `billing-agent`. A `request_decision` call can override it. |
+
+Who is notified is decided **inside Ratifia** by your org's policy — this server is a thin request/verdict bridge.
+
+### Filing decisions: workflow and step
+
+Every decision carries two labels:
 
-Routing (email / SMS / escalation) is decided **inside Ratifia** by your org's policy — this server is a thin request/verdict bridge.
+- **Workflow** (`workflowRef`) — the *category*: "deploys", "refunds". The dashboard's Workflow filter groups by it. Set a default per server with `RATIFIA_WORKFLOW`, or pass `workflow` to `request_decision`.
+- **Step** (`stepRef`) — the *specific instance* inside it: "api-v2.3-to-prod", "refund-INV-1042". Pass `step` to `request_decision`; it defaults to the title.
+
+```
+request_decision(
+  title: "Deploy API to prod?",
+  question: "Ship v2.3 to production?",
+  workflow: "deploys",
+  step: "api-v2.3-to-prod"
+)
+```
 
 ## Tools
 
@@ -65,6 +88,29 @@ Routing (email / SMS / escalation) is decided **inside Ratifia** by your org's p
 | `await_decision` | Block until the verdict lands (or a max wait elapses). |
 | `list_pending_decisions` | The agent's inbox — what's outstanding. |
 | `cancel_decision` | Withdraw a decision the agent no longer needs. |
+| `attach_evidence` | Attach immutable material the decision is judged **on** (a Slack thread, an email). |
+
+### Waiting for a verdict
+
+`await_decision` blocks for `max_wait_seconds` (default **90**, max **110**) and
+returns the moment the human answers. If they haven't yet, it comes back
+`pending` with `timed_out: true` — **that's normal, just call it again.**
+
+The 110s ceiling is deliberate: agent harnesses background a tool call that runs
+much past ~120s, so a longer block doesn't reach the agent sooner, it just lands
+late. While waiting, the server polls Ratifia every 1s for the first 15s (most
+decisions land there), then eases to 3s and 5s.
+
+Transient failures — network blips, 429s, 5xx — are retried internally. One that
+still surfaces comes back as data rather than an exception:
+
+```json
+{ "error": "unreachable", "message": "...", "retryable": true }
+```
+
+On `retryable: true` the call is worth repeating; the decision is still open and
+the human has already been notified, so **retry rather than requesting a second
+decision.**
 
 ## Decision shapes
 
@@ -121,6 +167,39 @@ request_decision(
 `tool_args` is optional (some tools take none); it's ignored unless `tool_name`
 is set.
 
+### Evidence — what the decision was made *on*
+
+A decision often rests on something outside the ask: the Slack thread where a
+customer complained, the email that set the terms, the policy clause that
+permits it. Attach that material and it becomes part of the decision's record.
+
+```
+request_decision(
+  title: "Approve refund?",
+  question: "This exceeds the $5,000 auto-approve floor.",
+  evidence: [{
+    kind: "slack_thread",
+    title: "#support — refund thread",
+    source_url: "https://acme.slack.com/archives/C123/p1700000000",
+    body: "ana: customer is furious\nbo: refund is within policy"
+  }]
+)
+```
+
+Found something after you asked? `attach_evidence(decision_id, ...)` appends it.
+
+Three properties worth knowing, because they shape how you should use it:
+
+- **Send the text, not just a link.** The stored snapshot (and its sha256) is
+  what the audit trail keeps. A permalink can be edited or deleted after the
+  fact; the snapshot can't.
+- **Sealed at the verdict.** Evidence can only be attached while the decision is
+  pending — so attach *before* you `await_decision`. Afterwards you get
+  `http_409` with `retryable: false`. That's the point: the record shows exactly
+  what the reviewer could see.
+- **Re-attaching is free.** Identical content dedupes on its hash, so a retry
+  never produces a second panel for the reviewer.
+
 ## How it works
 
 1. The agent calls `request_decision` before a consequential/irreversible step (deploy, delete, spend, send externally), an ambiguous call it shouldn't guess, or to get a human to pick/refine something.

package/dist/index.js

@@ -12,6 +12,8 @@
  *                        so the agent doesn't have to poll in a loop.
  *   - list_pending_decisions : the agent's own inbox — what's outstanding.
  *   - cancel_decision  : withdraw a decision the agent no longer needs.
+ *   - attach_evidence  : append immutable material the decision is judged ON
+ *                        (a Slack thread, an email). Sealed at the verdict.
  *
  * Routing (HOW a human is reached — email/SMS/phone/escalation) is decided
  * INSIDE Ratifia by the org's policy/route, never by this client. The MCP is a
@@ -23,36 +25,148 @@
  *   RATIFIA_API_KEY         org-scoped worker API key (required)
  *   RATIFIA_APP_URL         dashboard base for the decision link (default https://app.ratifia.com)
  *   RATIFIA_APPROVER_EMAIL  who the decision is assigned to / notified
- *   RATIFIA_POLICY          optional: policy name whose route decides HOW you're notified
+ *   RATIFIA_POLICY          optional: policy key deciding who reviews (must exist in the org)
  *                           (e.g. a route to your phone)
+ *   RATIFIA_WORKFLOW        optional: the workflow (category) decisions are filed under —
+ *                           what the dashboard's Workflow filter groups by. Defaults to
+ *                           `ratifia-mcp` (tools) / `ratifia-gate` (the gate hook).
  */
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { McpServer } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
+import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 const API_URL = (process.env.RATIFIA_API_URL ?? 'https://api.ratifia.com').replace(/\/+$/, '');
 const API_KEY = process.env.RATIFIA_API_KEY;
 const APP_URL = (process.env.RATIFIA_APP_URL ?? 'https://app.ratifia.com').replace(/\/+$/, '');
 const APPROVER_EMAIL = process.env.RATIFIA_APPROVER_EMAIL;
 const POLICY = process.env.RATIFIA_POLICY;
+const WORKFLOW = process.env.RATIFIA_WORKFLOW;
+/**
+ * Where a decision is filed. `workflowRef` is the category (the dashboard's
+ * Workflow filter groups by it — e.g. "deploys", "billing-agent");
+ * `stepRef` is the specific instance within it. Blank or whitespace-only values
+ * fall back rather than filing under an empty name.
+ */
+function label(value, fallback, max) {
+    const v = value?.trim();
+    return (v ? v : fallback).slice(0, max);
+}
 if (!API_KEY) {
     console.error('RATIFIA_API_KEY is required');
     process.exit(1);
 }
+/** Per-request ceiling. Node's fetch defaults run to ~300s, long enough to
+ *  outlive a whole await_decision budget and strand the caller on a dead
+ *  connection well past the deadline it was promised. */
+const REQUEST_TIMEOUT_MS = 15_000;
+/** An API failure that knows whether trying again is worth anything. */
+class ApiError extends Error {
+    /** null = no response at all (network, DNS, or our own timeout). */
+    status;
+    /** The API's machine-readable `error` code, when it sent one (e.g. `unknown_policy`). */
+    code;
+    constructor(message, status, code = null) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+    get retryable() {
+        if (this.status === null)
+            return true;
+        if (this.status === 408 || this.status === 429)
+            return true;
+        return this.status >= 500;
+    }
+}
+function errorCode(body) {
+    try {
+        const code = JSON.parse(body).error;
+        return typeof code === 'string' ? code : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** FN-255: RATIFIA_POLICY names a policy the org doesn't have. A misconfiguration, not an outage. */
+const isUnknownPolicy = (err) => err instanceof ApiError && err.code === 'unknown_policy';
+const unknownPolicyMessage = () => `RATIFIA_POLICY "${POLICY}" is not a policy key in this Ratifia org. Create a policy with this key in the Ratifia dashboard (Policies) or fix RATIFIA_POLICY in this MCP server's config. No decision was created: do not proceed with the action.`;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** `idempotencyKey` makes a retried write safe to collapse server-side; mint it
+ *  once per tool invocation so two independent asks never share one. */
 async function api(path, init) {
-    const res = await fetch(`${API_URL}${path}`, {
-        ...init,
-        headers: {
-            'Content-Type': 'application/json',
-            Authorization: `Bearer ${API_KEY}`,
-            ...(init?.headers ?? {}),
-        },
-    });
-    const text = await res.text();
-    if (!res.ok)
-        throw new Error(`Ratifia ${path} → ${res.status}: ${text.slice(0, 300)}`);
-    return (text ? JSON.parse(text) : {});
+    const { idempotencyKey, ...rest } = init ?? {};
+    try {
+        const res = await fetch(`${API_URL}${path}`, {
+            ...rest,
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${API_KEY}`,
+                ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
+                ...(rest.headers ?? {}),
+            },
+        });
+        const text = await res.text();
+        if (!res.ok)
+            throw new ApiError(`Ratifia ${path} → ${res.status}: ${text.slice(0, 300)}`, res.status, errorCode(text));
+        return (text ? JSON.parse(text) : {});
+    }
+    catch (err) {
+        if (err instanceof ApiError)
+            throw err;
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new ApiError(`Ratifia ${path} → unreachable: ${msg}`, null);
+    }
+}
+/** Retry transient failures with backoff. One blip used to abort an entire
+ *  wait, which reads to the agent as "this step failed" — the expensive
+ *  outcome, since it may then re-ask a human who was already notified. */
+async function apiRetry(fn, attempts = 3) {
+    for (let i = 0;; i++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            if (!(err instanceof ApiError) || !err.retryable || i >= attempts - 1)
+                throw err;
+            await sleep(500 * 2 ** i); // 500ms, then 1s
+        }
+    }
 }
 const getDecision = (id) => api(`/v1/worker/decisions/${encodeURIComponent(id)}`, { method: 'GET' });
+/** Evidence lives on the dual-auth decisions route, not /worker — an API key
+ *  authenticates there exactly as a dashboard session does. */
+const attachEvidence = (decisionId, e) => api(`/v1/decisions/${encodeURIComponent(decisionId)}/evidence`, {
+    method: 'POST',
+    body: JSON.stringify({
+        kind: e.kind,
+        ...(e.title ? { title: e.title } : {}),
+        ...(e.source_system ? { sourceSystem: e.source_system } : {}),
+        ...(e.source_url ? { sourceUrl: e.source_url } : {}),
+        ...(e.body ? { body: e.body } : {}),
+        ...(e.captured_at ? { capturedAt: e.captured_at } : {}),
+    }),
+});
+/** Poll fast while the human is plausibly still at the keyboard, then back off.
+ *  Most decisions land in the first few seconds, and a flat interval made every
+ *  one of those wait out the full tick before the agent could move. */
+const pollIntervalMs = (elapsedMs) => elapsedMs < 15_000 ? 1_000 : elapsedMs < 60_000 ? 3_000 : 5_000;
+/** Poll until the decision leaves PENDING or the budget runs out (returns it
+ *  still PENDING in that case). Transient API failures are retried, not fatal. */
+async function waitForDecision(decisionId, budgetMs) {
+    const start = Date.now();
+    let d = await apiRetry(() => getDecision(decisionId));
+    for (;;) {
+        if (d.status !== 'PENDING')
+            return d;
+        const elapsed = Date.now() - start;
+        const wait = pollIntervalMs(elapsed);
+        if (elapsed + wait > budgetMs)
+            return d;
+        await sleep(wait);
+        d = await apiRetry(() => getDecision(decisionId));
+    }
+}
 /** Agent-facing shape for a decision's current state. */
 const formatDecision = (d) => ({
     decision_id: d.id,
@@ -74,6 +188,33 @@ const formatDecision = (d) => ({
 const asToolResult = (payload) => ({
     content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
 });
+/** Report an API failure as a structured result rather than an MCP exception,
+ *  so the agent can retry on `retryable` instead of treating the step as lost
+ *  and abandoning a decision a human may already be looking at. */
+const asToolError = (err) => isUnknownPolicy(err)
+    ? asToolResult({ error: 'unknown_policy', policy: POLICY, message: unknownPolicyMessage(), retryable: false })
+    : asToolResult({
+        error: err instanceof ApiError && err.status ? `http_${err.status}` : 'unreachable',
+        message: err instanceof Error ? err.message : String(err),
+        retryable: err instanceof ApiError ? err.retryable : true,
+    });
+/** FN-239: one piece of evidence, shared by request_decision and attach_evidence. */
+const evidenceItemSchema = z.object({
+    kind: z
+        .enum(['slack_thread', 'email', 'document', 'link', 'note'])
+        .describe("What this material is. 'slack_thread' / 'email' for a captured conversation, 'document' for a doc or policy excerpt, 'link' for a bare reference with no text, 'note' for your own written rationale."),
+    title: z.string().optional().describe('Short reviewer-facing label, e.g. "#incidents — refund thread".'),
+    source_system: z.string().optional().describe('Where it came from, e.g. "slack", "email", "notion".'),
+    source_url: z.string().optional().describe('Deep link back to the original, for provenance.'),
+    body: z
+        .string()
+        .optional()
+        .describe('The actual text, captured. Send the content, not just a link — a link can be edited or deleted after the decision, and the stored snapshot is what the audit trail keeps. Required unless kind is "link".'),
+    captured_at: z
+        .string()
+        .optional()
+        .describe('ISO timestamp of when the material was originally written, if it predates now.'),
+});
 function buildResponseSpec(responseType, options, allowMultiple) {
     if (!responseType || responseType === 'approval')
         return undefined;
@@ -152,14 +293,17 @@ async function runGate() {
     const budgetMs = Math.max(10, Number(process.env.RATIFIA_GATE_TIMEOUT_SEC ?? 240)) * 1000;
     let decisionId;
     try {
-        const externalRunId = `gate-${Date.now()}-${Math.round(Math.random() * 1e6)}`;
-        const res = await api('/v1/worker/decisions', {
+        // One id per hook invocation: retries below collapse into this decision,
+        // while a genuinely separate tool call mints its own and gates separately.
+        const externalRunId = `gate-${randomUUID()}`;
+        const res = await apiRetry(() => api('/v1/worker/decisions', {
             method: 'POST',
+            idempotencyKey: externalRunId,
             body: JSON.stringify({
                 engine: 'mcp',
                 externalRunId,
                 stepRef: `tool:${toolName}`.slice(0, 80),
-                workflowRef: 'ratifia-gate',
+                workflowRef: label(WORKFLOW, 'ratifia-gate', 100),
                 ...(APPROVER_EMAIL ? { assigneeEmail: APPROVER_EMAIL } : {}),
                 ...(POLICY ? { policy: POLICY } : {}),
                 required: true,
@@ -168,7 +312,7 @@ async function runGate() {
                     blocks: [{ kind: 'tool_call', title: 'Tool call', tool: toolName, args: toolInput }],
                 },
             }),
-        });
+        }));
         // Policy gate resolved "no approval needed" → let it run.
         if (res.approvalNeeded === false || !res.decisionId) {
             return gateDecision('allow', 'no approval required by policy');
@@ -176,26 +320,24 @@ async function runGate() {
         decisionId = res.decisionId;
     }
     catch (err) {
+        // A bad RATIFIA_POLICY denies even with fail-open: fail-open is for Ratifia
+        // being unreachable, and letting a misconfigured gate wave every tool call
+        // through is exactly the outage it exists to prevent.
+        if (isUnknownPolicy(err))
+            return gateDecision('deny', unknownPolicyMessage());
         const msg = err instanceof Error ? err.message : String(err);
         return gateDecision(failOpen ? 'allow' : 'deny', `ratifia gate unreachable: ${msg}`);
     }
     // Block until the human answers (or the budget elapses → fail-closed).
-    const start = Date.now();
-    const pollMs = 4000;
     try {
-        for (;;) {
-            const d = await getDecision(decisionId);
-            if (d.status === 'APPROVED')
-                return gateDecision('allow', d.note ?? 'approved by reviewer');
-            if (d.status === 'REJECTED')
-                return gateDecision('deny', d.note ?? 'rejected by reviewer');
-            if (d.status !== 'PENDING')
-                return gateDecision('deny', `decision ${d.status.toLowerCase()}`);
-            if (Date.now() - start + pollMs > budgetMs) {
-                return gateDecision(failOpen ? 'allow' : 'deny', 'timed out waiting for approval');
-            }
-            await new Promise((r) => setTimeout(r, pollMs));
-        }
+        const d = await waitForDecision(decisionId, budgetMs);
+        if (d.status === 'APPROVED')
+            return gateDecision('allow', d.note ?? 'approved by reviewer');
+        if (d.status === 'REJECTED')
+            return gateDecision('deny', d.note ?? 'rejected by reviewer');
+        if (d.status !== 'PENDING')
+            return gateDecision('deny', `decision ${d.status.toLowerCase()}`);
+        return gateDecision(failOpen ? 'allow' : 'deny', 'timed out waiting for approval');
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -207,7 +349,7 @@ if (process.argv[2] === 'gate') {
     await runGate();
     process.exit(0);
 }
-const server = new McpServer({ name: 'ratifia', version: '0.5.0' }, {
+const server = new McpServer({ name: 'ratifia', version: '0.7.0' }, {
     instructions: [
         'Ratifia lets you request a HUMAN decision or input mid-task (human-in-the-loop) and resume once it is answered.',
         '',
@@ -215,58 +357,78 @@ const server = new McpServer({ name: 'ratifia', version: '0.5.0' }, {
         '',
         'Workflow:',
         '1. Call request_decision with a short title, a precise question, and enough context to decide (the command/diff/options + tradeoffs). Set timeout_minutes if it is time-sensitive.',
+        'Filing: set `workflow` to the project or ongoing effort the decision belongs to (e.g. the repo name, "billing-refunds") so a human can see related decisions together in the dashboard, and reuse the exact same string every time. Put what is specific to this decision (the release, record, environment) in `step`, e.g. "deploy-v2.3-prod". Without them every decision lands in one "ratifia-mcp" bucket.',
         '2. It returns a decision_id (+ url). The human is notified and may be away from their keyboard, so a verdict can take a while. (If the org policy auto-resolved that no approval was needed, it returns approval_required=false — just proceed.)',
         '3. Wait for the verdict: prefer await_decision (it blocks until answered) over polling check_decision in a loop. Either way, "approved"/"rejected" comes with a note — the note is the human\'s actual answer/input, so read and follow it. If you asked for a choice/typed value (response_type select/text), the answer is in response_value (selected option ids — map them back via response_spec.options — or text), not just the note.',
         '4. Do NOT perform the gated action until it resolves approved. On rejected or expired, do not proceed — adapt or ask again.',
         'Refining content: to have a human review/edit a draft (e.g. an email you want to send), pass proposed_output.content. They can refine it (in the dashboard or by replying in the Slack thread); once approved, use output.content as the final text — it may differ from what you sent.',
+        'Evidence: if your ask rests on material the human should see — a Slack conversation, an email, a policy excerpt — attach it (the `evidence` array on request_decision, or attach_evidence afterwards). Send the text, not just a link: the snapshot is what the audit trail keeps, and a link can change. Evidence can only be attached while the decision is pending; once it resolves the set is sealed, so attach before you await.',
         'Prefer one well-scoped decision with rich context over many small ones.',
     ].join('\n'),
 });
-server.tool('request_decision', 'Ask the human for a decision or input before proceeding (human-in-the-loop). Creates a Ratifia decision, notifies them (even away from keyboard), and returns a decision_id to await/poll. Use whenever you need approval, a choice, or input you should not assume. Set response_type to shape the answer: "approval" (yes/no, default), "select" (pick from options you provide), or "text" (a typed value) — for select/text the answer comes back in response_value. To have a human refine a draft (e.g. an email), pass proposed_output — the approved/edited text comes back in output.content. If this decision gates a specific tool/function call, pass tool_name (and tool_args) so the reviewer sees a structured "Tool call" panel of exactly what you would run.', {
-    title: z.string().describe('Short title, e.g. "Deploy API to prod?"'),
-    question: z.string().describe('Exactly what you need the human to decide or provide.'),
-    context: z
-        .string()
-        .optional()
-        .describe('Details to help them decide: options, tradeoffs, a diff, the command you would run.'),
-    timeout_minutes: z
-        .number()
-        .int()
-        .positive()
-        .optional()
-        .describe('Auto-expire (and reject) if unanswered after N minutes. Omit to wait indefinitely.'),
-    response_type: z
-        .enum(['approval', 'select', 'text'])
-        .optional()
-        .describe("What kind of answer you need. 'approval' (default) = yes/no gate. 'select' = the human picks from `options`. 'text' = the human types a value. For select/text, read the answer from `response_value` (not just `note`)."),
-    options: z
-        .array(z.object({
-        label: z.string().describe('What the human sees for this choice.'),
-        description: z.string().optional().describe('Optional one-line clarification of the choice.'),
-    }))
-        .min(2)
-        .optional()
-        .describe("The choices for a 'select' decision (at least 2). Required when response_type is 'select'."),
-    allow_multiple: z
-        .boolean()
-        .optional()
-        .describe("For 'select': allow picking more than one option (default single-choice)."),
-    proposed_output: z
-        .object({
-        title: z.string().optional().describe('Short label for the artifact, e.g. "Email body".'),
-        content: z.string().describe('The draft the human can edit before approving (e.g. the email text).'),
-    })
-        .optional()
-        .describe('A draft artifact the human can refine before approving — e.g. an email you propose to send. They can edit it (in the dashboard or by replying in the Slack thread); on approval the final text comes back in `output.content`. Use this when you want a human to review/refine content, not just say yes/no.'),
-    tool_name: z
-        .string()
-        .optional()
-        .describe('The tool/function this decision gates, e.g. "issue_refund" or "delete_database". Shown to the reviewer as a structured "Tool call" panel — the concrete action you would take if approved.'),
-    tool_args: z
-        .record(z.unknown())
-        .optional()
-        .describe('The arguments you would call `tool_name` with, as an object, e.g. { "amount_cents": 600000, "currency": "USD" }. Displayed next to the tool name. Ignored unless `tool_name` is set.'),
-}, async ({ title, question, context, timeout_minutes, response_type, options, allow_multiple, proposed_output, tool_name, tool_args }) => {
+server.registerTool('request_decision', {
+    description: 'Ask the human for a decision or input before proceeding (human-in-the-loop). Creates a Ratifia decision, notifies them (even away from keyboard), and returns a decision_id to await/poll. Use whenever you need approval, a choice, or input you should not assume. Set response_type to shape the answer: "approval" (yes/no, default), "select" (pick from options you provide), or "text" (a typed value) — for select/text the answer comes back in response_value. To have a human refine a draft (e.g. an email), pass proposed_output — the approved/edited text comes back in output.content. If this decision gates a specific tool/function call, pass tool_name (and tool_args) so the reviewer sees a structured "Tool call" panel of exactly what you would run.',
+    inputSchema: {
+        title: z.string().describe('Short title, e.g. "Deploy API to prod?"'),
+        question: z.string().describe('Exactly what you need the human to decide or provide.'),
+        context: z
+            .string()
+            .optional()
+            .describe('Details to help them decide: options, tradeoffs, a diff, the command you would run.'),
+        timeout_minutes: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe('Auto-expire (and reject) if unanswered after N minutes. Omit to wait indefinitely.'),
+        response_type: z
+            .enum(['approval', 'select', 'text'])
+            .optional()
+            .describe("What kind of answer you need. 'approval' (default) = yes/no gate. 'select' = the human picks from `options`. 'text' = the human types a value. For select/text, read the answer from `response_value` (not just `note`)."),
+        options: z
+            .array(z.object({
+            label: z.string().describe('What the human sees for this choice.'),
+            description: z.string().optional().describe('Optional one-line clarification of the choice.'),
+        }))
+            .min(2)
+            .optional()
+            .describe("The choices for a 'select' decision (at least 2). Required when response_type is 'select'."),
+        allow_multiple: z
+            .boolean()
+            .optional()
+            .describe("For 'select': allow picking more than one option (default single-choice)."),
+        proposed_output: z
+            .object({
+            title: z.string().optional().describe('Short label for the artifact, e.g. "Email body".'),
+            content: z.string().describe('The draft the human can edit before approving (e.g. the email text).'),
+        })
+            .optional()
+            .describe('A draft artifact the human can refine before approving — e.g. an email you propose to send. They can edit it (in the dashboard or by replying in the Slack thread); on approval the final text comes back in `output.content`. Use this when you want a human to review/refine content, not just say yes/no.'),
+        tool_name: z
+            .string()
+            .optional()
+            .describe('The tool/function this decision gates, e.g. "issue_refund" or "delete_database". Shown to the reviewer as a structured "Tool call" panel — the concrete action you would take if approved.'),
+        tool_args: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe('The arguments you would call `tool_name` with, as an object, e.g. { "amount_cents": 600000, "currency": "USD" }. Displayed next to the tool name. Ignored unless `tool_name` is set.'),
+        workflow: z
+            .string()
+            .max(100)
+            .optional()
+            .describe('The project or ongoing effort this decision belongs to, e.g. the repo name or "billing-refunds" — the dashboard groups and filters by it, so reuse the exact same string for related decisions and keep ids/versions out of it. Omit to use the server default (RATIFIA_WORKFLOW, else "ratifia-mcp").'),
+        step: z
+            .string()
+            .max(80)
+            .optional()
+            .describe('What is specific to this decision within the workflow, e.g. "deploy-v2.3-prod" or "refund-INV-1042". Omit to use the title.'),
+        evidence: z
+            .array(evidenceItemSchema)
+            .max(20)
+            .optional()
+            .describe('Material this decision should be made ON — the Slack thread, the email, the policy excerpt you are relying on. Stored immutably against the decision and sealed when it resolves, so the record shows what the human could see. Attach what you already have; use attach_evidence for anything you find afterwards.'),
+    },
+}, async ({ title, question, context, timeout_minutes, response_type, options, allow_multiple, proposed_output, tool_name, tool_args, workflow, step, evidence }) => {
     if (response_type === 'select' && (!options || options.length < 2)) {
         return asToolResult({
             error: 'invalid_request',
@@ -274,7 +436,11 @@ server.tool('request_decision', 'Ask the human for a decision or input before pr
         });
     }
     const responseSpec = buildResponseSpec(response_type, options, allow_multiple);
-    const externalRunId = `mcp-${Date.now()}-${Math.round(Math.random() * 1e6)}`;
+    // Minted once per tool invocation and reused as the Idempotency-Key: a
+    // retry of *this* call collapses server-side, while a second, independent
+    // request_decision — even with identical arguments — gets its own id and is
+    // correctly treated as a new ask.
+    const externalRunId = `mcp-${randomUUID()}`;
     // Structured context blocks (FN-83): a tool_call panel when the agent names
     // the tool it's gating, plus any free-text context. Order = display order.
     const contextBlocks = [];
@@ -284,29 +450,36 @@ server.tool('request_decision', 'Ask the human for a decision or input before pr
     if (context) {
         contextBlocks.push({ kind: 'text', title, text: context });
     }
-    const res = await api('/v1/worker/decisions', {
-        method: 'POST',
-        body: JSON.stringify({
-            // The agent is its own "engine" — it polls (check/await) for the
-            // verdict rather than parking on an engine resume event.
-            engine: 'mcp',
-            externalRunId,
-            stepRef: title.slice(0, 80),
-            workflowRef: 'ratifia-mcp',
-            ...(APPROVER_EMAIL ? { assigneeEmail: APPROVER_EMAIL } : {}),
-            ...(POLICY ? { policy: POLICY } : {}),
-            required: true,
-            ...(timeout_minutes ? { timeoutSec: timeout_minutes * 60 } : {}),
-            ...(responseSpec ? { responseSpec } : {}),
-            ...(proposed_output
-                ? { proposedOutput: { title: proposed_output.title, format: 'text', content: proposed_output.content } }
-                : {}),
-            context: {
-                prompt: question,
-                ...(contextBlocks.length ? { blocks: contextBlocks } : {}),
-            },
-        }),
-    });
+    let res;
+    try {
+        res = await apiRetry(() => api('/v1/worker/decisions', {
+            method: 'POST',
+            idempotencyKey: externalRunId,
+            body: JSON.stringify({
+                // The agent is its own "engine" — it polls (check/await) for the
+                // verdict rather than parking on an engine resume event.
+                engine: 'mcp',
+                externalRunId,
+                stepRef: label(step, title, 80),
+                workflowRef: label(workflow, label(WORKFLOW, 'ratifia-mcp', 100), 100),
+                ...(APPROVER_EMAIL ? { assigneeEmail: APPROVER_EMAIL } : {}),
+                ...(POLICY ? { policy: POLICY } : {}),
+                required: true,
+                ...(timeout_minutes ? { timeoutSec: timeout_minutes * 60 } : {}),
+                ...(responseSpec ? { responseSpec } : {}),
+                ...(proposed_output
+                    ? { proposedOutput: { title: proposed_output.title, format: 'text', content: proposed_output.content } }
+                    : {}),
+                context: {
+                    prompt: question,
+                    ...(contextBlocks.length ? { blocks: contextBlocks } : {}),
+                },
+            }),
+        }));
+    }
+    catch (err) {
+        return asToolError(err);
+    }
     // The policy gate can resolve "no approval needed" — no decision is created.
     // Tell the agent it may just proceed, rather than returning a bogus id/url.
     if (res.approvalNeeded === false || !res.decisionId) {
@@ -317,61 +490,135 @@ server.tool('request_decision', 'Ask the human for a decision or input before pr
             note: 'Ratifia policy did not require a human decision — you may proceed.',
         });
     }
+    // FN-239: evidence is attached after the decision exists — it hangs off the
+    // decision id, so there is nothing to attach to before this point. A failure
+    // here is reported, never thrown: the decision is open and the human has
+    // already been notified, so aborting would strand it and tempt a duplicate
+    // ask. The agent can retry the failed items with attach_evidence.
+    const evidenceErrors = [];
+    let evidenceAttached = 0;
+    for (const item of evidence ?? []) {
+        try {
+            await apiRetry(() => attachEvidence(res.decisionId, item));
+            evidenceAttached++;
+        }
+        catch (err) {
+            evidenceErrors.push(`${item.kind}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     return asToolResult({
         approval_required: true,
         decision_id: res.decisionId,
         status: 'pending',
         url: `${APP_URL}/decisions/${res.decisionId}`,
+        ...(evidence?.length ? { evidence_attached: evidenceAttached } : {}),
+        ...(evidenceErrors.length
+            ? {
+                evidence_errors: evidenceErrors,
+                evidence_note: 'The decision was created and the human notified; only these evidence items failed. Retry them with attach_evidence — do NOT request a second decision.',
+            }
+            : {}),
     });
 });
-server.tool('check_decision', "Check a Ratifia decision's status ONCE (non-blocking). Returns 'pending' until the human acts, then 'approved'/'rejected' plus their note (their input/answer). Prefer await_decision if you just want to wait for the verdict.", {
-    decision_id: z.string().describe('The decision_id returned by request_decision.'),
-}, async ({ decision_id }) => asToolResult(formatDecision(await getDecision(decision_id))));
-server.tool('await_decision', "Block until a Ratifia decision resolves (or max_wait_seconds elapses), so you don't have to poll in a loop. Returns as soon as the human acts ('approved'/'rejected' + their note), or status 'pending' with timed_out=true if still unanswered after the wait — just call await_decision again to keep waiting. Use this after request_decision to wait for the verdict.", {
-    decision_id: z.string().describe('The decision_id returned by request_decision.'),
-    max_wait_seconds: z
-        .number()
-        .int()
-        .positive()
-        .max(240)
-        .optional()
-        .describe('How long to block before returning (default 60, max 240). If still pending, call again to keep waiting.'),
+server.registerTool('attach_evidence', {
+    description: "Attach material a decision should be judged ON — a Slack conversation, an email, a policy excerpt — to a decision you already opened. Use it when you find something relevant after asking, or when the human asks 'what did the customer actually say?'. Evidence is immutable and append-only, and can only be attached while the decision is still pending: once it resolves the set is sealed, so the record shows exactly what the reviewer could see. Send the text itself, not just a link.",
+    inputSchema: {
+        decision_id: z.string().describe('The decision_id returned by request_decision.'),
+        ...evidenceItemSchema.shape,
+    },
+}, async ({ decision_id, ...item }) => {
+    try {
+        const res = await apiRetry(() => attachEvidence(decision_id, item));
+        return asToolResult({
+            decision_id,
+            evidence_id: res.evidence?.id ?? null,
+            // The API dedupes on content hash, so re-sending the same material is a
+            // no-op rather than a second panel for the reviewer.
+            deduplicated: Boolean(res.deduplicated),
+            status: 'attached',
+        });
+    }
+    catch (err) {
+        return asToolError(err);
+    }
+});
+server.registerTool('check_decision', {
+    description: "Check a Ratifia decision's status ONCE (non-blocking). Returns 'pending' until the human acts, then 'approved'/'rejected' plus their note (their input/answer). Prefer await_decision if you just want to wait for the verdict.",
+    inputSchema: {
+        decision_id: z.string().describe('The decision_id returned by request_decision.'),
+    },
+}, async ({ decision_id }) => {
+    try {
+        return asToolResult(formatDecision(await apiRetry(() => getDecision(decision_id))));
+    }
+    catch (err) {
+        return asToolError(err);
+    }
+});
+server.registerTool('await_decision', {
+    description: "Block until a Ratifia decision resolves (or max_wait_seconds elapses), so you don't have to poll in a loop. Returns as soon as the human acts ('approved'/'rejected' + their note), or status 'pending' with timed_out=true if still unanswered after the wait — just call await_decision again to keep waiting (that is normal, not a failure). Transient API errors are retried internally; if one still surfaces it comes back as error + retryable rather than throwing, so call again rather than re-requesting the decision. Use this after request_decision to wait for the verdict.",
+    inputSchema: {
+        decision_id: z.string().describe('The decision_id returned by request_decision.'),
+        max_wait_seconds: z
+            .number()
+            .int()
+            .positive()
+            .max(110)
+            .optional()
+            .describe('How long to block before returning (default 90, max 110). Kept under the ~120s at which a harness backgrounds a tool call — a longer wait does not reach you sooner, it just lands late. If still pending, call again to keep waiting.'),
+    },
 }, async ({ decision_id, max_wait_seconds }) => {
-    const budgetMs = (max_wait_seconds ?? 60) * 1000;
-    const pollMs = 4000;
-    const start = Date.now();
-    let d = await getDecision(decision_id);
-    while (d.status === 'PENDING' && Date.now() - start + pollMs <= budgetMs) {
-        await new Promise((r) => setTimeout(r, pollMs));
-        d = await getDecision(decision_id);
+    try {
+        const d = await waitForDecision(decision_id, (max_wait_seconds ?? 90) * 1000);
+        return asToolResult({
+            ...formatDecision(d),
+            ...(d.status === 'PENDING' ? { timed_out: true } : {}),
+        });
+    }
+    catch (err) {
+        return asToolError(err);
     }
-    return asToolResult({
-        ...formatDecision(d),
-        ...(d.status === 'PENDING' ? { timed_out: true } : {}),
-    });
 });
-server.tool('list_pending_decisions', 'List the decisions you have outstanding with Ratifia (default: still-pending), newest first. Use to reconcile after a restart, or to see what you are waiting on before deciding whether to keep waiting or cancel.', {
-    status: z
-        .enum(['PENDING', 'APPROVED', 'REJECTED', 'EXPIRED', 'CANCELLED'])
-        .optional()
-        .describe('Filter by status. Omit for PENDING (your outstanding asks).'),
-    limit: z.number().int().positive().max(200).optional().describe('Max to return (default 50).'),
+server.registerTool('list_pending_decisions', {
+    description: 'List the decisions you have outstanding with Ratifia (default: still-pending), newest first. Use to reconcile after a restart, or to see what you are waiting on before deciding whether to keep waiting or cancel.',
+    inputSchema: {
+        status: z
+            .enum(['PENDING', 'APPROVED', 'REJECTED', 'EXPIRED', 'CANCELLED'])
+            .optional()
+            .describe('Filter by status. Omit for PENDING (your outstanding asks).'),
+        limit: z.number().int().positive().max(200).optional().describe('Max to return (default 50).'),
+    },
 }, async ({ status, limit }) => {
     const qs = new URLSearchParams({ status: status ?? 'PENDING' });
     if (limit)
         qs.set('limit', String(limit));
-    const res = await api(`/v1/worker/decisions?${qs.toString()}`, {
-        method: 'GET',
-    });
-    return asToolResult({ count: res.decisions.length, decisions: res.decisions });
+    try {
+        const res = await apiRetry(() => api(`/v1/worker/decisions?${qs.toString()}`, { method: 'GET' }));
+        return asToolResult({ count: res.decisions.length, decisions: res.decisions });
+    }
+    catch (err) {
+        return asToolError(err);
+    }
+});
+server.registerTool('cancel_decision', {
+    description: 'Withdraw a decision you requested but no longer need (the task was aborted or the question became moot). Resolves it and stops notifying the human. Only PENDING decisions cancel; an already-answered one is returned unchanged (cancelled=false).',
+    inputSchema: {
+        decision_id: z.string().describe('The decision_id returned by request_decision.'),
+        note: z.string().optional().describe('Optional reason, recorded on the decision.'),
+    },
+}, async ({ decision_id, note }) => {
+    // Cancel is naturally idempotent (only PENDING transitions), so a retry is
+    // safe without a key: a second one returns the already-resolved decision.
+    try {
+        return asToolResult(await apiRetry(() => api(`/v1/worker/decisions/${encodeURIComponent(decision_id)}/cancel`, {
+            method: 'POST',
+            body: JSON.stringify(note ? { note } : {}),
+        })));
+    }
+    catch (err) {
+        return asToolError(err);
+    }
 });
-server.tool('cancel_decision', 'Withdraw a decision you requested but no longer need (the task was aborted or the question became moot). Resolves it and stops notifying the human. Only PENDING decisions cancel; an already-answered one is returned unchanged (cancelled=false).', {
-    decision_id: z.string().describe('The decision_id returned by request_decision.'),
-    note: z.string().optional().describe('Optional reason, recorded on the decision.'),
-}, async ({ decision_id, note }) => asToolResult(await api(`/v1/worker/decisions/${encodeURIComponent(decision_id)}/cancel`, {
-    method: 'POST',
-    body: JSON.stringify(note ? { note } : {}),
-})));
 const transport = new StdioServerTransport();
 await server.connect(transport);
 console.error(`ratifia-mcp connected → ${API_URL}`);

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@ratifia/mcp",
-  "version": "0.5.0",
+  "version": "0.9.0",
   "type": "module",
-  "description": "Ratifia MCP server — let an AI agent request a human decision/approval (HITL) mid-task and resume once it's answered. The agent becomes a Ratifia 'engine'.",
+  "description": "Ratifia MCP server \u2014 let an AI agent request a human decision/approval (HITL) mid-task and resume once it's answered. The agent becomes a Ratifia 'engine'.",
   "keywords": [
     "mcp",
     "model-context-protocol",
@@ -29,7 +29,7 @@
     "dist"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "publishConfig": {
     "access": "public"
@@ -38,11 +38,12 @@
     "build": "tsc",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
-    "prepare": "tsc"
+    "prepare": "tsc",
+    "validate": "node test/validate.mjs"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
-    "zod": "^3.23.0"
+    "@modelcontextprotocol/server": "^2.0.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",