@tpsdev-ai/flair 0.21.0 → 0.22.0

package/dist/resources/MemoryReflect.js

@@ -1,9 +1,11 @@
 /**
  * POST /MemoryReflect
  *
- * Gathers recent memories for an agent and returns a structured reflection
- * prompt. The agent feeds the prompt + memories to its LLM and writes
- * insights back as persistent memories (with derivedFrom linking).
+ * Gathers recent memories for an agent and either (a) returns a structured
+ * reflection prompt for a human/agent to run through their own LLM, or (b)
+ * with execute:true, runs the distillation server-side via Harper's models
+ * facade and stages the results as MemoryCandidate rows for review. See
+ * specs/FLAIR-NIGHTLY-REM-SLICE-2-DISTILLATION.md §3A (issue #707).
  *
  * Request:
  *   agentId      string   — which agent to reflect on
@@ -12,22 +14,33 @@
  *   maxMemories  number?  — cap (default: 50)
  *   focus        string?  — "lessons_learned" | "patterns" | "decisions" | "errors" (default: "lessons_learned")
  *   tag          string?  — required when scope="tagged"
+ *   execute      boolean? — default false. When true, distill server-side and
+ *                            stage MemoryCandidate rows instead of returning a prompt.
  *
- * Response:
+ * Response (execute: false, default — unchanged from pre-#707 behavior):
  *   memories       Memory[]   — source memories included in the prompt
  *   prompt         string     — structured LLM prompt
  *   suggestedTags  string[]   — tags Flair detected in the source set
  *   count          number     — number of memories included
+ *
+ * Response (execute: true):
+ *   candidates  MemoryCandidate[] — staged rows (rationalePrompt omitted — see below)
+ *   count       number
+ *   model       string            — resolved model id (see generatedBy note below)
+ *
+ * The pure logic behind execute mode (prompt building, actor resolution,
+ * generate+validate+retry, dedup) lives in ./memory-reflect-lib.ts — see that
+ * file's header for why: importing Resource/databases/models here pulls in
+ * the Harper runtime and can't be unit-tested directly (Harper injects
+ * `Resource` as a runtime global; bun's ESM linker rejects `import {
+ * Resource }` outright — see test/unit/resource-allow.test.ts). This
+ * resource is a thin orchestrator over the lib's tested functions.
  */
-import { Resource, databases } from "@harperfast/harper";
+import { Resource, databases, models, logger } from "@harperfast/harper";
+import { randomBytes } from "node:crypto";
 import { isAdmin, allowVerified } from "./agent-auth.js";
 import { patchRecordSilent } from "./table-helpers.js";
-const FOCUS_PROMPTS = {
-    lessons_learned: "Review these memories and identify concrete lessons learned. For each lesson: what happened, what you learned, and how it should change future behavior. Write atomic memories with durability=persistent.",
-    patterns: "Identify recurring patterns across these memories. What themes, approaches, or outcomes appear multiple times? Extract each pattern as a persistent memory.",
-    decisions: "Catalog the key decisions made and their outcomes. For each: what was decided, why, and what resulted. Promote important decisions to persistent.",
-    errors: "Extract errors, bugs, and failures. For each: what failed, root cause, and fix applied. These are high-value persistent memories.",
-};
+import { buildReflectionPrompt, buildExecutePrompt, resolveReflectActor, generateCandidates, dedupeCandidates, } from "./memory-reflect-lib.js";
 export class ReflectMemories extends Resource {
     // Self-authorize via the Ed25519 agent verify (auth reshape removes the gate's
     // admin elevation). Any verified agent may reflect; the isAdmin checks in post()
@@ -36,7 +49,7 @@ export class ReflectMemories extends Resource {
         return allowVerified(this.getContext?.());
     }
     async post(data) {
-        const { agentId: bodyAgentId, scope = "recent", since, maxMemories = 50, focus = "lessons_learned", tag, } = data || {};
+        const { agentId: bodyAgentId, scope = "recent", since, maxMemories = 50, focus = "lessons_learned", tag, execute = false, } = data || {};
         // Authenticated identity comes from getContext().request, not this.request
         // (see SemanticSearch / MemoryBootstrap for the same bug class). The prior
         // check was silently bypassed — bob could reflect on alice's memories and
@@ -46,13 +59,13 @@ export class ReflectMemories extends Resource {
         const actorId = request?.tpsAgent;
         const callerIsAdmin = request?.tpsAgentIsAdmin === true
             || (actorId ? await isAdmin(actorId) : false);
-        if (!bodyAgentId && !actorId) {
-            return new Response(JSON.stringify({ error: "agentId required" }), { status: 400 });
-        }
-        if (actorId && !callerIsAdmin && bodyAgentId && bodyAgentId !== actorId) {
-            return new Response(JSON.stringify({ error: "forbidden: can only reflect on own memories" }), { status: 403 });
+        // Same actor rules for both modes (spec §3A item 9) — resolved once via
+        // the shared, tested helper before either branch runs.
+        const actorResolution = resolveReflectActor({ bodyAgentId, actorId, callerIsAdmin });
+        if (actorResolution.error) {
+            return new Response(JSON.stringify(actorResolution.error.body), { status: actorResolution.error.status });
         }
-        const agentId = (actorId && !callerIsAdmin) ? actorId : bodyAgentId;
+        const agentId = actorResolution.agentId;
         const sinceDate = since ? new Date(since) : new Date(Date.now() - 24 * 3600_000);
         const memories = [];
         for await (const record of databases.flair.Memory.search()) {
@@ -83,38 +96,81 @@ export class ReflectMemories extends Resource {
             for (const t of m.tags ?? [])
                 tagSet.add(t);
         }
-        // Build prompt
-        const focusText = FOCUS_PROMPTS[focus] ?? FOCUS_PROMPTS.lessons_learned;
-        const memorySummary = memories
-            .map((m, i) => `[${i + 1}] (${m.id}) ${m.createdAt?.slice(0, 10) ?? "?"}: ${m.content.slice(0, 300)}`)
-            .join("\n");
-        const prompt = `# Memory Reflection — ${agentId}
-Focus: ${focus}
-Scope: ${scope} (since ${sinceDate.toISOString()})
-Memories: ${memories.length}
-
-## Task
-${focusText}
-
-## Source Memories
-${memorySummary || "(none)"}
-
-## Instructions
-For each insight:
-1. Write a new memory with durability=persistent
-2. Set derivedFrom=[<source memory ids>]
-3. Set tags from the source memories where relevant
-4. Keep each memory atomic — one insight per record`;
-        // Update lastReflected on source memories (read-modify-write to preserve embeddings)
-        const now = new Date().toISOString();
+        // Update lastReflected on source memories (read-modify-write to preserve
+        // embeddings). Unconditional for both modes — calling /ReflectMemories at
+        // all means these memories were considered, regardless of what happens next.
+        const nowISO = new Date().toISOString();
         for (const m of memories) {
-            patchRecordSilent(databases.flair.Memory, m.id, { lastReflected: now });
+            patchRecordSilent(databases.flair.Memory, m.id, { lastReflected: nowISO });
+        }
+        const promptInputs = memories.map((m) => ({ id: m.id, createdAt: m.createdAt, content: m.content }));
+        if (!execute) {
+            const prompt = buildReflectionPrompt({ agentId, focus, scope, sinceISO: sinceDate.toISOString(), memories: promptInputs });
+            return {
+                memories,
+                prompt,
+                suggestedTags: [...tagSet].slice(0, 20),
+                count: memories.length,
+            };
+        }
+        // ── execute mode (spec §3A) ─────────────────────────────────────────────
+        const executePrompt = buildExecutePrompt({ agentId, focus, scope, sinceISO: sinceDate.toISOString(), memories: promptInputs });
+        const gatheredMemoryIds = new Set(promptInputs.map((m) => m.id));
+        const configuredModel = process.env.FLAIR_REM_MODEL || undefined;
+        const outcome = await generateCandidates({
+            prompt: executePrompt,
+            model: configuredModel,
+            gatheredMemoryIds,
+            generate: (input, opts) => models.generate(input, opts),
+        });
+        if (!outcome.ok) {
+            if (outcome.reason === "no_backend") {
+                // Static body (K&S) — never echo Harper version, backend lists, or endpoints.
+                return new Response(JSON.stringify({ error: "No generative backend configured. See the models configuration docs." }), { status: 503 });
+            }
+            return new Response(JSON.stringify({ error: "distillation_failed", detail: "model output did not validate after one retry" }), { status: 502 });
+        }
+        if (outcome.usedJsonFallback) {
+            logger.warn?.(`MemoryReflect: json-fallback path active for agent ${agentId} (schema-mode output failed validation)`);
+        }
+        // Dedup against this agent's existing pending candidates (spec §3A item 4).
+        const existingPendingClaims = [];
+        for await (const c of databases.flair.MemoryCandidate.search({})) {
+            if (c.agentId !== agentId)
+                continue;
+            if (c.status !== "pending")
+                continue;
+            existingPendingClaims.push(c.claim);
+        }
+        const toStage = dedupeCandidates(outcome.candidates, existingPendingClaims);
+        // generatedBy: GenerateResult in the pinned @harperfast/harper 5.1.17 has
+        // no model/backend-id field (content/finishReason/usage/toolCalls/trace
+        // only) — the "from the generate result if available" branch is
+        // unreachable in this version, so this always falls back to the
+        // configured logical name, matching Harper's own default routing name.
+        const resolvedModel = configuredModel ?? "default";
+        const generatedAt = new Date().toISOString();
+        const staged = [];
+        for (const c of toStage) {
+            const row = {
+                id: `cand_${randomBytes(8).toString("hex")}`,
+                agentId,
+                claim: c.claim,
+                sourceMemoryIds: c.sourceMemoryIds,
+                rationalePrompt: executePrompt,
+                generatedBy: resolvedModel,
+                generatedAt,
+                status: "pending",
+            };
+            await databases.flair.MemoryCandidate.put(row);
+            staged.push(row);
         }
-        return {
-            memories,
-            prompt,
-            suggestedTags: [...tagSet].slice(0, 20),
-            count: memories.length,
-        };
+        // Response omits rationalePrompt (spec §3A item 5: "no prompt field") —
+        // it's identical across every row in this batch and already persisted
+        // for audit on the MemoryCandidate row itself; echoing it back per
+        // candidate would just repeat the same large string N times. Matches
+        // `flair rem candidates`' own listing, which doesn't surface it either.
+        const responseCandidates = staged.map(({ rationalePrompt, ...rest }) => rest);
+        return { candidates: responseCandidates, count: responseCandidates.length, model: resolvedModel };
     }
 }

package/dist/resources/MemoryUsage.js

@@ -0,0 +1,104 @@
+/**
+ * resources/MemoryUsage.ts — the dedup ledger for the usage-feedback signal
+ * (flair#683). One row per (agentId, memoryId) contribution; see
+ * schemas/memory.graphql's MemoryUsage type doc for the full field/design
+ * rationale.
+ *
+ * This file is a LOCKED-DOWN table guard, not the public write surface: the
+ * actual "record that a memory was used" action lives in
+ * resources/RecordUsage.ts (POST /RecordUsage) — see that file's module doc
+ * for why the action lives on a SEPARATE, non-table-backed resource (a
+ * confirmed-live Harper gotcha: the base TableResource has no default
+ * `post()` for a static-style raw-table call outside an
+ * `isCollection`-instantiated resource — resources/Memory.ts documents the
+ * HTTP-facing shape of this same limitation for the Memory table).
+ * RecordUsage writes ledger rows via `.put()` on the RAW table object
+ * (`databases.flair.MemoryUsage` — an upsert against the deterministic
+ * composite id, not a `.post()`), the same "call the other table directly,
+ * bypass its resource class's own auth wrapper" pattern resources/Memory.ts
+ * already uses for MemoryGrant (hasWriteGrant()) — so nothing below is
+ * bypassed by that internal path; it only gates the DIRECT `/MemoryUsage`
+ * HTTP route.
+ *
+ * Why agents get READ but NOT UPDATE/DELETE here (mirrored in
+ * src/cli.ts's FLAIR_AGENT_PERMISSION native-role grant): the ledger IS the
+ * dedup/anti-gaming primitive — Sherlock's "(agent, memory) contributes ≤ 1"
+ * rule is enforced by RecordUsage checking for an EXISTING ledger row before
+ * bumping usageCount. If an agent could DELETE its own row over HTTP, it
+ * could re-trigger RecordUsage for the same memory indefinitely (create row
+ * → count once → delete row → count again → repeat), completely defeating
+ * the dedup cap. Locking put()/delete() to admin/internal here is therefore
+ * LOAD-BEARING, not just defense in depth — it's the only thing enforcing
+ * this in an environment where the native Harper role hasn't been
+ * (re-)provisioned yet (auth-middleware.ts's documented pre-migration
+ * admin-fallback — and every ephemeral test Harper spawned via
+ * test/helpers/harper-lifecycle.ts, which never runs `flair init`'s role
+ * provisioning at all).
+ *
+ * Read scope is deliberately narrower than Memory's "open-within-org" model:
+ * an agent sees only ITS OWN contributions (or admin sees everything). The
+ * ledger is an audit trail, not a shared surface — there is no product need
+ * to expose "which agent used which memory" cross-agent, and narrowing this
+ * costs nothing.
+ */
+import { databases } from "@harperfast/harper";
+import { resolveAgentAuth, allowVerified } from "./agent-auth.js";
+const FORBIDDEN = (msg) => new Response(JSON.stringify({ error: msg }), { status: 403, headers: { "Content-Type": "application/json" } });
+const UNAUTH = () => new Response(JSON.stringify({ error: "authentication required" }), { status: 401, headers: { "Content-Type": "application/json" } });
+const NOT_FOUND = () => new Response(JSON.stringify({ error: "not found" }), { status: 404, headers: { "Content-Type": "application/json" } });
+export class MemoryUsage extends databases.flair.MemoryUsage {
+    /** Self-authorize now that the global gate is non-rejecting — same pattern
+     *  as every other table resource in this codebase (Memory.ts/MemoryGrant.ts
+     *  etc.). Per-record scoping happens in get()/search() below. */
+    allowRead() { return allowVerified(this.getContext?.()); }
+    async get(target) {
+        if (!target || (typeof target === "object" && target.isCollection)) {
+            return this.search(target);
+        }
+        const auth = await resolveAgentAuth(this.getContext?.());
+        if (auth.kind === "anonymous")
+            return NOT_FOUND();
+        if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin))
+            return super.get(target);
+        const record = await super.get(target);
+        if (!record || record.agentId !== auth.agentId)
+            return NOT_FOUND();
+        return record;
+    }
+    async search(query) {
+        const auth = await resolveAgentAuth(this.getContext?.());
+        if (auth.kind === "anonymous")
+            return UNAUTH();
+        if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin))
+            return super.search(query);
+        const scope = { attribute: "agentId", comparator: "equals", value: auth.agentId };
+        if (query && typeof query === "object" && !Array.isArray(query)) {
+            const existing = query.conditions ?? [];
+            query.conditions = Array.isArray(existing) ? [scope, ...existing] : [scope, existing];
+            return super.search(query);
+        }
+        const conditions = Array.isArray(query) && query.length > 0 ? [scope, ...query] : [scope];
+        return super.search(conditions);
+    }
+    // Append-only ledger: rows are created via RecordUsage's RAW table call
+    // (bypasses this class entirely — see module doc), never via this
+    // instance-level HTTP route, for non-admin callers.
+    async post(content) {
+        const auth = await resolveAgentAuth(this.getContext?.());
+        if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin))
+            return super.post(content);
+        return FORBIDDEN("forbidden: MemoryUsage rows are written by the /RecordUsage endpoint, not directly");
+    }
+    async put(content) {
+        const auth = await resolveAgentAuth(this.getContext?.());
+        if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin))
+            return super.put(content);
+        return FORBIDDEN("forbidden: MemoryUsage rows are immutable once written");
+    }
+    async delete(id) {
+        const auth = await resolveAgentAuth(this.getContext?.());
+        if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin))
+            return super.delete(id);
+        return FORBIDDEN("forbidden: MemoryUsage rows cannot be deleted by non-admins (dedup-integrity invariant — see module doc)");
+    }
+}

package/dist/resources/OAuth.js

@@ -216,7 +216,14 @@ ${scope.split(" ").map((s) => `<div class="scope">${s}</div>`).join("")}
                 status: 400, headers: { "content-type": "application/json" },
             });
         }
-        if (action === "deny") {
+        // flair#610 — mint an authorization code ONLY on an explicit approve. The
+        // consent form rendered by get() submits action=approve|deny and nothing
+        // else, so treating every non-"approve" value (deny, missing, empty, or
+        // garbage) as a denial is safe — and it closes the previous loose
+        // `action !== "deny"` check, which minted a code for a malformed or absent
+        // action. redirect_uri was already validated above, so this access_denied
+        // redirect can only target the allowed URI.
+        if (action !== "approve") {
             const params = new URLSearchParams({ error: "access_denied", state });
             return redirectTo(`${redirectUri}?${params}`);
         }

package/dist/resources/OrgEvent.js

@@ -12,6 +12,7 @@
  */
 import { databases } from "@harperfast/harper";
 import { resolveAgentAuth, allowVerified } from "./agent-auth.js";
+import { invalidEntitiesResponse } from "./entity-vocab.js";
 const FORBIDDEN = (msg) => new Response(JSON.stringify({ error: msg }), { status: 403, headers: { "Content-Type": "application/json" } });
 const UNAUTH = () => new Response(JSON.stringify({ error: "authentication required" }), { status: 401, headers: { "Content-Type": "application/json" } });
 export class OrgEvent extends databases.flair.OrgEvent {
@@ -39,6 +40,12 @@ export class OrgEvent extends databases.flair.OrgEvent {
         if (!content.id)
             content.id = `${content.authorId}-${new Date().toISOString()}`;
         content.createdAt = new Date().toISOString();
+        // attention-plane vocabulary gate (flair#675): `entities`, if present,
+        // must be well-formed vocabulary strings — see resources/entity-vocab.ts.
+        // Field is additive/optional; absent entities is not an error.
+        const entitiesError = invalidEntitiesResponse(content.entities);
+        if (entitiesError)
+            return entitiesError;
         // Harper 5: table resources use put() for create/upsert (post() removed).
         return databases.flair.OrgEvent.put(content);
     }
@@ -49,6 +56,10 @@ export class OrgEvent extends databases.flair.OrgEvent {
         if (auth.kind === "agent" && !auth.isAdmin && content.authorId !== auth.agentId) {
             return FORBIDDEN("forbidden: authorId must match authenticated agent");
         }
+        // attention-plane vocabulary gate (flair#675) — same as post() above.
+        const entitiesError = invalidEntitiesResponse(content.entities);
+        if (entitiesError)
+            return entitiesError;
         return databases.flair.OrgEvent.put(content);
     }
     async delete(id, context) {