@ratifia/mcp 0.12.0 → 0.13.0

package/dist/index.js

@@ -36,717 +36,34 @@
  *                           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 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
- * 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) {
+import { readFileSync } from 'node:fs';
+import { runGate } from './gate.js';
+import { createRatifiaServer } from './server.js';
+const token = process.env.RATIFIA_API_KEY;
+if (!token) {
     console.error('RATIFIA_API_KEY is required');
     process.exit(1);
 }
-/** 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. */
-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. */
-const isUnknownPolicy = (err) => err instanceof ApiError && err.code === 'unknown_policy';
-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. */
-async function api(path, init) {
-    const { idempotencyKey, ...rest } = init ?? {};
-    try {
-        const res = await fetch(`${API_URL}${path}`, {
-            ...rest,
-            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-            headers: {
-                'Content-Type': 'application/json',
-                Authorization: `Bearer ${API_KEY}`,
-                ...(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);
-    }
-}
-/** 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. */
-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
-        }
-    }
-}
-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 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;
-/** 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));
-    }
-}
-/** Agent-facing shape for a decision's current state. */
-const formatDecision = (d) => ({
-    decision_id: d.id,
-    status: d.status, // PENDING | APPROVED | REJECTED | EXPIRED
-    verdict: d.decision, // approve | reject | null
-    note: d.note, // the human's free-text input/answer — read and follow it
-    // FN-181: for a select/text decision the real answer is here, not in `note`.
-    // `response_value.selected` holds the chosen option id(s); map them back to
-    // labels via `response_spec.options`. `response_value.text` holds a typed value.
-    ...(d.responseSpec ? { response_spec: d.responseSpec } : {}),
-    ...(d.responseValue ? { response_value: d.responseValue } : {}),
-    // FN-185: if you sent a proposed_output (e.g. a draft email), the human may
-    // have refined it (in the dashboard or a Slack thread). `output.content` is the
-    // effective final text to act on — use it over your original draft.
-    ...(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) }],
-});
-/** Report an API failure as a structured result rather than an MCP exception,
- *  so the agent can retry on `retryable` instead of treating the step as lost
- *  and abandoning a decision a human may already be looking at. */
-const asToolError = (err) => isUnknownPolicy(err)
-    ? asToolResult({ error: 'unknown_policy', policy: POLICY, message: unknownPolicyMessage(), retryable: false })
-    : asToolResult({
-        error: err instanceof ApiError && err.status ? `http_${err.status}` : 'unreachable',
-        message: err instanceof Error ? err.message : String(err),
-        retryable: err instanceof ApiError ? err.retryable : true,
-    });
-/** FN-239: one piece of evidence, shared by request_decision and attach_evidence. */
-const evidenceItemSchema = z.object({
-    kind: z
-        .enum(['slack_thread', 'email', 'document', 'link', 'note'])
-        .describe("What this material is. 'slack_thread' / 'email' for a captured conversation, 'document' for a doc or policy excerpt, 'link' for a bare reference with no text, 'note' for your own written rationale."),
-    title: z.string().optional().describe('Short reviewer-facing label, e.g. "#incidents — refund thread".'),
-    source_system: z.string().optional().describe('Where it came from, e.g. "slack", "email", "notion".'),
-    source_url: z.string().optional().describe('Deep link back to the original, for provenance.'),
-    body: z
-        .string()
-        .optional()
-        .describe('The actual text, captured. Send the content, not just a link — a link can be edited or deleted after the decision, and the stored snapshot is what the audit trail keeps. Required unless kind is "link".'),
-    captured_at: z
-        .string()
-        .optional()
-        .describe('ISO timestamp of when the material was originally written, if it predates now.'),
-});
-function buildResponseSpec(responseType, options, allowMultiple) {
-    if (!responseType || responseType === 'approval')
-        return undefined;
-    if (responseType === 'text')
-        return { type: 'text' };
-    // select
-    const seen = new Set();
-    const specOptions = (options ?? []).map((o, i) => {
-        // Cap at 40: option ids ride in a Discord button custom_id (100-char limit)
-        // alongside the 28-char decision id, so keep them short.
-        let id = (o.label.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || `opt-${i}`).slice(0, 40);
-        while (seen.has(id))
-            id = `${id}-${i}`;
-        seen.add(id);
-        return { id, label: o.label, ...(o.description ? { description: o.description } : {}) };
-    });
-    return {
-        type: 'select',
-        options: specOptions,
-        min: 1,
-        max: allowMultiple ? specOptions.length : 1,
-    };
-}
-// ─── 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.
- */
-async function runGate() {
-    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 ?? '')
+const cfg = {
+    apiUrl: process.env.RATIFIA_API_URL ?? 'https://api.ratifia.com',
+    token,
+    appUrl: process.env.RATIFIA_APP_URL ?? 'https://app.ratifia.com',
+    approvers: (process.env.RATIFIA_APPROVER_EMAIL ?? '')
         .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(WORKFLOW, 'ratifia-gate', 100),
-                ...WHO,
-                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());
-        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}`);
-    }
-}
+        .filter(Boolean),
+    policy: process.env.RATIFIA_POLICY || undefined,
+    workflow: process.env.RATIFIA_WORKFLOW,
+};
 // Dispatch: `ratifia-mcp gate` runs the hook; otherwise start the MCP server.
 if (process.argv[2] === 'gate') {
-    await runGate();
+    await runGate(cfg);
     process.exit(0);
 }
 /** The published version, read from package.json so the handshake can't drift
  *  from npm again (it reported 0.6.0/0.7.0 through several releases). */
 const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
-const server = new McpServer({ name: 'ratifia', version: VERSION }, {
-    instructions: [
-        'Ratifia lets you request a HUMAN decision or input mid-task (human-in-the-loop) and resume once it is answered.',
-        '',
-        '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.',
-        '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.',
-        'Refining content: to have a human review/edit a draft (e.g. an email you want to send), pass proposed_output.content. They can refine it (in the dashboard or by replying in the Slack thread); 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.',
-        'Prefer one well-scoped decision with rich context over many small ones.',
-    ].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.',
-    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.'),
-        context: z
-            .string()
-            .optional()
-            .describe('Details to help them decide: options, tradeoffs, a diff, the command you would run.'),
-        timeout_minutes: z
-            .number()
-            .int()
-            .positive()
-            .optional()
-            .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()
-            .describe("What kind of answer you need. 'approval' (default) = yes/no gate. 'select' = the human picks from `options`. 'text' = the human types a value. For select/text, read the answer from `response_value` (not just `note`)."),
-        options: z
-            .array(z.object({
-            label: z.string().describe('What the human sees for this choice.'),
-            description: z.string().optional().describe('Optional one-line clarification of the choice.'),
-        }))
-            .min(2)
-            .optional()
-            .describe("The choices for a 'select' decision (at least 2). Required when response_type is 'select'."),
-        allow_multiple: z
-            .boolean()
-            .optional()
-            .describe("For 'select': allow picking more than one option (default single-choice)."),
-        proposed_output: z
-            .object({
-            title: z.string().optional().describe('Short label for the artifact, e.g. "Email body".'),
-            content: z.string().describe('The draft the human can edit before approving (e.g. the email text).'),
-        })
-            .optional()
-            .describe('A draft artifact the human can refine before approving — e.g. an email you propose to send. They can edit it (in the dashboard or by replying in the Slack thread); on approval the final text comes back in `output.content`. Use this when you want a human to review/refine content, not just say yes/no.'),
-        tool_name: z
-            .string()
-            .optional()
-            .describe('The tool/function this decision gates, e.g. "issue_refund" or "delete_database". Shown to the reviewer as a structured "Tool call" panel — the concrete action you would take if approved.'),
-        tool_args: z
-            .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, workflow, step, evidence }) => {
-    if (response_type === 'select' && (!options || options.length < 2)) {
-        return asToolResult({
-            error: 'invalid_request',
-            message: "response_type 'select' requires at least 2 options.",
-        });
-    }
-    const responseSpec = buildResponseSpec(response_type, options, allow_multiple);
-    // Minted once per tool invocation and reused as the Idempotency-Key: a
-    // retry of *this* call collapses server-side, while a second, independent
-    // request_decision — even with identical arguments — gets its own id and is
-    // correctly treated as a new ask.
-    const externalRunId = `mcp-${randomUUID()}`;
-    // Structured context blocks (FN-83): a tool_call panel when the agent names
-    // 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 ?? {} });
-    }
-    if (context) {
-        contextBlocks.push({ kind: 'text', title, text: context });
-    }
-    let res;
-    try {
-        res = await apiRetry(() => api('/v1/worker/decisions', {
-            method: 'POST',
-            idempotencyKey: externalRunId,
-            body: JSON.stringify({
-                // The agent is its own "engine" — it polls (check/await) for the
-                // verdict rather than parking on an engine resume event.
-                engine: 'mcp',
-                externalRunId,
-                stepRef: label(step, title, 80),
-                workflowRef: label(workflow, label(WORKFLOW, 'ratifia-mcp', 100), 100),
-                ...WHO,
-                required: true,
-                // 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 } }
-                    : {}),
-                context: {
-                    prompt: question,
-                    ...(contextBlocks.length ? { blocks: contextBlocks } : {}),
-                },
-            }),
-        }));
-    }
-    catch (err) {
-        return asToolError(err);
-    }
-    // The policy gate can resolve "no approval needed" — no decision is created.
-    // Tell the agent it may just proceed, rather than returning a bogus id/url.
-    if (res.approvalNeeded === false || !res.decisionId) {
-        return asToolResult({
-            approval_required: false,
-            status: 'not_required',
-            reason: res.reason ?? 'policy_gate_not_required',
-            note: 'Ratifia policy did not require a human decision — you may proceed.',
-        });
-    }
-    // FN-239: evidence is attached after the decision exists — it hangs off the
-    // decision id, so there is nothing to attach to before this point. A failure
-    // here is reported, never thrown: the decision is open and the human has
-    // already been notified, so aborting would strand it and tempt a duplicate
-    // ask. The agent can retry the failed items with attach_evidence.
-    const evidenceErrors = [];
-    let evidenceAttached = 0;
-    for (const item of evidence ?? []) {
-        try {
-            await apiRetry(() => attachEvidence(res.decisionId, item));
-            evidenceAttached++;
-        }
-        catch (err) {
-            evidenceErrors.push(`${item.kind}: ${err instanceof Error ? err.message : String(err)}`);
-        }
-    }
-    return asToolResult({
-        approval_required: true,
-        decision_id: res.decisionId,
-        status: 'pending',
-        url: `${APP_URL}/decisions/${res.decisionId}`,
-        ...(evidence?.length ? { evidence_attached: evidenceAttached } : {}),
-        ...(evidenceErrors.length
-            ? {
-                evidence_errors: evidenceErrors,
-                evidence_note: 'The decision was created and the human notified; only these evidence items failed. Retry them with attach_evidence — do NOT request a second decision.',
-            }
-            : {}),
-    });
-});
-server.registerTool('attach_evidence', {
-    description: "Attach material a decision should be judged ON — a Slack conversation, an email, a policy excerpt — to a decision you already opened. Use it when you find something relevant after asking, or when the human asks 'what did the customer actually say?'. Evidence is immutable and append-only, and can only be attached while the decision is still pending: once it resolves the set is sealed, so the record shows exactly what the reviewer could see. Send the text itself, not just a link.",
-    inputSchema: {
-        decision_id: z.string().describe('The decision_id returned by request_decision.'),
-        ...evidenceItemSchema.shape,
-    },
-}, async ({ decision_id, ...item }) => {
-    try {
-        const res = await apiRetry(() => attachEvidence(decision_id, item));
-        return asToolResult({
-            decision_id,
-            evidence_id: res.evidence?.id ?? null,
-            // The API dedupes on content hash, so re-sending the same material is a
-            // no-op rather than a second panel for the reviewer.
-            deduplicated: Boolean(res.deduplicated),
-            status: 'attached',
-        });
-    }
-    catch (err) {
-        return asToolError(err);
-    }
-});
-server.registerTool('check_decision', {
-    description: "Check a Ratifia decision's status ONCE (non-blocking). Returns 'pending' until the human acts, then 'approved'/'rejected' plus their note (their input/answer). Prefer await_decision if you just want to wait for the verdict.",
-    inputSchema: {
-        decision_id: z.string().describe('The decision_id returned by request_decision.'),
-    },
-}, async ({ decision_id }) => {
-    try {
-        return asToolResult(formatDecision(await apiRetry(() => getDecision(decision_id))));
-    }
-    catch (err) {
-        return asToolError(err);
-    }
-});
-server.registerTool('await_decision', {
-    description: "Block until a Ratifia decision resolves (or max_wait_seconds elapses), so you don't have to poll in a loop. Returns as soon as the human acts ('approved'/'rejected' + their note), or status 'pending' with timed_out=true if still unanswered after the wait — just call await_decision again to keep waiting (that is normal, not a failure). Transient API errors are retried internally; if one still surfaces it comes back as error + retryable rather than throwing, so call again rather than re-requesting the decision. Use this after request_decision to wait for the verdict.",
-    inputSchema: {
-        decision_id: z.string().describe('The decision_id returned by request_decision.'),
-        max_wait_seconds: z
-            .number()
-            .int()
-            .positive()
-            .max(110)
-            .optional()
-            .describe('How long to block before returning (default 90, max 110). Kept under the ~120s at which a harness backgrounds a tool call — a longer wait does not reach you sooner, it just lands late. If still pending, call again to keep waiting.'),
-    },
-}, async ({ decision_id, max_wait_seconds }) => {
-    try {
-        const d = await waitForDecision(decision_id, (max_wait_seconds ?? 90) * 1000);
-        return asToolResult({
-            ...formatDecision(d),
-            ...(d.status === 'PENDING' ? { timed_out: true } : {}),
-        });
-    }
-    catch (err) {
-        return asToolError(err);
-    }
-});
-server.registerTool('list_pending_decisions', {
-    description: 'List the decisions you have outstanding with Ratifia (default: still-pending), newest first. Use to reconcile after a restart, or to see what you are waiting on before deciding whether to keep waiting or cancel.',
-    inputSchema: {
-        status: z
-            .enum(['PENDING', 'APPROVED', 'REJECTED', 'EXPIRED', 'CANCELLED'])
-            .optional()
-            .describe('Filter by status. Omit for PENDING (your outstanding asks).'),
-        limit: z.number().int().positive().max(200).optional().describe('Max to return (default 50).'),
-    },
-}, async ({ status, limit }) => {
-    const qs = new URLSearchParams({ status: status ?? 'PENDING' });
-    if (limit)
-        qs.set('limit', String(limit));
-    try {
-        const res = await apiRetry(() => api(`/v1/worker/decisions?${qs.toString()}`, { method: 'GET' }));
-        return asToolResult({ count: res.decisions.length, decisions: res.decisions });
-    }
-    catch (err) {
-        return asToolError(err);
-    }
-});
-server.registerTool('cancel_decision', {
-    description: 'Withdraw a decision you requested but no longer need (the task was aborted or the question became moot). Resolves it and stops notifying the human. Only PENDING decisions cancel; an already-answered one is returned unchanged (cancelled=false).',
-    inputSchema: {
-        decision_id: z.string().describe('The decision_id returned by request_decision.'),
-        note: z.string().optional().describe('Optional reason, recorded on the decision.'),
-    },
-}, async ({ decision_id, note }) => {
-    // Cancel is naturally idempotent (only PENDING transitions), so a retry is
-    // safe without a key: a second one returns the already-resolved decision.
-    try {
-        return asToolResult(await apiRetry(() => api(`/v1/worker/decisions/${encodeURIComponent(decision_id)}/cancel`, {
-            method: 'POST',
-            body: JSON.stringify(note ? { note } : {}),
-        })));
-    }
-    catch (err) {
-        return asToolError(err);
-    }
-});
-const transport = new StdioServerTransport();
-await server.connect(transport);
-console.error(`ratifia-mcp connected → ${API_URL}`);
+const server = createRatifiaServer(cfg, { version: VERSION });
+await server.connect(new StdioServerTransport());
+console.error(`ratifia-mcp connected → ${cfg.apiUrl}`);