@ratifia/mcp 0.13.1 → 0.14.0

package/README.md

@@ -168,6 +168,37 @@ request_decision(
 `tool_args` is optional (some tools take none); it's ignored unless `tool_name`
 is set.
 
+### Link the records it is about
+
+Pass `links` (`{ label, url, description? }`, http(s) only, at most 20) for the
+PR, ticket, customer or invoice. The reviewer gets them as clickable links. A URL
+written inside `context` is shown as plain text, so put links here.
+
+### Say how risky it is
+
+The reviewer reads severity first. Pass `risk` and the decision page fills its
+"How hard to look", "What changes" and "If it's wrong" sections. Leave it out
+and those show as *not stated*:
+
+```
+request_decision(
+  title: "Drop legacy_sessions?",
+  question: "Drop the table as part of the cleanup migration?",
+  tool_name: "run_sql",
+  tool_args: { sql: "DROP TABLE legacy_sessions" },
+  risk: {
+    severity: "high",
+    reversible: false,
+    impact: [{ label: "Rows deleted", value: "1,240", normal: "0" }],
+    if_wrong: "Restore from last night's backup, about 20 minutes."
+  }
+)
+```
+
+Only `severity` is required. Use real numbers for `impact` ("1,240 rows",
+"$6,000"), not a risk label. Every value is shown to the reviewer as the
+agent's own claim, and an org policy can raise the severity but never lower it.
+
 ### Evidence — what the decision was made *on*
 
 A decision often rests on something outside the ask: the Slack thread where a

package/dist/gate.js

@@ -172,7 +172,7 @@ export async function runGate(cfg) {
                 context: {
                     prompt: `An agent wants to run the tool "${toolName}"${where ? ` in ${where}` : ''}. Approve?`,
                     blocks: [
-                        { kind: 'tool_call', title: 'Tool call', tool: toolName, args: toolInput },
+                        { kind: 'tool_call', title: 'Tool call', tool: toolName, args: toolInput, role: 'subject', src: 'ai' },
                         ...(fields.length ? [{ kind: 'fields', title: 'Where', fields }] : []),
                         ...(askedFor ? [{ kind: 'text', title: 'What the user asked for', text: askedFor }] : []),
                     ],

package/dist/server.js

@@ -56,6 +56,49 @@ const evidenceItemSchema = z.object({
         .optional()
         .describe('ISO timestamp of when the material was originally written, if it predates now.'),
 });
+/**
+ * How hard to look, sent as `context.risk`. Over the MCP the agent is the
+ * caller, so every value is its own assessment and is sent as `src: 'ai'` —
+ * the reviewer is told so, severity included. A policy floor can still raise it.
+ */
+const riskSchema = z.object({
+    severity: z
+        .enum(['low', 'medium', 'high'])
+        .describe('How hard the reviewer should look. Shown first on every surface.'),
+    reversible: z
+        .boolean()
+        .optional()
+        .describe('Whether there is an undo. Omitting it is not "yes": the reviewer is shown "not stated".'),
+    impact: z
+        .array(z.object({
+        label: z.string().min(1).max(120).describe('What is affected, e.g. "Rows deleted", "Refund amount".'),
+        value: z
+            .string()
+            .min(1)
+            .max(200)
+            .describe('Concrete: "1,240 of 1,300", "$6,000", "2,340 customers". Never a risk label or a confidence score.'),
+        normal: z
+            .string()
+            .max(200)
+            .optional()
+            .describe('What a normal value looks like, if you know it, e.g. "under $500". Shown beside the value.'),
+    }))
+        .max(20)
+        .optional()
+        .describe('What the action touches, one line per thing, with real numbers.'),
+    if_wrong: z
+        .string()
+        .max(2000)
+        .optional()
+        .describe('What happens if this turns out wrong: the rollback, the clawback, or "no undo". Omitting it tells the reviewer there is none.'),
+});
+/** `risk` as the API stores it, every value marked as the agent's own claim. */
+const toContextRisk = (r) => ({
+    severity: { value: r.severity, src: 'ai' },
+    ...(r.reversible !== undefined ? { reversible: { value: r.reversible, src: 'ai' } } : {}),
+    ...(r.impact?.length ? { impact: r.impact.map((i) => ({ ...i, src: 'ai' })) } : {}),
+    ...(r.if_wrong ? { ifWrong: { value: r.if_wrong, src: 'ai' } } : {}),
+});
 function buildResponseSpec(responseType, options, allowMultiple) {
     if (!responseType || responseType === 'approval')
         return undefined;
@@ -98,10 +141,11 @@ export function createRatifiaServer(cfg, opts) {
             'When to use request_decision: before a consequential or irreversible action (prod deploy, delete/drop, data migration, spending, sending something externally, credential rotation), or when a requirement is ambiguous and guessing wrong would be costly. Skip it for trivial, reversible, or clearly-authorized steps — that is just friction.',
             '',
             '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.',
+            '0. At the start of a run, call list_pending_decisions first: it picks up decisions answered while you were away or before your context was reset.',
+            '1. Call request_decision with a short title, a precise question, and enough context to decide (the command/diff/options + tradeoffs). For anything consequential, also pass risk: severity, whether it can be undone, what it touches in real numbers, and what happens if it is wrong. 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.',
+            '3. Wait for the verdict: prefer await_decision (it blocks until answered) over polling check_decision in a loop. If await_decision returns timed_out=true, call it again; that is normal. Do not end your turn while a decision is still pending unless something will read the verdict back: a verdict does not wake you, so start a background watcher or scheduled wake-up that calls check_decision, or save the decision_id where your next run will find it. Saying "still pending" and stopping drops the task. 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 edit it in the Ratifia app (Slack can only approve or reject it); 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.',
@@ -109,7 +153,7 @@ export function createRatifiaServer(cfg, opts) {
         ].join('\n'),
     });
     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.',
+        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. To give the reviewer clickable links (a PR, a ticket), pass links: a URL inside context is shown as plain text. 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. For anything consequential, pass risk (severity, reversible, impact, if_wrong): it is the first thing the reviewer reads.',
         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.'),
@@ -154,6 +198,22 @@ export function createRatifiaServer(cfg, opts) {
                 .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.'),
+            links: z
+                .array(z.object({
+                label: z.string().min(1).max(200).describe('What the link is, e.g. "PR #254" or "Invoice INV-1042".'),
+                url: z
+                    .string()
+                    .url()
+                    .regex(/^https?:\/\//i, 'must be an http(s) URL')
+                    .describe('The http(s) URL.'),
+                description: z.string().max(500).optional().describe('One line on why it matters.'),
+            }))
+                .max(20)
+                .optional()
+                .describe('The records this decision is about: the PR, the ticket, the customer, the invoice. Shown to the reviewer as clickable links. URLs written inside `context` stay plain text, so put every link the reviewer should open here.'),
+            risk: riskSchema
+                .optional()
+                .describe('How risky the action is: severity, whether it can be undone, what it touches, and what happens if it is wrong. The reviewer reads this first, and a decision without it is shown with severity "not stated". Send it for anything consequential.'),
             approvers: z
                 .array(z.string().email())
                 .min(1)
@@ -181,7 +241,7 @@ export function createRatifiaServer(cfg, opts) {
                 .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, approvers, policy, workflow, step, evidence }) => {
+    }, async ({ title, question, context, timeout_minutes, response_type, options, allow_multiple, proposed_output, tool_name, tool_args, approvers, policy, workflow, step, evidence, risk, links }) => {
         if (approvers?.length && policy) {
             return asToolResult({
                 error: 'invalid_request',
@@ -207,11 +267,23 @@ export function createRatifiaServer(cfg, opts) {
         // the tool it's gating, plus any free-text context. Order = display order.
         const contextBlocks = [];
         if (tool_name) {
-            contextBlocks.push({ kind: 'tool_call', title: 'Tool call', tool: tool_name, args: tool_args ?? {} });
+            // `subject`: it is the operation being approved, so the decision page shows
+            // it under "What you're approving" rather than in the evidence below.
+            contextBlocks.push({
+                kind: 'tool_call',
+                title: 'Tool call',
+                tool: tool_name,
+                args: tool_args ?? {},
+                role: 'subject',
+                src: 'ai',
+            });
         }
         if (context) {
             contextBlocks.push({ kind: 'text', title, text: context });
         }
+        if (links?.length) {
+            contextBlocks.push({ kind: 'links', title: 'Links', links, src: 'ai' });
+        }
         let res;
         try {
             res = await apiRetry(() => api('/v1/worker/decisions', {
@@ -235,6 +307,7 @@ export function createRatifiaServer(cfg, opts) {
                     context: {
                         prompt: question,
                         ...(contextBlocks.length ? { blocks: contextBlocks } : {}),
+                        ...(risk ? { risk: toContextRisk(risk) } : {}),
                     },
                 }),
             }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ratifia/mcp",
-  "version": "0.13.1",
+  "version": "0.14.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": [