@tpsdev-ai/flair 0.10.1 → 0.11.0

package/dist/cli.js

@@ -3454,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 = [];
@@ -3528,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 };
         }
@@ -8815,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/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/auth-middleware.js

@@ -142,8 +142,12 @@ 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 (a localhost caller works only because authorizeLocal=true).
-        url.pathname === "/ObservationCenter")
+        // instances (rockit-local works only because authorizeLocal=true).
+        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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.10.1",
+  "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",

package/schemas/schema.graphql

@@ -1,4 +1,13 @@
 
+# ─── 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 {