@tpsdev-ai/flair 0.10.0 → 0.10.1

package/README.md

@@ -17,7 +17,7 @@ Flair is the **identity + memory substrate for AI agents**. Cryptographic per-ag
 │  Codex CLI    ─┼─[ flair-mcp ]─┐                                 │
 │  Gemini CLI   ─┤               │                                 │
 │  Continue.dev ─┤               │   ┌──────────────────────┐      │
-│  Goose        ─┘               ├─▶ │  Flair (rockit)      │      │
+│  Goose        ─┘               ├─▶ │  Flair (self-hosted) │      │
 │  LangGraph   ─[ langgraph-flair ]──│  Ed25519 / HNSW /    │      │
 │  OpenClaw    ─[ openclaw-flair  ]──│  Soul + Memory       │      │
 │  n8n         ─[ n8n-nodes-flair ]──└──────────┬───────────┘      │
@@ -146,7 +146,7 @@ Not all memories are equal:
 Memories can be time-bounded with `validFrom` and `validTo` fields. Expired memories are excluded from search and bootstrap automatically — no manual cleanup.
 
 ### Relationship Graph
-Entity-to-entity triples with temporal bounds. Model structured knowledge — "Flint works-with Anvil since 2024-01-01" — queryable alongside semantic memory.
+Entity-to-entity triples with temporal bounds. Model structured knowledge — "Alice works-with Bob since 2024-01-01" — queryable alongside semantic memory.
 
 ### Real-Time Feeds
 Subscribe to memory or soul changes via WebSocket/SSE. Useful for dashboards, cross-agent sync, or audit trails.
@@ -392,7 +392,7 @@ Good for teams with multiple machines or always-on agents.
 
 ### Harper Fabric
 
-Deploy Flair on [Harper Fabric](https://www.harperdb.io/) for managed hosting with multi-region replication and failover. Federation is live against Harper Fabric hubs (e.g. `flair.heskew.harperfabric.com`) — pair your local instance to sync memories across nodes.
+Deploy Flair on [Harper Fabric](https://www.harperdb.io/) for managed hosting with multi-region replication and failover. Federation runs against Harper Fabric hubs (e.g. `flair.your-org.harperfabric.com`) — pair your local instance to sync memories across nodes.
 
 ## Security
 

package/dist/cli.js

@@ -3215,28 +3215,45 @@ federation
         }
         const result = await res.json();
         console.log(`✅ Paired with hub: ${result.instance?.id ?? hubUrl}`);
-        // Record the hub as our peer — locally or remotely depending on --target
-        const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
-        if (adminPass) {
-            const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
-            const opsEndpoint = resolveEffectiveOpsUrl(opts) ?? `http://127.0.0.1:${resolveOpsPort(opts)}`;
-            await fetch(`${opsEndpoint}/`, {
-                method: "POST",
-                headers: { "Content-Type": "application/json", Authorization: auth },
-                body: JSON.stringify({
-                    operation: "upsert", database: "flair", table: "Peer",
-                    records: [{
-                            id: result.instance?.id ?? "hub",
-                            publicKey: result.instance?.publicKey ?? "",
-                            role: "hub", endpoint: hubUrl, status: "paired",
-                            pairedAt: new Date().toISOString(),
-                            createdAt: new Date().toISOString(),
-                            updatedAt: new Date().toISOString(),
-                        }],
-                }),
-                signal: AbortSignal.timeout(10_000),
-            });
+        // Record the hub as our local peer. This is REQUIRED, not optional:
+        // `flair federation sync` reads the Peer table to find the hub, so
+        // without this record sync reports "No hub peer configured" and silently
+        // never runs. Previously this was gated on `if (adminPass)` and the write
+        // result was never checked — pairing with only an agent key (or a failed
+        // upsert) left no peer behind a misleadingly green "✅ Paired".
+        const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD ?? "";
+        if (!adminPass) {
+            console.error("Error: paired on the hub, but the local hub-peer record needs admin auth to write — " +
+                "pass --admin-pass, or set FLAIR_ADMIN_PASS / HDB_ADMIN_PASSWORD, then re-run pair. " +
+                "Without it, 'flair federation sync' will report 'No hub peer configured'.");
+            process.exit(1);
+        }
+        const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
+        const opsEndpoint = resolveEffectiveOpsUrl(opts) ?? `http://127.0.0.1:${resolveOpsPort(opts)}`;
+        const peerRes = await fetch(`${opsEndpoint}/`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: auth },
+            body: JSON.stringify({
+                operation: "upsert", database: "flair", table: "Peer",
+                records: [{
+                        id: result.instance?.id ?? "hub",
+                        publicKey: result.instance?.publicKey ?? "",
+                        role: "hub", endpoint: hubUrl, status: "paired",
+                        pairedAt: new Date().toISOString(),
+                        createdAt: new Date().toISOString(),
+                        updatedAt: new Date().toISOString(),
+                    }],
+            }),
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!peerRes.ok) {
+            const text = await peerRes.text().catch(() => "");
+            console.error(`Error: paired with the hub but failed to write the local hub-peer record ` +
+                `(${peerRes.status} ${text.slice(0, 200)}). Ops endpoint: ${opsEndpoint}. ` +
+                `'flair federation sync' will not find the hub until this succeeds — check --admin-pass and the ops port.`);
+            process.exit(1);
         }
+        console.log(`✅ Recorded hub as local peer: ${result.instance?.id ?? "hub"} → ${hubUrl}`);
     }
     catch (err) {
         console.error(`Error: ${err.message}`);
@@ -3373,25 +3390,63 @@ export async function runFederationSyncOnce(opts) {
         const hubUrl = hub.endpoint ?? hub.id;
         // ── Batching constants ──────────────────────────────────────────────
         // 2MB JSON budget (server cap is 10MB; 2MB leaves headroom for headers
-        // and signature metadata) + 200 records max per batch.
+        // and signature metadata) + 50 records max per batch. The hub merge itself
+        // is fast (~1.7s/50 records, per its SyncLog), but the Fabric ingress was
+        // observed to intermittently stall on larger POSTs — a 50-record batch hung
+        // ~2 min while the same records split into 2×25 went through immediately.
+        // 50 keeps batches in the reliable range, and sendBatch's adaptive split
+        // recovers if a stretch still stalls.
         const BUDGET_BYTES = 2_000_000;
-        const BUDGET_RECORDS = 200;
+        const BUDGET_RECORDS = 50;
         // ── sendBatch helper ────────────────────────────────────────────────
         // Secret key is lazy-loaded: only needed when there are records to send.
         // Loading earlier would cause a spurious error when SQL queries fail
         // (e.g. 401) before we know we have records.
         let secretKey;
+        // Statuses the Fabric ingress returns when a batch POST didn't complete in
+        // time (408) or was too large (413), plus the transient gateway 5xx family.
+        // Splitting the batch and retrying smaller chunks lets the sync converge
+        // instead of aborting the whole run.
+        const TIMEOUT_STATUSES = new Set([408, 413, 502, 503, 504]);
+        // Per-batch wall-clock cap. Without it a stalled connection to the Fabric
+        // ingress hangs the whole sync until the *gateway's* timeout fires (~2 min
+        // observed), which is what stranded the re-pair. A 45s cap is generous —
+        // a healthy 50-record batch merges in <2s — so a trip means a real stall,
+        // and we split-and-retry rather than wait it out.
+        const BATCH_TIMEOUT_MS = 45_000;
         async function sendBatch(batch) {
             if (!secretKey)
                 secretKey = await loadInstanceSecretKey(instance.id, opts);
             const syncBody = { instanceId: instance.id, records: batch, lamportClock: Date.now() };
             const signedSyncBody = signBodyFresh(syncBody, secretKey);
-            const syncRes = await fetch(`${hubUrl}/FederationSync`, {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify(signedSyncBody),
-            });
+            // Halve and retry down to a single record. Covers both an explicit
+            // timeout status AND a client-side abort (stalled socket). The hub
+            // merges idempotently (put-by-id), so retried records are safe.
+            const splittable = (status) => batch.length > 1 && (status === null || TIMEOUT_STATUSES.has(status));
+            const split = async () => {
+                const mid = Math.floor(batch.length / 2);
+                const left = await sendBatch(batch.slice(0, mid));
+                const right = await sendBatch(batch.slice(mid));
+                return { merged: left.merged + right.merged, skipped: left.skipped + right.skipped };
+            };
+            let syncRes;
+            try {
+                syncRes = await fetch(`${hubUrl}/FederationSync`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify(signedSyncBody),
+                    signal: AbortSignal.timeout(BATCH_TIMEOUT_MS),
+                });
+            }
+            catch (err) {
+                // Timeout/abort or network drop — no status. Split if we can.
+                if (splittable(null))
+                    return await split();
+                throw new Error(`Sync batch (${batch.length} record${batch.length === 1 ? "" : "s"}) failed: ${err?.message ?? err}`);
+            }
             if (!syncRes.ok) {
+                if (splittable(syncRes.status))
+                    return await split();
                 const text = await syncRes.text().catch(() => "");
                 throw new Error(`Sync batch failed: ${syncRes.status} ${text}`);
             }
@@ -4693,7 +4748,7 @@ function oauthDetailLines(o) {
 // discoverLocalFlairPort when the configured URL is unreachable, to detect
 // config-vs-daemon port drift (ops-mbdi). Order is ad-hoc — first hit wins.
 //
-// 9926: original default (long-running rockit installs predate the bump)
+// 9926: original default (long-running early installs predate the bump)
 // 19926: current default (DEFAULT_PORT)
 // 19925: ops-anvil VM secondary
 const LOCAL_FLAIR_PROBE_PORTS = [9926, 19926, 19925];
@@ -6969,7 +7024,7 @@ memory.command("list")
 });
 // ─── flair memory hygiene ────────────────────────────────────────────────────
 // Detect + remove junk memory rows that accumulate over time. Surfaced from
-// the 2026-05-07 manual cleanup (ops-ucyy): rockit had 627 records, ~250 of
+// the 2026-05-07 manual cleanup (ops-ucyy): an instance had 627 records, ~250 of
 // them were noise — `*-compact-*` ID fragments from an old pipeline, pangram
 // test content ("the quick brown fox..." / "Flair 251 test ..."), and
 // near-empty rows (<25 chars). We did the cleanup ad-hoc with raw curl + jq;

package/dist/resources/AgentCard.js

@@ -1,10 +1,5 @@
 import { Resource, databases } from "@harperfast/harper";
-function readSoulKind(entry) {
-    return String(entry.kind ?? entry.key ?? "").trim().toLowerCase();
-}
-function readSoulContent(entry) {
-    return String(entry.content ?? entry.value ?? "").trim();
-}
+import { selectPublicDescription, selectPublicSkills } from "./agentcard-fields.js";
 export class AgentCard extends Resource {
     async get(pathInfo) {
         const agentId = (typeof pathInfo === "string" ? pathInfo : null) ??
@@ -25,19 +20,15 @@ export class AgentCard extends Resource {
             if (row?.agentId === agentId)
                 souls.push(row);
         }
-        const descriptionEntry = souls.find((s) => readSoulKind(s) === "description" && readSoulContent(s)) ??
-            souls.find((s) => readSoulContent(s));
-        const skills = souls
-            .filter((s) => readSoulKind(s) === "capability")
-            .map((s) => readSoulContent(s))
-            .filter(Boolean);
         return {
             name: String(agent.name ?? agent.id ?? agentId),
-            description: descriptionEntry ? readSoulContent(descriptionEntry) : "",
+            // Only an explicit kind="description" soul publishes — no private-soul
+            // fallback (ops-vz6j). See agentcard-fields.ts for the security rationale.
+            description: selectPublicDescription(souls),
             url: String(agent.url ?? ""),
             version: String(agent.version ?? "1.0.0"),
             capabilities: agent.capabilities && typeof agent.capabilities === "object" ? agent.capabilities : {},
-            skills,
+            skills: selectPublicSkills(souls),
             defaultInputModes: ["text"],
             defaultOutputModes: ["text"],
         };

package/dist/resources/agentcard-fields.js

@@ -0,0 +1,40 @@
+// Pure selection logic for what an agent's public AgentCard exposes.
+//
+// SECURITY: `GET /AgentCard/{id}` is intentionally UNAUTHENTICATED (A2A spec —
+// agent cards are public discovery metadata, and the auth-middleware allow-list
+// lets it bypass auth). Everything these helpers return is therefore world-
+// readable. They must publish ONLY explicitly-kinded souls — never an implicit
+// fallback that could surface a private soul (an operator's internal note,
+// prompt fragment, or credential reminder) on the public endpoint.
+//
+// Kept free of any @harperfast/harper import so the real logic is unit-testable
+// without spinning up Harper (avoids the simulator-pattern that let the
+// description-fallback leak ship untested — ops-vz6j).
+export function readSoulKind(entry) {
+    return String(entry.kind ?? entry.key ?? "").trim().toLowerCase();
+}
+export function readSoulContent(entry) {
+    return String(entry.content ?? entry.value ?? "").trim();
+}
+/**
+ * The public description is ONLY an explicit `kind="description"` soul.
+ *
+ * There is deliberately no fallback to "the first soul with any content": that
+ * was the ops-vz6j leak — an agent with no description soul would publish an
+ * arbitrary private soul on the unauthenticated card. Absent an explicit
+ * description, publish nothing.
+ */
+export function selectPublicDescription(souls) {
+    const entry = souls.find((s) => readSoulKind(s) === "description" && readSoulContent(s));
+    return entry ? readSoulContent(entry) : "";
+}
+/**
+ * Public skills are ONLY `kind="capability"` souls — an explicit, operator-
+ * intended allow-list. Any other soul kind is never published.
+ */
+export function selectPublicSkills(souls) {
+    return souls
+        .filter((s) => readSoulKind(s) === "capability")
+        .map((s) => readSoulContent(s))
+        .filter(Boolean);
+}

package/dist/resources/auth-middleware.js

@@ -142,7 +142,7 @@ server.http(async (request, nextLayer) => {
         // and inline JS, with no embedded data. The JS prompts for admin-pass and
         // auths every API call (/Agent, /SemanticSearch, /FederationPeers, etc).
         // Without this allow-list entry, the HTML is 401-blocked on hosted Flair
-        // instances (rockit-local works only because authorizeLocal=true).
+        // instances (a localhost caller works only because authorizeLocal=true).
         url.pathname === "/ObservationCenter")
         return nextLayer(request);
     // If Harper has already authorized this request (e.g. authorizeLocal=true on localhost),
@@ -272,32 +272,34 @@ server.http(async (request, nextLayer) => {
     request.tpsAgent = agentId;
     request._tpsAuthVerified = true;
     request.tpsAgentIsAdmin = await isAdmin(agentId);
-    // Swap the Authorization header to Basic admin auth so Harper's internal auth
-    // pipeline (passport) authenticates the request with full permissions including
-    // HNSW vector search. This requires HDB_ADMIN_PASSWORD to be set.
-    // NOTE: server.getUser() alone doesn't grant HNSW permissions in Harper v5.
-    const adminPass = getAdminPass();
-    if (adminPass !== null) {
-        try {
-            const superAuth = "Basic " + btoa("admin:" + adminPass);
-            request.headers.set("authorization", superAuth);
-            if (request.headers.asObject)
-                request.headers.asObject.authorization = superAuth;
-        }
-        catch {
-            // Header manipulation failed — fall back to getUser
-            try {
-                request.user = await server.getUser("admin", null, request);
-            }
-            catch { }
-        }
+    // Grant Harper-level permissions for the cryptographically-verified agent by
+    // setting request.user directly to the admin super_user.
+    //
+    // Prior approach swapped the Authorization header to "Basic admin:<pass>" so
+    // Harper's auth pipeline would re-authenticate with full (HNSW-capable)
+    // permissions. That silently broke under Harper 5.0.9: its authentication
+    // layer (security/auth.ts `authentication()`) reads the Authorization header
+    // and resolves request.user BEFORE invoking this middleware via nextHandler.
+    // A TPS-Ed25519 header matches no Basic/Bearer strategy, so Harper sets
+    // request.user = null and never re-reads the header — our post-hoc swap was
+    // ignored, the request ran unauthenticated, and Harper surfaced it downstream
+    // as a generic "Login failed" 401. (Broke at the 2026-05-27 daemon restart,
+    // which loaded 5.0.9 fresh; the prior long-running process held an older
+    // in-memory Harper where the late header read still worked.)
+    //
+    // Setting request.user directly is the supported extension path and is honored
+    // by all downstream resources, including HNSW vector search. getUser(admin,
+    // null) looks up the admin record WITHOUT password validation — safe here
+    // because the Ed25519 signature verified above already proves agent identity
+    // cryptographically; no Basic credential is presented. This preserves the
+    // prior privilege model (verified agents act with admin perms; per-agent data
+    // isolation is still enforced downstream via the x-tps-agent header below).
+    try {
+        request.user = await server.getUser("admin", null, request);
     }
-    else {
-        // No admin password configured — try server.getUser as fallback (limited permissions)
-        try {
-            request.user = await server.getUser("admin", null, request);
-        }
-        catch { }
+    catch {
+        // Admin record unavailable — request proceeds as the verified tpsAgent
+        // without elevated perms; resource-level scoping still applies.
     }
     // Propagate authenticated agent to downstream resources via header.
     // Resources can read this to enforce agent-level scoping.

package/dist/resources/health.js

@@ -23,10 +23,10 @@ const exists = async (path) => {
  * which is what makes /Health work for callers outside `authorizeLocal`'s
  * localhost-bypass. Without this, Harper's intrinsic Basic-auth gate fires
  * BEFORE our HTTP middleware can apply the /Health bypass list in
- * auth-middleware.ts, so remote callers (e.g., from rockit hitting a Fabric-
+ * auth-middleware.ts, so remote callers (e.g., from a remote host hitting a Fabric-
  * hosted Flair) get a 401 even though the Resource handler is intentionally
  * unauthenticated. Symptom matched: Fabric returned 401 + WWW-Authenticate:
- * Basic on /Health while rockit-localhost returned 200 — the difference was
+ * Basic on /Health while a localhost caller returned 200 — the difference was
  * Harper's localhost-auto-auth, not anything in our code.
  *
  * Same pattern as `FederationPair.allowCreate(){ return true }` (PR #299):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",
   "license": "Apache-2.0",
@@ -55,7 +55,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@harperfast/harper": "5.0.9",
+    "@harperfast/harper": "5.0.21",
     "@types/js-yaml": "^4.0.9",
     "commander": "14.0.3",
     "harper-fabric-embeddings": "0.2.3",
@@ -64,6 +64,15 @@
     "tar": "^7.5.13",
     "tweetnacl": "1.0.3"
   },
+  "optionalDependencies": {
+    "@node-llama-cpp/linux-arm64": "3.18.1",
+    "@node-llama-cpp/linux-armv7l": "3.18.1",
+    "@node-llama-cpp/linux-x64": "3.18.1",
+    "@node-llama-cpp/mac-arm64-metal": "3.18.1",
+    "@node-llama-cpp/mac-x64": "3.18.1",
+    "@node-llama-cpp/win-arm64": "3.18.1",
+    "@node-llama-cpp/win-x64": "3.18.1"
+  },
   "devDependencies": {
     "@playwright/test": "^1.59.1",
     "@types/node": "24.11.0",

package/schemas/schema.graphql

@@ -2,7 +2,7 @@
 # ─── Observatory tables ───────────────────────────────────────────────────────
 
 type ObsOffice @table(database: "flair") @export {
-  id: ID @primaryKey        # e.g. "rockit"
+  id: ID @primaryKey        # e.g. "office1"
   name: String!
   publicKey: String!        # Ed25519 hex public key for auth verification
   status: String @indexed   # "online" | "offline" | "degraded"