@ratifia/mcp 0.12.0 → 0.13.0

package/README.md

@@ -84,7 +84,7 @@ request_decision(
 
 | Tool | What it does |
 |------|--------------|
-| `request_decision` | Create a decision, notify the human, return a `decision_id`. |
+| `request_decision` | Create a decision, notify the human, return a `decision_id`. `approvers` (emails) or `policy` (a policy key) say who answers for this call, overriding `RATIFIA_APPROVER_EMAIL` / `RATIFIA_POLICY`. |
 | `check_decision` | Poll a decision's status once. |
 | `await_decision` | Block until the verdict lands (or a max wait elapses). |
 | `list_pending_decisions` | The agent's inbox — what's outstanding. |
@@ -201,6 +201,29 @@ Three properties worth knowing, because they shape how you should use it:
 - **Re-attaching is free.** Identical content dedupes on its hash, so a retry
   never produces a second panel for the reviewer.
 
+## Hosted (no install)
+
+Ratifia also runs this server for you at **`https://api.ratifia.com/mcp`** (Streamable
+HTTP). Add that URL as a custom connector in claude.ai or ChatGPT and sign in with your
+Ratifia account (OAuth); a client that sends a fixed header can use
+`Authorization: Bearer <org API key>` instead. See
+[docs.ratifia.com/mcp](https://docs.ratifia.com/mcp).
+
+The hosted endpoint uses this package as a library:
+
+```ts
+import { createRatifiaMcpHandler } from '@ratifia/mcp'
+
+const handler = createRatifiaMcpHandler({ version: '1.0.0' })
+// After authenticating the request yourself:
+const res = await handler.fetch(request, {
+  authInfo: { token, clientId, scopes: [], extra: { ratifia: { apiUrl, token, appUrl, approvers: [] } } },
+})
+```
+
+`createRatifiaServer(config, { version })` builds a single server (it is what the stdio
+CLI runs). Neither reads env or credentials: the caller passes a `RatifiaConfig`.
+
 ## 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/client.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The Ratifia API client shared by the MCP tools (stdio or hosted) and the
+ * `gate` hook. No env reading here: callers pass a RatifiaConfig, so one process
+ * can serve many tokens (the hosted endpoint builds one per request).
+ */
+export interface RatifiaConfig {
+    /** API base, e.g. https://api.ratifia.com (no trailing slash needed). */
+    apiUrl: string;
+    /** Sent as `Authorization: Bearer <token>`: an org API key, or a connector's OAuth access token. */
+    token: string;
+    /** Dashboard base for the decision link. */
+    appUrl: string;
+    /** Default approvers when a call names neither approvers nor a policy. */
+    approvers: string[];
+    /** Default policy key. */
+    policy?: string;
+    /** Default workflow decisions are filed under. */
+    workflow?: string;
+    /** Defaults to global fetch. The hosted endpoint passes an in-process one. */
+    fetch?: typeof fetch;
+}
+export declare const trimUrl: (u: string) => string;
+/**
+ * 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.
+ */
+export declare function label(value: string | undefined, fallback: string, max: number): string;
+/**
+ * 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`.
+ */
+export declare function who(policy: string | undefined, approvers: string[]): Record<string, unknown>;
+/** An API failure that knows whether trying again is worth anything. */
+export declare class ApiError extends Error {
+    /** null = no response at all (network, DNS, or our own timeout). */
+    readonly status: number | null;
+    /** The API's machine-readable `error` code, when it sent one (e.g. `unknown_policy`). */
+    readonly code: string | null;
+    constructor(message: string, status: number | null, code?: string | null);
+    get retryable(): boolean;
+}
+/** FN-255: RATIFIA_POLICY names a policy the org doesn't have. A misconfiguration, not an outage. */
+export declare const isUnknownPolicy: (err: unknown) => boolean;
+export declare const unknownPolicyMessage: (policy: string | undefined) => string;
+export declare const sleep: (ms: number) => Promise<unknown>;
+/** 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. */
+export declare function apiRetry<T>(fn: () => Promise<T>, attempts?: number): Promise<T>;
+/** The structured answer shape a decision expects (FN-180/181). */
+export interface ResponseSpec {
+    type: 'approval' | 'select' | 'text';
+    options?: {
+        id: string;
+        label: string;
+        description?: string;
+    }[];
+    min?: number;
+    max?: number;
+}
+/** The human's structured answer, once decided. */
+export interface ResponseValue {
+    type: 'approval' | 'select' | 'text';
+    decision?: 'approve' | 'reject';
+    selected?: string[];
+    text?: string;
+}
+/** Decision row as returned by GET /v1/worker/decisions/:id (API-key scope). */
+/** An editable proposed artifact (e.g. an email body) — FN-185. */
+export interface DecisionOutput {
+    title?: string;
+    format?: 'text' | 'markdown';
+    content: string;
+}
+export interface DecisionRow {
+    id: string;
+    status: string;
+    decision: string | null;
+    note: string | null;
+    responseSpec: ResponseSpec | null;
+    responseValue: ResponseValue | null;
+    output: DecisionOutput | null;
+    refinedOutput: DecisionOutput | null;
+    decidedBy: string | null;
+    decidedAt: string | null;
+    policyVersionId?: string | null;
+    policyVersion?: number | null;
+}
+/** FN-239: immutable material a decision is made ON (a Slack thread, an email). */
+export interface EvidenceInput {
+    kind: 'slack_thread' | 'email' | 'document' | 'link' | 'note';
+    title?: string;
+    source_system?: string;
+    source_url?: string;
+    body?: string;
+    captured_at?: string;
+}
+export type RatifiaClient = ReturnType<typeof createClient>;
+export declare function createClient(cfg: Pick<RatifiaConfig, 'apiUrl' | 'token' | 'fetch'>): {
+    api: <T>(path: string, init?: RequestInit & {
+        idempotencyKey?: string;
+    }) => Promise<T>;
+    getDecision: (id: string) => Promise<DecisionRow>;
+    attachEvidence: (decisionId: string, e: EvidenceInput) => Promise<{
+        evidence?: {
+            id: string;
+            contentHash: string;
+        } | null;
+        deduplicated?: boolean;
+    }>;
+    waitForDecision: (decisionId: string, budgetMs: number) => Promise<DecisionRow>;
+};

package/dist/client.js

@@ -0,0 +1,136 @@
+export const trimUrl = (u) => u.replace(/\/+$/, '');
+/**
+ * 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.
+ */
+export function label(value, fallback, max) {
+    const v = value?.trim();
+    return (v ? v : fallback).slice(0, max);
+}
+/**
+ * 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`.
+ */
+export function who(policy, approvers) {
+    return policy ? { policy: { key: policy } } : approvers.length ? { approvers } : {};
+}
+/** 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. */
+export 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. */
+export const isUnknownPolicy = (err) => err instanceof ApiError && err.code === 'unknown_policy';
+export const unknownPolicyMessage = (policy) => `Policy "${policy}" is not a policy key in this Ratifia org. Create a policy with this key in the Ratifia dashboard (Policies), or fix the policy you passed (or RATIFIA_POLICY in this MCP server's config). No decision was created: do not proceed with the action.`;
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** 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. */
+export 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
+        }
+    }
+}
+/** 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;
+export function createClient(cfg) {
+    const apiUrl = trimUrl(cfg.apiUrl);
+    const doFetch = cfg.fetch ?? fetch;
+    /** `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 { idempotencyKey, ...rest } = init ?? {};
+        try {
+            const res = await doFetch(`${apiUrl}${path}`, {
+                ...rest,
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${cfg.token}`,
+                    ...(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);
+        }
+    }
+    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 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));
+        }
+    }
+    return { api, getDecision, attachEvidence, waitForDecision };
+}

package/dist/gate.d.ts

@@ -0,0 +1,10 @@
+import { type RatifiaConfig } from './client.js';
+/**
+ * `ratifia-mcp gate` — a Claude Code **PreToolUse hook**. Opens a Ratifia
+ * decision for the tool call (rendered as a `tool_call` context panel), blocks
+ * until a human answers, and returns allow/deny to the harness. The "list of
+ * tools" that trigger this is the hook's matcher in settings.json; narrow it
+ * further with RATIFIA_GATED_TOOLS. Fail-CLOSED (deny) on error/timeout unless
+ * RATIFIA_GATE_FAIL_OPEN=1 — a gate that fails open is no gate.
+ */
+export declare function runGate(cfg: RatifiaConfig): Promise<void>;

package/dist/gate.js

@@ -0,0 +1,212 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { apiRetry, createClient, isUnknownPolicy, label, unknownPolicyMessage, who } from './client.js';
+// ─── Gate mode (Claude Code PreToolUse hook) ─────────────────────────────────
+/** Read the hook payload from stdin (Claude Code pipes the PreToolUse JSON). */
+function readStdin() {
+    return new Promise((resolve) => {
+        if (process.stdin.isTTY)
+            return resolve('');
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (c) => (data += c));
+        process.stdin.on('end', () => resolve(data));
+        setTimeout(() => resolve(data), 3000); // don't hang if the stream never ends
+    });
+}
+/** Emit Claude Code's PreToolUse permission decision (allow | deny) as JSON. */
+function gateDecision(decision, reason) {
+    process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: decision,
+            permissionDecisionReason: 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
+ * until a human answers, and returns allow/deny to the harness. The "list of
+ * tools" that trigger this is the hook's matcher in settings.json; narrow it
+ * further with RATIFIA_GATED_TOOLS. Fail-CLOSED (deny) on error/timeout unless
+ * RATIFIA_GATE_FAIL_OPEN=1 — a gate that fails open is no gate.
+ */
+export async function runGate(cfg) {
+    const { api, waitForDecision } = createClient(cfg);
+    const failOpen = process.env.RATIFIA_GATE_FAIL_OPEN === '1';
+    let payload = {};
+    try {
+        payload = JSON.parse((await readStdin()) || '{}');
+    }
+    catch {
+        /* proceed with an empty payload */
+    }
+    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(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    if (gated.length > 0 && !gated.includes(toolName)) {
+        return gateDecision('allow', `not a gated tool: ${toolName}`);
+    }
+    // How long to block waiting for a human. Keep the settings.json hook `timeout`
+    // a little higher than this; on timeout we fail-closed (deny) by default.
+    const budgetMs = Math.max(10, Number(process.env.RATIFIA_GATE_TIMEOUT_SEC ?? 240)) * 1000;
+    let decisionId;
+    try {
+        // 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: label(cfg.workflow, 'ratifia-gate', 100),
+                ...who(cfg.policy, cfg.approvers),
+                required: true,
+                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 },
+                        ...(fields.length ? [{ kind: 'fields', title: 'Where', fields }] : []),
+                        ...(askedFor ? [{ kind: 'text', title: 'What the user asked for', text: askedFor }] : []),
+                    ],
+                },
+            }),
+        }));
+        // Policy gate resolved "no approval needed" → let it run.
+        if (res.approvalNeeded === false || !res.decisionId) {
+            return gateDecision('allow', 'no approval required by policy');
+        }
+        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(cfg.policy));
+        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).
+    try {
+        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);
+        return gateDecision(failOpen ? 'allow' : 'deny', `ratifia gate error: ${msg}`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};