@ratifia/mcp 0.10.1 → 0.12.0

package/README.md

@@ -57,8 +57,8 @@ real decisions. CI runs it on every push.
 | `RATIFIA_API_KEY` | ✅ | — | Org-scoped worker API key. |
 | `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` | | — | 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_APPROVER_EMAIL` | | — | Without a policy: who can answer, one email or a comma-separated list. Ignored when `RATIFIA_POLICY` is set. |
+| `RATIFIA_POLICY` | | — | The **key** of a policy deciding **who** reviews, the quorum they need, and the expiry (`timeout_minutes` is then not sent). It must exist in your org: an unknown key is a tool error, and the `gate` hook denies. |
 | `RATIFIA_GATE_INCLUDE_PROMPT` | | off | `gate` hook only: `1` includes the user's last request (from the transcript) in the decision. Off by default — the gate otherwise sends only metadata, never your conversation. |
 | `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. |
 
@@ -205,7 +205,7 @@ Three properties worth knowing, because they shape how you should use it:
 
 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.
 2. Ratifia notifies the human (even away from keyboard) per the org's routing.
-3. The agent `await_decision`s (or polls `check_decision`) — read `verdict`/`note`, plus `response_value` (select/text) or `output` (a refined draft).
+3. The agent `await_decision`s (or polls `check_decision`) — read `verdict`/`note`, plus `response_value` (select/text) or `output` (a refined draft). `policy_version` / `policy_version_id` say which version of the policy the decision ran under (null when no policy applied).
 4. The agent proceeds only on `approved`; on `rejected`/`expired` it adapts.
 
 Learn more at [ratifia.com](https://ratifia.com).

package/dist/index.js

@@ -24,8 +24,11 @@
  *   RATIFIA_API_URL         API base (default https://api.ratifia.com)
  *   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 key deciding who reviews (must exist in the org)
+ *   RATIFIA_APPROVER_EMAIL  who may answer (comma-separated for several); used only
+ *                           when RATIFIA_POLICY is unset
+ *   RATIFIA_POLICY          optional: policy key (must exist in the org). When set, the
+ *                           policy decides who approves and when it expires, and
+ *                           RATIFIA_APPROVER_EMAIL / timeout_minutes are not sent
  *                           (e.g. a route to your phone)
  *   RATIFIA_GATE_INCLUDE_PROMPT  gate hook only: 1 = include the user's last request from the
  *                           transcript in the decision (off by default — it is case content)
@@ -42,8 +45,21 @@ 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 APPROVERS = (process.env.RATIFIA_APPROVER_EMAIL ?? '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+const POLICY = process.env.RATIFIA_POLICY || undefined;
+/**
+ * Who answers (Ratifia PD-003): a policy owns its approvers and expiry, so with
+ * one set only its key is sent (approvers alongside it are refused, 422
+ * field_owned_by_policy). Without one, the decision is ad hoc to APPROVERS.
+ */
+const WHO = POLICY
+    ? { policy: { key: POLICY } }
+    : APPROVERS.length
+        ? { approvers: APPROVERS }
+        : {};
 const WORKFLOW = process.env.RATIFIA_WORKFLOW;
 /**
  * Where a decision is filed. `workflowRef` is the category (the dashboard's
@@ -188,6 +204,10 @@ const formatDecision = (d) => ({
     ...(d.output ? { output: d.output, refined: Boolean(d.refinedOutput) } : {}),
     decided_by: d.decidedBy,
     decided_at: d.decidedAt,
+    // FN-316: which version of the policy governed this decision, so an agent can
+    // cite it ("approved under refunds v3"). Stays put when the policy is edited.
+    policy_version: d.policyVersion ?? null,
+    policy_version_id: d.policyVersionId ?? null,
 });
 const asToolResult = (payload) => ({
     content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
@@ -406,8 +426,7 @@ async function runGate() {
                 externalRunId,
                 stepRef: `tool:${toolName}`.slice(0, 80),
                 workflowRef: label(WORKFLOW, 'ratifia-gate', 100),
-                ...(APPROVER_EMAIL ? { assigneeEmail: APPROVER_EMAIL } : {}),
-                ...(POLICY ? { policy: POLICY } : {}),
+                ...WHO,
                 required: true,
                 context: {
                     prompt: `An agent wants to run the tool "${toolName}"${where ? ` in ${where}` : ''}. Approve?`,
@@ -489,7 +508,7 @@ server.registerTool('request_decision', {
             .int()
             .positive()
             .optional()
-            .describe('Auto-expire (and reject) if unanswered after N minutes. Omit to wait indefinitely.'),
+            .describe("Auto-expire (and reject) if unanswered after N minutes. Omit to wait indefinitely. Ignored when this server is configured with a policy (RATIFIA_POLICY): the policy's expiry applies."),
         response_type: z
             .enum(['approval', 'select', 'text'])
             .optional()
@@ -571,10 +590,10 @@ server.registerTool('request_decision', {
                 externalRunId,
                 stepRef: label(step, title, 80),
                 workflowRef: label(workflow, label(WORKFLOW, 'ratifia-mcp', 100), 100),
-                ...(APPROVER_EMAIL ? { assigneeEmail: APPROVER_EMAIL } : {}),
-                ...(POLICY ? { policy: POLICY } : {}),
+                ...WHO,
                 required: true,
-                ...(timeout_minutes ? { timeoutSec: timeout_minutes * 60 } : {}),
+                // With a policy, the policy sets the expiry (a timeoutSec would be refused).
+                ...(timeout_minutes && !POLICY ? { timeoutSec: timeout_minutes * 60 } : {}),
                 ...(responseSpec ? { responseSpec } : {}),
                 ...(proposed_output
                     ? { proposedOutput: { title: proposed_output.title, format: 'text', content: proposed_output.content } }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ratifia/mcp",
-  "version": "0.10.1",
+  "version": "0.12.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'.",
   "keywords": [