@tpsdev-ai/flair 0.10.0 → 0.11.0

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}`);
             }
@@ -3399,24 +3454,35 @@ export async function runFederationSyncOnce(opts) {
         }
         let totalBatches = 0;
         for (const table of tables) {
-            let res;
-            try {
-                res = await fetch(`${opsEndpoint}/`, {
-                    method: "POST",
-                    headers: { "Content-Type": "application/json", Authorization: auth },
-                    body: JSON.stringify({ operation: "search_by_conditions", schema: "flair", table, operator: "and", conditions: [{ search_attribute: "updatedAt", search_type: "greater_than", search_value: since }], get_attributes: ["*"] }),
-                    signal: AbortSignal.timeout(15_000),
-                });
-            }
-            catch (err) {
-                return { pushed: totalMerged, skipped: totalSkipped, error: err instanceof Error ? err : new Error(String(err)) };
-            }
-            if (!res.ok) {
-                const text = await res.text().catch(() => "");
-                return { pushed: totalMerged, skipped: totalSkipped, error: new Error(`SQL query failed (${res.status}): ${text}`) };
+            let rows = [];
+            for (const query of [
+                { search_attribute: "updatedAt", search_type: "greater_than", search_value: since },
+                // Rows with null updatedAt (legacy direct-insert rows) use createdAt.
+                // COALESCE(updatedAt, createdAt) > since → pick up null-updatedAt rows
+                // whose createdAt > since. Filtered in JS below.
+                { search_attribute: "updatedAt", search_type: "equals", search_value: null },
+            ]) {
+                let res;
+                try {
+                    res = await fetch(`${opsEndpoint}/`, {
+                        method: "POST",
+                        headers: { "Content-Type": "application/json", Authorization: auth },
+                        body: JSON.stringify({ operation: "search_by_conditions", schema: "flair", table, operator: "and", conditions: [query], get_attributes: ["*"] }),
+                        signal: AbortSignal.timeout(15_000),
+                    });
+                }
+                catch (err) {
+                    return { pushed: totalMerged, skipped: totalSkipped, error: err instanceof Error ? err : new Error(String(err)) };
+                }
+                if (!res.ok) {
+                    const text = await res.text().catch(() => "");
+                    return { pushed: totalMerged, skipped: totalSkipped, error: new Error(`SQL query failed (${res.status}): ${text}`) };
+                }
+                const batch = await res.json();
+                // For null-updatedAt rows, use createdAt as the effective timestamp.
+                // Skip rows created before the last sync cursor.
+                rows = rows.concat(batch.filter((r) => r.updatedAt !== null || r.createdAt > since));
             }
-            // Stream-collect records into batches
-            const rows = await res.json();
             if (rows.length === 0)
                 continue;
             let batch = [];
@@ -3473,6 +3539,31 @@ export async function runFederationSyncOnce(opts) {
             console.warn(`⚠️  Local hub.lastSyncAt advance error: ${advErr?.message ?? advErr}. Next poll will re-send memories.`);
         }
         if (totalBatches === 0) {
+            // ops-c7t9: no-change syncs must still ping the hub so it updates the
+            // spoke's lastSyncAt (liveness). Without this, idle-but-alive spokes
+            // look indistinguishable from dead ones on the hub dashboard.
+            try {
+                if (!secretKey)
+                    secretKey = await loadInstanceSecretKey(instance.id, opts);
+                const pingBody = signBodyFresh({
+                    instanceId: instance.id,
+                    records: [],
+                    lamportClock: Date.now(),
+                }, secretKey);
+                const pingRes = await fetch(`${hubUrl}/FederationSync`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify(pingBody),
+                    signal: AbortSignal.timeout(10_000),
+                });
+                if (!pingRes.ok) {
+                    const txt = await pingRes.text().catch(() => "");
+                    console.warn(`⚠️  Liveness ping to hub failed (${pingRes.status}): ${txt.slice(0, 200)}. Hub won't update spoke liveness.`);
+                }
+            }
+            catch (pingErr) {
+                console.warn(`⚠️  Liveness ping error: ${pingErr?.message ?? pingErr}. Hub won't update spoke liveness.`);
+            }
             console.log("No changes since last sync.");
             return { pushed: 0, skipped: 0 };
         }
@@ -4693,7 +4784,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 +7060,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;
@@ -8760,9 +8851,74 @@ program
         process.exit(1);
     }
 });
+// ─── flair presence ─────────────────────────────────────────────────────────
+const VALID_PRESENCE_ACTIVITIES = ["coding", "reviewing", "planning", "idle"];
+const MAX_TASK_LENGTH = 120;
+const presence = program.command("presence").description("Manage agent presence (The Office Space)");
+presence
+    .command("set")
+    .description("Set your agent's current activity and task (POST /Presence)")
+    .option("--activity <activity>", `Activity type (${VALID_PRESENCE_ACTIVITIES.join("|")})`)
+    .option("--task <text>", "Short description of what you're working on")
+    .option("--agent <id>", "Agent ID (env: FLAIR_AGENT_ID)")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
+    .action(async (opts) => {
+    const agentId = resolveAgentIdOrEnv(opts);
+    if (!agentId) {
+        console.error("Error: agent ID required. Pass --agent <id> or set FLAIR_AGENT_ID environment variable.");
+        process.exit(1);
+    }
+    // Validate activity
+    if (!opts.activity) {
+        console.error("Error: --activity is required.");
+        process.exit(1);
+    }
+    const activity = opts.activity;
+    if (!VALID_PRESENCE_ACTIVITIES.includes(activity)) {
+        console.error(`Error: invalid activity '${activity}'. Must be one of: ${VALID_PRESENCE_ACTIVITIES.join(", ")}`);
+        process.exit(1);
+    }
+    // Validate task length
+    const task = opts.task ?? undefined;
+    if (task && task.length > MAX_TASK_LENGTH) {
+        console.error(`Error: --task exceeds ${MAX_TASK_LENGTH} character limit (got ${task.length}).`);
+        process.exit(1);
+    }
+    // Resolve key path
+    const keyPath = resolveKeyPath(agentId);
+    if (!keyPath) {
+        console.error(`Error: private key not found for agent '${agentId}'. Check ~/.flair/keys/ or set FLAIR_KEY_DIR.`);
+        process.exit(1);
+    }
+    // Build auth + POST
+    const baseUrl = resolveBaseUrl(opts).replace(/\/$/, "");
+    const auth = buildEd25519Auth(agentId, "POST", "/Presence", keyPath);
+    const body = { activity };
+    if (task)
+        body.currentTask = task;
+    const res = await fetch(`${baseUrl}/Presence`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: auth,
+        },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        console.error(`Error: POST /Presence failed (${res.status}): ${text}`);
+        process.exit(1);
+    }
+    const data = await res.json().catch(() => null);
+    console.log(`✓ Presence updated for '${agentId}': activity=${activity}${task ? `, task="${task}"` : ""}`);
+    if (data?.presenceStatus) {
+        console.log(`  Status: ${data.presenceStatus}`);
+    }
+});
 // Run CLI only when this is the entry point (not when imported for testing)
 if (import.meta.main) {
     await program.parseAsync();
 }
 // ─── Exported for testing ─────────────────────────────────────────────────────
-export { resolveKeyPath, buildEd25519Auth, readPortFromConfig, resolveHttpPort, resolveOpsPort, resolveTarget, resolveOpsTarget, resolveEffectiveOpsUrl, resolveOpsUrlFromTarget, signRequestBody, b64, b64url, program, api, isLocalBase, isLikelyRealSecret, shouldShowInlineSecretWarning, parseTokenFromFile, };
+export { resolveKeyPath, buildEd25519Auth, readPortFromConfig, resolveHttpPort, resolveOpsPort, resolveTarget, resolveOpsTarget, resolveEffectiveOpsUrl, resolveOpsUrlFromTarget, signRequestBody, b64, b64url, program, api, VALID_PRESENCE_ACTIVITIES, MAX_TASK_LENGTH, isLocalBase, isLikelyRealSecret, shouldShowInlineSecretWarning, parseTokenFromFile, };

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/Presence.js

@@ -0,0 +1,270 @@
+/**
+ * POST /Presence — agent heartbeat writes its own presence.
+ * GET  /Presence — public-safe presence roster for The Office Space.
+ *
+ * Extends the auto-generated Presence table resource (from schema.graphql).
+ * Overrides get() for public-safe roster and post() for Ed25519-authed
+ * heartbeat writes.
+ *
+ * Auth:
+ *   GET  — public (returns only allowlisted fields; safe for public renderer).
+ *   POST — Ed25519 agent credential (TPS-Ed25519 header). Agent writes only its
+ *          own record; cross-agent writes are rejected (403).
+ *
+ * Security (Sherlock):
+ *   - Write: per-agent Ed25519 auth. Cross-agent → 403.
+ *   - Read: field-allowlisted to public-safe set. No secrets, no admin data.
+ *   - currentTask is agent-authored free text → cap length, escape on render.
+ */
+import { databases } from "@harperfast/harper";
+// ─── Constants ────────────────────────────────────────────────────────────────
+const WINDOW_MS = 30_000;
+const CURRENT_TASK_MAX_LENGTH = 200;
+const VALID_ACTIVITIES = new Set(["coding", "reviewing", "planning", "idle"]);
+function idleThresholdMs() {
+    const env = process.env.PRESENCE_IDLE_THRESHOLD_MS;
+    return env ? Number(env) || 90_000 : 90_000;
+}
+function offlineThresholdMs() {
+    const env = process.env.PRESENCE_OFFLINE_THRESHOLD_MS;
+    return env ? Number(env) || 600_000 : 600_000;
+}
+// ─── Nonce replay protection ──────────────────────────────────────────────────
+const nonceSeen = new Map();
+function pruneNonces() {
+    const now = Date.now();
+    for (const [k, ts] of nonceSeen.entries()) {
+        if (now - ts > WINDOW_MS)
+            nonceSeen.delete(k);
+    }
+}
+// ─── Crypto helpers ───────────────────────────────────────────────────────────
+function b64ToArrayBuffer(b64) {
+    const std = b64.replace(/-/g, "+").replace(/_/g, "/");
+    const bin = atob(std);
+    const buf = new ArrayBuffer(bin.length);
+    const view = new Uint8Array(buf);
+    for (let i = 0; i < bin.length; i++)
+        view[i] = bin.charCodeAt(i);
+    return buf;
+}
+const keyCache = new Map();
+async function importEd25519Key(publicKeyStr) {
+    if (keyCache.has(publicKeyStr))
+        return keyCache.get(publicKeyStr);
+    let raw;
+    if (/^[0-9a-f]{64}$/i.test(publicKeyStr)) {
+        const bytes = new Uint8Array(32);
+        for (let i = 0; i < 32; i++)
+            bytes[i] = parseInt(publicKeyStr.slice(i * 2, i * 2 + 2), 16);
+        raw = bytes.buffer;
+    }
+    else {
+        raw = b64ToArrayBuffer(publicKeyStr);
+    }
+    const key = await crypto.subtle.importKey("raw", raw, { name: "Ed25519" }, false, ["verify"]);
+    keyCache.set(publicKeyStr, key);
+    return key;
+}
+// ─── Status derivation (pure — exported for unit testing) ─────────────────────
+export function derivePresenceStatus(now, lastHeartbeatAt, idleMs, offlineMs) {
+    const idle = idleMs ?? idleThresholdMs();
+    const offline = offlineMs ?? offlineThresholdMs();
+    if (lastHeartbeatAt == null || !Number.isFinite(lastHeartbeatAt))
+        return "offline";
+    const elapsed = now - lastHeartbeatAt;
+    if (elapsed < 0)
+        return "active";
+    if (elapsed < idle)
+        return "active";
+    if (elapsed < offline)
+        return "idle";
+    return "offline";
+}
+// ─── Public-safe field allowlist ──────────────────────────────────────────────
+const ROSTER_ALLOWLIST = new Set([
+    "id",
+    "displayName",
+    "role",
+    "runtime",
+    "activity",
+    "presenceStatus",
+    "currentTask",
+    "lastHeartbeatAt",
+]);
+function sanitizeCurrentTask(task) {
+    if (typeof task !== "string")
+        return null;
+    const trimmed = task.trim();
+    if (trimmed.length === 0)
+        return null;
+    return trimmed.slice(0, CURRENT_TASK_MAX_LENGTH);
+}
+function pickAllowlisted(record) {
+    const out = {};
+    for (const key of Object.keys(record)) {
+        if (ROSTER_ALLOWLIST.has(key))
+            out[key] = record[key];
+    }
+    return out;
+}
+// ─── Resource ─────────────────────────────────────────────────────────────────
+/**
+ * Extends the auto-generated Presence table resource (from schema.graphql) so
+ * Harper resolves the /Presence path without conflict. Overrides get() for the
+ * public-safe roster view and post() for Ed25519-authed heartbeat writes.
+ */
+export class Presence extends databases.flair.Presence {
+    /** Bypass Harper's role gate for GET (public-safe data only). */
+    allowRead() {
+        return true;
+    }
+    /** Bypass Harper's role gate for POST (Ed25519 auth handled internally). */
+    allowCreate() {
+        return true;
+    }
+    /**
+     * GET /Presence — public-safe presence roster.
+     *
+     * Joins Presence records with Agent metadata and derives presenceStatus.
+     * Only allowlisted fields are returned (no secrets, no admin data).
+     */
+    async get() {
+        const now = Date.now();
+        const idleThreshold = idleThresholdMs();
+        const offlineThreshold = offlineThresholdMs();
+        const results = [];
+        try {
+            const presenceRows = databases.flair.Presence.search();
+            for await (const row of presenceRows) {
+                const agentId = row?.agentId;
+                if (!agentId)
+                    continue;
+                let agent = null;
+                try {
+                    agent = await databases.flair.Agent.get(agentId);
+                }
+                catch { /* agent may not exist or be deactivated */ }
+                const entry = {
+                    id: agentId,
+                    displayName: agent?.displayName ?? agent?.name ?? agentId,
+                    role: agent?.role ?? "agent",
+                    runtime: agent?.runtime ?? null,
+                    activity: row?.activity ?? "idle",
+                    presenceStatus: derivePresenceStatus(now, typeof row?.lastHeartbeatAt === "number"
+                        ? row.lastHeartbeatAt
+                        : Number(row?.lastHeartbeatAt ?? 0), idleThreshold, offlineThreshold),
+                    currentTask: sanitizeCurrentTask(row?.currentTask),
+                    lastHeartbeatAt: typeof row?.lastHeartbeatAt === "number"
+                        ? row.lastHeartbeatAt
+                        : Number(row?.lastHeartbeatAt ?? 0),
+                };
+                results.push(pickAllowlisted(entry));
+            }
+        }
+        catch (err) {
+            return new Response(JSON.stringify({ error: "presence_query_failed", detail: err?.message }), { status: 500, headers: { "Content-Type": "application/json" } });
+        }
+        return results;
+    }
+    /**
+     * POST /Presence — agent heartbeat.
+     *
+     * Auth: TPS-Ed25519 header required. agentId from signature, NOT from body.
+     * An agent may update ONLY its own presence; cross-agent writes → 403.
+     *
+     * Bypasses Harper's default table post handler — writes via databases.flair.Presence
+     * directly so we control auth flow end-to-end.
+     */
+    async post(content, context) {
+        const ctx = this.getContext?.();
+        const request = ctx?.request ?? ctx;
+        // ── Parse Ed25519 auth header ────────────────────────────────────────────
+        const authHeader = request?.headers?.get?.("authorization") ??
+            request?.headers?.asObject?.authorization ??
+            "";
+        // If the middleware already verified and set tpsAgent, trust it
+        const middlewareAgent = request?.tpsAgent;
+        let agentId;
+        if (middlewareAgent) {
+            agentId = middlewareAgent;
+        }
+        else {
+            const m = authHeader.match(/^TPS-Ed25519\s+([^:]+):(\d+):([^:]+):(.+)$/);
+            if (!m) {
+                return new Response(JSON.stringify({ error: "Ed25519 agent auth required for heartbeat" }), { status: 401, headers: { "Content-Type": "application/json" } });
+            }
+            const [, headerAgentId, tsRaw, nonce, sigB64] = m;
+            const ts = Number(tsRaw);
+            const now = Date.now();
+            if (!Number.isFinite(ts) || Math.abs(now - ts) > WINDOW_MS) {
+                return new Response(JSON.stringify({ error: "timestamp_out_of_window" }), { status: 401, headers: { "Content-Type": "application/json" } });
+            }
+            pruneNonces();
+            const nonceKey = `${headerAgentId}:${nonce}`;
+            if (nonceSeen.has(nonceKey)) {
+                return new Response(JSON.stringify({ error: "nonce_replay_detected" }), { status: 401, headers: { "Content-Type": "application/json" } });
+            }
+            const agent = await databases.flair.Agent.get(headerAgentId).catch(() => null);
+            if (!agent) {
+                return new Response(JSON.stringify({ error: "unknown_agent" }), { status: 401, headers: { "Content-Type": "application/json" } });
+            }
+            try {
+                // request.url is just the path portion (e.g. "/Presence")
+                const pathname = (request.url ?? "/Presence").split("?")[0];
+                const payload = `${headerAgentId}:${tsRaw}:${nonce}:POST:${pathname}`;
+                const key = await importEd25519Key(agent.publicKey);
+                const sigBuf = b64ToArrayBuffer(sigB64);
+                const payloadBuf = new TextEncoder().encode(payload);
+                const ok = await crypto.subtle.verify({ name: "Ed25519" }, key, sigBuf, payloadBuf);
+                if (!ok) {
+                    return new Response(JSON.stringify({ error: "invalid_signature" }), { status: 401, headers: { "Content-Type": "application/json" } });
+                }
+            }
+            catch (e) {
+                return new Response(JSON.stringify({ error: "signature_verification_failed", detail: e?.message }), { status: 401, headers: { "Content-Type": "application/json" } });
+            }
+            nonceSeen.set(nonceKey, ts);
+            agentId = headerAgentId;
+        }
+        // ── Validate body ────────────────────────────────────────────────────────
+        const { currentTask, activity } = content || {};
+        if (activity !== undefined && !VALID_ACTIVITIES.has(activity)) {
+            return new Response(JSON.stringify({
+                error: "invalid_activity",
+                detail: `activity must be one of: ${[...VALID_ACTIVITIES].join(", ")}`,
+            }), { status: 400, headers: { "Content-Type": "application/json" } });
+        }
+        // ── Write presence ───────────────────────────────────────────────────────
+        const now = Date.now();
+        try {
+            let existing = null;
+            try {
+                existing = await databases.flair.Presence.get(agentId);
+            }
+            catch { /* first heartbeat */ }
+            const record = {
+                agentId,
+                lastHeartbeatAt: now,
+                currentTask: sanitizeCurrentTask(currentTask),
+                activity: activity ?? (existing?.activity ?? "idle"),
+            };
+            if (existing) {
+                const merged = { ...existing, ...record };
+                await databases.flair.Presence.put(merged);
+            }
+            else {
+                await databases.flair.Presence.put(record);
+            }
+            return {
+                ok: true,
+                agentId,
+                lastHeartbeatAt: now,
+                presenceStatus: "active",
+            };
+        }
+        catch (e) {
+            return new Response(JSON.stringify({ error: "presence_write_failed", detail: e?.message }), { status: 500, headers: { "Content-Type": "application/json" } });
+        }
+    }
+}

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

@@ -143,7 +143,11 @@ server.http(async (request, nextLayer) => {
         // 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).
-        url.pathname === "/ObservationCenter")
+        url.pathname === "/ObservationCenter" ||
+        // Presence roster is public-safe (field-allowlisted); GET serves the
+        // Office Space renderer without auth. POST handles Ed25519 auth internally
+        // (allowCreate=true on the Resource).
+        url.pathname === "/Presence")
         return nextLayer(request);
     // If Harper has already authorized this request (e.g. authorizeLocal=true on localhost),
     // trust Harper's auth decision and pass through without requiring additional headers.
@@ -272,32 +276,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.11.0",
   "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

@@ -1,8 +1,17 @@
 
+# ─── Presence table ───────────────────────────────────────────────────────────
+
+type Presence @table(database: "flair") @export {
+  agentId: ID @primaryKey
+  lastHeartbeatAt: BigInt        # unix ms timestamp
+  currentTask: String            # short human string, e.g. "Reviewing flair#467"
+  activity: String @indexed      # "coding" | "reviewing" | "planning" | "idle"
+}
+
 # ─── 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"