@unerr-ai/unerr 0.0.1 → 0.1.1

package/dist/proxy/nudge-state.js

@@ -0,0 +1,93 @@
+/**
+ * Per-session flag state for the Tier 0/1/2 nudge system (N1, N3, N5).
+ *
+ * State is a small JSON file at `.unerr/state/nudge-<session>.flags`. Session
+ * id comes from UNERR_SESSION_ID (set by the daemon/IDE). If unset, we fall
+ * back to a per-PID file — no cross-process state, but still beats v1.
+ *
+ * The store is best-effort and idempotent: if read or write fails, we treat
+ * it as "no state" — at worst the agent sees the Tier-0 reminder twice. We
+ * never throw; nudge emission must never crash the host command.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+function defaultState() {
+    return {
+        tier0_emitted: false,
+        tier1_emitted_kinds: [],
+        drift_count: 0,
+        tier2_emitted: false,
+    };
+}
+function statePath(cwd) {
+    const sessionId = process.env.UNERR_SESSION_ID ?? `pid-${process.pid}`;
+    return join(cwd, ".unerr", "state", `nudge-${sessionId}.flags`);
+}
+export function readNudgeState(cwd) {
+    try {
+        const path = statePath(cwd);
+        if (!existsSync(path))
+            return defaultState();
+        const raw = readFileSync(path, "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+            tier0_emitted: Boolean(parsed.tier0_emitted),
+            tier1_emitted_kinds: Array.isArray(parsed.tier1_emitted_kinds)
+                ? parsed.tier1_emitted_kinds.filter((s) => typeof s === "string")
+                : [],
+            drift_count: typeof parsed.drift_count === "number" ? parsed.drift_count : 0,
+            tier2_emitted: Boolean(parsed.tier2_emitted),
+            last_unerr_tool_at: typeof parsed.last_unerr_tool_at === "string"
+                ? parsed.last_unerr_tool_at
+                : undefined,
+        };
+    }
+    catch {
+        return defaultState();
+    }
+}
+export function writeNudgeState(cwd, state) {
+    try {
+        const path = statePath(cwd);
+        const dir = path.slice(0, path.lastIndexOf("/"));
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(path, JSON.stringify(state), "utf8");
+    }
+    catch {
+        /* best effort */
+    }
+}
+/** Convenience helper: read, mutate, write atomically. */
+export function updateNudgeState(cwd, mutator) {
+    const s = readNudgeState(cwd);
+    mutator(s);
+    writeNudgeState(cwd, s);
+    return s;
+}
+/** Reset all flags for the current session — escape hatch for tests. */
+export function _resetNudgeState(cwd) {
+    try {
+        writeNudgeState(cwd, defaultState());
+    }
+    catch {
+        /* ignore */
+    }
+}
+/**
+ * Called by the MCP layer on every successful unerr tool invocation.
+ * Resets the drift accumulator and stamps the last-used timestamp so
+ * Tier-2 escalation only fires on persistent drift.
+ */
+export function markUnerrToolUsed(cwd) {
+    try {
+        updateNudgeState(cwd, (s) => {
+            s.drift_count = 0;
+            s.tier2_emitted = false;
+            s.last_unerr_tool_at = new Date().toISOString();
+        });
+    }
+    catch {
+        /* best effort */
+    }
+}

package/dist/proxy/output-compressor.js

@@ -0,0 +1,185 @@
+/**
+ * Graph-Aware Output Compressor — intelligent truncation of large outputs.
+ *
+ * Intercepts large command outputs (>2K tokens) and compresses them by:
+ *   1. Identifying sections (file headers, diff hunks, error blocks)
+ *   2. Scoring sections by entity risk, caller count, change significance
+ *   3. Budget allocation — high-score sections get full text, low-score get summaries
+ *   4. Annotating preserved lines with graph intelligence
+ *
+ * Only applies to raw text outputs (git diff, test results, ls).
+ * Structured MCP tool responses pass through unchanged.
+ */
+import { estimateTokenCount } from "../intelligence/token-estimator.js";
+const ERROR_PATTERNS = [
+    /error/i,
+    /ERR[_!]/,
+    /FAIL/,
+    /TypeError/,
+    /SyntaxError/,
+    /ReferenceError/,
+    /ENOENT/,
+    /Cannot find/,
+    /Unexpected/,
+    /✗|✕|×/,
+];
+const DIFF_HEADER = /^(diff --git|---|\+\+\+|@@)/;
+const FILE_HEADER = /^(diff --git a\/(.+) b\/|---\s+a\/(.+)|[\w/]+\.[a-z]+:)/;
+function isErrorLine(line) {
+    return ERROR_PATTERNS.some((p) => p.test(line));
+}
+function extractFilePath(line) {
+    const diffMatch = line.match(/^diff --git a\/(.+?) b\//);
+    if (diffMatch)
+        return diffMatch[1] ?? null;
+    const fileMatch = line.match(/^---\s+a\/(.+)/);
+    if (fileMatch)
+        return fileMatch[1] ?? null;
+    const colonMatch = line.match(/^([\w/.]+\.[a-z]+):/);
+    if (colonMatch)
+        return colonMatch[1] ?? null;
+    return null;
+}
+function splitIntoSections(text) {
+    const lines = text.split("\n");
+    const sections = [];
+    let current = {
+        lines: [],
+        score: 0,
+        type: "content",
+        annotations: [],
+    };
+    for (const line of lines) {
+        if (DIFF_HEADER.test(line)) {
+            if (current.lines.length > 0)
+                sections.push(current);
+            const filePath = extractFilePath(line);
+            current = {
+                lines: [line],
+                score: 1,
+                type: FILE_HEADER.test(line) ? "header" : "hunk",
+                filePath: filePath ?? undefined,
+                annotations: [],
+            };
+            continue;
+        }
+        if (line.trim() === "" &&
+            current.lines.length > 0 &&
+            current.lines.every((l) => l.trim() === "")) {
+            current.type = "blank";
+        }
+        if (isErrorLine(line)) {
+            if (current.lines.length > 0 && current.type !== "error") {
+                sections.push(current);
+                current = { lines: [], score: 5, type: "error", annotations: [] };
+            }
+            current.type = "error";
+            current.score = Math.max(current.score, 5);
+        }
+        current.lines.push(line);
+    }
+    if (current.lines.length > 0)
+        sections.push(current);
+    return sections;
+}
+function scoreSections(sections, entityRiskMap) {
+    for (const section of sections) {
+        if (section.type === "error")
+            section.score += 10;
+        if (section.type === "header")
+            section.score += 3;
+        if (section.filePath && entityRiskMap) {
+            for (const [entityKey, info] of entityRiskMap) {
+                if (entityKey.startsWith(section.filePath)) {
+                    if (info.riskLevel === "high") {
+                        section.score += 8;
+                        section.annotations.push(`[HIGH_RISK: ${info.fanIn} callers]`);
+                    }
+                    else if (info.riskLevel === "medium") {
+                        section.score += 4;
+                    }
+                    if (info.isChokepoint) {
+                        section.score += 6;
+                        section.annotations.push("[CHOKEPOINT]");
+                    }
+                    if (info.conventions && info.conventions.length > 0) {
+                        section.annotations.push(`[CONVENTION: ${info.conventions[0]}]`);
+                    }
+                }
+            }
+        }
+        if (section.type === "blank")
+            section.score = 0;
+        const addedLines = section.lines.filter((l) => l.startsWith("+")).length;
+        const removedLines = section.lines.filter((l) => l.startsWith("-")).length;
+        section.score += (addedLines + removedLines) * 0.1;
+    }
+}
+/**
+ * Compress a large text output using graph-aware truncation.
+ * Preserves high-value sections and annotates with risk metadata.
+ */
+export function compressOutput(text, options = {}) {
+    const { tokenBudget = 2000, preserveFirstLines = 5, preserveLastLines = 3, entityRiskMap, } = options;
+    const originalTokens = estimateTokenCount(text);
+    if (originalTokens <= tokenBudget) {
+        return {
+            output: text,
+            originalTokens,
+            compressedTokens: originalTokens,
+            sectionsPreserved: 0,
+            sectionsOmitted: 0,
+            annotations: [],
+        };
+    }
+    const sections = splitIntoSections(text);
+    scoreSections(sections, entityRiskMap);
+    sections.sort((a, b) => b.score - a.score);
+    const result = [];
+    let currentTokens = 0;
+    let sectionsPreserved = 0;
+    let sectionsOmitted = 0;
+    const allAnnotations = [];
+    const lines = text.split("\n");
+    const firstLines = lines.slice(0, preserveFirstLines).join("\n");
+    const lastLines = lines.slice(-preserveLastLines).join("\n");
+    currentTokens += estimateTokenCount(firstLines);
+    currentTokens += estimateTokenCount(lastLines);
+    result.push(firstLines);
+    for (const section of sections) {
+        const sectionText = section.lines.join("\n");
+        const sectionTokens = estimateTokenCount(sectionText);
+        if (currentTokens + sectionTokens <= tokenBudget * 0.85) {
+            let annotated = sectionText;
+            if (section.annotations.length > 0) {
+                const prefix = section.annotations.join(" ");
+                annotated = `${prefix}\n${sectionText}`;
+                allAnnotations.push(...section.annotations);
+            }
+            result.push(annotated);
+            currentTokens += estimateTokenCount(annotated);
+            sectionsPreserved++;
+        }
+        else {
+            const lineCount = section.lines.length;
+            const label = section.type === "blank"
+                ? "blank lines"
+                : section.filePath
+                    ? `${section.filePath}`
+                    : section.type;
+            result.push(`[... ${lineCount} lines omitted (${label}) ...]`);
+            sectionsOmitted++;
+        }
+    }
+    result.push(lastLines);
+    const output = result.join("\n");
+    const compressedTokens = estimateTokenCount(output);
+    return {
+        output,
+        originalTokens,
+        compressedTokens,
+        sectionsPreserved,
+        sectionsOmitted,
+        annotations: allAnnotations,
+    };
+}

package/dist/proxy/pid-lock.js

@@ -0,0 +1,291 @@
+/**
+ * PID Lock — single-instance enforcement for the proxy.
+ *
+ * PID file format (JSON): { pid, startedAt, healthPort }
+ * Health check HTTP endpoint on random high port for stale detection.
+ * Heartbeat every 10s. Backward-compatible with plain PID format.
+ */
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
+import { createServer } from "node:http";
+import { join } from "node:path";
+const HEARTBEAT_INTERVAL_MS = 10_000;
+const PID_FILENAME = "proxy.pid";
+const HEALTH_CHECK_TIMEOUT_MS = 500;
+export class PidLock {
+    pidPath;
+    heartbeatTimer = null;
+    healthServer = null;
+    healthPort = 0;
+    startedAt = "";
+    toolCalls = 0;
+    mode = "full";
+    constructor(unerrStateDir) {
+        this.pidPath = join(unerrStateDir, PID_FILENAME);
+    }
+    /**
+     * Set the current operating mode (for health endpoint).
+     */
+    setMode(mode) {
+        this.mode = mode;
+    }
+    /**
+     * Increment tool call counter (for health endpoint).
+     */
+    recordToolCall() {
+        this.toolCalls++;
+    }
+    /**
+     * Get the health port (for external discovery).
+     */
+    getHealthPort() {
+        return this.healthPort;
+    }
+    /**
+     * Attempt to acquire the PID lock.
+     * Returns outcome: primary (we're the proxy), secondary (another is running), stale_recovered.
+     */
+    async acquire() {
+        const stateDir = join(this.pidPath, "..");
+        if (!existsSync(stateDir)) {
+            mkdirSync(stateDir, { recursive: true });
+        }
+        // Check existing PID
+        if (existsSync(this.pidPath)) {
+            try {
+                const raw = readFileSync(this.pidPath, "utf-8").trim();
+                const pidData = parsePidFile(raw);
+                if (pidData && isProcessAlive(pidData.pid)) {
+                    // Process is alive — verify it's really unerr via health check
+                    if (pidData.healthPort) {
+                        const healthy = await checkHealth(pidData.healthPort);
+                        if (healthy) {
+                            return {
+                                acquired: false,
+                                outcome: "secondary",
+                                existingPid: pidData.pid,
+                                existingHealthPort: pidData.healthPort,
+                            };
+                        }
+                        // Health check failed but process exists → likely recycled PID → stale
+                        unlinkSync(this.pidPath);
+                        return await this.becomePrimary("stale_recovered");
+                    }
+                    // No health port (legacy format) → assume real proxy
+                    return {
+                        acquired: false,
+                        outcome: "secondary",
+                        existingPid: pidData.pid,
+                    };
+                }
+                // Stale — clean up
+                unlinkSync(this.pidPath);
+                return await this.becomePrimary("stale_recovered");
+            }
+            catch {
+                // Corrupt PID file — remove it
+                try {
+                    unlinkSync(this.pidPath);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }
+        return await this.becomePrimary("primary");
+    }
+    async becomePrimary(outcome) {
+        // Start health server on random port
+        await this.startHealthServer();
+        this.startedAt = new Date().toISOString();
+        // Write JSON PID file
+        this.writePidFile();
+        // Start heartbeat
+        this.heartbeatTimer = setInterval(() => {
+            try {
+                this.writePidFile();
+            }
+            catch {
+                // PID file disappeared — directory might be deleted
+            }
+        }, HEARTBEAT_INTERVAL_MS);
+        if (this.heartbeatTimer.unref) {
+            this.heartbeatTimer.unref();
+        }
+        // Cleanup on exit (crash recovery)
+        process.on("exit", () => {
+            try {
+                unlinkSync(this.pidPath);
+            }
+            catch {
+                /* ignore */
+            }
+        });
+        return { acquired: true, outcome, healthPort: this.healthPort };
+    }
+    writePidFile() {
+        const data = {
+            pid: process.pid,
+            startedAt: this.startedAt,
+            healthPort: this.healthPort,
+        };
+        writeFileSync(this.pidPath, JSON.stringify(data), "utf-8");
+    }
+    async startHealthServer() {
+        return new Promise((resolve) => {
+            this.healthServer = createServer((req, res) => {
+                if (req.url === "/health" && req.method === "GET") {
+                    const uptimeS = Math.round((Date.now() - new Date(this.startedAt).getTime()) / 1000);
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({
+                        status: "ok",
+                        uptime_s: uptimeS,
+                        tool_calls: this.toolCalls,
+                        mode: this.mode,
+                        pid: process.pid,
+                    }));
+                }
+                else {
+                    res.writeHead(404);
+                    res.end();
+                }
+            });
+            // Listen on random port (0 = OS assigns)
+            this.healthServer.listen(0, "127.0.0.1", () => {
+                const addr = this.healthServer?.address();
+                this.healthPort = typeof addr === "object" && addr ? addr.port : 0;
+                resolve();
+            });
+            this.healthServer.unref();
+        });
+    }
+    /**
+     * Release the PID lock, stop heartbeat, and close health server.
+     */
+    release() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        if (this.healthServer) {
+            this.healthServer.close();
+            this.healthServer = null;
+        }
+        try {
+            if (existsSync(this.pidPath)) {
+                const raw = readFileSync(this.pidPath, "utf-8").trim();
+                const data = parsePidFile(raw);
+                if (data && data.pid === process.pid) {
+                    unlinkSync(this.pidPath);
+                }
+            }
+        }
+        catch {
+            // Best effort cleanup
+        }
+    }
+    /**
+     * Check if a proxy is currently running (for external callers).
+     */
+    isLocked() {
+        if (!existsSync(this.pidPath))
+            return { locked: false };
+        try {
+            const raw = readFileSync(this.pidPath, "utf-8").trim();
+            const data = parsePidFile(raw);
+            if (data && isProcessAlive(data.pid)) {
+                return { locked: true, pid: data.pid, healthPort: data.healthPort };
+            }
+            return { locked: false };
+        }
+        catch {
+            return { locked: false };
+        }
+    }
+    /**
+     * Non-destructive probe: check if proxy is alive without acquiring the lock.
+     * Uses health check for full verification (unlike isLocked() which is sync-only).
+     */
+    async probe() {
+        if (!existsSync(this.pidPath))
+            return { alive: false };
+        try {
+            const raw = readFileSync(this.pidPath, "utf-8").trim();
+            const pidData = parsePidFile(raw);
+            if (!pidData || !isProcessAlive(pidData.pid))
+                return { alive: false };
+            if (pidData.healthPort) {
+                const healthy = await checkHealth(pidData.healthPort);
+                if (!healthy)
+                    return { alive: false };
+            }
+            return { alive: true, pid: pidData.pid, healthPort: pidData.healthPort };
+        }
+        catch {
+            return { alive: false };
+        }
+    }
+    /**
+     * Read the PID file data (for external callers like --mcp bridge).
+     */
+    static readPidFile(stateDir) {
+        const pidPath = join(stateDir, PID_FILENAME);
+        if (!existsSync(pidPath))
+            return null;
+        try {
+            const raw = readFileSync(pidPath, "utf-8").trim();
+            const data = parsePidFile(raw);
+            if (data && isProcessAlive(data.pid))
+                return data;
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/**
+ * Parse PID file — handles both JSON format and legacy plain number.
+ */
+function parsePidFile(raw) {
+    // Try JSON first
+    if (raw.startsWith("{")) {
+        try {
+            const data = JSON.parse(raw);
+            if (typeof data.pid === "number" && !Number.isNaN(data.pid)) {
+                return data;
+            }
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    // Legacy: plain PID number
+    const pid = Number.parseInt(raw, 10);
+    if (!Number.isNaN(pid)) {
+        return { pid, startedAt: "", healthPort: 0 };
+    }
+    return null;
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a health endpoint is responding (used for stale PID verification).
+ */
+async function checkHealth(port) {
+    try {
+        const res = await fetch(`http://127.0.0.1:${port}/health`, {
+            signal: AbortSignal.timeout(HEALTH_CHECK_TIMEOUT_MS),
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/proxy/proxy-context.js

@@ -0,0 +1,11 @@
+/**
+ * ProxyContext — Local-only context for the proxy.
+ *
+ * Local-only LLM adapter — optional BYO-LLM capability.
+ */
+/**
+ * Create a ProxyContext with optional BYO-LLM adapter.
+ */
+export function createLocalContext(llmAdapter = null) {
+    return { llmAdapter };
+}