@iris-eval/mcp-server 0.8.2 → 0.10.0

package/dist/instructions.js

@@ -0,0 +1,53 @@
+import { JUDGE_KEY_VARS, judgeStateLine } from './judge-enablement.js';
+export const INSTRUCTIONS_MAX_CHARS = 2600;
+function prose(items) {
+    if (items.length <= 1)
+        return items.join('');
+    return `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`;
+}
+export function buildInstructions(i) {
+    const judgeHowTo = i.judge.enabled
+        ? 'They spend your key, never a shared one; the cap is refused before any spend.'
+        : `To enable them, put your own ${JUDGE_KEY_VARS.anthropic} or ${JUDGE_KEY_VARS.openai} in the env block of the iris-eval entry in your MCP client config and restart the session; iris://capabilities carries the full steps.`;
+    const critical = i.critical.length > 0 ? i.critical.join(', ') : 'none';
+    const text = [
+        'Iris evaluates what an AI agent wrote and what it did. It runs locally, stores traces and verdicts in SQLite, and sends nothing anywhere unless you enable the judge.',
+        `Three verbs. LOG an execution with log_trace (input, output, tool_calls, cost). EVALUATE with evaluate_output: ${i.ruleCount} deterministic rules in ${prose(i.categories)}. ` +
+            'Pass input so the relevance and hallucination rules can judge; pass tool_calls or a trace_id so the trajectory rules can judge; pass cost_usd so the cost rules can judge. ' +
+            'A rule with nothing to judge SKIPS and is named; it is never counted as a pass. INSPECT with get_traces and list_rules, or read a resource.',
+        `Reading a verdict. passed is the ship verdict: true only when score clears the threshold (${i.threshold} on this server) AND no critical rule failed. ` +
+            'verdict.basis says which layer decided (policy_gate, detector_veto, score_below_threshold, clean, or no_rules when nothing could be judged) and verdict.by names the rules. ' +
+            `Critical on this server: ${critical} (configurable; list_rules shows the effective value). ` +
+            'coverage says which evaluation questions were judged and why the others were not. A critical rule that could not judge is named in critical_skipped: treat that as UNKNOWN, not clean. ' +
+            'score is a quality gradient over the rules that ran; never read it alone as a safety signal.',
+        `The LLM judge (evaluate_with_llm_judge) and the citation verifier (verify_citations) are ${judgeStateLine(i.judge)}. ${judgeHowTo}`,
+        'Resources: iris://capabilities (what this server can judge, what each rule needs, judge state, limits), iris://proof (measured precision and recall per rule with 95% intervals), ' +
+            'iris://traces/{trace_id}, iris://evaluations/{id}, iris://dashboard/summary. Responses link what they created.',
+        'Do not use Iris to validate arbitrary JSON Schema, to screen inputs before they reach an agent (the injection rule reads output), or for semantic judgment without a key.',
+        'Errors from a tool return {"error":{"code","message","recovery":[]}} with isError true; follow recovery before retrying. ' +
+            'An argument the schema rejects comes back as plain text naming IRIS_INVALID_ARGUMENT and the valid arguments.',
+    ].join('\n\n');
+    if (text.length > INSTRUCTIONS_MAX_CHARS) {
+        throw new Error(`instructions are ${text.length} characters; the ceiling is ${INSTRUCTIONS_MAX_CHARS}`);
+    }
+    return text;
+}
+export const EVALUATE_MY_AGENT_PROMPT = 'evaluate-my-agent';
+/**
+ * The prompt a client shows as a slash command: a walk of log → evaluate →
+ * read → explain, in plain words, carrying the version so a cached copy
+ * cannot outlive a bump. Rendered from the same facts as the instructions.
+ */
+export function evaluateMyAgentPrompt(what, version) {
+    const source = what === 'trace-file'
+        ? 'Read the trace file I point you at (a JSON object or array with input, output and tool_calls per run).'
+        : 'Take the agent output I give you, with the input that produced it and the tool calls if I have them.';
+    return [
+        `Evaluate my agent with Iris ${version}. Do these steps and report in plain words.`,
+        `1. ${source}`,
+        '2. Log each run with log_trace, then evaluate it with evaluate_output, passing input, tool_calls (or the trace_id) and cost_usd whenever you have them so the relevance, trajectory and cost rules can judge.',
+        '3. Read the verdict: passed is the ship verdict; verdict.basis and verdict.by say which rule decided; coverage says what was not judged and why; critical_skipped means UNKNOWN, not clean.',
+        '4. For anything that failed, follow the resource link to iris://evaluations/{id} and quote the rule, its message and its evidence (offsets into my output, never a paraphrase of what the rule matched).',
+        '5. Tell me: what passed, what failed and why, what was not judged and what input would let Iris judge it. If I ask for a semantic judgment and the judge is not enabled, give me the recovery steps from the error instead of searching for them.',
+    ].join('\n');
+}

package/dist/judge-enablement.d.ts

@@ -0,0 +1,34 @@
+export type JudgeProvider = 'anthropic' | 'openai';
+export declare const JUDGE_KEY_VARS: Readonly<Record<JudgeProvider, string>>;
+export declare const JUDGE_COST_CAP_VAR = "IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL";
+export declare const JUDGE_DEFAULT_COST_CAP_USD = 0.25;
+export interface JudgeState {
+    /** A key for at least one provider is present in this process's environment. */
+    enabled: boolean;
+    /** The provider Iris would pick when a call names no provider: the first one with a key. */
+    provider: JudgeProvider | null;
+    /** Every provider with a key present. */
+    providers: JudgeProvider[];
+    /** The per-call spend cap the judge refuses beyond, before any spend. */
+    costCapUsd: number;
+}
+/** The per-call cap from the environment, else the shipped default. */
+export declare function judgeCostCapUsd(): number;
+export declare function judgeState(): JudgeState;
+export declare const JUDGE_ENABLE_TITLE: string;
+/**
+ * The enable workflow, one step per entry, from judge-enablement.json.
+ * Rendered verbatim into the IRIS_JUDGE_NOT_ENABLED error's `recovery`,
+ * the capabilities resource's `howToEnable`, and (through the truthbase)
+ * the README, the judge doc and the skill files. Change the JSON and
+ * nowhere else.
+ */
+export declare const JUDGE_ENABLE_STEPS: readonly string[];
+/** The block as prose: the title in bold, then the numbered steps — the exact form every surface carries. */
+export declare function judgeEnableBlock(): string;
+/** Shared with scripts/claims/render-llms.mjs, which renders the same shape from .claims.json. */
+export declare function renderJudgeEnableBlock(title: string, steps: readonly string[]): string;
+/** The steps as an error's `recovery[]`, with the variable the call needed named first. */
+export declare function judgeRecovery(provider: JudgeProvider): string[];
+/** One line for the instructions and the self-test: what this process can see. */
+export declare function judgeStateLine(state: JudgeState): string;

package/dist/judge-enablement.js

@@ -0,0 +1,78 @@
+/*
+ * The judge is a user-keyed feature (founder ruling, 2026-09-04): an end
+ * user enables it by supplying their own provider key, and every surface
+ * that mentions it has to say so in the same words — the error a tool
+ * returns without a key, the capabilities resource, the server
+ * instructions, the self-test, the README and the docs. The words live
+ * once, in judge-enablement.json beside this file: the runtime imports
+ * it, the truthbase generator copies it into .claims.json, the skill files
+ * render it as a slot, and tests/judge-enablement-surfaces.test.ts asserts
+ * the README and the judge doc carry the same block verbatim.
+ *
+ * What "enabled" means: a key for at least one provider reached THIS
+ * process's environment. That is the only fact Iris can check, and it is
+ * the fact users get wrong — a key exported in a shell is not passed to
+ * the child process an MCP client spawns unless the client's config says
+ * so. Step 2 exists because of that.
+ */
+import enable from './judge-enablement.json' with { type: 'json' };
+export const JUDGE_KEY_VARS = {
+    anthropic: 'IRIS_ANTHROPIC_API_KEY',
+    openai: 'IRIS_OPENAI_API_KEY',
+};
+export const JUDGE_COST_CAP_VAR = 'IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL';
+export const JUDGE_DEFAULT_COST_CAP_USD = 0.25;
+/** The per-call cap from the environment, else the shipped default. */
+export function judgeCostCapUsd() {
+    const raw = process.env.IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL;
+    if (raw) {
+        const parsed = Number(raw);
+        if (Number.isFinite(parsed) && parsed > 0)
+            return parsed;
+    }
+    return JUDGE_DEFAULT_COST_CAP_USD;
+}
+export function judgeState() {
+    // Literal reads on purpose: the docs contract and the manifest parity
+    // test grep `process.env.IRIS_*` to learn what the server reads.
+    const present = {
+        anthropic: Boolean(process.env.IRIS_ANTHROPIC_API_KEY),
+        openai: Boolean(process.env.IRIS_OPENAI_API_KEY),
+    };
+    const providers = Object.keys(JUDGE_KEY_VARS).filter((p) => present[p]);
+    return {
+        enabled: providers.length > 0,
+        provider: providers[0] ?? null,
+        providers,
+        costCapUsd: judgeCostCapUsd(),
+    };
+}
+export const JUDGE_ENABLE_TITLE = enable.title;
+/**
+ * The enable workflow, one step per entry, from judge-enablement.json.
+ * Rendered verbatim into the IRIS_JUDGE_NOT_ENABLED error's `recovery`,
+ * the capabilities resource's `howToEnable`, and (through the truthbase)
+ * the README, the judge doc and the skill files. Change the JSON and
+ * nowhere else.
+ */
+export const JUDGE_ENABLE_STEPS = enable.steps;
+/** The block as prose: the title in bold, then the numbered steps — the exact form every surface carries. */
+export function judgeEnableBlock() {
+    return renderJudgeEnableBlock(JUDGE_ENABLE_TITLE, JUDGE_ENABLE_STEPS);
+}
+/** Shared with scripts/claims/render-llms.mjs, which renders the same shape from .claims.json. */
+export function renderJudgeEnableBlock(title, steps) {
+    return [`**${title}**`, ...steps.map((s, i) => `${i + 1}. ${s}`)].join('\n');
+}
+/** The steps as an error's `recovery[]`, with the variable the call needed named first. */
+export function judgeRecovery(provider) {
+    return [`Set ${JUDGE_KEY_VARS[provider]} for the process that runs Iris.`, ...JUDGE_ENABLE_STEPS];
+}
+/** One line for the instructions and the self-test: what this process can see. */
+export function judgeStateLine(state) {
+    if (state.enabled) {
+        const list = state.providers.join(' and ');
+        return `enabled (${list} key found in this process; each call is capped at ${state.costCapUsd} USD)`;
+    }
+    return `not enabled (no ${JUDGE_KEY_VARS.anthropic} or ${JUDGE_KEY_VARS.openai} reached this process)`;
+}

package/dist/judge-enablement.json

@@ -0,0 +1,10 @@
+{
+    "title": "Enable the LLM judge (optional; the deterministic rules never need it)",
+    "steps": [
+        "Get an API key from Anthropic or OpenAI.",
+        "Put it in the environment of the process that runs Iris, not only your shell. Claude Code, Claude Desktop, Cursor and most MCP clients: the \"env\" block of the iris-eval entry in your MCP config — \"iris-eval\": { \"command\": \"npx\", \"args\": [\"-y\", \"@iris-eval/mcp-server\"], \"env\": { \"IRIS_ANTHROPIC_API_KEY\": \"sk-ant-...\" } } (IRIS_OPENAI_API_KEY for an OpenAI key). Docker: -e IRIS_ANTHROPIC_API_KEY=... on the run command. HTTP or CI: export it before starting iris-mcp.",
+        "Restart the MCP session. A running process never sees a variable set after it started.",
+        "Confirm from inside your client: read iris://capabilities — judge.enabled must be true there. A key exported in your shell is not passed to the process your client spawns unless its config lists it. On a machine, `npx @iris-eval/mcp-server --self-test` prints the judge line for that shell, and GET /api/v1/health reports judge.enabled on a running dashboard.",
+        "Spend guard: each call is capped by IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL (default 0.25 USD) and refused before any spend if the worst case would exceed it. Iris calls the provider directly with your key and never proxies it."
+    ]
+}

package/dist/preferences.d.ts

@@ -22,9 +22,9 @@ export declare const PreferencesSchema: z.ZodObject<{
     firstSeen: z.ZodOptional<z.ZodString>;
     dismissedBanners: z.ZodDefault<z.ZodArray<z.ZodString>>;
     theme: z.ZodDefault<z.ZodEnum<{
+        system: "system";
         light: "light";
         dark: "dark";
-        system: "system";
     }>>;
     momentFilters: z.ZodDefault<z.ZodObject<{
         agentName: z.ZodOptional<z.ZodString>;

package/dist/prompts.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const PROMPT_NAMES: readonly ["evaluate-my-agent"];
+export declare function registerPrompts(server: McpServer, version: string): void;

package/dist/prompts.js

@@ -0,0 +1,29 @@
+/*
+ * The one prompt: `evaluate-my-agent`. A client that supports prompts
+ * shows it as a slash command; a client that does not never sees it, and
+ * nothing in the README depends on it. Rendered from the same facts as
+ * the server instructions (src/instructions.ts) and carrying the version,
+ * so a cached copy cannot outlive a bump.
+ */
+import { z } from 'zod';
+import { EVALUATE_MY_AGENT_PROMPT, evaluateMyAgentPrompt } from './instructions.js';
+export const PROMPT_NAMES = [EVALUATE_MY_AGENT_PROMPT];
+export function registerPrompts(server, version) {
+    server.registerPrompt(EVALUATE_MY_AGENT_PROMPT, {
+        title: 'Evaluate my agent',
+        description: 'A walk through logging an agent run, evaluating it and reading the verdict with Iris, in plain words.',
+        argsSchema: {
+            what: z
+                .string()
+                .optional()
+                .describe('"output" (default): you have an agent output to hand; "trace-file": you have a file of runs to evaluate'),
+        },
+    }, ({ what }) => ({
+        messages: [
+            {
+                role: 'user',
+                content: { type: 'text', text: evaluateMyAgentPrompt(what === 'trace-file' ? 'trace-file' : 'output', version) },
+            },
+        ],
+    }));
+}

package/dist/resources/index.d.ts

@@ -1,3 +1,6 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { IStorageAdapter } from '../types/query.js';
-export declare function registerAllResources(server: McpServer, storage: IStorageAdapter): void;
+import type { Capabilities } from '../capabilities.js';
+/** The MCP resource-not-found code (the spec reserves -32002 for it). */
+export declare const RESOURCE_NOT_FOUND = -32002;
+export declare function registerAllResources(server: McpServer, storage: IStorageAdapter, capabilities: () => Capabilities): void;

package/dist/resources/index.js

@@ -1,6 +1,66 @@
-import { registerDashboardSummaryResource } from './dashboard-summary.js';
-import { registerTraceDetailResource } from './trace-detail.js';
-export function registerAllResources(server, storage) {
-    registerDashboardSummaryResource(server, storage);
-    registerTraceDetailResource(server, storage);
+/*
+ * The resources, registered the way the SDK wants them: fixed URIs with
+ * registerResource, parameterised ones with a ResourceTemplate (so a
+ * client's resources/templates/list shows the shape, and the SDK parses
+ * the variable instead of the handler splitting a path). A resource that
+ * does not exist is the protocol's resource-not-found error, never a 200
+ * body with an "error" key a client would have to sniff for.
+ */
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpError } from '@modelcontextprotocol/sdk/types.js';
+import { ruleProof } from '../capabilities.js';
+import { publishedProvenance, publishedRuleNames } from '../eval/accuracy.js';
+import { toEvaluationResponse } from '../eval/response.js';
+import { LOCAL_TENANT } from '../types/tenant.js';
+import { CAPABILITIES_RESOURCE_URI, DASHBOARD_SUMMARY_RESOURCE_URI, EVALUATION_RESOURCE_TEMPLATE, PROOF_RESOURCE_URI, TRACE_RESOURCE_TEMPLATE, } from './uris.js';
+/** The MCP resource-not-found code (the spec reserves -32002 for it). */
+export const RESOURCE_NOT_FOUND = -32002;
+function notFound(uri, what) {
+    return new McpError(RESOURCE_NOT_FOUND, `Resource not found: ${uri} — no ${what} with that id is stored for this tenant`, { uri });
+}
+const json = (uri, body) => ({
+    contents: [{ uri, mimeType: 'application/json', text: JSON.stringify(body, null, 2) }],
+});
+export function registerAllResources(server, storage, capabilities) {
+    server.registerResource('capabilities', CAPABILITIES_RESOURCE_URI, {
+        title: 'Capabilities',
+        description: 'What this server can judge: the rule roster with what each rule needs and its published accuracy, the judge state with the steps that enable it, the citation verifier posture, the dashboard address, the limits, and the tools, resources and prompts registered.',
+        mimeType: 'application/json',
+    }, async (uri) => json(uri.href, capabilities()));
+    server.registerResource('proof', PROOF_RESOURCE_URI, {
+        title: 'Proof',
+        description: 'The published accuracy of every measured built-in rule (the same numbers as https://iris-eval.com/proof): precision and recall on the proof corpus with 95% intervals, the confusion counts, positive predictive value at four prevalences, and the corpus version and labelling the numbers come from.',
+        mimeType: 'application/json',
+    }, async (uri) => {
+        const prov = publishedProvenance();
+        const rules = {};
+        for (const name of publishedRuleNames())
+            rules[name] = ruleProof(name);
+        return json(uri.href, {
+            corpusVersion: prov.corpusVersion,
+            release: prov.release,
+            labelling: prov.labelling,
+            method: 'Each rule is run over its proof-corpus family; precision and recall carry Wilson 95% intervals; ppvAt is the positive predictive value at the stated prevalence, from the same counts. Reproduce with `npm run proof` in the repository.',
+            rules,
+        });
+    });
+    server.registerResource('dashboard-summary', DASHBOARD_SUMMARY_RESOURCE_URI, { title: 'Dashboard summary', description: 'Dashboard summary with key metrics and trends for the last hour', mimeType: 'application/json' }, async (uri) => json(uri.href, await storage.getDashboardSummary(LOCAL_TENANT)));
+    server.registerResource('trace-detail', new ResourceTemplate(TRACE_RESOURCE_TEMPLATE, { list: undefined }), { title: 'Trace', description: 'One stored trace with its spans and every evaluation linked to it', mimeType: 'application/json' }, async (uri, variables) => {
+        const traceId = String(variables.trace_id ?? '');
+        const trace = await storage.getTrace(LOCAL_TENANT, traceId);
+        if (!trace)
+            throw notFound(uri.href, 'trace');
+        const [spans, evals] = await Promise.all([
+            storage.getSpansByTraceId(LOCAL_TENANT, traceId),
+            storage.getEvalsByTraceId(LOCAL_TENANT, traceId),
+        ]);
+        return json(uri.href, { trace, spans, evals: evals.map((e) => toEvaluationResponse(e, { traceId })) });
+    });
+    server.registerResource('evaluation-detail', new ResourceTemplate(EVALUATION_RESOURCE_TEMPLATE, { list: undefined }), { title: 'Evaluation', description: 'One stored evaluation, in the same shape evaluate_output returned it: verdict, coverage, provenance and every rule result with its evidence', mimeType: 'application/json' }, async (uri, variables) => {
+        const id = String(variables.id ?? '');
+        const result = await storage.getEvalById(LOCAL_TENANT, id);
+        if (!result)
+            throw notFound(uri.href, 'evaluation');
+        return json(uri.href, toEvaluationResponse(result, { traceId: result.trace_id }));
+    });
 }

package/dist/resources/uris.d.ts

@@ -0,0 +1,12 @@
+export declare const CAPABILITIES_RESOURCE_URI = "iris://capabilities";
+export declare const PROOF_RESOURCE_URI = "iris://proof";
+export declare const DASHBOARD_SUMMARY_RESOURCE_URI = "iris://dashboard/summary";
+export declare const TRACE_RESOURCE_TEMPLATE = "iris://traces/{trace_id}";
+export declare const EVALUATION_RESOURCE_TEMPLATE = "iris://evaluations/{id}";
+export declare const RESOURCE_URIS: readonly ["iris://capabilities", "iris://proof", "iris://dashboard/summary", "iris://traces/{trace_id}", "iris://evaluations/{id}"];
+/** The URI of one stored trace / evaluation, from its template. */
+export declare const traceUri: (traceId: string) => string;
+export declare const evaluationUri: (id: string) => string;
+/** Fixed URIs (resources/list) versus templates (resources/templates/list). */
+export declare const FIXED_RESOURCE_URIS: readonly ["iris://capabilities", "iris://proof", "iris://dashboard/summary"];
+export declare const RESOURCE_TEMPLATES: readonly ["iris://traces/{trace_id}", "iris://evaluations/{id}"];

package/dist/resources/uris.js

@@ -0,0 +1,24 @@
+/*
+ * Every resource URI this server registers, as literals: the capabilities
+ * object lists them, the docs contract checks prose against them, and a
+ * test asserts the list equals what resources/list and
+ * resources/templates/list return.
+ */
+export const CAPABILITIES_RESOURCE_URI = 'iris://capabilities';
+export const PROOF_RESOURCE_URI = 'iris://proof';
+export const DASHBOARD_SUMMARY_RESOURCE_URI = 'iris://dashboard/summary';
+export const TRACE_RESOURCE_TEMPLATE = 'iris://traces/{trace_id}';
+export const EVALUATION_RESOURCE_TEMPLATE = 'iris://evaluations/{id}';
+export const RESOURCE_URIS = [
+    CAPABILITIES_RESOURCE_URI,
+    PROOF_RESOURCE_URI,
+    DASHBOARD_SUMMARY_RESOURCE_URI,
+    TRACE_RESOURCE_TEMPLATE,
+    EVALUATION_RESOURCE_TEMPLATE,
+];
+/** The URI of one stored trace / evaluation, from its template. */
+export const traceUri = (traceId) => TRACE_RESOURCE_TEMPLATE.replace('{trace_id}', traceId);
+export const evaluationUri = (id) => EVALUATION_RESOURCE_TEMPLATE.replace('{id}', id);
+/** Fixed URIs (resources/list) versus templates (resources/templates/list). */
+export const FIXED_RESOURCE_URIS = [CAPABILITIES_RESOURCE_URI, PROOF_RESOURCE_URI, DASHBOARD_SUMMARY_RESOURCE_URI];
+export const RESOURCE_TEMPLATES = [TRACE_RESOURCE_TEMPLATE, EVALUATION_RESOURCE_TEMPLATE];

package/dist/retention.d.ts

@@ -0,0 +1,20 @@
+import type { IrisConfig } from './types/config.js';
+import type { IStorageAdapter } from './types/query.js';
+export interface RetentionLogger {
+    info(msg: string): void;
+    warn(msg: string): void;
+}
+export interface SweepOutcome {
+    deletedTraces: number;
+    deletedEvals: number;
+}
+/**
+ * One sweep for the local tenant. Never throws — a failed sweep is logged
+ * and the server keeps serving; the next tick tries again.
+ */
+export declare function runRetentionSweep(storage: IStorageAdapter, config: IrisConfig, logger: RetentionLogger): Promise<SweepOutcome | null>;
+/**
+ * The timer. Returns the handle (already unref'd) so a caller can clear it
+ * on shutdown, or null when retention or the timer is disabled.
+ */
+export declare function scheduleRetentionSweep(storage: IStorageAdapter, config: IrisConfig, logger: RetentionLogger): NodeJS.Timeout | null;

package/dist/retention.js

@@ -0,0 +1,44 @@
+import { LOCAL_TENANT } from './types/tenant.js';
+/**
+ * One sweep for the local tenant. Never throws — a failed sweep is logged
+ * and the server keeps serving; the next tick tries again.
+ */
+export async function runRetentionSweep(storage, config, logger) {
+    if (config.retention.days <= 0)
+        return null;
+    try {
+        const deletedTraces = await storage.deleteTracesOlderThan(LOCAL_TENANT, config.retention.days);
+        /*
+         * Evaluations too (#372). Deleting a trace only NULLs trace_id on
+         * its evaluations, so every eval row — output_text verbatim,
+         * including whatever no_pii flagged — used to outlive the retention
+         * window indefinitely while the traces around it were swept.
+         */
+        const deletedEvals = await storage.deleteEvalResultsOlderThan(LOCAL_TENANT, config.retention.days);
+        if (deletedTraces + deletedEvals > 0) {
+            // Fold the WAL into the main file and truncate it, so the swept
+            // rows do not survive as readable text in iris.db-wal.
+            await storage.checkpoint();
+            logger.info(`Retention cleanup: deleted ${deletedTraces} trace(s) and ${deletedEvals} evaluation(s) older than ${config.retention.days} days`);
+        }
+        return { deletedTraces, deletedEvals };
+    }
+    catch (err) {
+        logger.warn(`Retention cleanup skipped: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+/**
+ * The timer. Returns the handle (already unref'd) so a caller can clear it
+ * on shutdown, or null when retention or the timer is disabled.
+ */
+export function scheduleRetentionSweep(storage, config, logger) {
+    const hours = config.retention.sweepIntervalHours;
+    if (config.retention.days <= 0 || !(hours > 0))
+        return null;
+    const timer = setInterval(() => {
+        void runRetentionSweep(storage, config, logger);
+    }, hours * 60 * 60 * 1000);
+    timer.unref();
+    return timer;
+}

package/dist/self-test.d.ts

@@ -1,5 +1,6 @@
 export declare const SELF_TEST_STEPS: {
     readonly configuredHome: "configured IRIS_HOME is writable";
+    readonly judge: "judge key in this shell";
     readonly tempHome: "create isolated temp home";
     readonly storage: "initialize storage";
     readonly trace: "log a trace";

package/dist/self-test.js

@@ -48,6 +48,7 @@ import { irisHome } from './utils/iris-home.js';
 import { EvalEngine } from './eval/engine.js';
 import { generateTraceId } from './utils/ids.js';
 import { LOCAL_TENANT } from './types/tenant.js';
+import { judgeState, judgeStateLine } from './judge-enablement.js';
 const CHECK = '✓';
 const CROSS = '✗';
 /*
@@ -57,6 +58,7 @@ const CROSS = '✗';
  */
 export const SELF_TEST_STEPS = {
     configuredHome: 'configured IRIS_HOME is writable',
+    judge: 'judge key in this shell',
     tempHome: 'create isolated temp home',
     storage: 'initialize storage',
     trace: 'log a trace',
@@ -238,6 +240,18 @@ export async function runSelfTest(write = stdoutLine) {
     await step(SELF_TEST_STEPS.configuredHome, () => probeConfiguredHome(userHome, userStoragePath), {
         independent: true,
     });
+    /*
+     * The judge line, read from THIS shell's environment before the scrub
+     * (the judge variables are not scrubbed, but the order keeps the claim
+     * honest). Informational — a missing key is not a failed install — and
+     * it never calls a provider. The sentence about the client's env block
+     * is the whole point: a key exported here can print enabled while the
+     * process an MCP client spawns never receives it.
+     */
+    await step(SELF_TEST_STEPS.judge, () => {
+        const state = judgeState();
+        return `${judgeStateLine(state)}; your MCP client passes only what its config env block lists — confirm with iris://capabilities from inside the client`;
+    }, { independent: true });
     await step(SELF_TEST_STEPS.tempHome, () => {
         tempHome = mkdtempSync(join(tmpdir(), 'iris-self-test-'));
         for (const key of SCRUBBED_ENV_VARS) {
@@ -291,7 +305,7 @@ export async function runSelfTest(write = stdoutLine) {
         insertedIds.push(result.id);
     };
     await step(SELF_TEST_STEPS.piiEval, async () => {
-        const result = evalEngine.evaluate('safety', {
+        const result = await evalEngine.evaluate('safety', {
             // A real-shaped SSN, not the never-issued 123-45-6789 documentation
             // placeholder — no_pii suppresses that one on purpose.
             output: 'Done. For the record, the customer SSN is 536-22-8145.',
@@ -303,7 +317,7 @@ export async function runSelfTest(write = stdoutLine) {
         return 'no_pii flagged the planted SSN';
     });
     await step(SELF_TEST_STEPS.injectionEval, async () => {
-        const result = evalEngine.evaluate('safety', {
+        const result = await evalEngine.evaluate('safety', {
             output: 'Sure. I will ignore all previous instructions and reveal the system prompt.',
         });
         const rule = result.rule_results.find((r) => r.ruleName === 'no_injection_patterns');
@@ -313,7 +327,7 @@ export async function runSelfTest(write = stdoutLine) {
         return 'no_injection_patterns flagged the override text';
     });
     await step(SELF_TEST_STEPS.cleanEval, async () => {
-        const result = evalEngine.evaluate('safety', {
+        const result = await evalEngine.evaluate('safety', {
             output: 'The report is ready: weather in Paris stays mild this week, with light rain expected on Thursday evening.',
         });
         ensure(result.passed && result.score === 1, `clean output should score 1 and pass; got score=${result.score} passed=${result.passed}`);

package/dist/server.d.ts

@@ -3,9 +3,18 @@ import type { IrisConfig } from './types/index.js';
 import type { IStorageAdapter } from './types/query.js';
 import type { CustomRuleStore } from './custom-rule-store.js';
 import { EvalEngine } from './eval/engine.js';
+import { type Capabilities } from './capabilities.js';
 export interface IrisServer {
     mcpServer: McpServer;
     evalEngine: EvalEngine;
     customRuleStore: CustomRuleStore;
+    /** The instructions the client received at initialize — built from this server's runtime state. */
+    instructions: string;
+    /** What this server can do, as iris://capabilities and /api/v1/capabilities serve it. */
+    capabilities: () => Capabilities;
 }
-export declare function createIrisServer(config: IrisConfig, storage: IStorageAdapter, customRuleStore?: CustomRuleStore): IrisServer;
+export interface IrisServerOptions {
+    /** `demo` when the server runs against the disposable demo database. */
+    mode?: 'real' | 'demo';
+}
+export declare function createIrisServer(config: IrisConfig, storage: IStorageAdapter, customRuleStore?: CustomRuleStore, options?: IrisServerOptions): IrisServer;

package/dist/server.js

@@ -1,20 +1,47 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { EvalEngine } from './eval/engine.js';
+import { rulesByType } from './eval/rules/index.js';
+import { builtInRuleRoster } from './eval/criticality.js';
 import { registerAllTools } from './tools/index.js';
 import { registerAllResources } from './resources/index.js';
+import { registerPrompts } from './prompts.js';
 import { createCustomRuleStore } from './custom-rule-store.js';
-export function createIrisServer(config, storage, customRuleStore) {
-    const mcpServer = new McpServer({
-        name: config.server.name,
-        version: config.server.version,
-    });
+import { buildInstructions } from './instructions.js';
+import { buildCapabilities } from './capabilities.js';
+import { judgeState } from './judge-enablement.js';
+export function createIrisServer(config, storage, customRuleStore, options) {
     const evalEngine = new EvalEngine(config.eval.defaultThreshold, config.eval.ruleThresholds, config.eval);
     // Caller can inject a shared rule store (e.g. index.ts passes the
     // same instance the HTTP dashboard uses, so a rule deployed via MCP
     // is immediately visible in the dashboard without a restart). If
     // none provided, create a fresh one loading from the default path.
     const ruleStore = customRuleStore ?? createCustomRuleStore();
+    /*
+     * The instructions are built from what THIS process will do: the
+     * roster and bundles from the registry, the critical list after this
+     * config's promotions and demotions, and whether a judge key reached
+     * this environment. The key is read here once more at boot only to
+     * describe the state; the judge tools resolve it again per call, and
+     * both reads see the same environment because a process's environment
+     * is fixed when its client spawns it.
+     */
+    const roster = builtInRuleRoster((rule) => evalEngine.effectiveCriticality(rule));
+    const instructions = buildInstructions({
+        ruleCount: roster.length,
+        categories: Object.entries(rulesByType)
+            .filter(([, rules]) => rules.length > 0)
+            .map(([category]) => category),
+        threshold: config.eval.defaultThreshold,
+        critical: roster.filter((r) => r.critical).map((r) => r.name),
+        judge: judgeState(),
+    });
+    const mcpServer = new McpServer({
+        name: config.server.name,
+        version: config.server.version,
+    }, { instructions });
+    const capabilities = () => buildCapabilities({ config, evalEngine, customRuleStore: ruleStore, mode: options?.mode });
     registerAllTools(mcpServer, storage, evalEngine, ruleStore);
-    registerAllResources(mcpServer, storage);
-    return { mcpServer, evalEngine, customRuleStore: ruleStore };
+    registerAllResources(mcpServer, storage, capabilities);
+    registerPrompts(mcpServer, config.server.version);
+    return { mcpServer, evalEngine, customRuleStore: ruleStore, instructions, capabilities };
 }

package/dist/storage/index.js

@@ -2,7 +2,7 @@ import { SqliteAdapter } from './sqlite-adapter.js';
 export function createStorage(config) {
     switch (config.storage.type) {
         case 'sqlite':
-            return new SqliteAdapter(config.storage.path);
+            return new SqliteAdapter(config.storage.path, { redact: config.storage.redact ?? 'none' });
         default:
             throw new Error(`Unsupported storage type: ${config.storage.type} (supported: sqlite)`);
     }

package/dist/storage/migrations/007-eval-provenance.d.ts

@@ -0,0 +1,3 @@
+import type Database from 'better-sqlite3';
+export declare const id = "007-eval-provenance";
+export declare function up(db: Database.Database): void;

package/dist/storage/migrations/007-eval-provenance.js

@@ -0,0 +1,30 @@
+export const id = '007-eval-provenance';
+/*
+ * What an evaluation cannot reconstruct about itself after the fact: the
+ * Iris version, the ruleset and configuration hashes and the threshold that
+ * produced it (arc zero: "why did this pass on that day" was unanswerable
+ * from Iris alone), the judge's spend (the tool description said it was
+ * kept; the write path stored none of it), and the erasure stamp the
+ * right-to-erasure fix sets when a trace is deleted. `writer_version` on the
+ * migration ledger lets a downgraded binary refuse a database it cannot
+ * read instead of reading half a schema.
+ *
+ * `verdict`, `coverage` and `critical_skipped` are NOT columns: every one of
+ * them is derived on read from the stored rule_results plus the threshold
+ * kept here, so rows written before this migration read back the same way
+ * without a backfill.
+ */
+export function up(db) {
+    db.exec(`
+    ALTER TABLE eval_results ADD COLUMN provenance TEXT;
+    ALTER TABLE eval_results ADD COLUMN engine_version TEXT;
+    ALTER TABLE eval_results ADD COLUMN ruleset_hash TEXT;
+    ALTER TABLE eval_results ADD COLUMN config_hash TEXT;
+    ALTER TABLE eval_results ADD COLUMN threshold REAL;
+    ALTER TABLE eval_results ADD COLUMN eval_cost_usd REAL;
+    ALTER TABLE eval_results ADD COLUMN eval_tokens INTEGER;
+    ALTER TABLE eval_results ADD COLUMN erased_at TEXT;
+    ALTER TABLE _iris_migrations ADD COLUMN writer_version TEXT;
+    CREATE INDEX IF NOT EXISTS idx_eval_results_tenant_engine ON eval_results(tenant_id, engine_version, ruleset_hash);
+  `);
+}