@tpsdev-ai/flair 0.51.1 → 0.52.0

package/dist/rem/runner.js

@@ -2,7 +2,9 @@
  * 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.
+ *   1. Pre-flight: check pause sentinel / FLAIR_REM_PAUSE env. Exit clean if
+ *      paused. Then GET /Health within 2s (#1515); refuse to start if it
+ *      cannot be served.
  *   2. Snapshot agent state (memory + soul) to ~/.flair/snapshots/<agent>/.
  *   3. Maintenance — delegate to /MemoryMaintenance (same code path `flair rem light` uses).
  *   4. Trust-tier filter on input memories — permanently deferred (see below).
@@ -55,6 +57,7 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { homedir } from "node:os";
+import { setImmediate as yieldToEventLoop } from "node:timers/promises";
 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");
@@ -134,6 +137,67 @@ export const DEFAULT_MAX_TAGS_PER_CYCLE = 200;
  * resources/ — see src/cli.ts) and kept in sync by value.
  */
 export const DEFAULT_MAX_AUTO_PROMOTE_PER_CYCLE = 200;
+/**
+ * Per-run distillation gather cap (#1515). Tens, not thousands — a 3k
+ * backlog drains across nights. Mirror of resources/memory-reflect-lib.ts
+ * (src/ cannot import resources/).
+ */
+export const DEFAULT_MAX_MEMORIES_PER_RUN = 50;
+/** Hard ceiling on FLAIR_REM_MAX_MEMORIES. Mirror of the resource-side cap. */
+export const ABSOLUTE_MAX_MEMORIES_PER_RUN = 200;
+/** Refuse to start if GET /Health cannot be served within this budget. */
+export const DEFAULT_HEALTH_PREFLIGHT_MS = 2000;
+/**
+ * Resolve the per-run gather cap: explicit override > FLAIR_REM_MAX_MEMORIES
+ * > DEFAULT_MAX_MEMORIES_PER_RUN, clamped to ABSOLUTE_MAX_MEMORIES_PER_RUN.
+ */
+export function resolveMaxMemoriesPerRun(override, env = process.env) {
+    let resolved = DEFAULT_MAX_MEMORIES_PER_RUN;
+    if (typeof override === "number" && Number.isFinite(override) && override > 0) {
+        resolved = Math.floor(override);
+    }
+    else {
+        const fromEnv = Number(env.FLAIR_REM_MAX_MEMORIES);
+        if (Number.isFinite(fromEnv) && fromEnv > 0)
+            resolved = Math.floor(fromEnv);
+    }
+    return Math.min(resolved, ABSOLUTE_MAX_MEMORIES_PER_RUN);
+}
+/**
+ * Self-check that /Health can be served before snapshot/distillation.
+ * Injected `healthProbe` is preferred (CLI uses fetch + AbortSignal). When
+ * omitted, races `GET /Health` through apiCall against the same budget.
+ */
+export async function runHealthPreflight(apiCall, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_HEALTH_PREFLIGHT_MS;
+    const started = Date.now();
+    if (opts.probe)
+        return opts.probe(timeoutMs);
+    let timer;
+    try {
+        await Promise.race([
+            apiCall("GET", "/Health").then((body) => {
+                if (body && typeof body === "object" && body.ok === false) {
+                    throw new Error("GET /Health returned {ok:false}");
+                }
+            }),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`GET /Health did not respond within ${timeoutMs}ms`)), timeoutMs);
+            }),
+        ]);
+        return { ok: true, elapsedMs: Date.now() - started };
+    }
+    catch (err) {
+        return { ok: false, elapsedMs: Date.now() - started, error: err?.message ?? String(err) };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+export function formatHealthRefuseMessage(result, timeoutMs = DEFAULT_HEALTH_PREFLIGHT_MS) {
+    return `GET /Health could not be served within ${timeoutMs}ms (${result.error ?? "unknown error"}). Refusing to start REM so this run cannot take the instance down. Restore /Health, or \`flair rem pause\` to keep the scheduler from retrying.`;
+}
 function readPauseSentinel(path) {
     try {
         const contents = readFileSync(path, "utf-8");
@@ -190,24 +254,54 @@ function describeApiError(err) {
     }
     return message;
 }
+/** True when /ReflectMemories (or the pause check) refused because the operator aborted. */
+export function isRemAbortedFailure(err) {
+    const text = describeApiError(err);
+    return text.includes("rem_aborted") || text.includes("REM distillation aborted");
+}
+/**
+ * True when this agent owns any `adk:<app>:<user>` tag, regardless of
+ * recency. Continuity session tags are excluded (they are not per-user).
+ * Used so an idle ADK agent (no tag activity inside the 48h window) is
+ * never treated as non-ADK and distilled with scope:"all" (#1515 / #1205b).
+ */
+export function hasAdkUserTags(memories, agentId) {
+    for (const m of memories) {
+        if (!m || typeof m !== "object")
+            continue;
+        if (m.agentId !== agentId)
+            continue;
+        const mt = m.tags;
+        if (!Array.isArray(mt))
+            continue;
+        for (const t of mt) {
+            if (typeof t !== "string")
+                continue;
+            if (t.startsWith(CONTINUITY_TAG_PREFIX))
+                continue;
+            if (t.startsWith(ADK_TAG_PREFIX))
+                return true;
+        }
+    }
+    return false;
+}
 /**
  * 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.
+ * Uses the ops-API `search_by_conditions` convention (admin-authed) via the
+ * injected `opsSearch` helper — the same shape `flair rem candidates` uses.
+ * Returns 0 when no `opsSearch` is available (the agent-authed runner carries
+ * no admin creds) or on any error — the runner should not fail the cycle just
+ * because the candidate count couldn't be sampled.
  */
-async function fetchPendingCandidateCount(api, agentId) {
+async function fetchPendingCandidateCount(opsSearch, agentId) {
+    if (!opsSearch)
+        return 0;
     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);
+        const rows = await opsSearch("MemoryCandidate", [
+            { search_attribute: "agentId", search_type: "equals", search_value: agentId },
+            { search_attribute: "status", search_type: "equals", search_value: "pending" },
+        ], ["id"]);
         return rows.length;
     }
     catch {
@@ -362,6 +456,21 @@ export async function runNightlyCycle(opts) {
         return { status: "paused", logRow: row };
     }
     const errors = [];
+    const healthTimeoutMs = opts.healthTimeoutMs ?? DEFAULT_HEALTH_PREFLIGHT_MS;
+    const health = await runHealthPreflight(opts.apiCall, {
+        probe: opts.healthProbe,
+        timeoutMs: healthTimeoutMs,
+    });
+    if (!health.ok) {
+        const row = {
+            ...baseRow,
+            status: "refused",
+            durationMs: Date.now() - startedMs,
+            errors: [formatHealthRefuseMessage(health, healthTimeoutMs)],
+        };
+        appendLogRow(logPath, row);
+        return { status: "refused", logRow: row };
+    }
     // Step 2: snapshot
     let snapshotPath;
     let memoryCount = 0;
@@ -382,7 +491,7 @@ export async function runNightlyCycle(opts) {
         // 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);
+        pendingCandidates = await fetchPendingCandidateCount(opts.opsSearch, opts.agentId);
         if (!opts.dryRun) {
             const created = await createSnapshot({
                 agentId: opts.agentId,
@@ -472,18 +581,34 @@ export async function runNightlyCycle(opts) {
     let autoPromoted;
     // flair#1257 slice 3: settled continuity sessions distilled this cycle.
     let continuitySessions;
+    // #1515: aggregate gather stats from every /ReflectMemories call this cycle.
+    let distill;
+    let distillAborted = false;
     const collectStagedIds = (obj) => asArray(obj.candidates)
         .map((c) => (c && typeof c === "object" ? c.id : c))
         .filter((id) => typeof id === "string");
+    const noteGather = (obj, maxMemories) => {
+        const gathered = typeof obj.gathered === "number" ? obj.gathered : 0;
+        const unreflected = typeof obj.unreflected === "number" ? obj.unreflected : 0;
+        if (!distill) {
+            distill = { gathered, unreflected, maxMemories };
+            return;
+        }
+        distill.gathered += gathered;
+        distill.unreflected += unreflected;
+    };
+    const cycleIsAborted = () => process.env.FLAIR_REM_PAUSE === "1" || (existsSync(pauseFlagPath) && readPauseSentinel(pauseFlagPath));
     if (!opts.dryRun) {
         sliceLabel = "2";
         const distillSince = opts.distillSince ?? new Date(startedMs - DEFAULT_DISTILL_LOOKBACK_MS);
         const maxTags = opts.maxTagsPerCycle ?? DEFAULT_MAX_TAGS_PER_CYCLE;
+        const maxMemories = resolveMaxMemoriesPerRun(opts.maxMemoriesPerRun);
         // Derive active adk: tags from the memories already fetched in step 2 — no
         // extra query/scan. See deriveActiveAdkTags for why a separate bounded DB
         // query isn't available (Memory has no REST search handler; ops-API needs
         // admin the runner lacks).
         const activeAdkTags = deriveActiveAdkTags(fetchedMemories, distillSince, opts.agentId);
+        const adkShaped = hasAdkUserTags(fetchedMemories, opts.agentId);
         if (activeAdkTags.length > 0) {
             // Per-tag distillation path (ADK). One scope:"tagged" call per active
             // tag; aggregate every batch's staged ids into the single `candidates`
@@ -496,35 +621,62 @@ export async function runNightlyCycle(opts) {
                 errors.push(`distillation: ${activeAdkTags.length} active adk tags exceed the per-cycle cap (${maxTags}); ${activeAdkTags.length - maxTags} deferred to a later cycle`);
             }
             for (const tag of tagsToRun) {
+                if (cycleIsAborted()) {
+                    distillAborted = true;
+                    errors.push("distillation: aborted by operator (flair rem pause or FLAIR_REM_PAUSE=1)");
+                    break;
+                }
+                await yieldToEventLoop();
                 try {
                     const reflectRaw = await opts.apiCall("POST", "/ReflectMemories", {
                         agentId: opts.agentId,
                         execute: true,
                         scope: "tagged",
                         tag,
+                        maxMemories,
                     });
                     const obj = (reflectRaw && typeof reflectRaw === "object") ? reflectRaw : {};
                     if (obj.error) {
                         errors.push(`distillation[${tag}]: ${describeApiError(obj.error)}`);
+                        if (isRemAbortedFailure(obj.error)) {
+                            distillAborted = true;
+                            break;
+                        }
                     }
                     else {
                         staged.push(...collectStagedIds(obj));
+                        noteGather(obj, maxMemories);
                     }
                 }
                 catch (err) {
                     errors.push(`distillation[${tag}]: ${describeApiError(err?.message ?? err)}`);
+                    if (isRemAbortedFailure(err?.message ?? err)) {
+                        distillAborted = true;
+                        break;
+                    }
                 }
             }
             // `candidates` is defined (even if empty) whenever distillation was
             // ATTEMPTED this cycle — same contract as the agentId-only path.
             candidates = staged;
         }
+        else if (adkShaped) {
+            // ADK agentId whose users are all idle this window. Do NOT fall through
+            // to scope:"all" — that mixes every user's backlog (#1205b bleed).
+            // Active tags will be re-selected next cycle when they have recent rows.
+            errors.push("distillation: ADK agent has no active adk tags this cycle; skipped agentId-wide distill to avoid cross-user bleed");
+        }
         else {
-            // AgentId-only path (non-ADK, unchanged pre-#1205b behavior).
+            // AgentId-only path (non-ADK). scope:"all" + oldest-unreflected cap so
+            // a multi-thousand backlog drains across nights (#1515) instead of
+            // only the default 24h recent window.
             try {
+                await yieldToEventLoop();
                 const reflectRaw = await opts.apiCall("POST", "/ReflectMemories", {
                     agentId: opts.agentId,
                     execute: true,
+                    scope: "all",
+                    maxMemories,
                 });
                 const obj = (reflectRaw && typeof reflectRaw === "object") ? reflectRaw : {};
                 if (obj.error) {
@@ -532,17 +684,23 @@ export async function runNightlyCycle(opts) {
                     // MemoryReflect signals failure via HTTP status (503/502) — apiCall
                     // implementations throw for those. Handled the same way regardless.
                     errors.push(`distillation: ${describeApiError(obj.error)}`);
+                    if (isRemAbortedFailure(obj.error))
+                        distillAborted = true;
                 }
                 else {
                     candidates = collectStagedIds(obj);
+                    noteGather(obj, maxMemories);
                 }
             }
             catch (err) {
                 // Distillation failure is recorded, not fatal — maintenance already
                 // succeeded and the cycle's guaranteed steps are done (spec § 3B item
                 // 3). Zero partial candidates is guaranteed server-side (all-or-
-                // nothing staging in /ReflectMemories).
+                // nothing staging in /ReflectMemories). rem_aborted IS fatal to the
+                // rest of this cycle (no auto-promote / dedup).
                 errors.push(`distillation: ${describeApiError(err?.message ?? err)}`);
+                if (isRemAbortedFailure(err?.message ?? err))
+                    distillAborted = true;
             }
         }
         // ── Step 5a (flair#1257 slice 3): continuity-session distillation ─────────
@@ -570,12 +728,18 @@ export async function runNightlyCycle(opts) {
         if (settledContinuityTags.length > continuityToRun.length) {
             errors.push(`distillation: ${settledContinuityTags.length - continuityToRun.length} settled continuity session(s) deferred by the per-cycle tag cap (${maxTags}); re-selected next cycle while un-expired`);
         }
-        if (continuityToRun.length > 0) {
+        if (!distillAborted && continuityToRun.length > 0) {
             // `candidates` is defined whenever distillation was ATTEMPTED (same
             // contract as both paths above).
             candidates = candidates ?? [];
             let distilled = 0;
             for (const tag of continuityToRun) {
+                if (distillAborted || cycleIsAborted()) {
+                    distillAborted = true;
+                    errors.push("distillation: aborted by operator (flair rem pause or FLAIR_REM_PAUSE=1)");
+                    break;
+                }
+                await yieldToEventLoop();
                 try {
                     const reflectRaw = await opts.apiCall("POST", "/ReflectMemories", {
                         agentId: opts.agentId,
@@ -583,18 +747,28 @@ export async function runNightlyCycle(opts) {
                         scope: "tagged",
                         tag,
                         focus: "continuity",
+                        maxMemories,
                     });
                     const obj = (reflectRaw && typeof reflectRaw === "object") ? reflectRaw : {};
                     if (obj.error) {
                         errors.push(`distillation[${tag}]: ${describeApiError(obj.error)}`);
+                        if (isRemAbortedFailure(obj.error)) {
+                            distillAborted = true;
+                            break;
+                        }
                     }
                     else {
                         candidates.push(...collectStagedIds(obj));
+                        noteGather(obj, maxMemories);
                         distilled++;
                     }
                 }
                 catch (err) {
                     errors.push(`distillation[${tag}]: ${describeApiError(err?.message ?? err)}`);
+                    if (isRemAbortedFailure(err?.message ?? err)) {
+                        distillAborted = true;
+                        break;
+                    }
                 }
             }
             continuitySessions = distilled;
@@ -613,7 +787,7 @@ export async function runNightlyCycle(opts) {
         // distillation: a failure is recorded and the candidates stay pending
         // (re-swept next cycle, or promotable by the human `rem promote` path).
         // Bounded by the per-cycle cap.
-        if (activeAdkTags.length > 0 || continuityToRun.length > 0) {
+        if (!distillAborted && (activeAdkTags.length > 0 || continuityToRun.length > 0)) {
             try {
                 const apRaw = await opts.apiCall("POST", "/AutoPromoteCandidates", {
                     agentId: opts.agentId,
@@ -651,7 +825,7 @@ export async function runNightlyCycle(opts) {
     // recomputation is idempotent (same inputs → same aggregate, just wasted
     // work), not incorrect.
     let dedup;
-    if (!opts.dryRun) {
+    if (!opts.dryRun && !distillAborted) {
         try {
             const dedupRaw = await opts.apiCall("POST", "/MemoryDedupStats", {});
             const obj = (dedupRaw && typeof dedupRaw === "object") ? dedupRaw : {};
@@ -678,6 +852,14 @@ export async function runNightlyCycle(opts) {
         }
     }
     // Step 7: log
+    if (distillAborted) {
+        distill = {
+            gathered: distill?.gathered ?? 0,
+            unreflected: distill?.unreflected ?? 0,
+            maxMemories: distill?.maxMemories ?? resolveMaxMemoriesPerRun(opts.maxMemoriesPerRun),
+            aborted: true,
+        };
+    }
     const row = {
         ...baseRow,
         slice: sliceLabel,
@@ -692,6 +874,7 @@ export async function runNightlyCycle(opts) {
         candidates,
         autoPromoted,
         continuitySessions,
+        distill,
         dedup,
         durationMs: Date.now() - startedMs,
         errors,

package/dist/resources/AdminMemory.js

@@ -1,6 +1,7 @@
 import { Resource, databases } from "harper";
 import { layout, htmlResponse, esc } from "./admin-layout.js";
 import { allowAdmin } from "./agent-auth.js";
+import { applyHitStats } from "./hit-tracking.js";
 /**
  * GET /AdminMemory                browse + search memories (list view)
  * GET /AdminMemory?id=<id>        per-memory detail view with full provenance pane
@@ -146,7 +147,7 @@ export class AdminMemory extends Resource {
         const memDb = databases.flair.Memory;
         let memory = null;
         try {
-            memory = await memDb.get(id);
+            memory = await applyHitStats(await memDb.get(id), this.getContext?.());
         }
         catch { /* table missing or other error */ }
         if (!memory) {

package/dist/resources/AgentSeed.js

@@ -14,12 +14,16 @@
  * Response:
  *   { agent, soulEntries, memories }
  *
- * Auth: admin only.
+ * Auth: operator (verified Harper administrator Basic) or deliberate
+ * `internalContext()`. Admin-agent Ed25519 keys are refused — role is not
+ * source. Intended: provisioning a principal and its Soul is a trust-root act.
  */
 import { Resource, databases } from "harper";
-import { isAdmin, allowAdmin, invalidateAdminCache } from "./agent-auth.js";
+import { allowAdmin, invalidateAdminCache } from "./agent-auth.js";
+import { authorizeSoulWrite, refuseSoulWriteContent, soulProvenance } from "./soul-write-policy.js";
 import { reconcileAdminFields } from "./agent-admin.js";
 import { noteMemoryUpsert } from "./bm25-index-service.js";
+import { rejectSkillWritePath } from "./skill-write.js";
 const DEFAULT_SOUL_KEYS = (agentId, displayName, role, now) => ({
     name: displayName,
     role,
@@ -47,11 +51,9 @@ export class AgentSeed extends Resource {
         // undefined and this belt-and-suspenders check fail-closed every request,
         // even from a real admin already verified by allowCreate()).
         const ctx = this.getContext?.();
-        const request = ctx?.request ?? ctx;
-        const actorId = request?.tpsAgent;
-        if (!actorId || !(await isAdmin(actorId))) {
-            return new Response(JSON.stringify({ error: "forbidden: admin only" }), { status: 403 });
-        }
+        const { auth, source, denied } = await authorizeSoulWrite(ctx);
+        if (denied)
+            return denied;
         const { agentId, displayName, role = "agent", soulTemplate, starterMemories } = data || {};
         if (!agentId)
             return new Response(JSON.stringify({ error: "agentId required" }), { status: 400 });
@@ -60,6 +62,14 @@ export class AgentSeed extends Resource {
         }
         const now = new Date().toISOString();
         const name = displayName || agentId;
+        // Validate the entire caller-controlled template before creating any rows.
+        const defaults = DEFAULT_SOUL_KEYS(agentId, name, role, now);
+        const merged = { ...defaults, ...(soulTemplate || {}) };
+        for (const value of Object.values(merged)) {
+            const refusal = await refuseSoulWriteContent({ agentId, value: String(value) });
+            if (refusal)
+                return refusal;
+        }
         // ── Agent record ──────────────────────────────────────────────────────────
         const existingAgent = await databases.flair.Agent.get(agentId).catch(() => null);
         let agent = existingAgent;
@@ -75,8 +85,6 @@ export class AgentSeed extends Resource {
             invalidateAdminCache();
         }
         // ── Soul entries ──────────────────────────────────────────────────────────
-        const defaults = DEFAULT_SOUL_KEYS(agentId, name, role, now);
-        const merged = { ...defaults, ...(soulTemplate || {}) };
         const soulEntries = [];
         for (const [key, value] of Object.entries(merged)) {
             const id = `${agentId}:${key}`;
@@ -85,7 +93,7 @@ export class AgentSeed extends Resource {
                 soulEntries.push(existing); // skip — don't overwrite existing soul entries
                 continue;
             }
-            const entry = { id, agentId, key, value: String(value), durability: "permanent", createdAt: now, updatedAt: now };
+            const entry = { id, agentId, key, value: String(value), provenance: soulProvenance(auth, source, now), durability: "permanent", createdAt: now, updatedAt: now };
             await databases.flair.Soul.put(entry);
             soulEntries.push(entry);
         }
@@ -112,6 +120,14 @@ export class AgentSeed extends Resource {
         else {
             for (let i = 0; i < memDefs.length; i++) {
                 const def = memDefs[i];
+                // ── flair#1542: reject skill-tagged starter memories ──
+                // This admin-only seed writes via the RAW table object, bypassing
+                // Memory.post()/put()'s SkillScan gate + forced durability. A
+                // skill-tagged starter memory would land unscanned — reject it (skills
+                // are written via skill_store, not seeded as onboarding memories).
+                const skillDenial = rejectSkillWritePath(def);
+                if (skillDenial)
+                    return skillDenial;
                 const id = `seed-${agentId}-${i}-${Date.now()}`;
                 const record = {
                     id,