@tpsdev-ai/flair 0.5.6 → 0.6.0

package/dist/deploy.js

@@ -0,0 +1,161 @@
+import { spawn } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+// Files that must be present in a Flair package for deployment.
+// Mirrors the `files` array in package.json — keep in sync.
+export const REQUIRED_PACKAGE_FILES = [
+    "dist",
+    "schemas",
+    "ui",
+    "config.yaml",
+];
+export function validateOptions(opts) {
+    const errors = [];
+    if (!opts.target) {
+        if (!opts.fabricOrg)
+            errors.push("--fabric-org required (or FABRIC_ORG env)");
+        if (!opts.fabricCluster)
+            errors.push("--fabric-cluster required (or FABRIC_CLUSTER env)");
+    }
+    const hasBasic = !!(opts.fabricUser && opts.fabricPassword);
+    const hasBearer = !!opts.fabricToken;
+    if (!hasBasic && !hasBearer) {
+        errors.push("credentials required: pass --fabric-user + --fabric-password " +
+            "(or FABRIC_USER / FABRIC_PASSWORD env), or --fabric-token " +
+            "(FABRIC_TOKEN env)");
+    }
+    return errors;
+}
+export function buildTargetUrl(opts) {
+    if (opts.target)
+        return opts.target;
+    return `https://${opts.fabricCluster}.${opts.fabricOrg}.harperfabric.com`;
+}
+export function resolvePackageRoot(override) {
+    if (override) {
+        const abs = resolve(override);
+        if (!existsSync(join(abs, "package.json"))) {
+            throw new Error(`No package.json at ${abs}`);
+        }
+        return abs;
+    }
+    // Walk up from this module's location — works when installed locally
+    // and when npx extracts the tarball to a tmpdir.
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        let dir = here;
+        for (let i = 0; i < 8; i++) {
+            const pkgPath = join(dir, "package.json");
+            if (existsSync(pkgPath)) {
+                const json = JSON.parse(readFileSync(pkgPath, "utf8"));
+                if (json.name === "@tpsdev-ai/flair")
+                    return dir;
+            }
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    try {
+        const req = createRequire(import.meta.url);
+        return dirname(req.resolve("@tpsdev-ai/flair/package.json"));
+    }
+    catch {
+        throw new Error("Could not locate @tpsdev-ai/flair package root. Try --package-root.");
+    }
+}
+export function validatePackageLayout(packageRoot) {
+    const missing = [];
+    for (const f of REQUIRED_PACKAGE_FILES) {
+        if (!existsSync(join(packageRoot, f)))
+            missing.push(f);
+    }
+    if (missing.length) {
+        throw new Error(`Flair package at ${packageRoot} is missing required entries: ` +
+            missing.join(", "));
+    }
+}
+function resolveHarperBin(packageRoot) {
+    const local = join(packageRoot, "node_modules/@harperfast/harper/dist/bin/harper.js");
+    if (existsSync(local))
+        return local;
+    try {
+        const req = createRequire(join(packageRoot, "package.json"));
+        const mainPath = req.resolve("@harperfast/harper");
+        let dir = dirname(mainPath);
+        for (let i = 0; i < 6; i++) {
+            const candidate = join(dir, "dist/bin/harper.js");
+            if (existsSync(candidate))
+                return candidate;
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    throw new Error("Could not locate Harper CLI binary (@harperfast/harper). " +
+        "Flair deploy requires Harper to be installed alongside Flair.");
+}
+function spawnHarper(bin, args, cwd, env) {
+    return new Promise((resolveP, rejectP) => {
+        const p = spawn(process.execPath, [bin, ...args], {
+            cwd,
+            stdio: "inherit",
+            env,
+        });
+        p.on("error", rejectP);
+        p.on("exit", (code) => {
+            if (code === 0)
+                resolveP();
+            else
+                rejectP(new Error(`harper deploy exited with code ${code}`));
+        });
+    });
+}
+export async function deploy(opts) {
+    const errors = validateOptions(opts);
+    if (errors.length) {
+        throw new Error(errors.join("\n"));
+    }
+    const packageRoot = resolvePackageRoot(opts.packageRoot);
+    validatePackageLayout(packageRoot);
+    const pkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+    const version = opts.version ?? pkg.version;
+    const project = opts.project ?? "flair";
+    const url = buildTargetUrl(opts);
+    if (opts.dryRun) {
+        return { url, project, version, packageRoot, dryRun: true };
+    }
+    if (opts.fabricToken && !(opts.fabricUser && opts.fabricPassword)) {
+        throw new Error("Bearer token auth (--fabric-token) is not yet supported — " +
+            "Harper's deploy_component CLI path only accepts Basic auth today. " +
+            "Pass --fabric-user + --fabric-password instead.");
+    }
+    const harperBin = resolveHarperBin(packageRoot);
+    const args = [
+        "deploy",
+        `target=${url}`,
+        `project=${project}`,
+        `restart=${opts.restart !== false}`,
+        `replicated=${opts.replicated !== false}`,
+    ];
+    // Credentials go via env, not argv, so they don't appear in `ps` output
+    // for the lifetime of the Harper child process. Harper's cliOperations
+    // reads CLI_TARGET_USERNAME / CLI_TARGET_PASSWORD as env fallbacks.
+    const childEnv = {
+        ...process.env,
+        CLI_TARGET_USERNAME: opts.fabricUser,
+        CLI_TARGET_PASSWORD: opts.fabricPassword,
+    };
+    await spawnHarper(harperBin, args, packageRoot, childEnv);
+    return { url, project, version, packageRoot, dryRun: false };
+}

package/dist/resources/ObservationCenter.js

@@ -0,0 +1,19 @@
+import { Resource } from "@harperfast/harper";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+const HERE = dirname(fileURLToPath(import.meta.url));
+const HTML_PATH = resolve(HERE, "..", "..", "ui", "observation-center.html");
+const HTML = readFileSync(HTML_PATH, "utf8");
+/**
+ * GET /ObservationCenter — serves the read-only dashboard shell.
+ * The HTML handles its own Basic-auth prompt and polls authenticated JSON endpoints.
+ */
+export class ObservationCenter extends Resource {
+    async get() {
+        return new Response(HTML, {
+            status: 200,
+            headers: { "content-type": "text/html; charset=utf-8" },
+        });
+    }
+}

package/dist/resources/health.js

@@ -1,5 +1,21 @@
 import { Resource, databases } from "@harperfast/harper";
+import { promises as fsp } from "node:fs";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
 const db = databases;
+const redactHome = (p) => {
+    const home = homedir();
+    return p.startsWith(home) ? "~" + p.slice(home.length) : p;
+};
+const exists = async (path) => {
+    try {
+        await fsp.stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
 /**
  * Health endpoint — unauthenticated, returns only { ok: true }.
  *
@@ -15,26 +31,87 @@ export class Health extends Resource {
 /**
  * Authenticated health detail — returns memory/agent/soul stats + process info.
  * Requires Ed25519 agent auth or admin basic auth.
+ *
+ * Every optional-subsystem lookup is wrapped so a missing table or absent
+ * schema downgrades to "not configured" rather than failing the whole call.
  */
 export class HealthDetail extends Resource {
     async get() {
         const stats = { ok: true };
+        const nowMs = Date.now();
+        const warnings = [];
+        const ctx = this.getContext?.();
+        const request = ctx?.request ?? ctx;
+        const callerAgent = request?.tpsAgent;
+        const isAdmin = request?.tpsAgentIsAdmin === true || !callerAgent;
+        stats.caller = { agentId: callerAgent ?? null, isAdmin };
+        let memoriesList = [];
         // ── Memory stats ──
         try {
-            const list = [];
             for await (const m of db.flair.Memory.search({})) {
-                list.push(m);
+                memoriesList.push(m);
+            }
+            // Per-model counts: "hash-512d" is the hash-fallback marker; any other
+            // value (or missing value) is a real embedding. Multiple distinct
+            // non-hash models means mixed vector spaces — cross-space searches
+            // return garbage unless reconciled via `flair reembed`.
+            const modelCounts = {};
+            for (const m of memoriesList) {
+                const model = m.embeddingModel || "hash-512d";
+                modelCounts[model] = (modelCounts[model] ?? 0) + 1;
+            }
+            const hashFallback = modelCounts["hash-512d"] ?? 0;
+            const withEmbeddings = memoriesList.length - hashFallback;
+            const realModels = Object.keys(modelCounts).filter((k) => k !== "hash-512d");
+            const byDurability = { permanent: 0, persistent: 0, standard: 0, ephemeral: 0 };
+            let archived = 0;
+            let expired = 0;
+            for (const m of memoriesList) {
+                const d = (m.durability ?? "standard");
+                if (d in byDurability)
+                    byDurability[d]++;
+                if (m.archived)
+                    archived++;
+                if (!m.archived && m.validTo && new Date(m.validTo).getTime() < nowMs)
+                    expired++;
             }
             stats.memories = {
-                total: list.length,
-                withEmbeddings: list.filter((m) => m.embeddingModel && m.embeddingModel !== "hash-512d").length,
-                hashFallback: list.filter((m) => !m.embeddingModel || m.embeddingModel === "hash-512d").length,
+                total: memoriesList.length,
+                withEmbeddings,
+                hashFallback,
+                modelCounts,
+                byDurability,
+                archived,
+                expired,
             };
-            if (list.length > 0) {
-                const sorted = list.filter((m) => m.createdAt).sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+            if (memoriesList.length > 0) {
+                const sorted = memoriesList
+                    .filter((m) => m.createdAt)
+                    .sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
                 if (sorted[0])
                     stats.lastWrite = sorted[0].createdAt;
             }
+            if (expired > 0)
+                warnings.push({ level: "warn", message: `${expired} memories have expired validTo but aren't archived` });
+            // Hash-fallback coverage — tiered by percentage. Thresholds are
+            // first-pass defaults; Kern's review on ops-n4n may tune them.
+            if (memoriesList.length > 0) {
+                const pct = Math.round((hashFallback / memoriesList.length) * 100);
+                if (pct >= 10) {
+                    warnings.push({
+                        level: "warn",
+                        message: `${hashFallback}/${memoriesList.length} (${pct}%) memories are hash-fallback — run: flair reembed --stale-only --dry-run`,
+                    });
+                }
+            }
+            // Mixed embedding models — searches across vector spaces return garbage.
+            if (realModels.length > 1) {
+                const list = realModels.map((k) => `${k}:${modelCounts[k]}`).join(", ");
+                warnings.push({
+                    level: "warn",
+                    message: `multiple embedding models in use (${list}) — cross-model search unreliable; run: flair reembed against one model`,
+                });
+            }
         }
         catch {
             stats.memories = null;
@@ -42,28 +119,380 @@ export class HealthDetail extends Resource {
         // ── Agent stats ──
         try {
             const agents = [];
-            for await (const a of db.flair.Agent.search({})) {
+            for await (const a of db.flair.Agent.search({}))
                 agents.push(a);
+            const blank = (id) => ({
+                id, memoryCount: 0, hashFallback: 0, writes24h: 0, lastWriteAt: null,
+            });
+            const perAgentMap = new Map();
+            for (const a of agents) {
+                if (a.id)
+                    perAgentMap.set(a.id, blank(a.id));
+            }
+            const cutoff24h = nowMs - 24 * 3600 * 1000;
+            for (const m of memoriesList) {
+                if (!m.agentId)
+                    continue;
+                const row = perAgentMap.get(m.agentId) ?? blank(m.agentId);
+                row.memoryCount++;
+                if (!m.embeddingModel || m.embeddingModel === "hash-512d")
+                    row.hashFallback++;
+                if (m.createdAt) {
+                    const ts = new Date(m.createdAt).getTime();
+                    if (ts >= cutoff24h)
+                        row.writes24h++;
+                    if (!row.lastWriteAt || ts > new Date(row.lastWriteAt).getTime()) {
+                        row.lastWriteAt = m.createdAt;
+                    }
+                }
+                perAgentMap.set(m.agentId, row);
             }
+            const perAgentFull = Array.from(perAgentMap.values()).sort((a, b) => b.memoryCount - a.memoryCount);
+            const perAgent = isAdmin
+                ? perAgentFull
+                : perAgentFull.filter((r) => r.id === callerAgent);
             stats.agents = {
                 count: agents.length,
-                names: agents.map((a) => a.id).filter(Boolean),
+                names: isAdmin ? agents.map((a) => a.id).filter(Boolean) : undefined,
+                perAgent,
             };
         }
         catch {
             stats.agents = null;
         }
-        // ── Soul stats ──
+        // ── Relationships ──
         try {
-            let count = 0;
-            for await (const _ of db.flair.Soul.search({})) {
-                count++;
+            const rels = [];
+            for await (const r of db.flair.Relationship.search({}))
+                rels.push(r);
+            if (rels.length === 0) {
+                stats.relationships = null;
+            }
+            else {
+                const active = rels.filter((r) => !r.validTo || new Date(r.validTo).getTime() > nowMs).length;
+                stats.relationships = { total: rels.length, active };
             }
-            stats.soulEntries = count;
+        }
+        catch {
+            stats.relationships = null;
+        }
+        // ── Soul ──
+        try {
+            const souls = [];
+            for await (const s of db.flair.Soul.search({}))
+                souls.push(s);
+            stats.soulEntries = souls.length;
+            const byPriority = { critical: 0, high: 0, standard: 0, low: 0 };
+            for (const s of souls) {
+                const p = (s.priority ?? "standard");
+                if (p in byPriority)
+                    byPriority[p]++;
+            }
+            stats.soul = { total: souls.length, byPriority };
         }
         catch {
             stats.soulEntries = null;
+            stats.soul = null;
+        }
+        // ── Federation ──
+        try {
+            const instances = [];
+            try {
+                for await (const i of db.flair.Instance.search({}))
+                    instances.push(i);
+            }
+            catch { /* absent */ }
+            const peers = [];
+            try {
+                for await (const p of db.flair.Peer.search({}))
+                    peers.push(p);
+            }
+            catch { /* absent */ }
+            const tokens = [];
+            try {
+                for await (const t of db.flair.PairingToken.search({}))
+                    tokens.push(t);
+            }
+            catch { /* absent */ }
+            if (instances.length === 0 && peers.length === 0) {
+                stats.federation = null;
+            }
+            else {
+                const inst = instances[0];
+                const peersBlock = {
+                    total: peers.length,
+                    connected: peers.filter((p) => p.status === "connected").length,
+                    disconnected: peers.filter((p) => p.status === "disconnected").length,
+                    revoked: peers.filter((p) => p.status === "revoked").length,
+                };
+                const pendingTokens = tokens.filter((t) => !t.consumedBy && t.expiresAt && new Date(t.expiresAt).getTime() > nowMs).length;
+                stats.federation = {
+                    instance: inst ? { id: inst.id, role: inst.role, status: inst.status } : null,
+                    peers: peersBlock,
+                    pendingTokens,
+                    peerList: isAdmin
+                        ? peers.map((p) => ({
+                            id: p.id,
+                            role: p.role,
+                            status: p.status,
+                            lastSyncAt: p.lastSyncAt ?? null,
+                        }))
+                        : undefined,
+                };
+                if (peers.length > 0 && peersBlock.connected === 0) {
+                    const oldest = peers
+                        .map((p) => (p.lastSyncAt ? new Date(p.lastSyncAt).getTime() : 0))
+                        .reduce((a, b) => (a === 0 ? b : b === 0 ? a : Math.min(a, b)), 0);
+                    if (oldest > 0 && nowMs - oldest > 24 * 3600 * 1000) {
+                        warnings.push({ level: "warn", message: "federation peers all disconnected >24h" });
+                    }
+                }
+                if (pendingTokens > 0) {
+                    warnings.push({ level: "info", message: `${pendingTokens} pairing token(s) unconsumed` });
+                }
+            }
+        }
+        catch {
+            stats.federation = null;
+        }
+        // ── OAuth / IdP ──
+        try {
+            const clients = [];
+            try {
+                for await (const c of db.flair.OAuthClient.search({}))
+                    clients.push(c);
+            }
+            catch { /* absent */ }
+            const idps = [];
+            try {
+                for await (const i of db.flair.IdpConfig.search({}))
+                    idps.push(i);
+            }
+            catch { /* absent */ }
+            let activeTokens = 0;
+            let tokensAvailable = true;
+            try {
+                const toks = [];
+                for await (const t of db.flair.OAuthToken.search({}))
+                    toks.push(t);
+                activeTokens = toks.filter((t) => {
+                    if (t.revokedAt)
+                        return false;
+                    if (t.expiresAt && new Date(t.expiresAt).getTime() < nowMs)
+                        return false;
+                    return true;
+                }).length;
+            }
+            catch {
+                tokensAvailable = false;
+            }
+            if (clients.length === 0 && idps.length === 0) {
+                stats.oauth = null;
+            }
+            else {
+                stats.oauth = {
+                    clients: clients.length,
+                    idpConfigs: idps.length,
+                    activeTokens: tokensAvailable ? activeTokens : 0,
+                    clientList: isAdmin
+                        ? clients.map((c) => ({
+                            id: c.id,
+                            name: c.name,
+                            registeredBy: c.registeredBy ?? null,
+                            createdAt: c.createdAt ?? null,
+                        }))
+                        : undefined,
+                    idpList: isAdmin
+                        ? idps.map((i) => ({ id: i.id, name: i.name, issuer: i.issuer }))
+                        : undefined,
+                };
+            }
+        }
+        catch {
+            stats.oauth = null;
+        }
+        // ── REM ──
+        try {
+            const logsDir = join(homedir(), ".flair", "logs");
+            const remLog = join(logsDir, "rem.jsonl");
+            const nightlyLog = join(logsDir, "rem-nightly.jsonl");
+            const tailJsonl = async (path, maxBytes = 256 * 1024) => {
+                let fh = null;
+                try {
+                    const st = await fsp.stat(path).catch(() => null);
+                    if (!st)
+                        return [];
+                    const start = Math.max(0, st.size - maxBytes);
+                    const len = st.size - start;
+                    if (len === 0)
+                        return [];
+                    fh = await fsp.open(path, "r");
+                    const buf = Buffer.alloc(len);
+                    await fh.read(buf, 0, len, start);
+                    return buf
+                        .toString("utf-8")
+                        .split("\n")
+                        .filter((l) => l.trim())
+                        .map((l) => { try {
+                        return JSON.parse(l);
+                    }
+                    catch {
+                        return null;
+                    } })
+                        .filter(Boolean);
+                }
+                catch {
+                    return [];
+                }
+                finally {
+                    if (fh)
+                        await fh.close().catch(() => { });
+                }
+            };
+            const remRecords = await tailJsonl(remLog);
+            const findLast = (kind) => {
+                for (let i = remRecords.length - 1; i >= 0; i--) {
+                    const r = remRecords[i];
+                    if (r && (r.kind === kind || r.type === kind))
+                        return r.at ?? r.ts ?? r.timestamp ?? null;
+                }
+                return null;
+            };
+            const lastLightAt = findLast("light");
+            const lastRapidAt = findLast("rapid");
+            const lastRestorativeAt = findLast("restorative");
+            let nightlyEnabled = null;
+            const plat = platform();
+            if (plat === "darwin") {
+                nightlyEnabled = await exists(join(homedir(), "Library", "LaunchAgents", "dev.flair.rem.nightly.plist"));
+            }
+            else if (plat === "linux") {
+                nightlyEnabled = await exists(join(homedir(), ".config", "systemd", "user", "flair-rem-nightly.timer"));
+            }
+            const nightlyRecords = await tailJsonl(nightlyLog);
+            const lastNightlyRec = nightlyRecords[nightlyRecords.length - 1];
+            const lastNightlyAt = lastNightlyRec ? (lastNightlyRec.at ?? lastNightlyRec.ts ?? lastNightlyRec.timestamp ?? null) : null;
+            let pendingCandidates = null;
+            try {
+                let count = 0;
+                for await (const c of db.flair.MemoryCandidate.search({})) {
+                    if (c.status === "pending")
+                        count++;
+                }
+                pendingCandidates = count;
+            }
+            catch {
+                pendingCandidates = null;
+            }
+            const allNull = !lastLightAt &&
+                !lastRapidAt &&
+                !lastRestorativeAt &&
+                nightlyEnabled === null &&
+                !lastNightlyAt &&
+                pendingCandidates === null;
+            if (allNull) {
+                stats.rem = null;
+            }
+            else {
+                stats.rem = {
+                    lastLightAt,
+                    lastRapidAt,
+                    lastRestorativeAt,
+                    nightlyEnabled,
+                    lastNightlyAt,
+                    pendingCandidates,
+                };
+                if (nightlyEnabled && lastNightlyAt && nowMs - new Date(lastNightlyAt).getTime() > 48 * 3600 * 1000) {
+                    warnings.push({ level: "warn", message: "nightly REM hasn't run in >48h" });
+                }
+            }
+        }
+        catch {
+            stats.rem = null;
+        }
+        // ── Disk ──
+        try {
+            const dataDir = process.env.HDB_ROOT ?? join(homedir(), ".flair", "data");
+            const snapshotDir = join(homedir(), ".flair", "snapshots");
+            const dirSize = async (root, maxDepth = 6) => {
+                if (!(await exists(root)))
+                    return null;
+                let total = 0;
+                const walk = async (p, depth) => {
+                    if (depth > maxDepth)
+                        return;
+                    let entries;
+                    try {
+                        entries = await fsp.readdir(p, { withFileTypes: true });
+                    }
+                    catch {
+                        return;
+                    }
+                    const subdirs = [];
+                    const files = [];
+                    for (const e of entries) {
+                        const full = join(p, e.name);
+                        if (e.isDirectory())
+                            subdirs.push(full);
+                        else if (e.isFile())
+                            files.push(full);
+                    }
+                    const sizes = await Promise.all(files.map((f) => fsp.stat(f).then((s) => s.size).catch(() => 0)));
+                    total += sizes.reduce((a, b) => a + b, 0);
+                    await Promise.all(subdirs.map((d) => walk(d, depth + 1)));
+                };
+                await walk(root, 0);
+                return total;
+            };
+            const [dataBytes, snapshotBytes] = await Promise.all([dirSize(dataDir), dirSize(snapshotDir)]);
+            if (dataBytes === null && snapshotBytes === null) {
+                stats.disk = null;
+            }
+            else {
+                stats.disk = {
+                    dataDir: isAdmin ? dataDir : redactHome(dataDir),
+                    dataBytes: dataBytes ?? 0,
+                    snapshotDir: isAdmin ? snapshotDir : redactHome(snapshotDir),
+                    snapshotBytes: snapshotBytes ?? 0,
+                };
+            }
+        }
+        catch {
+            stats.disk = null;
+        }
+        // ── Bridges ──
+        try {
+            const cwd = process.cwd();
+            const candidates = [join(cwd, "node_modules"), join(homedir(), ".flair", "node_modules")];
+            const installed = new Set();
+            await Promise.all(candidates.map(async (base) => {
+                if (!(await exists(base)))
+                    return;
+                try {
+                    const names = await fsp.readdir(base);
+                    for (const name of names) {
+                        if (name.startsWith("flair-bridge-"))
+                            installed.add(name);
+                    }
+                }
+                catch { /* skip */ }
+            }));
+            if (installed.size === 0) {
+                stats.bridges = null;
+            }
+            else {
+                stats.bridges = {
+                    installed: Array.from(installed).sort(),
+                    lastImport: null,
+                    lastExport: null,
+                };
+            }
+        }
+        catch {
+            stats.bridges = null;
         }
+        // ── Warnings ──
+        stats.warnings = warnings;
         // ── Process info ──
         stats.pid = process.pid;
         stats.uptimeSeconds = Math.floor(process.uptime());