@iris-eval/mcp-server 0.3.0 → 0.4.0-rc.1

package/dist/storage/sqlite-adapter.js

@@ -1,7 +1,38 @@
+/*
+ * SqliteAdapter — tenant-enforcing SQLite implementation of IStorageAdapter.
+ *
+ * Every public method takes a TenantId as its first parameter and uses
+ * it in the SQL layer to prevent cross-tenant data leaks. See the
+ * 2026-04-23 threat model §5 for the design principles.
+ *
+ * Discipline:
+ *   - Every method first validates tenantId is a non-empty string.
+ *     If validation fails, throws TenantContextRequiredError. This is
+ *     defense-in-depth — the TenantId type system already prevents
+ *     empty strings at compile time, but we verify at runtime too so
+ *     any dynamic bypass (e.g. a buggy cast) still fails safe.
+ *   - Every INSERT binds tenant_id from the parameter, never from the
+ *     payload data.
+ *   - Every SELECT includes `WHERE tenant_id = ?` as the first
+ *     condition; composite indexes put tenant_id first.
+ *   - Aggregate queries (stats, trends) scope to the tenant.
+ *   - DELETE operations scope to the tenant — a tenant can only delete
+ *     its own data.
+ */
 import Database from 'better-sqlite3';
+import { TenantContextRequiredError } from '../types/tenant.js';
 import { runMigrations } from './migrations/index.js';
 const ALLOWED_SORT_COLUMNS = new Set(['timestamp', 'latency_ms', 'cost_usd']);
 const ALLOWED_SORT_ORDERS = new Set(['asc', 'desc']);
+/**
+ * Defense-in-depth runtime check. The TypeScript brand prevents most
+ * misuse at compile time; this catches any dynamic cast bypass.
+ */
+function assertTenant(tenantId) {
+    if (typeof tenantId !== 'string' || tenantId.length === 0) {
+        throw new TenantContextRequiredError('SqliteAdapter method invoked without a valid TenantId; refusing to query');
+    }
+}
 export class SqliteAdapter {
     db;
     constructor(dbPath) {
@@ -16,34 +47,39 @@ export class SqliteAdapter {
     async close() {
         this.db.close();
     }
-    async insertTrace(trace) {
+    async insertTrace(tenantId, trace) {
+        assertTenant(tenantId);
         const insertTraceStmt = this.db.prepare(`
-      INSERT INTO traces (trace_id, agent_name, framework, input, output, tool_calls, latency_ms, token_usage, cost_usd, metadata, timestamp)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      INSERT INTO traces (tenant_id, trace_id, agent_name, framework, input, output, tool_calls, latency_ms, token_usage, cost_usd, metadata, timestamp)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
         const insertSpanStmt = this.db.prepare(`
-      INSERT INTO spans (span_id, trace_id, parent_span_id, name, kind, status_code, status_message, start_time, end_time, attributes, events)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      INSERT INTO spans (tenant_id, span_id, trace_id, parent_span_id, name, kind, status_code, status_message, start_time, end_time, attributes, events)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
         const insertAll = this.db.transaction((t) => {
-            insertTraceStmt.run(t.trace_id, t.agent_name, t.framework ?? null, t.input ?? null, t.output ?? null, t.tool_calls ? JSON.stringify(t.tool_calls) : null, t.latency_ms ?? null, t.token_usage ? JSON.stringify(t.token_usage) : null, t.cost_usd ?? null, t.metadata ? JSON.stringify(t.metadata) : null, t.timestamp);
+            insertTraceStmt.run(tenantId, t.trace_id, t.agent_name, t.framework ?? null, t.input ?? null, t.output ?? null, t.tool_calls ? JSON.stringify(t.tool_calls) : null, t.latency_ms ?? null, t.token_usage ? JSON.stringify(t.token_usage) : null, t.cost_usd ?? null, t.metadata ? JSON.stringify(t.metadata) : null, t.timestamp);
             if (t.spans) {
                 for (const span of t.spans) {
-                    insertSpanStmt.run(span.span_id, t.trace_id, span.parent_span_id ?? null, span.name, span.kind, span.status_code, span.status_message ?? null, span.start_time, span.end_time ?? null, span.attributes ? JSON.stringify(span.attributes) : null, span.events ? JSON.stringify(span.events) : null);
+                    insertSpanStmt.run(tenantId, span.span_id, t.trace_id, span.parent_span_id ?? null, span.name, span.kind, span.status_code, span.status_message ?? null, span.start_time, span.end_time ?? null, span.attributes ? JSON.stringify(span.attributes) : null, span.events ? JSON.stringify(span.events) : null);
                 }
             }
         });
         insertAll(trace);
     }
-    async getTrace(traceId) {
-        const row = this.db.prepare('SELECT * FROM traces WHERE trace_id = ?').get(traceId);
+    async getTrace(tenantId, traceId) {
+        assertTenant(tenantId);
+        const row = this.db
+            .prepare('SELECT * FROM traces WHERE tenant_id = ? AND trace_id = ?')
+            .get(tenantId, traceId);
         if (!row)
             return null;
         return this.rowToTrace(row);
     }
-    async queryTraces(options) {
-        const conditions = [];
-        const params = [];
+    async queryTraces(tenantId, options) {
+        assertTenant(tenantId);
+        const conditions = ['tenant_id = ?'];
+        const params = [tenantId];
         const filter = options.filter;
         if (filter?.agent_name) {
             conditions.push('agent_name = ?');
@@ -62,14 +98,14 @@ export class SqliteAdapter {
             params.push(filter.until);
         }
         if (filter?.min_score !== undefined) {
-            conditions.push('EXISTS (SELECT 1 FROM eval_results e WHERE e.trace_id = traces.trace_id AND e.score >= ?)');
+            conditions.push('EXISTS (SELECT 1 FROM eval_results e WHERE e.tenant_id = traces.tenant_id AND e.trace_id = traces.trace_id AND e.score >= ?)');
             params.push(filter.min_score);
         }
         if (filter?.max_score !== undefined) {
-            conditions.push('EXISTS (SELECT 1 FROM eval_results e WHERE e.trace_id = traces.trace_id AND e.score <= ?)');
+            conditions.push('EXISTS (SELECT 1 FROM eval_results e WHERE e.tenant_id = traces.tenant_id AND e.trace_id = traces.trace_id AND e.score <= ?)');
             params.push(filter.max_score);
         }
-        const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+        const whereClause = `WHERE ${conditions.join(' AND ')}`;
         const sortBy = options.sort_by ?? 'timestamp';
         const sortOrder = options.sort_order ?? 'desc';
         if (!ALLOWED_SORT_COLUMNS.has(sortBy)) {
@@ -93,33 +129,38 @@ export class SqliteAdapter {
             offset,
         };
     }
-    async insertSpan(span) {
+    async insertSpan(tenantId, span) {
+        assertTenant(tenantId);
         this.db.prepare(`
-      INSERT INTO spans (span_id, trace_id, parent_span_id, name, kind, status_code, status_message, start_time, end_time, attributes, events)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(span.span_id, span.trace_id, span.parent_span_id ?? null, span.name, span.kind, span.status_code, span.status_message ?? null, span.start_time, span.end_time ?? null, span.attributes ? JSON.stringify(span.attributes) : null, span.events ? JSON.stringify(span.events) : null);
+      INSERT INTO spans (tenant_id, span_id, trace_id, parent_span_id, name, kind, status_code, status_message, start_time, end_time, attributes, events)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(tenantId, span.span_id, span.trace_id, span.parent_span_id ?? null, span.name, span.kind, span.status_code, span.status_message ?? null, span.start_time, span.end_time ?? null, span.attributes ? JSON.stringify(span.attributes) : null, span.events ? JSON.stringify(span.events) : null);
     }
-    async getSpansByTraceId(traceId) {
+    async getSpansByTraceId(tenantId, traceId) {
+        assertTenant(tenantId);
         const rows = this.db
-            .prepare('SELECT * FROM spans WHERE trace_id = ? ORDER BY start_time')
-            .all(traceId);
+            .prepare('SELECT * FROM spans WHERE tenant_id = ? AND trace_id = ? ORDER BY start_time')
+            .all(tenantId, traceId);
         return rows.map((row) => this.rowToSpan(row));
     }
-    async insertEvalResult(result) {
+    async insertEvalResult(tenantId, result) {
+        assertTenant(tenantId);
         this.db.prepare(`
-      INSERT INTO eval_results (id, trace_id, eval_type, output_text, expected_text, score, passed, rule_results, suggestions, rules_evaluated, rules_skipped, insufficient_data)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(result.id, result.trace_id ?? null, result.eval_type, result.output_text, result.expected_text ?? null, result.score, result.passed ? 1 : 0, JSON.stringify(result.rule_results), JSON.stringify(result.suggestions), result.rules_evaluated ?? null, result.rules_skipped ?? null, result.insufficient_data ? 1 : 0);
+      INSERT INTO eval_results (tenant_id, id, trace_id, eval_type, output_text, expected_text, score, passed, rule_results, suggestions, rules_evaluated, rules_skipped, insufficient_data)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(tenantId, result.id, result.trace_id ?? null, result.eval_type, result.output_text, result.expected_text ?? null, result.score, result.passed ? 1 : 0, JSON.stringify(result.rule_results), JSON.stringify(result.suggestions), result.rules_evaluated ?? null, result.rules_skipped ?? null, result.insufficient_data ? 1 : 0);
     }
-    async getEvalsByTraceId(traceId) {
+    async getEvalsByTraceId(tenantId, traceId) {
+        assertTenant(tenantId);
         const rows = this.db
-            .prepare('SELECT * FROM eval_results WHERE trace_id = ? ORDER BY created_at DESC')
-            .all(traceId);
+            .prepare('SELECT * FROM eval_results WHERE tenant_id = ? AND trace_id = ? ORDER BY created_at DESC')
+            .all(tenantId, traceId);
         return rows.map((row) => this.rowToEvalResult(row));
     }
-    async queryEvalResults(options) {
-        const conditions = [];
-        const params = [];
+    async queryEvalResults(tenantId, options) {
+        assertTenant(tenantId);
+        const conditions = ['tenant_id = ?'];
+        const params = [tenantId];
         if (options.eval_type) {
             conditions.push('eval_type = ?');
             params.push(options.eval_type);
@@ -136,7 +177,7 @@ export class SqliteAdapter {
             conditions.push('created_at <= ?');
             params.push(options.until);
         }
-        const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+        const whereClause = `WHERE ${conditions.join(' AND ')}`;
         const limit = options.limit ?? 50;
         const offset = options.offset ?? 0;
         const countRow = this.db
@@ -150,37 +191,38 @@ export class SqliteAdapter {
             total: countRow.count,
         };
     }
-    async getDashboardSummary(sinceHours = 24) {
+    async getDashboardSummary(tenantId, sinceHours = 24) {
+        assertTenant(tenantId);
         const since = new Date(Date.now() - sinceHours * 60 * 60 * 1000).toISOString();
         const stats = this.db.prepare(`
       SELECT
         COUNT(*) as total_traces,
         COALESCE(AVG(latency_ms), 0) as avg_latency_ms,
         COALESCE(SUM(cost_usd), 0) as total_cost_usd
-      FROM traces WHERE timestamp >= ?
-    `).get(since);
+      FROM traces WHERE tenant_id = ? AND timestamp >= ?
+    `).get(tenantId, since);
         const errorCount = this.db.prepare(`
       SELECT COUNT(DISTINCT t.trace_id) as count
       FROM traces t
-      JOIN spans s ON s.trace_id = t.trace_id
-      WHERE t.timestamp >= ? AND s.status_code = 'ERROR'
-    `).get(since);
+      JOIN spans s ON s.tenant_id = t.tenant_id AND s.trace_id = t.trace_id
+      WHERE t.tenant_id = ? AND t.timestamp >= ? AND s.status_code = 'ERROR'
+    `).get(tenantId, since);
         const evalStats = this.db.prepare(`
       SELECT
         COUNT(*) as total,
         SUM(CASE WHEN passed = 1 THEN 1 ELSE 0 END) as passed_count
-      FROM eval_results WHERE created_at >= ?
-    `).get(since);
+      FROM eval_results WHERE tenant_id = ? AND created_at >= ?
+    `).get(tenantId, since);
         const tracesPerHour = this.db.prepare(`
       SELECT strftime('%Y-%m-%dT%H:00:00', timestamp) as hour, COUNT(*) as count
-      FROM traces WHERE timestamp >= ?
+      FROM traces WHERE tenant_id = ? AND timestamp >= ?
       GROUP BY hour ORDER BY hour
-    `).all(since);
+    `).all(tenantId, since);
         const topAgents = this.db.prepare(`
       SELECT agent_name, COUNT(*) as count
-      FROM traces WHERE timestamp >= ?
+      FROM traces WHERE tenant_id = ? AND timestamp >= ?
       GROUP BY agent_name ORDER BY count DESC LIMIT 10
-    `).all(since);
+    `).all(tenantId, since);
         return {
             total_traces: stats.total_traces,
             avg_latency_ms: Math.round(stats.avg_latency_ms * 100) / 100,
@@ -200,7 +242,8 @@ export class SqliteAdapter {
         const hours = period === '24h' ? 24 : period === '7d' ? 168 : 720;
         return new Date(Date.now() - hours * 60 * 60 * 1000).toISOString();
     }
-    async getEvalStats(period) {
+    async getEvalStats(tenantId, period) {
+        assertTenant(tenantId);
         const since = this.periodToSince(period);
         const agg = this.db.prepare(`
       SELECT
@@ -208,27 +251,25 @@ export class SqliteAdapter {
         COALESCE(AVG(score), 0)                      AS avg_score,
         SUM(CASE WHEN passed = 1 THEN 1 ELSE 0 END) AS passed_count
       FROM eval_results
-      WHERE created_at >= ? AND trace_id IS NOT NULL
-    `).get(since);
+      WHERE tenant_id = ? AND created_at >= ? AND trace_id IS NOT NULL
+    `).get(tenantId, since);
         const cost = this.db.prepare(`
       SELECT COALESCE(SUM(cost_usd), 0) AS total_cost
       FROM traces
-      WHERE timestamp >= ?
-    `).get(since);
+      WHERE tenant_id = ? AND timestamp >= ?
+    `).get(tenantId, since);
         const agents = this.db.prepare(`
       SELECT COUNT(DISTINCT agent_name) AS agent_count
       FROM traces
-      WHERE timestamp >= ?
-    `).get(since);
-        // Safety violations — scan rule_results JSON for failing safety rules.
-        // rule_results is stored as a JSON array of EvalRuleResult objects.
+      WHERE tenant_id = ? AND timestamp >= ?
+    `).get(tenantId, since);
         const safetyRows = this.db.prepare(`
       SELECT rule_results
       FROM eval_results
-      WHERE created_at >= ?
+      WHERE tenant_id = ? AND created_at >= ?
         AND eval_type = 'safety'
         AND passed = 0
-    `).all(since);
+    `).all(tenantId, since);
         const violations = { pii: 0, injection: 0, hallucination: 0 };
         for (const row of safetyRows) {
             const rules = JSON.parse(row.rule_results);
@@ -255,21 +296,18 @@ export class SqliteAdapter {
             period,
         };
     }
-    async getEvalStatsTrend(period) {
+    async getEvalStatsTrend(tenantId, period) {
+        assertTenant(tenantId);
         const since = this.periodToSince(period);
-        // Determine bucket format for strftime
         let bucketExpr;
         if (period === '24h') {
-            // hourly buckets
             bucketExpr = "strftime('%Y-%m-%dT%H:00:00Z', created_at)";
         }
         else if (period === '7d') {
-            // 6-hour buckets: floor hour to nearest 6
             bucketExpr =
                 "strftime('%Y-%m-%dT', created_at) || printf('%02d', (CAST(strftime('%H', created_at) AS INTEGER) / 6) * 6) || ':00:00Z'";
         }
         else {
-            // daily buckets
             bucketExpr = "strftime('%Y-%m-%dT00:00:00Z', created_at)";
         }
         const rows = this.db.prepare(`
@@ -281,10 +319,10 @@ export class SqliteAdapter {
           ELSE 0 END                                   AS pass_rate,
         COUNT(*)                                       AS eval_count
       FROM eval_results
-      WHERE created_at >= ?
+      WHERE tenant_id = ? AND created_at >= ?
       GROUP BY bucket
       ORDER BY bucket
-    `).all(since);
+    `).all(tenantId, since);
         return rows.map((r) => ({
             timestamp: r.bucket,
             avgScore: Math.round(r.avg_score * 1000) / 1000,
@@ -292,14 +330,14 @@ export class SqliteAdapter {
             evalCount: r.eval_count,
         }));
     }
-    async getEvalStatsRules(period) {
+    async getEvalStatsRules(tenantId, period) {
+        assertTenant(tenantId);
         const since = this.periodToSince(period);
         const rows = this.db.prepare(`
       SELECT rule_results
       FROM eval_results
-      WHERE created_at >= ?
-    `).all(since);
-        // Aggregate per-rule stats from the JSON arrays
+      WHERE tenant_id = ? AND created_at >= ?
+    `).all(tenantId, since);
         const ruleMap = new Map();
         for (const row of rows) {
             const rules = JSON.parse(row.rule_results);
@@ -324,11 +362,11 @@ export class SqliteAdapter {
                 failCount: stats.failCount,
             });
         }
-        // Sort by passRate ASC (worst rules first)
         result.sort((a, b) => a.passRate - b.passRate);
         return result;
     }
-    async getEvalStatsFailures(period, limit) {
+    async getEvalStatsFailures(tenantId, period, limit) {
+        assertTenant(tenantId);
         const since = this.periodToSince(period);
         const rows = this.db.prepare(`
       SELECT
@@ -339,14 +377,13 @@ export class SqliteAdapter {
         e.output_text,
         e.created_at
       FROM eval_results e
-      LEFT JOIN traces t ON t.trace_id = e.trace_id
-      WHERE e.created_at >= ?
+      LEFT JOIN traces t ON t.tenant_id = e.tenant_id AND t.trace_id = e.trace_id
+      WHERE e.tenant_id = ? AND e.created_at >= ?
         AND e.passed = 0
       ORDER BY e.created_at DESC
       LIMIT ?
-    `).all(since, limit);
+    `).all(tenantId, since, limit);
         return rows.map((r) => {
-            // Find the first failing rule to surface as the primary rule
             const rules = JSON.parse(r.rule_results);
             const failingRule = rules.find((rule) => !rule.passed);
             return {
@@ -359,21 +396,35 @@ export class SqliteAdapter {
             };
         });
     }
-    async deleteTracesOlderThan(days) {
+    async deleteTracesOlderThan(tenantId, days) {
+        assertTenant(tenantId);
         const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
-        const result = this.db.prepare('DELETE FROM traces WHERE timestamp < ?').run(cutoff);
+        const result = this.db
+            .prepare('DELETE FROM traces WHERE tenant_id = ? AND timestamp < ?')
+            .run(tenantId, cutoff);
         return result.changes;
     }
-    async getDistinctValues(column) {
+    async deleteTrace(tenantId, traceId) {
+        assertTenant(tenantId);
+        // Tenant-scoped: a trace id owned by a different tenant is
+        // untouchable from this call. Cross-tenant deletions are not just
+        // denied — they're invisible (no indication the id even exists).
+        const result = this.db
+            .prepare('DELETE FROM traces WHERE tenant_id = ? AND trace_id = ?')
+            .run(tenantId, traceId);
+        return result.changes > 0;
+    }
+    async getDistinctValues(tenantId, column) {
+        assertTenant(tenantId);
         const queries = {
-            agent_name: 'SELECT DISTINCT agent_name FROM traces WHERE agent_name IS NOT NULL ORDER BY agent_name',
-            framework: 'SELECT DISTINCT framework FROM traces WHERE framework IS NOT NULL ORDER BY framework',
+            agent_name: 'SELECT DISTINCT agent_name FROM traces WHERE tenant_id = ? AND agent_name IS NOT NULL ORDER BY agent_name',
+            framework: 'SELECT DISTINCT framework FROM traces WHERE tenant_id = ? AND framework IS NOT NULL ORDER BY framework',
         };
         const query = queries[column];
         if (!query) {
             throw new Error(`Column '${column}' is not queryable (allowed: ${Object.keys(queries).join(', ')})`);
         }
-        const rows = this.db.prepare(query).all();
+        const rows = this.db.prepare(query).all(tenantId);
         return rows.map((row) => row[column]);
     }
     rowToTrace(row) {

package/dist/tools/delete-rule.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CustomRuleStore } from '../custom-rule-store.js';
+export declare function registerDeleteRuleTool(server: McpServer, customRuleStore: CustomRuleStore): void;

package/dist/tools/delete-rule.js

@@ -0,0 +1,53 @@
+/*
+ * delete_rule MCP tool — remove a deployed custom rule.
+ *
+ * Destructive counterpart to deploy_rule. Removes the rule from
+ * ~/.iris/custom-rules.json (stops firing on future evaluate_output
+ * calls) and appends a `rule.delete` entry to the audit log.
+ *
+ * Past eval_results that referenced this rule stay intact — the
+ * history is preserved even after the rule is removed. The audit
+ * log row is the permanent record that the rule ever existed.
+ */
+import { z } from 'zod';
+const inputSchema = {
+    rule_id: z
+        .string()
+        .regex(/^rule-[a-z0-9]+$/)
+        .describe('Rule id to delete (format: rule-<hex>); obtained from list_rules or deploy_rule response'),
+};
+export function registerDeleteRuleTool(server, customRuleStore) {
+    server.registerTool('delete_rule', {
+        title: 'Delete Custom Rule',
+        description: [
+            'Remove a deployed custom evaluation rule. The rule stops firing on future evaluate_output calls; past eval_results that referenced it are preserved.',
+            '',
+            'Behavior. DESTRUCTIVE — rewrites ~/.iris/custom-rules.json without the deleted row and appends a `rule.delete` entry to the audit log (~/.iris/audit.log). Not idempotent: deleting an already-deleted rule returns `deleted: false` rather than re-emitting the audit row. The rule stops firing immediately on the live process. Historical eval_results that reference this rule_id stay in the database — drift analytics + audit trail remain valid. Tenant-scoped in Cloud tier; OSS operates on LOCAL_TENANT. Rate-limited to 20 req/min on HTTP MCP.',
+            '',
+            'Output shape. Returns JSON: `{ "deleted": boolean, "rule_id": string }`. `deleted=true` if a row was removed; `deleted=false` if no rule with that id existed.',
+            '',
+            "Use when a custom rule is obsolete (behavior changed, false positives unacceptable, replaced by a better rule). Typical flow: list_rules → identify the stale one → delete_rule(id). Combine with deploy_rule to replace: delete_rule(oldId) + deploy_rule(newDefinition). To temporarily disable a rule WITHOUT deletion, use the dashboard's toggle affordance instead — delete is permanent in intent (rule is gone; re-adding requires a new id).",
+            '',
+            "Don't use to pause a rule (toggle in the dashboard preserves history better). Don't use on built-in (non-custom) rules — the rule_id format checks for `rule-<hex>` custom ids; built-ins aren't in the store. Don't use to delete a trace or eval result (use delete_trace for traces; eval_results deletion is not exposed in v0.4 — they fall under data retention).",
+            '',
+            "Error modes. Throws 400 on malformed rule_id (wrong prefix). Returns `{deleted: false}` if rule_id doesn't match any deployed rule (not an error — idempotent-ish). Returns 429 on HTTP rate limit. File-write failures propagate as 500.",
+        ].join('\n'),
+        inputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async (args) => {
+        const deleted = customRuleStore.delete(args.rule_id, 'mcp');
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ deleted, rule_id: args.rule_id }),
+                },
+            ],
+        };
+    });
+}

package/dist/tools/delete-trace.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { IStorageAdapter } from '../types/query.js';
+export declare function registerDeleteTraceTool(server: McpServer, storage: IStorageAdapter): void;

package/dist/tools/delete-trace.js

@@ -0,0 +1,54 @@
+/*
+ * delete_trace MCP tool — remove a single trace by id.
+ *
+ * Destructive. Scoped to tenant — an agent cannot delete a trace
+ * belonging to another tenant (cross-tenant deletes look like
+ * "id not found").
+ *
+ * Cascades to spans via FK ON DELETE CASCADE. eval_results for the
+ * trace have their trace_id set to NULL (score history survives
+ * even after the underlying trace is gone).
+ */
+import { z } from 'zod';
+import { LOCAL_TENANT } from '../types/tenant.js';
+const inputSchema = {
+    trace_id: z
+        .string()
+        .regex(/^[a-f0-9]{32}$/)
+        .describe('Trace id to delete (32-hex lowercase; obtained from log_trace response or get_traces)'),
+};
+export function registerDeleteTraceTool(server, storage) {
+    server.registerTool('delete_trace', {
+        title: 'Delete Trace',
+        description: [
+            'Remove a single trace by id. Cascades to spans; eval_results keep the score history with trace_id NULLed.',
+            '',
+            'Behavior. DESTRUCTIVE — SQL DELETE scoped to the caller\'s tenant_id. Cascades: spans belonging to this trace are deleted (FK ON DELETE CASCADE); eval_results that referenced this trace have their trace_id set to NULL (FK ON DELETE SET NULL) so aggregate dashboards + historical scores remain valid even after the trace is gone. Not idempotent: deleting an already-deleted trace returns `deleted: false`. Does not emit an audit log entry in v0.4 — traces are user-scope data, not policy changes. Rate-limited to 20 req/min on HTTP MCP.',
+            '',
+            'Output shape. Returns JSON: `{ "deleted": boolean, "trace_id": string }`. `deleted=true` if a row was removed; `deleted=false` if no trace with that id existed (or it belonged to a different tenant — cross-tenant deletes silently fail).',
+            '',
+            "Use when a trace was captured in error, contains sensitive data that must be removed for compliance (e.g., a customer exercises GDPR right-to-erasure), or when cleaning up test data. Combine with get_traces to find candidates: query with filters → review → delete_trace(id) per target. For bulk time-window deletion, use `deleteTracesOlderThan` via the CLI / retention config — delete_trace is the single-row surgical path.",
+            '',
+            "Don't use to clean up OLD data in bulk (use retention config with --retention-days). Don't use to PAUSE a trace — traces are immutable once stored; there's nothing to pause. Don't use to delete eval_results — eval_results survive their trace's deletion intentionally (for audit + drift analysis); they're pruned only by retention.",
+            '',
+            "Error modes. Throws 400 on malformed trace_id (wrong format: not 32-char lowercase hex). Returns `{deleted: false}` when the id doesn't exist in the caller's tenant (not an error — the trace may simply have been deleted already). Returns 429 on HTTP rate limit. Storage failures propagate as 500.",
+        ].join('\n'),
+        inputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async (args) => {
+        const deleted = await storage.deleteTrace(LOCAL_TENANT, args.trace_id);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ deleted, trace_id: args.trace_id }),
+                },
+            ],
+        };
+    });
+}

package/dist/tools/deploy-rule.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CustomRuleStore } from '../custom-rule-store.js';
+export declare function registerDeployRuleTool(server: McpServer, customRuleStore: CustomRuleStore): void;

package/dist/tools/deploy-rule.js

@@ -0,0 +1,91 @@
+/*
+ * deploy_rule MCP tool — programmatically add a custom eval rule.
+ *
+ * Mirror of the dashboard's Make-This-A-Rule composer, but callable
+ * from an agent. An agent that observes a failure pattern can deploy
+ * a rule without a human in the loop.
+ *
+ * Writes to ~/.iris/custom-rules.json (single source of truth) and
+ * appends to the audit log. Persisted rules auto-load on server boot
+ * and fire on every future evaluate_output call of the matching
+ * eval_type.
+ */
+import { z } from 'zod';
+const CustomRuleDefinitionSchema = z.object({
+    name: z.string(),
+    type: z.enum([
+        'regex_match',
+        'regex_no_match',
+        'min_length',
+        'max_length',
+        'contains_keywords',
+        'excludes_keywords',
+        'json_schema',
+        'cost_threshold',
+    ]),
+    config: z.record(z.unknown()),
+    weight: z.number().optional(),
+});
+const inputSchema = {
+    name: z.string().min(1).max(120).describe('Human-readable rule name (used in eval results)'),
+    description: z
+        .string()
+        .max(500)
+        .optional()
+        .describe('What this rule checks for and why it matters'),
+    evalType: z
+        .enum(['completeness', 'relevance', 'safety', 'cost', 'custom'])
+        .describe('Eval category this rule belongs to; determines when it fires'),
+    severity: z
+        .enum(['low', 'medium', 'high', 'critical'])
+        .default('medium')
+        .describe('Severity used for dashboard sort + audit alerts'),
+    definition: CustomRuleDefinitionSchema.describe('Check definition (regex, length, keyword, cost, or schema)'),
+    sourceMomentId: z
+        .string()
+        .optional()
+        .describe('Optional Decision Moment ID the rule was derived from (preserves workflow-inversion provenance)'),
+};
+export function registerDeployRuleTool(server, customRuleStore) {
+    server.registerTool('deploy_rule', {
+        title: 'Deploy Custom Rule',
+        description: [
+            'Deploy a new custom evaluation rule that will fire on every future evaluate_output call of its eval category.',
+            '',
+            'Behavior. Writes a row to ~/.iris/custom-rules.json (atomic write via temp file + rename) and appends a `rule.deploy` entry to the audit log (~/.iris/audit.log). The rule activates immediately for the running process and persists across restarts. Each call mints a fresh rule_id; not idempotent (deploying twice creates two rules). Tenant-scoped in Cloud tier; OSS rules are owned by LOCAL_TENANT. Rate-limited to 20 req/min on HTTP MCP.',
+            '',
+            'Output shape. Returns JSON: `{ "rule": { "id": "rule-XXXX", "name", "description", "evalType", "severity", "definition", "enabled": true, "createdAt", "updatedAt", "version": 1, "sourceMomentId?" } }`. The returned rule is the canonical persisted form; save the `id` if you plan to update or delete later.',
+            '',
+            "Use when an agent observes a recurring failure pattern and decides to enforce it as a standing rule. The `sourceMomentId` field preserves provenance — downstream audit can trace the rule back to the moment that inspired it. Combine with evaluate_output + get_traces: 1) evaluate_output surfaces failures; 2) get_traces filters to the failure set; 3) analyze the pattern; 4) deploy_rule bakes it into the default eval path.",
+            '',
+            "Don't use to VALIDATE a rule before committing — deploy writes immediately. Use the dashboard's preview endpoint (POST /api/v1/rules/custom/preview) for dry-run validation against sample output. Don't use to EDIT an existing rule — this call only creates; edits require a dedicated flow (coming in v0.5). To update a rule today: delete_rule then deploy_rule with the new definition.",
+            '',
+            "Error modes. Throws 400 on invalid definition (Zod rejects — e.g., regex that fails safe-regex2 ReDoS check, or length > 1000 chars). Throws 400 on empty `name`. Throws 400 if the eval category mismatches the definition type. Returns 429 when HTTP rate limit exceeded. File-write failures (disk full, read-only fs) propagate as 500; the audit log is best-effort and does not block deploy.",
+        ].join('\n'),
+        inputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async (args) => {
+        const rule = customRuleStore.deploy({
+            name: args.name,
+            description: args.description,
+            evalType: args.evalType,
+            severity: args.severity,
+            definition: args.definition,
+            sourceMomentId: args.sourceMomentId,
+            user: 'mcp',
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ rule }),
+                },
+            ],
+        };
+    });
+}