@unerr-ai/unerr 0.2.0 → 0.2.2

package/dist/proxy/lifecycle-machine.js

@@ -1,187 +0,0 @@
-/**
- * Proxy Lifecycle State Machine — XState v5 formalization of the boot sequence.
- *
- * States: idle → detecting → setup|indexing → ready → running → shutdown
- *                                                         ↘ error → shutdown
- *
- * This machine is the source of truth for proxy lifecycle. Every state transition
- * emits events that higher layers (Layer 1 temporal intelligence, Layer 2 UI) can
- * subscribe to without modifying the core boot flow.
- *
- * Design: pure machine definition (no side effects). Side effects are injected
- * via the `actions` map when creating the actor in lifecycle-actor.ts.
- */
-import { assign, setup } from "xstate";
-export const proxyMachine = setup({
-    types: {
-        context: {},
-        events: {},
-        input: {},
-    },
-    actions: {
-        recordError: assign({
-            error: (_, params) => params.message,
-        }),
-        markGraphLoaded: assign({ graphLoaded: true }),
-        markMcpReady: assign({ mcpReady: true }),
-        setRepoId: assign({
-            repoId: (_, params) => params.repoId,
-        }),
-        recordStateEntry: assign({ stateEnteredAt: () => Date.now() }),
-    },
-    guards: {
-        needsSetup: (_, params) => params.needsSetup,
-        isReady: ({ context }) => context.graphLoaded,
-    },
-}).createMachine({
-    id: "proxy",
-    initial: "idle",
-    context: ({ input }) => ({
-        repoPath: input.repoPath,
-        repoId: undefined,
-        graphLoaded: false,
-        mcpReady: false,
-        error: undefined,
-        bootStartedAt: Date.now(),
-        stateEnteredAt: Date.now(),
-    }),
-    states: {
-        idle: {
-            on: {
-                START_DETECT: {
-                    target: "detecting",
-                    actions: [{ type: "recordStateEntry" }],
-                },
-            },
-        },
-        detecting: {
-            on: {
-                DETECT_COMPLETE: [
-                    {
-                        guard: {
-                            type: "needsSetup",
-                            params: ({ event }) => ({ needsSetup: event.needsSetup }),
-                        },
-                        target: "setup",
-                        actions: [{ type: "recordStateEntry" }],
-                    },
-                    {
-                        target: "indexing",
-                        actions: [
-                            { type: "recordStateEntry" },
-                            {
-                                type: "setRepoId",
-                                params: ({ event }) => ({ repoId: event.repoId ?? "" }),
-                            },
-                        ],
-                    },
-                ],
-                ERROR: {
-                    target: "error",
-                    actions: [
-                        {
-                            type: "recordError",
-                            params: ({ event }) => ({ message: event.message }),
-                        },
-                        { type: "recordStateEntry" },
-                    ],
-                },
-            },
-        },
-        setup: {
-            on: {
-                SETUP_COMPLETE: {
-                    target: "indexing",
-                    actions: [
-                        {
-                            type: "setRepoId",
-                            params: ({ event }) => ({ repoId: event.repoId }),
-                        },
-                        { type: "recordStateEntry" },
-                    ],
-                },
-                ERROR: {
-                    target: "error",
-                    actions: [
-                        {
-                            type: "recordError",
-                            params: ({ event }) => ({ message: event.message }),
-                        },
-                        { type: "recordStateEntry" },
-                    ],
-                },
-                SHUTDOWN: { target: "shutdown" },
-            },
-        },
-        indexing: {
-            on: {
-                GRAPH_LOADED: {
-                    actions: [{ type: "markGraphLoaded" }],
-                },
-                INDEX_COMPLETE: {
-                    target: "ready",
-                    actions: [{ type: "recordStateEntry" }],
-                },
-                ERROR: {
-                    target: "error",
-                    actions: [
-                        {
-                            type: "recordError",
-                            params: ({ event }) => ({ message: event.message }),
-                        },
-                        { type: "recordStateEntry" },
-                    ],
-                },
-                SHUTDOWN: { target: "shutdown" },
-            },
-        },
-        ready: {
-            on: {
-                MCP_READY: {
-                    target: "running",
-                    actions: [{ type: "markMcpReady" }, { type: "recordStateEntry" }],
-                },
-                ERROR: {
-                    target: "error",
-                    actions: [
-                        {
-                            type: "recordError",
-                            params: ({ event }) => ({ message: event.message }),
-                        },
-                        { type: "recordStateEntry" },
-                    ],
-                },
-                SHUTDOWN: { target: "shutdown" },
-            },
-        },
-        running: {
-            on: {
-                ERROR: {
-                    target: "error",
-                    actions: [
-                        {
-                            type: "recordError",
-                            params: ({ event }) => ({ message: event.message }),
-                        },
-                        { type: "recordStateEntry" },
-                    ],
-                },
-                SHUTDOWN: {
-                    target: "shutdown",
-                    actions: [{ type: "recordStateEntry" }],
-                },
-            },
-        },
-        error: {
-            on: {
-                SHUTDOWN: {
-                    target: "shutdown",
-                    actions: [{ type: "recordStateEntry" }],
-                },
-            },
-        },
-        shutdown: {
-            type: "final",
-        },
-    },
-});

package/dist/proxy/log-tailer.js

@@ -1,265 +0,0 @@
-/**
- * Log Tailer — relays new metric/log events from child processes to the
- * proxy console via startupLog.
- *
- * Three streams (compression, token_flow, file_read) live in `.unerr/metrics.db`
- * and are polled by `id > lastSeen` every `pollIntervalMs` (default 500ms).
- * One stream (`logs/unerr.jsonl`) stays JSONL and is tailed via `fs.watch`.
- *
- * Why this shape: SQLite gives ordered-by-id polling for free, so we no
- * longer have to track byte offsets or worry about partial writes. The
- * remaining JSONL file is structured log output that doesn't need indexed
- * aggregation, so leaving it as a flat file keeps `tail -f .../unerr.jsonl`
- * useful for debugging.
- */
-import { closeSync, existsSync, openSync, readSync, statSync, watch, } from "node:fs";
-import { join } from "node:path";
-import { openMetricsStore, } from "../tracking/metrics-store.js";
-import { startupLog } from "../utils/startup-log.js";
-function formatSize(bytes) {
-    if (bytes >= 1024 * 1024)
-        return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
-    if (bytes >= 1024)
-        return `${(bytes / 1024).toFixed(1)}KB`;
-    return `${bytes}B`;
-}
-/** Read new lines from a file starting at the given byte offset. */
-function readNewLines(filePath, fromOffset) {
-    try {
-        const stat = statSync(filePath);
-        if (stat.size <= fromOffset)
-            return { lines: [], newOffset: fromOffset };
-        const bytesToRead = stat.size - fromOffset;
-        const buf = Buffer.alloc(bytesToRead);
-        const fd = openSync(filePath, "r");
-        try {
-            readSync(fd, buf, 0, bytesToRead, fromOffset);
-        }
-        finally {
-            closeSync(fd);
-        }
-        const text = buf.toString("utf-8");
-        const rawLines = text.split("\n").filter((l) => l.trim());
-        return { lines: rawLines, newOffset: stat.size };
-    }
-    catch {
-        return { lines: [], newOffset: fromOffset };
-    }
-}
-/** Format and print a compression log entry. */
-function printCompressionEntry(entry) {
-    const cmd = String(entry.command ?? "");
-    const cmdSlug = cmd.length > 40 ? `${cmd.slice(0, 37)}...` : cmd;
-    const category = String(entry.category ?? "unknown");
-    const savedPct = Number(entry.savedPct ?? 0);
-    const rawBytes = Number(entry.rawBytes ?? 0);
-    const compressedBytes = Number(entry.compressedBytes ?? 0);
-    const omniFallback = Boolean(entry.omniFallback);
-    const strategy = omniFallback ? `omni(${category})` : category;
-    if (savedPct === 0)
-        return; // skip no-op compressions on console
-    startupLog.step(`${startupLog.fmt.muted("[exec]")} ${startupLog.fmt.dim(`"${cmdSlug}"`)} ${startupLog.fmt.muted("→")} ${startupLog.fmt.cyan(strategy)} ${startupLog.fmt.muted(`(${formatSize(rawBytes)} → ${formatSize(compressedBytes)}, ${savedPct}% saved)`)}`);
-}
-/** Format and print a token-flow.jsonl entry from child processes. */
-function printTokenFlowEntry(entry) {
-    const pid = Number(entry.pid ?? 0);
-    if (pid === process.pid)
-        return;
-    const tokensSaved = Number(entry.tokens_saved ?? 0);
-    if (tokensSaved <= 0)
-        return;
-    startupLog.tokenFlow({
-        turn: Number(entry.turn ?? 0),
-        tool: entry.tool != null ? String(entry.tool) : null,
-        mechanism: String(entry.mechanism ?? "unknown"),
-        tokensSaved,
-        tokensDelivered: Number(entry.tokens_with ?? 0),
-        sessionTotal: 0,
-        pid,
-    });
-}
-/** Format and print a file-reads.jsonl entry from child processes. */
-function printFileReadEntry(entry) {
-    const savedPct = Number(entry.savedPct ?? 0);
-    if (savedPct === 0)
-        return; // skip full reads with no savings
-    const file = String(entry.file ?? "");
-    const fileSlug = file.length > 40 ? `...${file.slice(-37)}` : file;
-    const mode = String(entry.mode ?? "full");
-    const totalLines = Number(entry.totalLines ?? 0);
-    const returnedLines = Number(entry.returnedLines ?? 0);
-    startupLog.step(`${startupLog.fmt.muted("[mcp]")} ${startupLog.fmt.dim(fileSlug)} ${startupLog.fmt.muted("→")} ${startupLog.fmt.cyan(mode)} ${startupLog.fmt.muted(`(${totalLines} → ${returnedLines} lines, ${savedPct}% saved)`)}`);
-}
-/** Format and print a general unerr.jsonl entry from child processes. */
-function printGeneralEntry(entry) {
-    const pid = Number(entry.pid ?? 0);
-    // Only relay entries from OTHER processes (not our own PID)
-    if (pid === process.pid)
-        return;
-    const level = String(entry.level ?? "");
-    const msg = String(entry.msg ?? "");
-    // Skip noisy low-value entries
-    if (!msg || level === "step" || level === "ready")
-        return;
-    const prefix = startupLog.fmt.muted(`[pid:${pid}]`);
-    switch (level) {
-        case "error":
-            startupLog.error(`${prefix} ${msg}`);
-            break;
-        case "warn":
-            startupLog.warn(`${prefix} ${msg}`);
-            break;
-        case "done":
-            startupLog.done(`${prefix} ${msg}`, typeof entry.ms === "number" ? entry.ms : undefined);
-            break;
-        case "metric":
-            startupLog.step(`${prefix} ${startupLog.fmt.cyan(msg)}: ${startupLog.fmt.bold(String(entry.value))} ${startupLog.fmt.muted(String(entry.unit ?? ""))}`);
-            break;
-        default:
-            startupLog.step(`${prefix} ${msg}`);
-    }
-}
-function tailFile(state, handler) {
-    const { lines, newOffset } = readNewLines(state.path, state.offset);
-    state.offset = newOffset;
-    for (const line of lines) {
-        try {
-            const entry = JSON.parse(line);
-            handler(entry);
-        }
-        catch {
-            // malformed line — skip
-        }
-    }
-}
-// ── Row → wire-shape adapters ────────────────────────────────────────
-// The console printers expect the old JSONL field names (camelCase).
-// These keep the printers untouched while the storage backend swaps.
-function compressionRowToEntry(r) {
-    return {
-        ts: r.ts_iso,
-        command: r.command,
-        category: r.category,
-        confidence: r.confidence,
-        rawBytes: r.raw_bytes,
-        compressedBytes: r.compressed_bytes,
-        savedPct: r.saved_pct,
-        omniFallback: r.omni_fallback === 1,
-        teeFile: r.tee_file,
-    };
-}
-function fileReadRowToEntry(r) {
-    return {
-        ts: r.ts_iso,
-        file: r.file,
-        mode: r.mode,
-        totalLines: r.total_lines,
-        returnedLines: r.returned_lines,
-        savedPct: r.saved_pct,
-        entity: r.entity,
-        tokenEstimate: r.token_estimate,
-    };
-}
-function tokenFlowRowToEntry(r) {
-    return {
-        id: r.id,
-        ts: r.ts_iso,
-        session_id: r.session_id,
-        pid: r.pid,
-        turn: r.turn,
-        mechanism: r.mechanism,
-        tool: r.tool,
-        tokens_without: r.tokens_without,
-        tokens_with: r.tokens_with,
-        tokens_saved: r.tokens_saved,
-        detail: r.detail ? JSON.parse(r.detail) : undefined,
-    };
-}
-/**
- * Start tailing the proxy's child-process activity.
- *
- *   - compression / token_flow / file_read: polled from `.unerr/metrics.db`
- *     via `id > lastSeen` (no offsets, no partial-read races).
- *   - unerr.jsonl: still `fs.watch`-tailed — it's a flat structured log,
- *     not a metric stream.
- */
-export function startLogTailer(cwd, options) {
-    const unerrDir = join(cwd, ".unerr");
-    const logsDir = join(unerrDir, "logs");
-    const generalPath = join(logsDir, "unerr.jsonl");
-    const pollIntervalMs = options?.pollIntervalMs ?? 500;
-    // ── JSONL path: unerr.jsonl via fs.watch + offset ────────────────
-    const generalState = {
-        path: generalPath,
-        offset: existsSync(generalPath) ? statSync(generalPath).size : 0,
-        watcher: null,
-    };
-    function setupWatcher(state, handler) {
-        try {
-            state.watcher = watch(state.path, () => {
-                tailFile(state, handler);
-            });
-            state.watcher.unref();
-        }
-        catch {
-            /* file may not exist yet — handled by the JSONL poll fallback below */
-        }
-    }
-    setupWatcher(generalState, printGeneralEntry);
-    // ── SQLite path: compression / token_flow / file_read ────────────
-    // Initialize lastSeen to the current max id so we only relay *new* events.
-    const store = openMetricsStore(unerrDir);
-    const initial = store.lastIds();
-    let lastCompressionId = initial.compression;
-    let lastFileReadId = initial.fileRead;
-    let lastTokenFlowId = initial.tokenFlow;
-    const sqlPoll = setInterval(() => {
-        try {
-            const cRows = store.compressionSince(lastCompressionId);
-            for (const r of cRows) {
-                printCompressionEntry(compressionRowToEntry(r));
-                lastCompressionId = r.id;
-            }
-            const fRows = store.fileReadsSince(lastFileReadId);
-            for (const r of fRows) {
-                printFileReadEntry(fileReadRowToEntry(r));
-                lastFileReadId = r.id;
-            }
-            const tRows = store.tokenFlowSince(lastTokenFlowId);
-            for (const r of tRows) {
-                const entry = tokenFlowRowToEntry(r);
-                printTokenFlowEntry(entry);
-                options?.onTokenFlowEvent?.(entry);
-                lastTokenFlowId = r.id;
-            }
-        }
-        catch {
-            /* poll round failed — try again next tick */
-        }
-    }, pollIntervalMs);
-    sqlPoll.unref();
-    // ── JSONL poll fallback (unerr.jsonl appears after startup) ──────
-    const jsonlPoll = setInterval(() => {
-        if (!generalState.watcher && existsSync(generalState.path)) {
-            try {
-                generalState.offset = 0;
-                generalState.watcher = watch(generalState.path, () => {
-                    tailFile(generalState, printGeneralEntry);
-                });
-                generalState.watcher.unref();
-            }
-            catch {
-                /* retry next poll */
-            }
-        }
-        tailFile(generalState, printGeneralEntry);
-    }, 3000);
-    jsonlPoll.unref();
-    return {
-        close() {
-            clearInterval(sqlPoll);
-            clearInterval(jsonlPoll);
-            generalState.watcher?.close();
-        },
-    };
-}

package/dist/proxy/model-pricing.js

@@ -1,98 +0,0 @@
-/**
- * Model Pricing Table + Dollar Savings Calculator.
- *
- * T.2: Per-model input/output token pricing (USD per million tokens).
- * T.3: Dollar savings = tokens_saved × input_rate (we save on agent input).
- *
- * All pricing is input-side (tokens we prevent the agent from consuming).
- */
-const MODEL_RATES = [
-    {
-        id: "claude-sonnet-4-20250514",
-        name: "Claude Sonnet 4",
-        inputPerMillion: 3,
-        outputPerMillion: 15,
-    },
-    {
-        id: "claude-opus-4-20250514",
-        name: "Claude Opus 4",
-        inputPerMillion: 15,
-        outputPerMillion: 75,
-    },
-    {
-        id: "claude-haiku-4-20250506",
-        name: "Claude Haiku 4",
-        inputPerMillion: 0.8,
-        outputPerMillion: 4,
-    },
-    { id: "gpt-4o", name: "GPT-4o", inputPerMillion: 2.5, outputPerMillion: 10 },
-    {
-        id: "gpt-4o-mini",
-        name: "GPT-4o Mini",
-        inputPerMillion: 0.15,
-        outputPerMillion: 0.6,
-    },
-    {
-        id: "gemini-2.0-flash",
-        name: "Gemini 2.0 Flash",
-        inputPerMillion: 0.1,
-        outputPerMillion: 0.4,
-    },
-    {
-        id: "gemini-1.5-pro",
-        name: "Gemini 1.5 Pro",
-        inputPerMillion: 1.25,
-        outputPerMillion: 5,
-    },
-    {
-        id: "ollama",
-        name: "Ollama (local)",
-        inputPerMillion: 0,
-        outputPerMillion: 0,
-    },
-];
-const DEFAULT_MODEL = "claude-sonnet-4-20250514";
-/**
- * Get the pricing rate for a model. Returns default (Sonnet) for unknown models.
- */
-export function getModelRate(modelId) {
-    const id = modelId ?? DEFAULT_MODEL;
-    return MODEL_RATES.find((m) => m.id === id) ?? MODEL_RATES[0];
-}
-/**
- * Calculate dollar savings from tokens saved.
- * Savings are on input tokens (what the agent would have consumed).
- */
-export function calculateDollarSavings(tokensSaved, modelId) {
-    const rate = getModelRate(modelId);
-    return (tokensSaved * rate.inputPerMillion) / 1_000_000;
-}
-/**
- * Format dollar amount for display.
- */
-export function formatDollars(amount) {
-    if (amount >= 1)
-        return `$${amount.toFixed(2)}`;
-    if (amount >= 0.01)
-        return `$${amount.toFixed(2)}`;
-    if (amount >= 0.001)
-        return `$${amount.toFixed(3)}`;
-    return `$${amount.toFixed(4)}`;
-}
-/**
- * Format a complete savings summary string.
- */
-export function formatSavingsSummary(tokensSaved, modelId) {
-    const dollars = calculateDollarSavings(tokensSaved, modelId);
-    const rate = getModelRate(modelId);
-    const tokensStr = tokensSaved >= 1000
-        ? `${(tokensSaved / 1000).toFixed(1)}K`
-        : String(tokensSaved);
-    return `${tokensStr} tokens saved (${formatDollars(dollars)} at ${rate.name} rates)`;
-}
-/**
- * Get all supported models.
- */
-export function getAllModelRates() {
-    return [...MODEL_RATES];
-}

package/dist/proxy/network-firewall.js

@@ -1,141 +0,0 @@
-/**
- * NetworkFirewall — Zero-leakage network boundary for True Local Mode.
- *
- * When sealed, intercepts globalThis.fetch and rejects any outbound
- * request that targets a non-localhost address. This is the belt-and-
- * suspenders safety net: even if a code path accidentally imports a
- * cloud service, the firewall catches it.
- *
- * Localhost addresses (Ollama, LM Studio, CozoDB) are always allowed.
- * The user's configured BYO-LLM baseUrl is also allowlisted.
- *
- * Allowlist is built BEFORE seal() via addAllowedHost(). Once seal()
- * is called the allowlist is frozen — no runtime additions permitted.
- *
- * If Level 2 (fetch interception) ever fires in production, it
- * indicates a bug in Level 1 (conditional service instantiation)
- * that must be fixed.
- */
-const LOCALHOST_HOSTNAMES = new Set([
-    "localhost",
-    "127.0.0.1",
-    "::1",
-    "0.0.0.0",
-]);
-/** Parsed URL hostname cache for allowlisted BYO-LLM endpoints. */
-const allowlistedHosts = new Set();
-let sealed = false;
-let blockedCallCount = 0;
-// Capture the original fetch before anything can monkey-patch it.
-const originalFetch = globalThis.fetch;
-/**
- * Extract hostname from a fetch input (string, URL, or Request).
- * Returns null if the input cannot be parsed.
- */
-function extractHostname(input) {
-    try {
-        if (typeof input === "string") {
-            return new URL(input).hostname;
-        }
-        if (input instanceof URL) {
-            return input.hostname;
-        }
-        // Request object
-        if (input && typeof input.url === "string") {
-            return new URL(input.url).hostname;
-        }
-    }
-    catch {
-        // Malformed URL — treat as blocked
-    }
-    return null;
-}
-function isLocalhost(hostname) {
-    return (LOCALHOST_HOSTNAMES.has(hostname) ||
-        allowlistedHosts.has(hostname) ||
-        hostname.endsWith(".local"));
-}
-/**
- * Add a hostname to the firewall allowlist.
- *
- * Must be called BEFORE seal(). Throws if called after seal() to
- * enforce immutability of the allowlist at runtime.
- */
-export function addAllowedHost(hostname) {
-    if (sealed) {
-        throw new Error(`[NetworkFirewall] Cannot add host "${hostname}" — firewall is already sealed. All allowlist entries must be added before seal().`);
-    }
-    allowlistedHosts.add(hostname);
-}
-/**
- * Add a URL's hostname to the firewall allowlist.
- * Convenience wrapper — extracts hostname from a URL string.
- * Must be called BEFORE seal().
- */
-export function addAllowedUrl(url) {
-    let hostname;
-    try {
-        hostname = new URL(url).hostname;
-    }
-    catch {
-        return; // Skip malformed URLs
-    }
-    addAllowedHost(hostname);
-}
-/**
- * Seal the network firewall. All non-localhost fetch() calls will be
- * rejected with a NetworkFirewallError.
- *
- * @param allowedBaseUrls - Additional URLs to allowlist (e.g., BYO-LLM baseUrl).
- *   Only the hostname is extracted; paths are ignored.
- *   These are added to any hosts previously registered via addAllowedHost().
- */
-export function seal(allowedBaseUrls) {
-    if (sealed)
-        return;
-    // Populate allowlist from user-configured endpoints
-    if (allowedBaseUrls) {
-        for (const url of allowedBaseUrls) {
-            try {
-                allowlistedHosts.add(new URL(url).hostname);
-            }
-            catch {
-                // Skip malformed URLs
-            }
-        }
-    }
-    sealed = true;
-    globalThis.fetch = ((input, init) => {
-        const hostname = extractHostname(input);
-        if (hostname && !isLocalhost(hostname)) {
-            blockedCallCount++;
-            process.stderr.write(`[unerr] FIREWALL: Blocked outbound call to ${hostname} (Local Mode active)\n`);
-            return Promise.reject(new Error(`[NetworkFirewall] Outbound network call to ${hostname} blocked — Local Mode active. This indicates a code path that should be gated on mode !== 'local'.`));
-        }
-        return originalFetch(input, init);
-    });
-}
-/**
- * Unseal the firewall, restoring the original fetch.
- * Used in tests and for mode transitions.
- */
-export function unseal() {
-    sealed = false;
-    globalThis.fetch = originalFetch;
-    allowlistedHosts.clear();
-}
-/** Returns true if the firewall is currently sealed. */
-export function isSealed() {
-    return sealed;
-}
-/**
- * Number of outbound calls blocked since the firewall was sealed.
- * If this is >0 in production, a Level 1 gate is missing.
- */
-export function getBlockedCount() {
-    return blockedCallCount;
-}
-/** Reset the blocked call counter (for testing). */
-export function resetBlockedCount() {
-    blockedCallCount = 0;
-}