@ratifia/mcp 0.11.0 → 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. |
 

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
@@ -410,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?`,
@@ -493,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()
@@ -575,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.11.0",
+  "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": [