@iris-eval/mcp-server 0.3.1 → 0.4.0

package/dist/otel/exporter.js

@@ -0,0 +1,116 @@
+// OTLP/HTTP JSON exporter — posts ExportTraceServiceRequest payloads to
+// an OpenTelemetry collector, Jaeger, Grafana Tempo, or Datadog OTLP
+// ingest endpoint. Works against any receiver that speaks OTLP/HTTP
+// JSON at /v1/traces (the OTLP spec canonical path).
+//
+// Hand-rolled against the OTLP spec rather than pulling in @opentelemetry/*
+// — consistent with the LLM client + citation resolver approach (keep
+// supply-chain surface small, the wire format is simple). gRPC transport
+// is not included in v0.4.0; callers with gRPC-only receivers should
+// front it with an HTTP-accepting collector (Jaeger/Tempo/OTEL Collector
+// accept HTTP natively).
+//
+// Batch behavior: callers (typically log_trace handler) accumulate Trace
+// rows and call exportTraces([...]) at convenient points. The exporter
+// does NOT own a timer — keeping it stateless keeps it testable and
+// avoids accidentally leaking a process-wide interval in tests.
+import { buildExportPayload } from './mapper.js';
+export class OtelExporter {
+    endpoint;
+    serviceName;
+    headers;
+    timeoutMs;
+    constructor(config) {
+        // Normalize endpoint — strip trailing slash; append /v1/traces if
+        // the caller gave a collector root. This matches the behavior of
+        // the official OTLP/HTTP clients.
+        const base = config.endpoint.replace(/\/+$/, '');
+        const path = config.pathPrefix ?? '/v1/traces';
+        this.endpoint = base.endsWith(path) ? base : base + path;
+        this.serviceName = config.serviceName;
+        this.headers = { ...(config.headers ?? {}) };
+        this.timeoutMs = config.timeoutMs ?? 15_000;
+    }
+    async exportTraces(traces) {
+        if (traces.length === 0) {
+            return { ok: true, status: 204, bytesSent: 0, latencyMs: 0 };
+        }
+        const payload = buildExportPayload(traces, this.serviceName);
+        const body = JSON.stringify(payload);
+        const started = Date.now();
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const res = await fetch(this.endpoint, {
+                method: 'POST',
+                signal: controller.signal,
+                headers: {
+                    'content-type': 'application/json',
+                    ...this.headers,
+                },
+                body,
+            });
+            const latencyMs = Date.now() - started;
+            if (!res.ok) {
+                const text = await res.text().catch(() => '');
+                return {
+                    ok: false,
+                    status: res.status,
+                    bytesSent: body.length,
+                    latencyMs,
+                    error: `OTLP exporter got ${res.status}: ${text.slice(0, 200)}`,
+                };
+            }
+            return {
+                ok: true,
+                status: res.status,
+                bytesSent: body.length,
+                latencyMs,
+            };
+        }
+        catch (err) {
+            const latencyMs = Date.now() - started;
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                ok: false,
+                status: 0,
+                bytesSent: body.length,
+                latencyMs,
+                error: msg,
+            };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+export function exporterFromEnv() {
+    const endpoint = process.env.IRIS_OTEL_ENDPOINT;
+    if (!endpoint)
+        return null;
+    const serviceName = process.env.IRIS_OTEL_SERVICE_NAME ?? 'iris-mcp';
+    // IRIS_OTEL_HEADERS is a comma-separated list of key=value pairs —
+    // the OTel Collector convention. e.g. "authorization=Bearer xyz,x-tenant=foo".
+    let headers;
+    const rawHeaders = process.env.IRIS_OTEL_HEADERS;
+    if (rawHeaders) {
+        headers = {};
+        for (const pair of rawHeaders.split(',')) {
+            const eq = pair.indexOf('=');
+            if (eq < 1)
+                continue;
+            const k = pair.slice(0, eq).trim();
+            const v = pair.slice(eq + 1).trim();
+            if (k && v)
+                headers[k] = v;
+        }
+    }
+    const timeoutRaw = process.env.IRIS_OTEL_TIMEOUT_MS;
+    const timeoutMs = timeoutRaw ? Number(timeoutRaw) : undefined;
+    return new OtelExporter({
+        endpoint,
+        serviceName,
+        headers,
+        timeoutMs: Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : undefined,
+    });
+}

package/dist/otel/lazy.d.ts

@@ -0,0 +1,5 @@
+import { OtelExporter } from './exporter.js';
+import type { Trace } from '../types/trace.js';
+export declare function getLazyExporter(): OtelExporter | null;
+export declare function __resetExporterForTests(override?: OtelExporter | null): void;
+export declare function bestEffortExport(trace: Trace, onError?: (err: Error) => void): void;

package/dist/otel/lazy.js

@@ -0,0 +1,31 @@
+// Process-wide lazy exporter — initialized on first use, then reused.
+// Tests may reset it via __resetExporterForTests.
+import { exporterFromEnv } from './exporter.js';
+let cachedExporter; // undefined = not yet resolved
+export function getLazyExporter() {
+    if (cachedExporter === undefined) {
+        cachedExporter = exporterFromEnv();
+    }
+    return cachedExporter;
+}
+export function __resetExporterForTests(override) {
+    cachedExporter = override === undefined ? undefined : override;
+}
+// Fire-and-forget wrapper with inline error swallow. Runs in the
+// background; the caller does NOT await. We log on failure so operators
+// aren't surprised by silent drop, but never let an exporter problem
+// bubble into user-visible tool errors.
+export function bestEffortExport(trace, onError) {
+    const exporter = getLazyExporter();
+    if (!exporter)
+        return;
+    exporter
+        .exportTraces([trace])
+        .then((result) => {
+        if (!result.ok) {
+            const msg = `OTel export failed: status=${result.status} ${result.error ?? ''}`.trim();
+            onError?.(new Error(msg));
+        }
+    })
+        .catch((err) => onError?.(err));
+}

package/dist/otel/mapper.d.ts

@@ -0,0 +1,24 @@
+import type { Span, Trace } from '../types/trace.js';
+export interface OtlpKeyValue {
+    key: string;
+    value: OtlpAnyValue;
+}
+export type OtlpAnyValue = {
+    stringValue: string;
+} | {
+    boolValue: boolean;
+} | {
+    intValue: string;
+} | {
+    doubleValue: number;
+} | {
+    arrayValue: {
+        values: OtlpAnyValue[];
+    };
+} | {
+    kvlistValue: {
+        values: OtlpKeyValue[];
+    };
+};
+export declare function mapSpan(span: Span, traceIdOverride?: string): unknown;
+export declare function buildExportPayload(traces: readonly Trace[], serviceName: string): unknown;

package/dist/otel/mapper.js

@@ -0,0 +1,208 @@
+// Map Iris trace/span types to OTLP JSON shape for export.
+//
+// Reference: https://opentelemetry.io/docs/specs/otlp/#otlphttp-json-encoding
+// and the ExportTraceServiceRequest proto. OTLP JSON encodes uint64 IDs
+// as lowercase hex strings; trace_id is 16 bytes (32 hex chars), span_id
+// is 8 bytes (16 hex chars). Timestamps are nanoseconds since epoch as
+// strings (uint64 range exceeds JS Number.MAX_SAFE_INTEGER so we emit as
+// decimal string).
+//
+// We intentionally do not depend on @opentelemetry/* — the exporter
+// serializes these plain objects, and the payload shape is the OTLP spec.
+// OTel SpanKind enum values (from opentelemetry-proto/trace/v1/trace.proto).
+const KIND_MAP = {
+    INTERNAL: 1,
+    SERVER: 2,
+    CLIENT: 3,
+    PRODUCER: 4,
+    CONSUMER: 5,
+    // Iris-specific kinds — map to INTERNAL for OTel. The actual LLM /
+    // tool semantics are preserved in attributes (llm.provider, tool.name).
+    LLM: 1,
+    TOOL: 1,
+};
+const STATUS_MAP = {
+    UNSET: 0,
+    OK: 1,
+    ERROR: 2,
+};
+// Convert "abcdef0123..." (any length hex) to exactly 32 hex chars, or
+// if non-hex, hash it. Iris sometimes generates IDs like "mcp-<uuid>"
+// that aren't pure hex.
+function toTraceIdHex(raw) {
+    const hex = raw.replace(/-/g, '').toLowerCase();
+    if (/^[0-9a-f]{32}$/.test(hex))
+        return hex;
+    if (/^[0-9a-f]{16,}$/.test(hex))
+        return hex.slice(0, 32).padEnd(32, '0');
+    // Fallback: hash to 32 hex chars deterministically.
+    return djb2Hex(raw, 32);
+}
+function toSpanIdHex(raw) {
+    const hex = raw.replace(/-/g, '').toLowerCase();
+    if (/^[0-9a-f]{16}$/.test(hex))
+        return hex;
+    if (/^[0-9a-f]{8,}$/.test(hex))
+        return hex.slice(0, 16).padEnd(16, '0');
+    return djb2Hex(raw, 16);
+}
+// Tiny deterministic string → hex hash. Not cryptographic — just to give
+// OTel consumers a stable id when Iris produced a non-hex identifier.
+function djb2Hex(s, hexLen) {
+    let h = 5381n;
+    for (let i = 0; i < s.length; i++) {
+        h = ((h << 5n) + h + BigInt(s.charCodeAt(i))) & ((1n << 64n) - 1n);
+    }
+    // Use BigInt to avoid JS Number collisions on long strings.
+    let hex = h.toString(16);
+    while (hex.length < hexLen)
+        hex = hex + djb2Step(s + hex).toString(16);
+    return hex.slice(0, hexLen).padEnd(hexLen, '0');
+}
+function djb2Step(s) {
+    let h = 5381n;
+    for (let i = 0; i < s.length; i++) {
+        h = ((h << 5n) + h + BigInt(s.charCodeAt(i))) & ((1n << 64n) - 1n);
+    }
+    return h;
+}
+function toNanoString(iso) {
+    if (!iso)
+        return '0';
+    const ms = new Date(iso).getTime();
+    if (!Number.isFinite(ms))
+        return '0';
+    // ms → ns as string (BigInt-safe).
+    return (BigInt(ms) * 1000000n).toString();
+}
+function toAnyValue(v) {
+    if (typeof v === 'string')
+        return { stringValue: v };
+    if (typeof v === 'boolean')
+        return { boolValue: v };
+    if (typeof v === 'number') {
+        if (Number.isInteger(v))
+            return { intValue: String(v) };
+        return { doubleValue: v };
+    }
+    if (Array.isArray(v)) {
+        return { arrayValue: { values: v.map(toAnyValue) } };
+    }
+    if (v && typeof v === 'object') {
+        return {
+            kvlistValue: {
+                values: Object.entries(v).map(([k, val]) => ({
+                    key: k,
+                    value: toAnyValue(val),
+                })),
+            },
+        };
+    }
+    // null / undefined / bigint / fn / symbol — fall back to string
+    return { stringValue: String(v) };
+}
+function flattenAttrs(attrs) {
+    if (!attrs)
+        return [];
+    return Object.entries(attrs).map(([k, v]) => ({ key: k, value: toAnyValue(v) }));
+}
+// Iris Span → OTLP Span JSON shape.
+export function mapSpan(span, traceIdOverride) {
+    const attributes = flattenAttrs(span.attributes);
+    // Surface Iris-specific kinds via attributes so OTel consumers can
+    // filter on iris.span_kind even though we mapped everything non-OTel to INTERNAL.
+    if (span.kind === 'LLM' || span.kind === 'TOOL') {
+        attributes.push({ key: 'iris.span_kind', value: { stringValue: span.kind } });
+    }
+    const events = (span.events ?? []).map((e) => ({
+        timeUnixNano: toNanoString(e.timestamp),
+        name: e.name,
+        attributes: flattenAttrs(e.attributes),
+    }));
+    return {
+        traceId: toTraceIdHex(traceIdOverride ?? span.trace_id),
+        spanId: toSpanIdHex(span.span_id),
+        parentSpanId: span.parent_span_id ? toSpanIdHex(span.parent_span_id) : undefined,
+        name: span.name,
+        kind: KIND_MAP[span.kind] ?? 1,
+        startTimeUnixNano: toNanoString(span.start_time),
+        endTimeUnixNano: toNanoString(span.end_time ?? span.start_time),
+        attributes,
+        events,
+        status: {
+            code: STATUS_MAP[span.status_code] ?? 0,
+            message: span.status_message,
+        },
+    };
+}
+// Build a full OTLP ExportTraceServiceRequest payload from an Iris trace.
+// If the trace has no explicit spans, we synthesize one root span from
+// the trace-level fields (agent_name + latency + cost + token_usage as
+// attributes) so exports aren't empty for simple trace rows.
+export function buildExportPayload(traces, serviceName) {
+    const resource = {
+        attributes: [
+            { key: 'service.name', value: { stringValue: serviceName } },
+            { key: 'telemetry.sdk.name', value: { stringValue: 'iris-mcp' } },
+            { key: 'telemetry.sdk.language', value: { stringValue: 'nodejs' } },
+            { key: 'telemetry.sdk.version', value: { stringValue: '0.4.0' } },
+        ],
+    };
+    const spans = [];
+    for (const trace of traces) {
+        if (trace.spans && trace.spans.length > 0) {
+            for (const s of trace.spans)
+                spans.push(mapSpan(s, trace.trace_id));
+        }
+        else {
+            // Synthesize root span from trace-level info.
+            const attrs = {
+                'iris.agent_name': trace.agent_name,
+                'iris.framework': trace.framework,
+            };
+            if (trace.input)
+                attrs['iris.input'] = truncate(trace.input);
+            if (trace.output)
+                attrs['iris.output'] = truncate(trace.output);
+            if (trace.cost_usd !== undefined)
+                attrs['iris.cost_usd'] = trace.cost_usd;
+            if (trace.token_usage?.total_tokens !== undefined)
+                attrs['iris.total_tokens'] = trace.token_usage.total_tokens;
+            if (trace.token_usage?.prompt_tokens !== undefined)
+                attrs['iris.prompt_tokens'] = trace.token_usage.prompt_tokens;
+            if (trace.token_usage?.completion_tokens !== undefined)
+                attrs['iris.completion_tokens'] = trace.token_usage.completion_tokens;
+            const end = trace.latency_ms
+                ? new Date(new Date(trace.timestamp).getTime() + trace.latency_ms).toISOString()
+                : trace.timestamp;
+            spans.push({
+                traceId: toTraceIdHex(trace.trace_id),
+                spanId: toSpanIdHex(trace.trace_id + ':root'),
+                parentSpanId: undefined,
+                name: trace.agent_name || 'agent_execution',
+                kind: 1,
+                startTimeUnixNano: toNanoString(trace.timestamp),
+                endTimeUnixNano: toNanoString(end),
+                attributes: flattenAttrs(attrs),
+                events: [],
+                status: { code: 0 },
+            });
+        }
+    }
+    return {
+        resourceSpans: [
+            {
+                resource,
+                scopeSpans: [
+                    {
+                        scope: { name: 'iris.trace.v1' },
+                        spans,
+                    },
+                ],
+            },
+        ],
+    };
+}
+function truncate(s, max = 4096) {
+    return s.length > max ? s.slice(0, max) + '…' : s;
+}

package/dist/preferences.d.ts

@@ -0,0 +1,129 @@
+import { z } from 'zod';
+declare const MomentFiltersSchema: z.ZodObject<{
+    agentName: z.ZodOptional<z.ZodString>;
+    verdict: z.ZodOptional<z.ZodEnum<["pass", "fail", "partial", "unevaluated"]>>;
+    significanceKind: z.ZodOptional<z.ZodEnum<["safety-violation", "cost-spike", "first-failure", "novel-pattern", "rule-collision", "normal-pass", "normal-fail"]>>;
+}, "strict", z.ZodTypeAny, {
+    verdict?: "pass" | "fail" | "partial" | "unevaluated" | undefined;
+    agentName?: string | undefined;
+    significanceKind?: "safety-violation" | "cost-spike" | "first-failure" | "novel-pattern" | "rule-collision" | "normal-pass" | "normal-fail" | undefined;
+}, {
+    verdict?: "pass" | "fail" | "partial" | "unevaluated" | undefined;
+    agentName?: string | undefined;
+    significanceKind?: "safety-violation" | "cost-spike" | "first-failure" | "novel-pattern" | "rule-collision" | "normal-pass" | "normal-fail" | undefined;
+}>;
+export declare const PreferencesSchema: z.ZodObject<{
+    autoLaunch: z.ZodDefault<z.ZodBoolean>;
+    firstSeen: z.ZodOptional<z.ZodString>;
+    dismissedBanners: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Theme override; "system" defers to prefers-color-scheme. v0.4. */
+    theme: z.ZodDefault<z.ZodEnum<["dark", "light", "system"]>>;
+    /** Last filter set used on /moments — applied on next visit when the URL has no filter params. v0.4. */
+    momentFilters: z.ZodDefault<z.ZodObject<{
+        agentName: z.ZodOptional<z.ZodString>;
+        verdict: z.ZodOptional<z.ZodEnum<["pass", "fail", "partial", "unevaluated"]>>;
+        significanceKind: z.ZodOptional<z.ZodEnum<["safety-violation", "cost-spike", "first-failure", "novel-pattern", "rule-collision", "normal-pass", "normal-fail"]>>;
+    }, "strict", z.ZodTypeAny, {
+        verdict?: "pass" | "fail" | "partial" | "unevaluated" | undefined;
+        agentName?: string | undefined;
+        significanceKind?: "safety-violation" | "cost-spike" | "first-failure" | "novel-pattern" | "rule-collision" | "normal-pass" | "normal-fail" | undefined;
+    }, {
+        verdict?: "pass" | "fail" | "partial" | "unevaluated" | undefined;
+        agentName?: string | undefined;
+        significanceKind?: "safety-violation" | "cost-spike" | "first-failure" | "novel-pattern" | "rule-collision" | "normal-pass" | "normal-fail" | undefined;
+    }>>;
+    /** Tour ids the user has completed or dismissed. v0.4. */
+    dismissedTours: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Decision Moments hidden from the timeline by user action. v0.4. */
+    archivedMoments: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Density mode for chrome (Design System v2.A). 'compact' default per R2.3. */
+    density: z.ZodDefault<z.ZodEnum<["compact", "comfortable"]>>;
+    /** Sidebar collapsed (icon-only at 64px) vs expanded (256px). Default expanded per R2.4. */
+    sidebarCollapsed: z.ZodDefault<z.ZodBoolean>;
+    /** ISO timestamp of last notifications-popover opened — drives unread badge. */
+    notificationsLastSeen: z.ZodOptional<z.ZodString>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    autoLaunch: z.ZodDefault<z.ZodBoolean>;
+    firstSeen: z.ZodOptional<z.ZodString>;
+    dismissedBanners: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Theme override; "system" defers to prefers-color-scheme. v0.4. */
+    theme: z.ZodDefault<z.ZodEnum<["dark", "light", "system"]>>;
+    /** Last filter set used on /moments — applied on next visit when the URL has no filter params. v0.4. */
+    momentFilters: z.ZodDefault<z.ZodObject<{
+        agentName: z.ZodOptional<z.ZodString>;
+        verdict: z.ZodOptional<z.ZodEnum<["pass", "fail", "partial", "unevaluated"]>>;
+        significanceKind: z.ZodOptional<z.ZodEnum<["safety-violation", "cost-spike", "first-failure", "novel-pattern", "rule-collision", "normal-pass", "normal-fail"]>>;
+    }, "strict", z.ZodTypeAny, {
+        verdict?: "pass" | "fail" | "partial" | "unevaluated" | undefined;
+        agentName?: string | undefined;
+        significanceKind?: "safety-violation" | "cost-spike" | "first-failure" | "novel-pattern" | "rule-collision" | "normal-pass" | "normal-fail" | undefined;
+    }, {
+        verdict?: "pass" | "fail" | "partial" | "unevaluated" | undefined;
+        agentName?: string | undefined;
+        significanceKind?: "safety-violation" | "cost-spike" | "first-failure" | "novel-pattern" | "rule-collision" | "normal-pass" | "normal-fail" | undefined;
+    }>>;
+    /** Tour ids the user has completed or dismissed. v0.4. */
+    dismissedTours: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Decision Moments hidden from the timeline by user action. v0.4. */
+    archivedMoments: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Density mode for chrome (Design System v2.A). 'compact' default per R2.3. */
+    density: z.ZodDefault<z.ZodEnum<["compact", "comfortable"]>>;
+    /** Sidebar collapsed (icon-only at 64px) vs expanded (256px). Default expanded per R2.4. */
+    sidebarCollapsed: z.ZodDefault<z.ZodBoolean>;
+    /** ISO timestamp of last notifications-popover opened — drives unread badge. */
+    notificationsLastSeen: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    autoLaunch: z.ZodDefault<z.ZodBoolean>;
+    firstSeen: z.ZodOptional<z.ZodString>;
+    dismissedBanners: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Theme override; "system" defers to prefers-color-scheme. v0.4. */
+    theme: z.ZodDefault<z.ZodEnum<["dark", "light", "system"]>>;
+    /** Last filter set used on /moments — applied on next visit when the URL has no filter params. v0.4. */
+    momentFilters: z.ZodDefault<z.ZodObject<{
+        agentName: z.ZodOptional<z.ZodString>;
+        verdict: z.ZodOptional<z.ZodEnum<["pass", "fail", "partial", "unevaluated"]>>;
+        significanceKind: z.ZodOptional<z.ZodEnum<["safety-violation", "cost-spike", "first-failure", "novel-pattern", "rule-collision", "normal-pass", "normal-fail"]>>;
+    }, "strict", z.ZodTypeAny, {
+        verdict?: "pass" | "fail" | "partial" | "unevaluated" | undefined;
+        agentName?: string | undefined;
+        significanceKind?: "safety-violation" | "cost-spike" | "first-failure" | "novel-pattern" | "rule-collision" | "normal-pass" | "normal-fail" | undefined;
+    }, {
+        verdict?: "pass" | "fail" | "partial" | "unevaluated" | undefined;
+        agentName?: string | undefined;
+        significanceKind?: "safety-violation" | "cost-spike" | "first-failure" | "novel-pattern" | "rule-collision" | "normal-pass" | "normal-fail" | undefined;
+    }>>;
+    /** Tour ids the user has completed or dismissed. v0.4. */
+    dismissedTours: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Decision Moments hidden from the timeline by user action. v0.4. */
+    archivedMoments: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Density mode for chrome (Design System v2.A). 'compact' default per R2.3. */
+    density: z.ZodDefault<z.ZodEnum<["compact", "comfortable"]>>;
+    /** Sidebar collapsed (icon-only at 64px) vs expanded (256px). Default expanded per R2.4. */
+    sidebarCollapsed: z.ZodDefault<z.ZodBoolean>;
+    /** ISO timestamp of last notifications-popover opened — drives unread badge. */
+    notificationsLastSeen: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>;
+export type Preferences = z.infer<typeof PreferencesSchema>;
+export type MomentFilters = z.infer<typeof MomentFiltersSchema>;
+export interface PreferenceState {
+    /** True if `~/.iris/preferences.json` did not exist when iris-mcp started. */
+    isFirstRun: boolean;
+    /** Resolved preferences (defaulted + validated). */
+    preferences: Preferences;
+    /** Absolute path to the preferences file. */
+    path: string;
+}
+export declare function loadOrInitPreferences(customPath?: string): PreferenceState;
+export declare function shouldAutoLaunchDashboard(state: PreferenceState): boolean;
+export interface PreferenceStore {
+    readonly path: string;
+    /** Current preferences (always defaulted + validated). */
+    read(): Preferences;
+    /**
+     * Apply a partial update + persist atomically. Returns the merged result.
+     * Throws if the merge fails Zod validation (e.g., illegal verdict value).
+     */
+    patch(input: Partial<Preferences>): Preferences;
+}
+export declare function createPreferenceStore(customPath?: string): PreferenceStore;
+export {};

package/dist/preferences.js

@@ -0,0 +1,152 @@
+/*
+ * preferences — first-run + per-user dashboard preferences for iris-mcp.
+ *
+ * State lives at ~/.iris/preferences.json. The file is created on first
+ * dashboard launch with `autoLaunch: true` and `firstSeen` set to the
+ * current ISO timestamp.
+ *
+ * Subsequent runs read the file and respect the user's autoLaunch setting.
+ * The env var IRIS_NO_AUTO_LAUNCH=1 overrides preferences and disables
+ * auto-launch unconditionally (useful for CI, headless servers, container
+ * runs, and remote SSH sessions).
+ *
+ * The file format is intentionally small — additional preferences will be
+ * added as the dashboard grows; the schema validates known keys but
+ * tolerates unknown ones forward-compatibly.
+ *
+ * v0.4 expansions (B8.2): theme, momentFilters (last filter set used on
+ * /moments), dismissedTours, archivedMoments. These let the dashboard
+ * remember the user's last view across reloads + across iris-mcp restarts.
+ */
+import { mkdirSync, readFileSync, writeFileSync, existsSync, renameSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { z } from 'zod';
+const MomentFiltersSchema = z
+    .object({
+    agentName: z.string().max(200).optional(),
+    verdict: z.enum(['pass', 'fail', 'partial', 'unevaluated']).optional(),
+    significanceKind: z
+        .enum([
+        'safety-violation',
+        'cost-spike',
+        'first-failure',
+        'novel-pattern',
+        'rule-collision',
+        'normal-pass',
+        'normal-fail',
+    ])
+        .optional(),
+})
+    .strict();
+export const PreferencesSchema = z
+    .object({
+    autoLaunch: z.boolean().default(true),
+    firstSeen: z.string().datetime({ offset: true }).optional(),
+    dismissedBanners: z.array(z.string().max(80)).default([]),
+    /** Theme override; "system" defers to prefers-color-scheme. v0.4. */
+    theme: z.enum(['dark', 'light', 'system']).default('system'),
+    /** Last filter set used on /moments — applied on next visit when the URL has no filter params. v0.4. */
+    momentFilters: MomentFiltersSchema.default({}),
+    /** Tour ids the user has completed or dismissed. v0.4. */
+    dismissedTours: z.array(z.string().max(80)).default([]),
+    /** Decision Moments hidden from the timeline by user action. v0.4. */
+    archivedMoments: z.array(z.string().max(200)).default([]),
+    /** Density mode for chrome (Design System v2.A). 'compact' default per R2.3. */
+    density: z.enum(['compact', 'comfortable']).default('compact'),
+    /** Sidebar collapsed (icon-only at 64px) vs expanded (256px). Default expanded per R2.4. */
+    sidebarCollapsed: z.boolean().default(false),
+    /** ISO timestamp of last notifications-popover opened — drives unread badge. */
+    notificationsLastSeen: z.string().datetime({ offset: true }).optional(),
+})
+    .passthrough();
+function defaultPreferencesPath() {
+    return join(homedir(), '.iris', 'preferences.json');
+}
+function freshPreferences() {
+    return PreferencesSchema.parse({
+        autoLaunch: true,
+        firstSeen: new Date().toISOString(),
+        dismissedBanners: [],
+        theme: 'system',
+        momentFilters: {},
+        dismissedTours: [],
+        archivedMoments: [],
+    });
+}
+function writeAtomic(targetPath, contents) {
+    mkdirSync(dirname(targetPath), { recursive: true });
+    const tmp = `${targetPath}.tmp.${process.pid}`;
+    writeFileSync(tmp, contents, 'utf-8');
+    renameSync(tmp, targetPath);
+}
+export function loadOrInitPreferences(customPath) {
+    const path = customPath ?? defaultPreferencesPath();
+    if (!existsSync(path)) {
+        const fresh = freshPreferences();
+        try {
+            writeAtomic(path, JSON.stringify(fresh, null, 2));
+        }
+        catch {
+            // Filesystem may be read-only (containerized run); we still proceed
+            // with the defaults in memory but isFirstRun stays true so callers
+            // can decide whether to auto-launch anyway.
+        }
+        return { isFirstRun: true, preferences: fresh, path };
+    }
+    try {
+        const raw = readFileSync(path, 'utf-8');
+        const parsed = PreferencesSchema.safeParse(JSON.parse(raw));
+        if (parsed.success) {
+            return { isFirstRun: false, preferences: parsed.data, path };
+        }
+        // Malformed file — fall back to defaults but DON'T overwrite the
+        // existing file. The user may want to fix it manually.
+        return {
+            isFirstRun: false,
+            preferences: PreferencesSchema.parse({}),
+            path,
+        };
+    }
+    catch {
+        return {
+            isFirstRun: false,
+            preferences: PreferencesSchema.parse({}),
+            path,
+        };
+    }
+}
+export function shouldAutoLaunchDashboard(state) {
+    if (process.env.IRIS_NO_AUTO_LAUNCH === '1')
+        return false;
+    if (process.env.CI === 'true' || process.env.CI === '1')
+        return false;
+    return state.preferences.autoLaunch !== false;
+}
+export function createPreferenceStore(customPath) {
+    const path = customPath ?? defaultPreferencesPath();
+    let current = loadOrInitPreferences(path).preferences;
+    return {
+        path,
+        read() {
+            return current;
+        },
+        patch(input) {
+            const merged = { ...current, ...input };
+            // Re-parse so default coalescing + validation runs, and so passthrough
+            // forward-compat preserves any unknown keys present in the file.
+            const validated = PreferencesSchema.parse(merged);
+            try {
+                writeAtomic(path, JSON.stringify(validated, null, 2));
+            }
+            catch (err) {
+                // If persist fails (read-only fs, disk full), still update memory
+                // so the UI feels responsive — but rethrow so the API surfaces it.
+                current = validated;
+                throw err;
+            }
+            current = validated;
+            return validated;
+        },
+    };
+}