@ratifia/mcp 0.8.0 → 0.10.0

package/README.md

@@ -58,9 +58,27 @@ real decisions. CI runs it on every push.
 | `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 deciding **who** reviews and the quorum they need. It must exist in your org: an unknown name is a tool error, and the `gate` hook denies. |
+| `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_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. |
 
-Routing (email / SMS / escalation) is decided **inside Ratifia** by your org's policy — this server is a thin request/verdict bridge.
+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:
+
+- **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
 

package/dist/index.js

@@ -25,18 +25,36 @@
  *   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 deciding who reviews (must exist in the org)
+ *   RATIFIA_POLICY          optional: policy key deciding who reviews (must exist in the org)
  *                           (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)
+ *   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/server';
 import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
 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);
@@ -75,7 +93,7 @@ function errorCode(body) {
 }
 /** 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}" does not exist in this Ratifia org. Create the policy 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 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. */
@@ -247,6 +265,87 @@ function gateDecision(decision, reason) {
         },
     }));
 }
+/**
+ * Where the agent is working, read straight from `.git` rather than shelling out
+ * to git — a hook runs on every gated tool call and must stay cheap.
+ */
+function repoContext(cwd) {
+    let dir;
+    try {
+        dir = resolve(cwd);
+    }
+    catch {
+        return {};
+    }
+    for (let i = 0; i < 6; i++) {
+        try {
+            const dotGit = join(dir, '.git');
+            if (existsSync(dotGit)) {
+                // A worktree's `.git` is a FILE ("gitdir: <path>"); a normal repo's is a
+                // directory. Read HEAD from whichever this is.
+                const gitDir = statSync(dotGit).isDirectory()
+                    ? dotGit
+                    : resolve(dir, readFileSync(dotGit, 'utf8').replace(/^gitdir:/, '').trim());
+                const head = readFileSync(join(gitDir, 'HEAD'), 'utf8').trim();
+                // Keep the whole branch name: "feat/x" is not "x".
+                const branch = head.startsWith('ref: refs/heads/')
+                    ? head.slice('ref: refs/heads/'.length)
+                    : head.startsWith('ref: ')
+                        ? head.slice(head.lastIndexOf('/') + 1)
+                        : head.slice(0, 7);
+                return { repo: basename(dir), branch };
+            }
+        }
+        catch {
+            // `.git` is a directory (readFileSync throws EISDIR) or unreadable — the
+            // repo name is still the useful half.
+            return { repo: basename(dir) };
+        }
+        const up = dirname(dir);
+        if (up === dir)
+            break;
+        dir = up;
+    }
+    return { repo: basename(resolve(cwd)) };
+}
+/**
+ * The user's most recent request, from the transcript the harness points at.
+ * OFF unless RATIFIA_GATE_INCLUDE_PROMPT=1: it is case content, and the gate is
+ * otherwise metadata only. The file is JSONL and written asynchronously, so the
+ * newest lines may lag; a miss just means no block.
+ */
+function lastUserRequest(transcriptPath) {
+    if (process.env.RATIFIA_GATE_INCLUDE_PROMPT !== '1')
+        return null;
+    if (typeof transcriptPath !== 'string' || !transcriptPath)
+        return null;
+    try {
+        const lines = readFileSync(transcriptPath, 'utf8').split('\n').filter(Boolean);
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const row = JSON.parse(lines[i]);
+            if (row.type !== 'user' && row.message?.role !== 'user')
+                continue;
+            const content = row.message?.content;
+            const text = typeof content === 'string'
+                ? content
+                : Array.isArray(content)
+                    ? content
+                        .filter((c) => typeof c === 'object' && c !== null && c.type === 'text')
+                        .map((c) => c.text)
+                        .join('\n')
+                    : '';
+            const trimmed = text.trim();
+            // Skip the harness's own injected turns — they are not what the user asked.
+            if (!trimmed || trimmed.startsWith('<'))
+                continue;
+            return trimmed.length > 1500 ? `${trimmed.slice(0, 1500)}…` : trimmed;
+        }
+    }
+    catch {
+        /* unreadable transcript — the gate still works without it */
+    }
+    return null;
+}
 /**
  * `ratifia-mcp gate` — a Claude Code **PreToolUse hook**. Opens a Ratifia
  * decision for the tool call (rendered as a `tool_call` context panel), blocks
@@ -266,6 +365,23 @@ async function runGate() {
     }
     const toolName = String(payload.tool_name ?? 'unknown_tool');
     const toolInput = payload.tool_input ?? {};
+    // FN: the reviewer sees WHAT would run (the tool call) — give them WHERE and
+    // WHO too. All of it comes from the harness payload; none of it is guessed.
+    const cwd = typeof payload.cwd === 'string' ? payload.cwd : '';
+    const { repo, branch } = cwd ? repoContext(cwd) : {};
+    const where = [repo, branch && `(${branch})`].filter(Boolean).join(' ');
+    const askedFor = lastUserRequest(payload.transcript_path);
+    const fields = [
+        repo ? { label: 'Repo', value: branch ? `${repo} (${branch})` : repo } : null,
+        cwd ? { label: 'Directory', value: cwd } : null,
+        typeof payload.agent_type === 'string' && payload.agent_type ? { label: 'Agent', value: payload.agent_type } : null,
+        typeof payload.permission_mode === 'string' && payload.permission_mode
+            ? { label: 'Permission mode', value: payload.permission_mode }
+            : null,
+        typeof payload.session_id === 'string' && payload.session_id
+            ? { label: 'Session', value: payload.session_id.slice(0, 12) }
+            : null,
+    ].filter((f) => f !== null);
     // Optional allow-list: if set, only gate these tools; pass the rest through.
     const gated = (process.env.RATIFIA_GATED_TOOLS ?? '')
         .split(',')
@@ -289,13 +405,17 @@ async function runGate() {
                 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,
                 context: {
-                    prompt: `An agent wants to run the tool "${toolName}". Approve?`,
-                    blocks: [{ kind: 'tool_call', title: 'Tool call', tool: toolName, args: toolInput }],
+                    prompt: `An agent wants to run the tool "${toolName}"${where ? ` in ${where}` : ''}. Approve?`,
+                    blocks: [
+                        { kind: 'tool_call', title: 'Tool call', tool: toolName, args: toolInput },
+                        ...(fields.length ? [{ kind: 'fields', title: 'Where', fields }] : []),
+                        ...(askedFor ? [{ kind: 'text', title: 'What the user asked for', text: askedFor }] : []),
+                    ],
                 },
             }),
         }));
@@ -343,6 +463,7 @@ const server = new McpServer({ name: 'ratifia', version: '0.7.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.',
@@ -397,13 +518,23 @@ server.registerTool('request_decision', {
             .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, evidence }) => {
+}, 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',
@@ -435,8 +566,8 @@ server.registerTool('request_decision', {
                 // verdict rather than parking on an engine resume event.
                 engine: 'mcp',
                 externalRunId,
-                stepRef: title.slice(0, 80),
-                workflowRef: 'ratifia-mcp',
+                stepRef: label(step, title, 80),
+                workflowRef: label(workflow, label(WORKFLOW, 'ratifia-mcp', 100), 100),
                 ...(APPROVER_EMAIL ? { assigneeEmail: APPROVER_EMAIL } : {}),
                 ...(POLICY ? { policy: POLICY } : {}),
                 required: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ratifia/mcp",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "type": "module",
   "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": [