@unerr-ai/unerr 0.1.0 → 0.1.2

package/dist/server/http.js

@@ -0,0 +1,156 @@
+/**
+ * Layer 7: Hono HTTP server factory for the intelligence dashboard.
+ *
+ * Serves:
+ *   /api/system/*       — Proxy status and configuration
+ *   /api/intelligence/* — Graph, health, entity, causal, durability
+ *   /api/session/*      — Session stats, efficiency, intents, ledger
+ *   /api/stream         — SSE real-time event transport
+ *   /assets/*      — Vite-built SPA static assets (production)
+ *   /*             — SPA fallback (index.html)
+ *
+ * Bound strictly to 127.0.0.1 — localhost only, no network exposure.
+ * Runs inside the same process as the MCP proxy for direct memory access.
+ */
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { createServer } from "node:net";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { serve } from "@hono/node-server";
+import { serveStatic } from "@hono/node-server/serve-static";
+import { Hono } from "hono";
+import { cacheMiddleware, corsMiddleware, errorMiddleware, timingMiddleware, } from "./middleware.js";
+import { createDriftRoutes } from "./routes/drift.js";
+import { createIntelligenceRoutes, } from "./routes/intelligence.js";
+import { createReasoningQualityRoutes, } from "./routes/reasoning-quality.js";
+import { createSessionRoutes, } from "./routes/session.js";
+import { createStreamRoutes } from "./routes/stream.js";
+import { createSystemRoutes } from "./routes/system.js";
+import { createTemporalRoutes, } from "./routes/temporal.js";
+import { createTimelineRoutes, } from "./routes/timeline.js";
+import { createTokenFlowRoutes, } from "./routes/token-flow.js";
+const PORT_START = 7600;
+const PORT_END = 7700;
+/**
+ * Find an available port in the 7655-7660 range.
+ * Returns 0 if all ports are occupied.
+ */
+async function findAvailablePort() {
+    for (let port = PORT_START; port <= PORT_END; port++) {
+        const available = await new Promise((resolve) => {
+            const server = createServer();
+            server.once("error", () => resolve(false));
+            server.once("listening", () => {
+                server.close(() => resolve(true));
+            });
+            server.listen(port, "127.0.0.1");
+        });
+        if (available)
+            return port;
+    }
+    return 0;
+}
+/**
+ * Create and start the dashboard HTTP server.
+ * Non-blocking: returns null if no port available (dashboard is non-critical).
+ */
+export async function startDashboardServer(opts) {
+    const port = await findAvailablePort();
+    if (port === 0) {
+        process.stderr.write("[dashboard] All ports 7655-7660 occupied, skipping dashboard server.\n");
+        return null;
+    }
+    // Update the system route deps with the resolved port
+    opts.system.dashboardPort = port;
+    const app = new Hono();
+    // Middleware stack
+    app.use("*", corsMiddleware);
+    app.use("*", cacheMiddleware);
+    app.use("*", timingMiddleware);
+    app.use("*", errorMiddleware);
+    // API routes
+    app.route("/api/system", createSystemRoutes(opts.system));
+    app.route("/api/drift", createDriftRoutes({ cwd: opts.system.cwd }));
+    app.route("/api/intelligence", createIntelligenceRoutes(opts.intelligence));
+    app.route("/api/session", createSessionRoutes(opts.session));
+    app.route("/api/stream", createStreamRoutes(opts.stream));
+    if (opts.temporal) {
+        app.route("", createTemporalRoutes(opts.temporal));
+    }
+    if (opts.timeline) {
+        app.route("/api/timeline", createTimelineRoutes(opts.timeline));
+    }
+    if (opts.tokenFlow) {
+        app.route("/api/token-flow", createTokenFlowRoutes(opts.tokenFlow));
+    }
+    if (opts.reasoningQuality) {
+        app.route("/api/reasoning-quality", createReasoningQualityRoutes(opts.reasoningQuality));
+    }
+    // SPA serving — skipped for daemon children (supervisor serves UI on :9847)
+    if (!opts.apiOnly) {
+        const distDir = join(dirname(fileURLToPath(import.meta.url)), "ui");
+        const spaIndex = join(distDir, "index.html");
+        if (existsSync(spaIndex)) {
+            const spaHtml = readFileSync(spaIndex, "utf-8");
+            app.use("*", serveStatic({ root: distDir }));
+            app.get("*", (c) => {
+                const path = c.req.path;
+                if (path.startsWith("/api/")) {
+                    return c.notFound();
+                }
+                return c.html(spaHtml);
+            });
+        }
+        else {
+            app.get("/", (c) => {
+                return c.json({
+                    message: "unerr dashboard API is running. UI not built yet.",
+                    hint: "Run 'pnpm run build:ui' to build the dashboard SPA.",
+                    api: {
+                        status: "/api/system/status",
+                        config: "/api/system/config",
+                        intelligence: "/api/intelligence/{graph-stats,health,top-entities,...}",
+                        session: "/api/session/{stats,efficiency,intents,ledger}",
+                        stream: "/api/stream (SSE)",
+                    },
+                });
+            });
+        }
+    }
+    else {
+        app.get("/", (c) => c.json({ status: "ok", mode: "api-only" }));
+    }
+    // Start server
+    const server = serve({
+        fetch: app.fetch,
+        port,
+        hostname: "127.0.0.1",
+    });
+    // Write server.json atomically
+    const serverJsonPath = join(opts.stateDir, "server.json");
+    const serverInfo = {
+        port,
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+        url: `http://localhost:${port}`,
+    };
+    const tmpPath = `${serverJsonPath}.tmp.${process.pid}`;
+    writeFileSync(tmpPath, JSON.stringify(serverInfo, null, 2));
+    const { renameSync } = await import("node:fs");
+    renameSync(tmpPath, serverJsonPath);
+    const close = () => {
+        try {
+            server.close();
+        }
+        catch {
+            // Server may already be closed
+        }
+        try {
+            unlinkSync(serverJsonPath);
+        }
+        catch {
+            // File may not exist
+        }
+    };
+    return { port, close };
+}

package/dist/server/middleware.js

@@ -0,0 +1,70 @@
+/**
+ * Layer 7: Hono middleware stack for the dashboard HTTP server.
+ *
+ * Order: CORS → Cache-Control → Request ID + Timing → Error Boundary
+ */
+import { createMiddleware } from "hono/factory";
+/**
+ * Strict localhost-only CORS. Rejects any origin that isn't
+ * http://localhost:* or http://127.0.0.1:*
+ */
+export const corsMiddleware = createMiddleware(async (c, next) => {
+    const origin = c.req.header("origin");
+    if (origin) {
+        const isLocalhost = origin.startsWith("http://localhost") ||
+            origin.startsWith("http://127.0.0.1");
+        if (!isLocalhost) {
+            return c.json({ data: null, error: "CORS: origin not allowed" }, 403);
+        }
+        c.header("Access-Control-Allow-Origin", origin);
+        c.header("Access-Control-Allow-Methods", "GET, OPTIONS");
+        c.header("Access-Control-Allow-Headers", "Content-Type");
+    }
+    if (c.req.method === "OPTIONS") {
+        return c.body(null, 204);
+    }
+    await next();
+});
+/**
+ * Cache-Control headers based on path.
+ * /assets/* → immutable (content-hashed by Vite)
+ * /api/* → no-cache
+ */
+export const cacheMiddleware = createMiddleware(async (c, next) => {
+    await next();
+    const path = c.req.path;
+    if (path.startsWith("/assets/")) {
+        c.header("Cache-Control", "public, max-age=31536000, immutable");
+    }
+    else if (path.startsWith("/api/")) {
+        c.header("Cache-Control", "no-cache, no-store, must-revalidate");
+    }
+});
+/**
+ * Request ID and timing. Adds X-Request-Id and logs to stderr.
+ */
+export const timingMiddleware = createMiddleware(async (c, next) => {
+    const reqId = Math.random().toString(36).slice(2, 10);
+    const start = performance.now();
+    c.set("reqId", reqId);
+    c.header("X-Request-Id", reqId);
+    await next();
+    const ms = (performance.now() - start).toFixed(1);
+    process.stderr.write(`[dashboard] ${c.req.method} ${c.req.path} → ${c.res.status} (${ms}ms)\n`);
+});
+/**
+ * Global error boundary. Never crash — return structured error envelope.
+ */
+export const errorMiddleware = createMiddleware(async (c, next) => {
+    try {
+        await next();
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[dashboard] ERROR: ${message}\n`);
+        return c.json({
+            data: null,
+            _meta: { source: "local", latency_ms: 0, error: message },
+        }, 500);
+    }
+});

package/dist/server/routes/drift.js

@@ -0,0 +1,97 @@
+/**
+ * N10 — Drift metrics endpoint for the Reasoning Quality dashboard pane.
+ *
+ * Surfaces nudge-v2 session state (Tier-1 emissions per kind, drift count,
+ * Tier-2 escalations, last unerr-tool timestamp) so the UI can render a
+ * "drift events this session" sparkline and "drift correction rate" KPI.
+ *
+ * Read-only — no side effects, no DB writes. Reads `.unerr/state/nudge-*.flags`
+ * files directly. Falls back to empty data if no sessions have flag files yet.
+ *
+ * GET /api/drift/sessions  — aggregate across all known session flag files
+ * GET /api/drift/current   — current session only (UNERR_SESSION_ID)
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { Hono } from "hono";
+function readFlags(path) {
+    try {
+        if (!existsSync(path))
+            return null;
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function listSessionFiles(stateDir) {
+    try {
+        if (!existsSync(stateDir))
+            return [];
+        return readdirSync(stateDir)
+            .filter((f) => f.startsWith("nudge-") && f.endsWith(".flags"))
+            .map((f) => join(stateDir, f));
+    }
+    catch {
+        return [];
+    }
+}
+function rowFor(file) {
+    const flags = readFlags(file);
+    if (!flags)
+        return null;
+    const id = file
+        .split("/")
+        .pop()
+        ?.replace(/^nudge-/, "")
+        .replace(/\.flags$/, "");
+    return {
+        session_id: id ?? "",
+        tier0_emitted: Boolean(flags.tier0_emitted),
+        tier1_kinds: Array.isArray(flags.tier1_emitted_kinds)
+            ? flags.tier1_emitted_kinds
+            : [],
+        drift_count: typeof flags.drift_count === "number" ? flags.drift_count : 0,
+        tier2_emitted: Boolean(flags.tier2_emitted),
+        last_unerr_tool_at: flags.last_unerr_tool_at ?? null,
+    };
+}
+export function createDriftRoutes(deps) {
+    const app = new Hono();
+    const stateDir = join(deps.cwd, ".unerr", "state");
+    app.get("/sessions", (c) => {
+        const rows = [];
+        for (const file of listSessionFiles(stateDir)) {
+            const r = rowFor(file);
+            if (r)
+                rows.push(r);
+        }
+        const totalDrift = rows.reduce((s, r) => s + r.drift_count, 0);
+        const corrected = rows.filter((r) => r.last_unerr_tool_at).length;
+        return c.json({
+            data: {
+                sessions: rows,
+                total_sessions: rows.length,
+                total_drift_events: totalDrift,
+                sessions_with_correction: corrected,
+                correction_rate: rows.length > 0 ? corrected / rows.length : 0,
+            },
+        });
+    });
+    app.get("/current", (c) => {
+        const id = process.env.UNERR_SESSION_ID ?? `pid-${process.pid}`;
+        const file = join(stateDir, `nudge-${id}.flags`);
+        const row = rowFor(file);
+        return c.json({
+            data: row ?? {
+                session_id: id,
+                tier0_emitted: false,
+                tier1_kinds: [],
+                drift_count: 0,
+                tier2_emitted: false,
+                last_unerr_tool_at: null,
+            },
+        });
+    });
+    return app;
+}