@tpsdev-ai/flair 0.21.0 → 0.22.1

package/dist/resources/health.js

@@ -1,8 +1,11 @@
 import { Resource, databases } from "@harperfast/harper";
-import { promises as fsp } from "node:fs";
+import { promises as fsp, existsSync, readFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
-import { join } from "node:path";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { getRerankStatus } from "./rerank-provider.js";
+import { allowVerified, resolveAgentAuth } from "./agent-auth.js";
+import { getMigrationStatusSnapshot } from "./migrations/status.js";
 const db = databases;
 const redactHome = (p) => {
     const home = homedir();
@@ -17,6 +20,35 @@ const exists = async (path) => {
         return false;
     }
 };
+/**
+ * Resolve the runtime package version from package.json (duplicated from
+ * admin-layout.ts / AdminInstance.ts — same "keep in sync" idiom as the
+ * federation-crypto helpers in src/cli.ts; see those two files' comments for
+ * why it's inlined rather than imported). `process.env.npm_package_version`
+ * is only populated inside `npm run`, so reading package.json relative to
+ * THIS running module is the only way to report the version of the code
+ * that's actually executing — which is exactly what `flair upgrade`'s
+ * post-restart verification (flair#635) needs: proof the NEW package is
+ * what's serving, not just what landed on disk before a restart.
+ */
+function resolveVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const candidates = [
+            join(here, "..", "..", "package.json"),
+            join(here, "..", "package.json"),
+        ];
+        for (const p of candidates) {
+            if (existsSync(p)) {
+                const pkg = JSON.parse(readFileSync(p, "utf-8"));
+                if (pkg.version)
+                    return pkg.version;
+            }
+        }
+    }
+    catch { /* fall through */ }
+    return process.env.npm_package_version ?? "dev";
+}
 /**
  * Health endpoint — truly public, returns only { ok: true }.
  *
@@ -45,25 +77,57 @@ export class Health extends Resource {
         return true;
     }
     async get() {
-        return { ok: true };
+        // `version` (flair#695, the CLI↔server handshake — src/version-handshake.ts):
+        // exposed on the PUBLIC endpoint deliberately, so the check works even
+        // before an agent identity/key exists (fresh install, pre-`flair init`).
+        // Sherlock verdict: fine while locally bound; if /Health is ever fronted
+        // PUBLICLY over Fabric, the public surface must omit this field (the
+        // richer, auth-gated /HealthDetail already carried version pre-existing —
+        // this only adds it to the anonymous endpoint too).
+        return { ok: true, version: resolveVersion() };
     }
 }
 /**
  * Authenticated health detail — returns memory/agent/soul stats + process info.
  * Requires Ed25519 agent auth or admin basic auth.
  *
+ * allowRead()=allowVerified (authorizeLocal-escalation-class follow-up to
+ * #601/#604/#609/#612 — flair#614's backstop found this resource had NO
+ * allow* at all, despite this docstring's stated intent). Harper's own
+ * default (`user?.role.permission.super_user`, satisfiable only by a genuine
+ * admin OR authorizeLocal's forged loopback super_user) was silently
+ * standing in instead. Any verified agent may read — get() below still
+ * filters sensitive fields (peer/OAuth-client lists, absolute paths, full
+ * agent roster) down to admin-only.
+ *
  * Every optional-subsystem lookup is wrapped so a missing table or absent
  * schema downgrades to "not configured" rather than failing the whole call.
  */
 export class HealthDetail extends Resource {
+    async allowRead() {
+        return allowVerified(this.getContext?.());
+    }
     async get() {
         const stats = { ok: true };
         const nowMs = Date.now();
         const warnings = [];
         const ctx = this.getContext?.();
-        const request = ctx?.request ?? ctx;
-        const callerAgent = request?.tpsAgent;
-        const isAdmin = request?.tpsAgentIsAdmin === true || !callerAgent;
+        // #614 fix: resolve identity via the shared three-way verdict
+        // (internal/agent/anonymous — agent-auth.ts) instead of reading
+        // tpsAgent/tpsAgentIsAdmin off the raw request directly. The OLD
+        // computation was `request?.tpsAgentIsAdmin === true || !callerAgent` —
+        // the `|| !callerAgent` half meant an UNRESOLVED caller (no tpsAgent at
+        // all — i.e. anonymous) defaulted to isAdmin=TRUE, backwards from every
+        // other resource in this codebase and the opposite of fail-safe.
+        // allowRead() above already denies a genuine anonymous HTTP caller
+        // before get() ever runs; this fixes the internal computation to match
+        // (defense-in-depth, and correct semantics if get() is ever reached
+        // another way). Only a true "internal" verdict (no HTTP request at all —
+        // a programmatic/in-process call) or a verified admin agent is isAdmin;
+        // an unresolved/anonymous HTTP caller is never treated as admin.
+        const auth = await resolveAgentAuth(ctx);
+        const callerAgent = auth.kind === "agent" ? auth.agentId : undefined;
+        const isAdmin = auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin);
         stats.caller = { agentId: callerAgent ?? null, isAdmin };
         let memoriesList = [];
         // ── Memory stats ──
@@ -435,6 +499,29 @@ export class HealthDetail extends Resource {
         catch {
             stats.rem = null;
         }
+        // ── Migrations (flair#695: zero-touch boot-keyed auto-migration) ──
+        // `{ id, rowsDone, rowsRemaining, state }` per registered migration, per
+        // flair#695 §A. `cyclePhase: "pre-hash"` is the
+        // "pre-flight integrity check in progress" state the K&S verdict calls
+        // for; a halted migration surfaces here (with `reason`) AND as a
+        // warning below so it's visible without a separate lookup.
+        try {
+            const migrationsDataDir = process.env.HDB_ROOT ?? join(homedir(), ".flair", "data");
+            const snapshot = getMigrationStatusSnapshot(migrationsDataDir);
+            stats.migrations = {
+                cyclePhase: snapshot.cyclePhase,
+                lastCycleAt: snapshot.lastCycleAt ?? null,
+                migrations: snapshot.migrations,
+            };
+            for (const m of snapshot.migrations) {
+                if (m.state === "halted" || m.state === "failed") {
+                    warnings.push({ level: "warn", message: `migration '${m.id}' ${m.state}${m.reason ? `: ${m.reason}` : ""} — see \`flair doctor\`` });
+                }
+            }
+        }
+        catch {
+            stats.migrations = null;
+        }
         // ── Disk ──
         try {
             const dataDir = process.env.HDB_ROOT ?? join(homedir(), ".flair", "data");
@@ -535,6 +622,10 @@ export class HealthDetail extends Resource {
         // ── Warnings ──
         stats.warnings = warnings;
         // ── Process info ──
+        // version: the RUNNING process's own package.json — used by `flair
+        // upgrade`'s post-restart verification (flair#635) to prove the new
+        // code is actually serving, not just installed on disk.
+        stats.version = resolveVersion();
         stats.pid = process.pid;
         stats.uptimeSeconds = Math.floor(process.uptime());
         return stats;

package/dist/resources/mcp-client-metadata-fields.js

@@ -0,0 +1,112 @@
+/**
+ * Client ID Metadata Document (CIMD) field logic for Flair agent identities.
+ *
+ * Produces the JSON metadata document an OAuth authorization server fetches
+ * when a client_id is an HTTPS URL — draft-ietf-oauth-client-id-metadata-
+ * document-00, adopted by the MCP draft authorization spec IN PLACE OF DCR
+ * (no registration row to create or replicate across nodes; the served
+ * document IS the registration).
+ *
+ * Shape is pinned to HarperFast/oauth **issue #161** ("client_credentials
+ * (2/4): CIMD-first client resolution for private_key_jwt agents") — the
+ * FORMAL shape spec for this document, shipped in @harperfast/oauth@2.2.0
+ * via PR #170 (with #167's CIMD resolution layer). #161 requires:
+ *
+ *   - `grant_types: ["client_credentials"]`;
+ *     `token_endpoint_auth_method: "private_key_jwt"`.
+ *   - `jwks` = JWK Set of PUBLIC OKP/Ed25519 keys ONLY — reject any key
+ *     carrying a private `d`, reject empty sets, reject non-OKP/non-Ed25519
+ *     keys.
+ *   - client_credentials-only clients carry NEITHER `redirect_uris` NOR
+ *     `response_types` — #161 explicitly blesses this as a documented
+ *     deviation from the CIMD draft's general required-fields list (which
+ *     includes `redirect_uris` for interactive/DCR-style clients).
+ *   - `client_credentials` combined with `refresh_token` is rejected.
+ *   - Security gate (AS-side, enforced by the plugin, documented here for
+ *     deployment coordination): `clientIdMetadataDocuments.allowedHosts`
+ *     MUST be configured and this document's `client_id` host MUST be on
+ *     it — merely hosting a reachable document must never be sufficient to
+ *     mint tokens. Replaces the old DCR `initialAccessToken` gate.
+ *
+ * The AS-side machinery consuming this document (fetch/validate/cache —
+ * #167's CIMD resolution layer, extended by #170 for client_credentials +
+ * private_key_jwt) is SHIPPED in the published @harperfast/oauth@2.2.0.
+ * This module's output is proven against that real published code — not a
+ * mirror — in test/unit/mcp-client-credentials-live-package.test.ts, which
+ * drives 2.2.0's actual `resolveCimdClient` pipeline (via its exported
+ * `_setDnsLookup`/`_setFetch` test hooks) and confirms the document
+ * resolves and validates end-to-end, plus the fail-closed negatives (no
+ * `allowedHosts` configured → rejected; leaked private `d` in a JWK →
+ * rejected by the plugin even if our own build-time guard were bypassed).
+ *
+ * Kept free of any @harperfast/harper import (mirrors agentcard-fields.ts)
+ * so the document shape is unit-testable without spinning up Harper.
+ */
+/** The grant this agent's CIMD document targets — formalized by oauth#161, accepted by the published 2.2.0 validator. See module header. */
+export const CIMD_TARGET_GRANT_TYPES = ["client_credentials"];
+/** The auth method this agent's CIMD document targets — formalized by oauth#161, accepted by the published 2.2.0 validator. See module header. */
+export const CIMD_TARGET_AUTH_METHOD = "private_key_jwt";
+/** Build a Client ID Metadata Document for a headless Flair agent. */
+export function buildCimdDocument(params) {
+    const { clientId, clientName, jwk } = params;
+    if (!clientId)
+        throw new Error("clientId is required");
+    if (!clientName)
+        throw new Error("clientName is required");
+    if (!jwk || jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || typeof jwk.x !== "string" || !jwk.x) {
+        throw new Error("jwk must be a public Ed25519 JWK ({kty:'OKP', crv:'Ed25519', x:'...'})");
+    }
+    // Belt-and-suspenders (oauth#161: "reject any key carrying private `d`").
+    // Ed25519Jwk's TS type has no `d` field, so a well-typed caller can't
+    // construct one — but this function's argument still crosses a runtime
+    // boundary (a JWK read from disk/network, or a caller using `as any`), so
+    // check for it explicitly rather than trust the type alone. A CIMD
+    // document is fetched by an unauthenticated AS over the public internet;
+    // there is no scenario where leaking `d` here is acceptable.
+    if (typeof jwk.d !== "undefined") {
+        throw new Error("jwk must be a PUBLIC key — refusing to build a CIMD document from a JWK carrying a private 'd' component");
+    }
+    return {
+        client_id: clientId,
+        client_name: clientName,
+        // Exactly one key, always non-empty and always OKP/Ed25519 — both are
+        // structurally guaranteed by the validation above (oauth#161 also
+        // requires rejecting an EMPTY jwks set and non-OKP/non-Ed25519 keys;
+        // this function's single-already-validated-jwk API makes both
+        // impossible to violate from here).
+        jwks: { keys: [jwk] },
+        // pending oauth#161 — rejected by today's open-draft #167 validator; see module header.
+        token_endpoint_auth_method: CIMD_TARGET_AUTH_METHOD,
+        grant_types: [...CIMD_TARGET_GRANT_TYPES],
+        // redirect_uris AND response_types are both deliberately omitted — #161
+        // blesses this explicitly for client_credentials-only CIMD clients (no
+        // redirect-based flow is ever possible for a headless agent). Neither
+        // field is declared on CimdDocument, so neither can slip back in via
+        // this object literal.
+    };
+}
+/**
+ * Normalize a Flair `Agent.publicKey` value into a JWK OKP `x`. Accepts both
+ * encodings `Agent.publicKey` is written in across this repo (hex 64-char,
+ * or base64/base64url 44-char raw 32-byte key) — the same two forms
+ * resources/ed25519-auth.ts's `importEd25519Key` accepts, so a document
+ * built from this always matches what the verified-request path already
+ * treats as the agent's key.
+ */
+export function agentPublicKeyToJwk(publicKeyStr, kid) {
+    const trimmed = (publicKeyStr ?? "").trim();
+    let raw;
+    if (/^[0-9a-f]{64}$/i.test(trimmed)) {
+        raw = Buffer.from(trimmed, "hex");
+    }
+    else {
+        raw = Buffer.from(trimmed.replace(/-/g, "+").replace(/_/g, "/"), "base64");
+    }
+    if (raw.length !== 32) {
+        throw new Error(`agent public key must decode to 32 bytes (got ${raw.length})`);
+    }
+    const jwk = { kty: "OKP", crv: "Ed25519", x: raw.toString("base64url") };
+    if (kid)
+        jwk.kid = kid;
+    return jwk;
+}

package/dist/resources/mcp-handler.js

@@ -1,7 +1,7 @@
 /**
  * mcp-handler.ts — the Model-2 custom MCP protocol handler.
  *
- * A minimal in-process MCP (JSON-RPC 2.0) handler serving the 9 curated flair
+ * A minimal in-process MCP (JSON-RPC 2.0) handler serving the 12 curated flair
  * tools over Streamable HTTP. It is wrapped by `@harperfast/oauth`'s
  * `withMCPAuth` (see mcp-oauth.ts), which fails closed on any missing/invalid
  * Bearer token BEFORE this handler runs and, on success, sets

package/dist/resources/mcp-tools.js

@@ -1,17 +1,20 @@
 /**
- * mcp-tools.ts — the 10 curated flair tools for the Model-2 custom /mcp handler.
+ * mcp-tools.ts — the 12 curated flair tools for the Model-2 custom /mcp handler.
  *
- * Curated BY CONSTRUCTION: this module implements exactly the 10 tools that the
- * `@tpsdev-ai/flair-mcp` stdio proxy exposes, each a thin wrapper over the
- * existing flair Resource handler. No business logic is re-implemented — the
- * wrapped handlers (Memory / SemanticSearch / BootstrapMemories / Soul /
- * WorkspaceState / OrgEvent) enforce per-agent scoping/ownership via
- * `resolveAgentAuth(getContext())`, so the MCP surface inherits the SAME security
- * model as the signed-REST path. There is no raw CRUD surface — the only way to
- * reach the datastore through /mcp is via one of these 10 semantic tools.
+ * Curated BY CONSTRUCTION: this module implements a fixed set of tools, each a
+ * thin wrapper over the existing flair Resource handler. No business logic is
+ * re-implemented — the wrapped handlers (Memory / SemanticSearch /
+ * BootstrapMemories / Soul / WorkspaceState / OrgEvent / AttentionQuery /
+ * RecordUsage) enforce per-agent scoping/ownership via
+ * `resolveAgentAuth(getContext())` (or, for `attention`, AttentionQuery's own
+ * per-source scoping — see resources/AttentionQuery.ts's module doc), so the
+ * MCP surface inherits the SAME security model as the signed-REST path. There
+ * is no raw CRUD surface — the only way to reach the datastore through /mcp is
+ * via one of these 12 semantic tools.
  *
  *   memory_search · memory_store · memory_update · memory_get · memory_delete ·
- *   bootstrap · soul_set · soul_get · flair_workspace_set · flair_orgevent
+ *   bootstrap · soul_set · soul_get · flair_workspace_set · flair_orgevent ·
+ *   attention · record_usage
  *
  * ── The scoping seam ────────────────────────────────────────────────────────
  * The /mcp handler resolves the OAuth token's `sub` → a flair `Agent` id, then
@@ -21,6 +24,16 @@
  * agent exactly as an Ed25519-signed REST call would. Identity ALWAYS comes from
  * the resolved agent, never from the tool arguments — an agent can only act as
  * itself (no forging of agentId / authorId in the body).
+ *
+ * NOTE (flair#677 scope call): the legacy `@tpsdev-ai/flair-mcp` stdio proxy
+ * (packages/flair-mcp) is a SEPARATE, independently-published package that
+ * talks to flair over HTTP via `FlairClient` — it is not wired through this
+ * registry at all (its own tool list is hardcoded in packages/flair-mcp/src/
+ * index.ts). Per the zero-install north star (retiring flair-mcp in favor of
+ * this native /mcp handler), `attention` is added HERE only, not mirrored into
+ * the legacy stdio proxy — adding it there would mean a separate package
+ * version bump + a new FlairClient method, out of scope for this query-only
+ * slice.
  */
 const H = {};
 const LOADERS = {
@@ -30,6 +43,8 @@ const LOADERS = {
     Soul: async () => (await import("./Soul.js")).Soul,
     WorkspaceState: async () => (await import("./WorkspaceState.js")).WorkspaceState,
     OrgEvent: async () => (await import("./OrgEvent.js")).OrgEvent,
+    AttentionQuery: async () => (await import("./AttentionQuery.js")).AttentionQuery,
+    RecordUsage: async () => (await import("./RecordUsage.js")).RecordUsage,
 };
 /** Resolve a handler class — from the test override if set, else lazy-load + cache. */
 async function handler(key) {
@@ -188,6 +203,7 @@ async function bootstrap(agent, args) {
         channel: args?.channel,
         surface: args?.surface,
         subjects: args?.subjects,
+        entities: args?.entities,
     }));
 }
 async function soulSet(agent, args) {
@@ -249,6 +265,28 @@ async function orgEvent(agent, args) {
         body.targetIds = args.targets;
     return unwrap(await h.post(body));
 }
+async function attention(agent, args) {
+    const Cls = await handler("AttentionQuery");
+    const h = new Cls(undefined, delegationContext(agent));
+    return unwrap(await h.post({ entity: args?.entity, days: args?.days }));
+}
+/**
+ * record_usage (flair#683) — report that memory(ies) were actually used
+ * (cited/grounded an answer or decision), driving the usage-feedback signal
+ * (Memory.usageCount → usageBoost → compositeScore). Distinct from search:
+ * calling memory_search does NOT count as usage — this tool is the explicit,
+ * verified-use report resources/RecordUsage.ts's module doc describes.
+ * Identity is the RESOLVED agent (delegationContext), never forgeable via
+ * args — same no-forge contract as every other write tool here.
+ */
+async function recordUsage(agent, args) {
+    const Cls = await handler("RecordUsage");
+    const h = new Cls(undefined, delegationContext(agent));
+    const memoryIds = Array.isArray(args?.memoryIds)
+        ? args.memoryIds
+        : typeof args?.memoryId === "string" ? [args.memoryId] : undefined;
+    return unwrap(await h.post({ memoryIds, attribution: args?.attribution }));
+}
 export const TOOLS = {
     memory_search: {
         def: {
@@ -340,6 +378,11 @@ export const TOOLS = {
                     channel: { type: "string", description: "Channel name (discord, tps-mail, claude-code)" },
                     surface: { type: "string", description: "Surface name (tps-build, tps-review, cli-session)" },
                     subjects: { type: "array", items: { type: "string" }, description: "Entity names to preload context for" },
+                    entities: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Your declared attention-plane vocabulary strings (e.g. \"issue:owner/repo#123\") for collision surfacing's 'Others in the room' block — teammates with overlapping active work. Falls back to your own most-recent workspace-state entities when omitted.",
+                    },
                 },
             },
         },
@@ -410,6 +453,41 @@ export const TOOLS = {
         },
         impl: orgEvent,
     },
+    attention: {
+        def: {
+            name: "attention",
+            description: "What's touching entity E in the last N days? A unified, grouped-by-source view across memories, " +
+                "relationships, active work (WorkspaceState), teammate presence, and org events. Entity must be a " +
+                "vocabulary string (e.g. 'repo:owner/name', 'issue:owner/repo#123', 'subsystem:embeddings').",
+            annotations: { readOnlyHint: true },
+            inputSchema: {
+                type: "object",
+                properties: {
+                    entity: { type: "string", description: "Vocabulary string, exact match (type:value — e.g. 'repo:tpsdev-ai/flair')" },
+                    days: { type: "number", description: "Window size in days (default 7)" },
+                },
+                required: ["entity"],
+            },
+        },
+        impl: attention,
+    },
+    record_usage: {
+        def: {
+            name: "record_usage",
+            description: "Report that one or more memories were actually USED — cited or relied on to ground an answer or decision. " +
+                "Distinct from search (surfacing a memory is not usage). Drives the recall-quality usage signal; dedup'd " +
+                "(you can only count once per memory) and rate-limited.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    memoryIds: { type: "array", items: { type: "string" }, description: "IDs of the memories that were used (max 20 per call)" },
+                    memoryId: { type: "string", description: "Convenience alias for a single memory id (use memoryIds for multiple)" },
+                    attribution: { type: "string", description: "Optional free-text note on what used it (opaque — stored for audit only, max 500 chars)" },
+                },
+            },
+        },
+        impl: recordUsage,
+    },
 };
 /** The tool definitions for a tools/list response (exactly the 9 curated tools). */
 export function listToolDefs() {