@tpsdev-ai/flair 0.8.2 → 0.9.0

package/dist/rem/runner.js

@@ -0,0 +1,221 @@
+/**
+ * REM nightly runner — orchestrates the cycle.
+ *
+ * Per FLAIR-NIGHTLY-REM § 4, in order:
+ *   1. Pre-flight: check pause sentinel / FLAIR_REM_PAUSE env. Exit clean if paused.
+ *   2. Snapshot agent state (memory + soul) to ~/.flair/snapshots/<agent>/.
+ *   3. Maintenance — delegate to /MemoryMaintenance (same code path `flair rem light` uses).
+ *   4. (slice-2 next) trust-tier filter on input memories.
+ *   5. (slice-2 next) distillation — call /ReflectMemories, persist candidates.
+ *   6. Append a row to ~/.flair/logs/rem-nightly.jsonl.
+ *
+ * Status today:
+ *   - Steps 1, 2, 6 shipped in slice-1 PR-1 (#414).
+ *   - Step 3 (maintenance) ships in this PR — fills `archived`/`expired` in
+ *     the audit row.
+ *   - Steps 4, 5 are slice-2 follow-ups; require an in-process distillation
+ *     LLM path (today `/ReflectMemories` returns a prompt for human/agent
+ *     consumption, not server-side candidate generation).
+ *
+ * The audit row's `slice` field tells readers which steps populated which
+ * counts: `slice: "1"` rows have `archived`/`expired` undefined; `slice:
+ * "2-maintenance"` rows populate them; future slice-2 rows will populate
+ * `consolidated` and `candidates`.
+ *
+ * Pure dependency injection so the runner is unit-testable without Harper.
+ * The CLI wires the real `apiCall` + `pkgVersion`; tests pass stubs.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { homedir } from "node:os";
+import { createSnapshot } from "./snapshot.js";
+export const REM_PAUSE_FLAG = resolve(homedir(), ".flair", "rem.paused");
+export const REM_NIGHTLY_LOG = resolve(homedir(), ".flair", "logs", "rem-nightly.jsonl");
+function readPauseSentinel(path) {
+    try {
+        const contents = readFileSync(path, "utf-8");
+        // Existence alone is enough; the body is just a touch-timestamp.
+        return contents.length >= 0;
+    }
+    catch {
+        return false;
+    }
+}
+function appendLogRow(logPath, row) {
+    const dir = dirname(logPath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    appendFileSync(logPath, JSON.stringify(row) + "\n", { mode: 0o600 });
+}
+/**
+ * Coerces a Harper REST list response into a flat array. The /Memory and
+ * /Soul resources can return either an array directly or a paginated shape
+ * `{ results: [], items: [] }` depending on path/options.
+ */
+function asArray(raw) {
+    if (Array.isArray(raw))
+        return raw;
+    if (raw && typeof raw === "object") {
+        const obj = raw;
+        if (Array.isArray(obj.results))
+            return obj.results;
+        if (Array.isArray(obj.items))
+            return obj.items;
+    }
+    return [];
+}
+/**
+ * Counts pending memory candidates for the agent.
+ *
+ * Falls back to a `search_by_conditions` POST that mirrors the pattern
+ * `flair rem candidates` uses. Returns 0 on any error — the runner should
+ * not fail the cycle just because the candidate count couldn't be sampled.
+ */
+async function fetchPendingCandidateCount(api, agentId) {
+    try {
+        const result = await api("POST", "/MemoryCandidate/search_by_conditions", {
+            operator: "and",
+            conditions: [
+                { search_attribute: "agentId", search_type: "equals", search_value: agentId },
+                { search_attribute: "status", search_type: "equals", search_value: "pending" },
+            ],
+            get_attributes: ["id"],
+        });
+        const rows = asArray(result);
+        return rows.length;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Runs one nightly cycle for the given agent. See module header for steps.
+ * Pure orchestration; all I/O goes through injected dependencies.
+ */
+export async function runNightlyCycle(opts) {
+    const startedAt = opts.nowOverride ?? new Date();
+    const startedMs = startedAt.getTime();
+    const logPath = opts.logPath ?? REM_NIGHTLY_LOG;
+    const pauseFlagPath = opts.pauseFlagPath ?? REM_PAUSE_FLAG;
+    const envPaused = opts.envPaused ?? process.env.FLAIR_REM_PAUSE === "1";
+    const baseRow = {
+        agentId: opts.agentId,
+        runAt: startedAt.toISOString(),
+        slice: "1",
+        errors: [],
+    };
+    // Step 1: pre-flight (pause)
+    if (envPaused || (existsSync(pauseFlagPath) && readPauseSentinel(pauseFlagPath))) {
+        const row = {
+            ...baseRow,
+            status: "paused",
+            durationMs: Date.now() - startedMs,
+            errors: [],
+        };
+        appendLogRow(logPath, row);
+        return { status: "paused", logRow: row };
+    }
+    const errors = [];
+    // Step 2: snapshot
+    let snapshotPath;
+    let memoryCount = 0;
+    let soulCount = 0;
+    let pendingCandidates = 0;
+    try {
+        // Fetch agent data
+        const memoriesRaw = await opts.apiCall("GET", `/Memory?agentId=${encodeURIComponent(opts.agentId)}`);
+        const memories = asArray(memoriesRaw);
+        memoryCount = memories.length;
+        const soulRaw = await opts.apiCall("GET", `/Soul?agentId=${encodeURIComponent(opts.agentId)}`);
+        const souls = asArray(soulRaw);
+        soulCount = souls.length;
+        // For the snapshot's soul.json: keep the full multi-row shape if there
+        // are multiple souls (different keys), or unwrap a single-row response.
+        const soulForSnapshot = souls.length === 1 ? souls[0] : souls.length > 1 ? souls : null;
+        pendingCandidates = await fetchPendingCandidateCount(opts.apiCall, opts.agentId);
+        if (!opts.dryRun) {
+            const created = await createSnapshot({
+                agentId: opts.agentId,
+                flairVersion: opts.flairVersion,
+                memories,
+                soul: soulForSnapshot,
+                pendingCandidateCount: pendingCandidates,
+                rootOverride: opts.snapshotRoot,
+                nowOverride: opts.nowOverride,
+            });
+            snapshotPath = created.path;
+        }
+    }
+    catch (err) {
+        errors.push(`snapshot: ${err?.message ?? String(err)}`);
+        const row = {
+            ...baseRow,
+            status: "failed",
+            memoryCount,
+            soulCount,
+            pendingCandidates,
+            durationMs: Date.now() - startedMs,
+            errors,
+        };
+        appendLogRow(logPath, row);
+        return { status: "failed", logRow: row };
+    }
+    // Step 3: maintenance — soft-delete expired + soft-archive stale.
+    // Delegates to /MemoryMaintenance (same endpoint `flair rem light` uses).
+    // In dry-run mode the snapshot wasn't written, but we still want to know
+    // what maintenance WOULD do — POST with dryRun=true so the response counts
+    // are accurate without mutating state.
+    let archived = 0;
+    let expired = 0;
+    let sliceLabel = "2-maintenance";
+    try {
+        const maintRaw = await opts.apiCall("POST", "/MemoryMaintenance", {
+            agentId: opts.agentId,
+            dryRun: opts.dryRun ?? false,
+        });
+        if (maintRaw && typeof maintRaw === "object") {
+            const obj = maintRaw;
+            if (obj.error) {
+                // /MemoryMaintenance returned { error: "..." } — treat as failure.
+                throw new Error(String(obj.error));
+            }
+            expired = typeof obj.expired === "number" ? obj.expired : 0;
+            archived = typeof obj.archived === "number" ? obj.archived : 0;
+        }
+    }
+    catch (err) {
+        errors.push(`maintenance: ${err?.message ?? String(err)}`);
+        const row = {
+            ...baseRow,
+            slice: sliceLabel,
+            status: "failed",
+            snapshotPath,
+            memoryCount,
+            soulCount,
+            pendingCandidates,
+            durationMs: Date.now() - startedMs,
+            errors,
+        };
+        appendLogRow(logPath, row);
+        return { status: "failed", logRow: row, snapshotPath };
+    }
+    // Step 6: log
+    const row = {
+        ...baseRow,
+        slice: sliceLabel,
+        status: opts.dryRun ? "dry-run" : "completed",
+        dryRun: opts.dryRun || undefined,
+        snapshotPath,
+        memoryCount,
+        soulCount,
+        pendingCandidates,
+        archived,
+        expired,
+        durationMs: Date.now() - startedMs,
+        errors,
+        // `consolidated` and `candidates` populate when slice-2 PR-4 (distillation)
+        // lands; today they remain undefined so the row is honest about what ran.
+    };
+    appendLogRow(logPath, row);
+    return { status: row.status, logRow: row, snapshotPath };
+}

package/dist/rem/scheduler.js

@@ -0,0 +1,240 @@
+/**
+ * REM nightly scheduler — platform-native scheduler install/uninstall.
+ *
+ * Per FLAIR-NIGHTLY-REM § 3 (`flair rem nightly enable|disable`). Renders
+ * launchd plist (macOS) or systemd timer+service (Linux) from templates,
+ * deploys a shim script to `~/.flair/bin/flair-rem-nightly`, and loads the
+ * job into the user-session scheduler.
+ *
+ * Templates use `{{KEY}}` placeholders — single-pass substitution. The full
+ * placeholder set is enumerated in `interface SchedulerSubstitutions` so
+ * adding a new key requires touching both this module and the template.
+ *
+ * No daemon code lives here — the scheduler invokes the shim, the shim
+ * invokes `flair rem nightly run-once`, the runner module does the work.
+ */
+import { existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync, rmSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { homedir, platform } from "node:os";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+export const SHIM_PATH_DEFAULT = resolve(homedir(), ".flair", "bin", "flair-rem-nightly");
+export const LAUNCHD_PLIST_PATH = resolve(homedir(), "Library", "LaunchAgents", "dev.flair.rem.nightly.plist");
+export const SYSTEMD_USER_DIR = resolve(homedir(), ".config", "systemd", "user");
+export const SYSTEMD_TIMER_PATH = resolve(SYSTEMD_USER_DIR, "flair-rem-nightly.timer");
+export const SYSTEMD_SERVICE_PATH = resolve(SYSTEMD_USER_DIR, "flair-rem-nightly.service");
+function detectPlatform(override) {
+    if (override)
+        return override;
+    const p = platform();
+    if (p === "darwin")
+        return "darwin";
+    if (p === "linux")
+        return "linux";
+    throw new Error(`unsupported platform for REM nightly scheduler: ${p} (only darwin and linux)`);
+}
+function defaultTemplateRoot() {
+    // Templates live alongside dist/ in the published package and alongside
+    // src/rem/ in the source tree. Walk up from this file until we find
+    // a directory containing templates/.
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        resolve(here, "..", "..", "templates"),
+        resolve(here, "..", "..", "..", "templates"),
+        resolve(here, "..", "templates"),
+    ];
+    for (const c of candidates) {
+        if (existsSync(c))
+            return c;
+    }
+    throw new Error(`unable to locate templates directory (looked in: ${candidates.join(", ")})`);
+}
+export function renderTemplate(text, subs) {
+    return text.replace(/\{\{([A-Z_]+)\}\}/g, (_, key) => {
+        const value = subs[key];
+        if (value === undefined)
+            throw new Error(`unknown template placeholder: ${key}`);
+        return String(value);
+    });
+}
+export function readTemplate(rootDir, relativePath) {
+    const full = resolve(rootDir, relativePath);
+    if (!existsSync(full)) {
+        throw new Error(`template not found: ${full}`);
+    }
+    return readFileSync(full, "utf-8");
+}
+/**
+ * Validates the hour:minute schedule. Throws on invalid input rather than
+ * silently coercing — surface bad input at the install boundary.
+ */
+function validateSchedule(hour, minute) {
+    if (!Number.isInteger(hour) || hour < 0 || hour > 23) {
+        throw new Error(`hour must be an integer 0-23, got ${hour}`);
+    }
+    if (!Number.isInteger(minute) || minute < 0 || minute > 59) {
+        throw new Error(`minute must be an integer 0-59, got ${minute}`);
+    }
+}
+function buildSubstitutions(opts, shimPath, flairBin) {
+    validateSchedule(opts.hour, opts.minute);
+    if (!/^[a-zA-Z0-9_-]+$/.test(opts.agentId)) {
+        throw new Error(`invalid agent id: ${opts.agentId}`);
+    }
+    return {
+        FLAIR_BIN: flairBin,
+        SHIM_PATH: shimPath,
+        HOME: homedir(),
+        AGENT_ID: opts.agentId,
+        FLAIR_URL: opts.flairUrl,
+        HOUR: String(opts.hour),
+        HOUR_PAD: String(opts.hour).padStart(2, "0"),
+        MINUTE: String(opts.minute),
+        MINUTE_PAD: String(opts.minute).padStart(2, "0"),
+    };
+}
+function writeFileWithDir(path, contents, mode = 0o600) {
+    const dir = dirname(path);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeFileSync(path, contents, { mode });
+}
+// 30s ceiling on launchctl/systemctl invocations so a hung service manager
+// can't block the CLI indefinitely. Sherlock #415 follow-up.
+const SPAWN_TIMEOUT_MS = 30_000;
+function spawnReport(cmd) {
+    const r = spawnSync(cmd[0], cmd.slice(1), {
+        encoding: "buffer",
+        timeout: SPAWN_TIMEOUT_MS,
+    });
+    return {
+        code: r.status,
+        stdout: r.stdout?.toString("utf-8") ?? "",
+        stderr: r.stderr?.toString("utf-8") ?? "",
+    };
+}
+/**
+ * Installs the platform-native scheduler entry and the shim script.
+ *
+ * macOS: writes ~/Library/LaunchAgents/dev.flair.rem.nightly.plist + bootstraps it via launchctl.
+ * Linux: writes ~/.config/systemd/user/flair-rem-nightly.{timer,service} + enables the timer.
+ *
+ * In both cases, also deploys ~/.flair/bin/flair-rem-nightly as the shim
+ * the scheduler invokes.
+ */
+export function enableScheduler(opts) {
+    const plat = detectPlatform(opts.platformOverride);
+    const flairBin = opts.flairBin ?? process.argv[1] ?? "flair";
+    const shimPath = opts.shimPathOverride ?? SHIM_PATH_DEFAULT;
+    const templateRoot = opts.templateRootOverride ?? defaultTemplateRoot();
+    const subs = buildSubstitutions(opts, shimPath, flairBin);
+    // 1. Deploy the shim (always — both platforms invoke it).
+    const shimContents = renderTemplate(readTemplate(templateRoot, "bin/flair-rem-nightly.sh.tmpl"), subs);
+    writeFileWithDir(shimPath, shimContents, 0o700);
+    chmodSync(shimPath, 0o700);
+    // 2. Write the scheduler entry.
+    if (plat === "darwin") {
+        const plistPath = opts.launchdPlistOverride ?? LAUNCHD_PLIST_PATH;
+        const plistContents = renderTemplate(readTemplate(templateRoot, "launchd/dev.flair.rem.nightly.plist.tmpl"), subs);
+        writeFileWithDir(plistPath, plistContents, 0o600);
+        const loadCommand = ["launchctl", "bootstrap", `gui/${process.getuid?.() ?? ""}`, plistPath];
+        let loadResult;
+        if (!opts.skipLoad) {
+            // Bootout first in case a prior install left the job loaded.
+            spawnReport(["launchctl", "bootout", `gui/${process.getuid?.() ?? ""}`, plistPath]);
+            loadResult = spawnReport(loadCommand);
+        }
+        return { platform: plat, shimPath, schedulerPath: plistPath, loadCommand, loadResult };
+    }
+    // Linux: systemd user units.
+    const timerPath = opts.systemdTimerOverride ?? SYSTEMD_TIMER_PATH;
+    const servicePath = opts.systemdServiceOverride ?? SYSTEMD_SERVICE_PATH;
+    const serviceContents = renderTemplate(readTemplate(templateRoot, "systemd/flair-rem-nightly.service.tmpl"), subs);
+    const timerContents = renderTemplate(readTemplate(templateRoot, "systemd/flair-rem-nightly.timer.tmpl"), subs);
+    writeFileWithDir(servicePath, serviceContents, 0o600);
+    writeFileWithDir(timerPath, timerContents, 0o600);
+    const loadCommand = ["systemctl", "--user", "enable", "--now", "flair-rem-nightly.timer"];
+    let loadResult;
+    if (!opts.skipLoad) {
+        spawnReport(["systemctl", "--user", "daemon-reload"]);
+        loadResult = spawnReport(loadCommand);
+    }
+    return { platform: plat, shimPath, schedulerPath: timerPath, loadCommand, loadResult };
+}
+/**
+ * Removes the scheduler entry. Audit log + snapshots are preserved.
+ */
+export function disableScheduler(opts = {}) {
+    const plat = detectPlatform(opts.platformOverride);
+    const removed = [];
+    if (plat === "darwin") {
+        const plistPath = opts.launchdPlistOverride ?? LAUNCHD_PLIST_PATH;
+        const unloadCommand = ["launchctl", "bootout", `gui/${process.getuid?.() ?? ""}`, plistPath];
+        let unloadResult;
+        if (existsSync(plistPath)) {
+            if (!opts.skipUnload) {
+                unloadResult = spawnReport(unloadCommand);
+            }
+            rmSync(plistPath, { force: true });
+            removed.push(plistPath);
+        }
+        if (opts.removeShim) {
+            const shim = opts.shimPathOverride ?? SHIM_PATH_DEFAULT;
+            if (existsSync(shim)) {
+                rmSync(shim, { force: true });
+                removed.push(shim);
+            }
+        }
+        return { platform: plat, removed, unloadCommand, unloadResult };
+    }
+    const timerPath = opts.systemdTimerOverride ?? SYSTEMD_TIMER_PATH;
+    const servicePath = opts.systemdServiceOverride ?? SYSTEMD_SERVICE_PATH;
+    const unloadCommand = ["systemctl", "--user", "disable", "--now", "flair-rem-nightly.timer"];
+    let unloadResult;
+    if (existsSync(timerPath) || existsSync(servicePath)) {
+        if (!opts.skipUnload) {
+            unloadResult = spawnReport(unloadCommand);
+            spawnReport(["systemctl", "--user", "daemon-reload"]);
+        }
+        if (existsSync(timerPath)) {
+            rmSync(timerPath, { force: true });
+            removed.push(timerPath);
+        }
+        if (existsSync(servicePath)) {
+            rmSync(servicePath, { force: true });
+            removed.push(servicePath);
+        }
+    }
+    if (opts.removeShim) {
+        const shim = opts.shimPathOverride ?? SHIM_PATH_DEFAULT;
+        if (existsSync(shim)) {
+            rmSync(shim, { force: true });
+            removed.push(shim);
+        }
+    }
+    return { platform: plat, removed, unloadCommand, unloadResult };
+}
+/**
+ * Reports whether the scheduler is installed. Filesystem-only — does not
+ * shell out to launchctl/systemctl to query active state. The Health
+ * endpoint already does that via existence checks; same approach here.
+ */
+export function schedulerStatus(opts = {}) {
+    const plat = detectPlatform(opts.platformOverride);
+    if (plat === "darwin") {
+        return {
+            platform: plat,
+            installed: existsSync(LAUNCHD_PLIST_PATH),
+            schedulerPath: LAUNCHD_PLIST_PATH,
+            shimPath: SHIM_PATH_DEFAULT,
+            shimExists: existsSync(SHIM_PATH_DEFAULT),
+        };
+    }
+    return {
+        platform: plat,
+        installed: existsSync(SYSTEMD_TIMER_PATH) && existsSync(SYSTEMD_SERVICE_PATH),
+        schedulerPath: SYSTEMD_TIMER_PATH,
+        shimPath: SHIM_PATH_DEFAULT,
+        shimExists: existsSync(SHIM_PATH_DEFAULT),
+    };
+}

package/dist/rem/snapshot.js

@@ -0,0 +1,139 @@
+/**
+ * REM snapshot module — pre-cycle snapshot + listing + restore extraction.
+ *
+ * Per FLAIR-NIGHTLY-REM § 4 step 2 and § 9. Produces tar.gz archives at
+ * ~/.flair/snapshots/<agentId>/<ISO-timestamp>.tar.gz containing:
+ *   - memories.jsonl  — one Memory row per line
+ *   - soul.json       — Soul row (or null)
+ *   - metadata.json   — agent id, run id, flair version, counts
+ *
+ * Mirrors the `flair session snapshot` pattern (tar.gz, 600 perms, agent-
+ * rooted under ~/.flair/snapshots/). Pure filesystem — the caller fetches
+ * the data via the Harper HTTP API and passes it in.
+ *
+ * Used by:
+ *   - `flair rem snapshot list`
+ *   - `flair rem restore <date>`
+ *   - The nightly runner (slice-1 follow-on)
+ */
+import { mkdirSync, writeFileSync, statSync, chmodSync, rmSync, existsSync, readdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+import { create as tarCreate, extract as tarExtract, list as tarList } from "tar";
+export const SNAPSHOT_ROOT = resolve(homedir(), ".flair", "snapshots");
+/** Validates the agent id and returns its snapshot directory. */
+export function remSnapshotDir(agent) {
+    if (!/^[a-zA-Z0-9_-]+$/.test(agent)) {
+        throw new Error(`invalid agent id: ${agent}`);
+    }
+    return resolve(SNAPSHOT_ROOT, agent);
+}
+/**
+ * Creates a tar.gz snapshot at <root>/<agentId>/<ISO-timestamp>.tar.gz.
+ * Returns the path, byte size, and metadata embedded in the archive.
+ *
+ * Tarball perms: 0600 (owner-only).
+ */
+export async function createSnapshot(opts) {
+    const now = opts.nowOverride ?? new Date();
+    const isoFull = now.toISOString().replace(/[:.]/g, "-");
+    const root = opts.rootOverride ?? SNAPSHOT_ROOT;
+    if (!/^[a-zA-Z0-9_-]+$/.test(opts.agentId)) {
+        throw new Error(`invalid agent id: ${opts.agentId}`);
+    }
+    const dir = resolve(root, opts.agentId);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tarballName = `${isoFull}.tar.gz`;
+    const tarballPath = resolve(dir, tarballName);
+    const meta = {
+        agentId: opts.agentId,
+        runId: opts.runId ?? `rem-nightly-${isoFull}`,
+        flairVersion: opts.flairVersion,
+        createdAt: now.toISOString(),
+        memoryCount: opts.memories.length,
+        pendingCandidateCount: opts.pendingCandidateCount,
+        soulPresent: opts.soul !== null,
+    };
+    const tmpDir = resolve(dir, `.tmp-${process.pid}-${Date.now()}`);
+    mkdirSync(tmpDir, { recursive: true, mode: 0o700 });
+    try {
+        const memoryLines = opts.memories.map((m) => JSON.stringify(m)).join("\n");
+        writeFileSync(resolve(tmpDir, "memories.jsonl"), memoryLines + (memoryLines.length ? "\n" : ""), { mode: 0o600 });
+        writeFileSync(resolve(tmpDir, "soul.json"), JSON.stringify(opts.soul, null, 2) + "\n", { mode: 0o600 });
+        writeFileSync(resolve(tmpDir, "metadata.json"), JSON.stringify(meta, null, 2) + "\n", { mode: 0o600 });
+        await tarCreate({ gzip: true, cwd: tmpDir, file: tarballPath, portable: true }, ["memories.jsonl", "soul.json", "metadata.json"]);
+        chmodSync(tarballPath, 0o600);
+    }
+    finally {
+        rmSync(tmpDir, { recursive: true, force: true });
+    }
+    return { path: tarballPath, size: statSync(tarballPath).size, meta };
+}
+/**
+ * Lists snapshots at <root>/<agent>/*.tar.gz. Returns rows sorted by mtime
+ * descending. Pass an agent filter to restrict to a single agent.
+ */
+export function listSnapshots(agentFilter, rootOverride) {
+    const root = rootOverride ?? SNAPSHOT_ROOT;
+    if (!existsSync(root))
+        return [];
+    let agents;
+    if (agentFilter) {
+        if (!/^[a-zA-Z0-9_-]+$/.test(agentFilter)) {
+            throw new Error(`invalid agent id: ${agentFilter}`);
+        }
+        agents = [agentFilter];
+    }
+    else {
+        agents = readdirSync(root).filter((d) => {
+            try {
+                return statSync(resolve(root, d)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    const rows = [];
+    for (const a of agents) {
+        const dir = resolve(root, a);
+        if (!existsSync(dir))
+            continue;
+        for (const f of readdirSync(dir)) {
+            if (!f.endsWith(".tar.gz"))
+                continue;
+            const p = resolve(dir, f);
+            const s = statSync(p);
+            rows.push({ agent: a, file: f, path: p, size: s.size, mtime: s.mtime.toISOString() });
+        }
+    }
+    rows.sort((a, b) => b.mtime.localeCompare(a.mtime));
+    return rows;
+}
+/**
+ * Extracts a snapshot tar.gz into a target directory. Refuses to extract
+ * over an existing directory — operator must pass a clean target.
+ *
+ * In dry-run mode, returns the tarball entry list without writing anything.
+ */
+export async function extractSnapshot(opts) {
+    if (!existsSync(opts.snapshotPath)) {
+        throw new Error(`snapshot does not exist: ${opts.snapshotPath}`);
+    }
+    const entries = [];
+    await tarList({
+        file: opts.snapshotPath,
+        onReadEntry: (e) => entries.push({ path: e.path, size: e.size ?? 0 }),
+    });
+    if (opts.dryRun) {
+        return { entries };
+    }
+    const targetDir = opts.targetDir ?? `${opts.snapshotPath}.restored`;
+    if (existsSync(targetDir)) {
+        throw new Error(`target directory already exists: ${targetDir}`);
+    }
+    mkdirSync(targetDir, { recursive: true, mode: 0o700 });
+    await tarExtract({ file: opts.snapshotPath, cwd: targetDir });
+    return { targetDir, entries };
+}

package/dist/resources/A2AAdapter.js

@@ -265,6 +265,11 @@ function statusFromOrgEvent(event) {
         null);
 }
 export class A2AAdapter extends Resource {
+    // A2A discovery surface — agent cards and adapter metadata are intentionally
+    // public so other agents/clients can discover this Flair as a memory peer.
+    // Handler enforces auth on actual A2A actions (POST below).
+    allowRead() { return true; }
+    allowCreate() { return true; }
     async get() {
         const host = process.env.FLAIR_PUBLIC_URL || "http://localhost:9926";
         return new Response(JSON.stringify({

package/dist/resources/Admin.js

@@ -0,0 +1,16 @@
+import { Resource } from "@harperfast/harper";
+/**
+ * GET /Admin — friendly redirect to /AdminDashboard.
+ *
+ * Operators bookmark or type the bare /Admin path. Without this resource
+ * they hit a 404 and assume the admin UI is broken. The dashboard is the
+ * canonical landing surface; redirect there.
+ */
+export class Admin extends Resource {
+    async get() {
+        return new Response("", {
+            status: 302,
+            headers: { Location: "/AdminDashboard" },
+        });
+    }
+}