@unerr-ai/unerr 0.2.1 → 0.2.3

package/dist/proxy/fact-ranking.js

@@ -1,154 +0,0 @@
-/**
- * Composite fact ranking — used by both recall_facts handlers (mcp-server.ts +
- * proxy.ts) so they stay in lock-step.
- *
- * Score = effective_confidence × (1 + log2(1 + reinforcements) × 0.3) × type_weight
- *
- * type_weight values codify "how anti-drift is this kind of fact":
- *   negative   1.5  (highest — anti-pattern, prevents future failure)
- *   convention 1.4  (project standard, must follow)
- *   semantic   1.2  (architecture / design context)
- *   procedural 1.0  (hot-file, modification pattern — useful but lower priority)
- *   episodic   0.8  (session history, lowest — interesting but rarely actionable)
- */
-const TYPE_WEIGHT = {
-    negative: 1.5,
-    convention: 1.4,
-    semantic: 1.2,
-    procedural: 1.0,
-    episodic: 0.8,
-};
-/**
- * Per-type rotation decay coefficient: how aggressively a fact's effective
- * rank drops with each show. Tuned so the *importance* gradient mirrors
- * TYPE_WEIGHT but inverted — anti-patterns must keep surfacing even after
- * being shown (low decay), episodic noise should age out quickly.
- *
- * effective_score = composite_score / (1 + shows × decay)
- */
-const TYPE_DECAY = {
-    negative: 0.3, // must-know — repeat slowly
-    convention: 0.4,
-    semantic: 0.5,
-    procedural: 0.6,
-    episodic: 0.8, // session history — fade fast
-};
-export function factTypeWeight(type) {
-    return TYPE_WEIGHT[type] ?? 1.0;
-}
-export function factTypeDecay(type) {
-    return TYPE_DECAY[type] ?? 0.5;
-}
-export function factScore(f) {
-    return (f.effective_confidence *
-        (1 + Math.log2(1 + f.reinforcement_count) * 0.3) *
-        factTypeWeight(f.fact_type));
-}
-/** Sort facts by composite score descending (does not mutate input). */
-export function rankFacts(facts) {
-    return [...facts].sort((a, b) => factScore(b) - factScore(a));
-}
-/**
- * Cross-channel dedup window: a fact surfaced via `ur|fct` (smuggle channel)
- * gets a temporary score penalty so explicit `recall_facts` calls right after
- * don't dominate top slots with the same fact.
- *
- * Penalty decays linearly from `RECENT_SHOW_PENALTY_MIN` (immediately after a
- * show) up to 1.0 at the edge of `RECENT_SHOW_WINDOW_MS`.
- */
-export const RECENT_SHOW_WINDOW_MS = 5 * 60 * 1000;
-export const RECENT_SHOW_PENALTY_MIN = 0.3;
-/** Multiplier applied when a fact's subject is in the active-session
- * recency set (gives "current task" facts a gentle nudge above strangers). */
-export const ACTIVE_SUBJECT_BOOST = 1.25;
-/**
- * Rotation-, recency-, and subject-aware ranker for recall_facts.
- *
- * - Per-type decay: anti-patterns repeat slowly, episodic noise fades fast.
- * - Cross-channel dedup: facts smuggled in the last 5 min are penalized.
- * - Active-subject boost: facts about recently-touched entities outrank strangers.
- *
- * Backward compatible: with no options, behaves like rankFacts().
- */
-export function rankFactsWithRotation(facts, opts = {}) {
-    const { getShowCount, getLastShownMs, recentSubjects, now = Date.now(), } = opts;
-    if (!getShowCount && !getLastShownMs && !recentSubjects) {
-        return rankFacts(facts);
-    }
-    const scored = facts.map((f) => {
-        let score = factScore(f);
-        if (getShowCount) {
-            const shows = getShowCount(f.fact_id);
-            const decay = factTypeDecay(f.fact_type);
-            score = score / (1 + shows * decay);
-        }
-        if (getLastShownMs) {
-            const last = getLastShownMs(f.fact_id);
-            if (last > 0) {
-                const age = now - last;
-                if (age < RECENT_SHOW_WINDOW_MS) {
-                    // Linear: penalty=MIN immediately after, 1.0 at window edge.
-                    const t = Math.max(0, age) / RECENT_SHOW_WINDOW_MS;
-                    const factor = RECENT_SHOW_PENALTY_MIN + (1 - RECENT_SHOW_PENALTY_MIN) * t;
-                    score *= factor;
-                }
-            }
-        }
-        if (recentSubjects && f.subject && recentSubjects.has(f.subject)) {
-            score *= ACTIVE_SUBJECT_BOOST;
-        }
-        return { fact: f, score };
-    });
-    return scored.sort((a, b) => b.score - a.score).map(({ fact }) => fact);
-}
-/**
- * Slice the ranked list to `limit` while enforcing diversity quotas so a hot
- * file doesn't dominate the top-N with five same-type, same-subject facts.
- *
- *   - max 60% of slots same fact_type
- *   - max 2 slots per subject
- *
- * Two-pass: first fills slots that satisfy both quotas; second pass relaxes
- * quotas to fill any remaining gaps so we never under-return.
- */
-export function applyDiversityQuota(ranked, limit, opts = {}) {
-    if (ranked.length <= limit)
-        return [...ranked];
-    const { maxSameTypePct = 0.6, maxSameSubject = 2 } = opts;
-    const maxSameType = Math.max(1, Math.floor(limit * maxSameTypePct));
-    const result = [];
-    const skipped = [];
-    const typeCounts = new Map();
-    const subjectCounts = new Map();
-    for (const f of ranked) {
-        if (result.length >= limit)
-            break;
-        const tc = typeCounts.get(f.fact_type) ?? 0;
-        const sc = f.subject ? (subjectCounts.get(f.subject) ?? 0) : 0;
-        if (tc >= maxSameType || sc >= maxSameSubject) {
-            skipped.push(f);
-            continue;
-        }
-        result.push(f);
-        typeCounts.set(f.fact_type, tc + 1);
-        if (f.subject)
-            subjectCounts.set(f.subject, sc + 1);
-    }
-    for (const f of skipped) {
-        if (result.length >= limit)
-            break;
-        result.push(f);
-    }
-    return result;
-}
-/**
- * Default visible-cap for recall_facts.
- * Override via `args.limit` (max 25 to keep wire bounded).
- */
-export const DEFAULT_FACT_LIMIT = 5;
-export const MAX_FACT_LIMIT = 25;
-export function resolveFactLimit(argsLimit) {
-    if (typeof argsLimit !== "number" || argsLimit <= 0)
-        return DEFAULT_FACT_LIMIT;
-    return Math.min(Math.floor(argsLimit), MAX_FACT_LIMIT);
-}

package/dist/proxy/format-encoder.js

@@ -1,266 +0,0 @@
-/**
- * Layer 6 — shape-aware columnar wire encoding for MCP tool payloads.
- * Sprint FE-C (encoder core) + FE-E (session legends, tier fallback).
- */
-import { OUTPUT_FORMAT_LEGEND, } from "./session-legend.js";
-export const COLUMNAR_LEGEND_TEXT = "Layer 6 columnar: body starts with _fmt:columnar; next line is pipe-separated headers; following lines are rows in column order. Newlines in cells are escaped as \\\\n. Cells containing | or quotes use CSV-style double quotes.";
-export function isUniformObjectArray(arr) {
-    const objects = arr.filter((x) => x !== null && typeof x === "object" && !Array.isArray(x));
-    if (objects.length !== arr.length || objects.length === 0)
-        return false;
-    const firstKeys = new Set(Object.keys(objects[0]));
-    for (let i = 1; i < objects.length; i++) {
-        const k = new Set(Object.keys(objects[i]));
-        if (k.size !== firstKeys.size)
-            return false;
-        for (const key of firstKeys) {
-            if (!k.has(key))
-                return false;
-        }
-    }
-    return true;
-}
-export function detectShape(data) {
-    if (Array.isArray(data)) {
-        if (data.length === 0)
-            return "heterogeneous";
-        return isUniformObjectArray(data) ? "uniform-array" : "heterogeneous";
-    }
-    if (data !== null && typeof data === "object" && !(data instanceof Date)) {
-        const o = data;
-        if (Object.keys(o).length === 0)
-            return "heterogeneous";
-        return "single-object";
-    }
-    return "heterogeneous";
-}
-/**
- * Escape a columnar cell for pipe-separated output.
- * Newlines are replaced with literal \\n (backslash-n) so rows stay on one line.
- * Pipes and double-quotes trigger CSV-style quoting (cell wrapped in `"`).
- */
-export function escapeColumnarCell(value) {
-    if (value === null || value === undefined)
-        return "";
-    let s = typeof value === "string" ? value : JSON.stringify(value);
-    // Flatten newlines FIRST so rows never span multiple lines
-    s = s.replace(/\r\n/g, "\\n").replace(/\n/g, "\\n").replace(/\r/g, "\\n");
-    // If pipe or double-quote remains, use CSV-style quoting
-    if (/[|"]/.test(s)) {
-        return `"${s.replace(/"/g, '""')}"`;
-    }
-    return s;
-}
-export function encodeColumnar(rows, columns) {
-    const header = `_fmt:columnar\n${columns.join("|")}`;
-    const lines = rows.map((row) => columns.map((c) => escapeColumnarCell(row[c])).join("|"));
-    return `${header}\n${lines.join("\n")}`;
-}
-function sortedColumnsFromFirstRow(rows) {
-    const first = rows[0];
-    if (!first)
-        return [];
-    return Object.keys(first).sort();
-}
-/**
- * P6.2: encode an object with multiple uniform arrays as `_fmt:multi`.
- *
- * Format:
- *   _fmt:multi
- *   @meta k1=v1|k2=v2|...                   ← scalars (one line)
- *   @<arrayName>[col1|col2|...]             ← uniform-object array, columnar
- *   val|val|val
- *   ...
- *   @<arrayName>[]                          ← string-array (line per item)
- *   item
- *   item
- *
- * Used when a response has 2+ recognized uniform arrays (file_outline has
- * entities/imports/exports; file_connections has connections/entities).
- */
-export function encodeMultiSection(scalars, sections) {
-    const lines = ["_fmt:multi"];
-    // Scalars row
-    const scalarPairs = Object.entries(scalars)
-        .filter(([, v]) => v !== undefined && v !== null && typeof v !== "object")
-        .map(([k, v]) => `${k}=${String(v)}`);
-    if (scalarPairs.length > 0) {
-        lines.push(`@meta ${scalarPairs.join("|")}`);
-    }
-    // Sections
-    for (const sec of sections) {
-        if (sec.items.length === 0) {
-            lines.push(`@${sec.name}[]`);
-            continue;
-        }
-        if (sec.kind === "uniform-object") {
-            const rows = sec.items;
-            const columns = sortedColumnsFromFirstRow(rows);
-            lines.push(`@${sec.name}[${columns.join("|")}]`);
-            for (const row of rows) {
-                lines.push(columns.map((c) => escapeColumnarCell(row[c])).join("|"));
-            }
-        }
-        else {
-            // string-list: one item per line
-            lines.push(`@${sec.name}[]`);
-            for (const item of sec.items) {
-                const s = typeof item === "string" ? item : JSON.stringify(item);
-                // Flatten newlines so each item stays on one line
-                lines.push(s.replace(/\r\n|\n|\r/g, "\\n"));
-            }
-        }
-    }
-    return lines.join("\n");
-}
-function isErrorEnvelope(x) {
-    return (typeof x === "object" &&
-        x !== null &&
-        !Array.isArray(x) &&
-        "error" in x &&
-        typeof x.error === "string");
-}
-function shouldSkipFormatting(meta) {
-    return meta.format === "outline" || meta.gated === true;
-}
-/**
- * Apply columnar encoding to uniform arrays. Mutates `meta.format`, `meta.columns`, legends.
- * Single objects, strings, errors, outline payloads, and heterogeneous data pass through as JSON.
- */
-export function formatToolOutput(toolName, content, meta, options) {
-    void toolName;
-    const tier = options?.tier ?? "columnar";
-    const legend = options?.legend ?? null;
-    // BA-4.3: Attach output format legend once per session (first formatted response)
-    if (legend?.consumeOutputFormatLegend()) {
-        meta.output_format_legend = OUTPUT_FORMAT_LEGEND;
-    }
-    if (shouldSkipFormatting(meta))
-        return content;
-    if (content === null || content === undefined)
-        return content;
-    if (typeof content === "string")
-        return content;
-    if (isErrorEnvelope(content))
-        return content;
-    if (typeof content === "object" &&
-        content !== null &&
-        "message" in content &&
-        ("progress" in content || "total" in content) &&
-        typeof content.message === "string") {
-        return content;
-    }
-    if (tier === "expanded") {
-        meta.format = "json";
-        return content;
-    }
-    const skipColumnar = tier === "minified";
-    const shape = detectShape(content);
-    const attachColumnarLegend = () => {
-        if (legend?.consumeColumnarLegend()) {
-            meta.columnar_legend = COLUMNAR_LEGEND_TEXT;
-        }
-    };
-    if (!skipColumnar && shape === "uniform-array" && Array.isArray(content)) {
-        const rows = content;
-        const columns = sortedColumnsFromFirstRow(rows);
-        meta.format = "columnar";
-        meta.columns = columns;
-        attachColumnarLegend();
-        return encodeColumnar(rows, columns);
-    }
-    // Tier-3 P6.1: extended wrapper detection.
-    // Recognize known wrapper-array field names; columnar-encode the array
-    // if it's uniform-object AND it's the only array in the wrapper. When
-    // multiple arrays coexist (file_outline has entities + imports + exports),
-    // bail out — that's P6.2's _fmt:multi job.
-    const KNOWN_ARRAY_WRAPPERS = [
-        "items",
-        "facts",
-        "references",
-        "connections",
-        "entities",
-        "imports",
-        "exports",
-        "tests",
-        "candidates",
-        // get_conventions: kinds hoisted to top level for _fmt:multi
-        "naming",
-        "import_direction",
-        "structure",
-        "other",
-        "guidance",
-    ];
-    if (!skipColumnar) {
-        if (typeof content === "object" && content !== null) {
-            const obj = content;
-            const arrayFieldsPresent = KNOWN_ARRAY_WRAPPERS.filter((k) => k in obj && Array.isArray(obj[k]));
-            // P6.2: 2+ recognized arrays → _fmt:multi.
-            if (arrayFieldsPresent.length >= 2) {
-                const sections = arrayFieldsPresent.map((k) => {
-                    const items = obj[k];
-                    const kind = items.length > 0 &&
-                        typeof items[0] === "object" &&
-                        items[0] !== null &&
-                        isUniformObjectArray(items)
-                        ? "uniform-object"
-                        : "string-list";
-                    return { name: k, items, kind };
-                });
-                // Scalars: everything that's not one of the array fields, not nested object
-                const scalars = {};
-                for (const [k, v] of Object.entries(obj)) {
-                    if (arrayFieldsPresent.includes(k))
-                        continue;
-                    scalars[k] = v;
-                }
-                meta.format = "columnar"; // Re-use the columnar format flag; legend covers _fmt:multi too.
-                attachColumnarLegend();
-                return encodeMultiSection(scalars, sections);
-            }
-            // Single recognized array → columnar it.
-            if (arrayFieldsPresent.length === 1) {
-                const arrayKey = arrayFieldsPresent[0];
-                const items = obj[arrayKey];
-                if (items.length > 0 && isUniformObjectArray(items)) {
-                    const columns = sortedColumnsFromFirstRow(items);
-                    meta.format = "columnar";
-                    meta.columns = columns;
-                    attachColumnarLegend();
-                    // Preserve all non-array scalars as a one-line metadata header.
-                    const scalarFields = Object.entries(obj)
-                        .filter(([k, v]) => k !== arrayKey &&
-                        !Array.isArray(v) &&
-                        v !== undefined &&
-                        v !== null &&
-                        typeof v !== "object")
-                        .map(([k, v]) => `${k}=${String(v)}`)
-                        .join("|");
-                    // encodeColumnar already prepends `_fmt:columnar` — don't double it.
-                    // The wrapper context (which array this is) lives in `_list_meta:`
-                    // (when there are scalars) or is implicit from the toolName.
-                    let text = encodeColumnar(items, columns);
-                    if (scalarFields) {
-                        text = `_list_meta:${scalarFields}\n${text}`;
-                    }
-                    return text;
-                }
-            }
-        }
-    }
-    else {
-        if (shape === "uniform-array" && Array.isArray(content)) {
-            meta.format = "json";
-            return content;
-        }
-        if (typeof content === "object" &&
-            content !== null &&
-            "items" in content &&
-            Array.isArray(content.items)) {
-            meta.format = "json";
-            return content;
-        }
-    }
-    meta.format = "json";
-    return content;
-}

package/dist/proxy/http-transport.js

@@ -1,90 +0,0 @@
-/**
- * Sprint 5.3: HTTP/SSE Transport for Main Proxy
- *
- * Adds Streamable HTTP transport alongside STDIO for remote/CI access.
- * Endpoints:
- *   POST /mcp   — MCP Streamable HTTP (recommended)
- *   GET  /mcp   — SSE stream for server-initiated messages
- *   GET  /health — Health check (no auth)
- *
- * Bearer token auth required on /mcp (uses proxy credentials).
- * All output to stderr — stdout reserved for STDIO MCP.
- */
-import { createServer as createHttpServer, } from "node:http";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-/**
- * Start an HTTP server that serves MCP via Streamable HTTP transport.
- * Returns a handle for shutdown.
- */
-export async function startHttpTransport(opts) {
-    const { port, apiKey, mcpServer, log = () => { } } = opts;
-    // Create a stateful transport (session-aware)
-    const transport = new StreamableHTTPServerTransport({
-        sessionIdGenerator: () => crypto.randomUUID(),
-    });
-    // Connect to MCP server
-    await mcpServer.connect(transport);
-    const httpServer = createHttpServer(async (req, res) => {
-        const url = new URL(req.url ?? "/", `http://localhost:${port}`);
-        // CORS
-        res.setHeader("Access-Control-Allow-Origin", "*");
-        res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
-        res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, Mcp-Session-Id");
-        res.setHeader("Access-Control-Expose-Headers", "Mcp-Session-Id");
-        if (req.method === "OPTIONS") {
-            res.writeHead(204);
-            res.end();
-            return;
-        }
-        // Health — no auth
-        if (url.pathname === "/health") {
-            res.writeHead(200, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({
-                status: "ok",
-                transport: "streamable-http",
-                pid: process.pid,
-            }));
-            return;
-        }
-        // Auth check for /mcp
-        if (url.pathname === "/mcp") {
-            if (apiKey) {
-                const authHeader = req.headers.authorization;
-                const token = authHeader?.startsWith("Bearer ")
-                    ? authHeader.slice(7)
-                    : authHeader;
-                if (token !== apiKey) {
-                    res.writeHead(401, { "Content-Type": "application/json" });
-                    res.end(JSON.stringify({ error: "Unauthorized" }));
-                    return;
-                }
-            }
-            // Delegate to StreamableHTTPServerTransport
-            await transport.handleRequest(req, res);
-            return;
-        }
-        // 404
-        res.writeHead(404, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({
-            error: "Not found",
-            endpoints: ["/mcp", "/health"],
-        }));
-    });
-    return new Promise((resolve) => {
-        httpServer.listen(port, "127.0.0.1", () => {
-            const addr = httpServer.address();
-            const resolvedPort = typeof addr === "object" && addr ? addr.port : port;
-            log(`HTTP transport listening on http://127.0.0.1:${resolvedPort}/mcp`);
-            resolve({
-                server: httpServer,
-                port: resolvedPort,
-                close: () => {
-                    transport.close().catch(() => { });
-                    httpServer.close();
-                },
-            });
-        });
-        // Don't block process exit
-        httpServer.unref();
-    });
-}

package/dist/proxy/lifecycle-actor.js

@@ -1,55 +0,0 @@
-/**
- * Proxy Lifecycle Actor — wraps XState machine with a convenient imperative API.
- *
- * proxy.ts creates one LifecycleActor per boot. The actor:
- *   - Receives events from each boot step
- *   - Emits state transitions for subscribers (startup renderer, telemetry)
- *   - Provides .waitFor(state) for async coordination
- *   - Tracks timing for each phase (detecting, indexing, etc.)
- */
-import { createActor, waitFor } from "xstate";
-import { proxyMachine, } from "./lifecycle-machine.js";
-export function createLifecycleActor(repoPath) {
-    const actor = createActor(proxyMachine, {
-        input: { repoPath },
-    });
-    actor.start();
-    const send = (event) => {
-        actor.send(event);
-    };
-    const getState = () => {
-        return actor.getSnapshot().value;
-    };
-    const getContext = () => {
-        return actor.getSnapshot().context;
-    };
-    const getSnapshot = () => ({
-        value: getState(),
-        context: getContext(),
-    });
-    const waitForState = async (state, timeoutMs = 30_000) => {
-        const snap = actor.getSnapshot();
-        if (snap.value === state)
-            return;
-        if (snap.status === "done")
-            return;
-        await waitFor(actor, (snapshot) => snapshot.value === state || snapshot.status === "done", { timeout: timeoutMs });
-    };
-    const subscribe = (callback) => {
-        return actor.subscribe((snapshot) => {
-            callback(snapshot.value, snapshot.context);
-        });
-    };
-    const stop = () => {
-        actor.stop();
-    };
-    return {
-        send,
-        getState,
-        getContext,
-        getSnapshot,
-        waitForState,
-        subscribe,
-        stop,
-    };
-}