@tpsdev-ai/flair 0.44.4 → 0.44.6

package/dist/cli.js

@@ -23,7 +23,7 @@ import { detectClients, renderWiringSummary, wireClaudeCode, wireCodex, wireGemi
 import { flairCliVersion, clearFlairCliVersionCache, mcpServerSpec, unpinnedSpecWarning } from "./lib/mcp-spec.js";
 import { resolveAgentKeyPath, loadEd25519PrivateKeyFromFile, signClientAssertion, buildTokenRequestForm, getMcpAccessToken, McpTokenRequestError, defaultMcpClientId, defaultMcpTokenEndpoint, defaultMcpResource, defaultMcpIssuer, MAX_ASSERTION_LIFETIME_SECONDS, } from "./mcp-client-assertion.js";
 import { enableMcp, disableMcp, mcpStatus, checkLocalOriginRefusal, selfVerifyMcpMetadata, } from "./lib/mcp-enable.js";
-import { readClientMcpBlock, checkClaudeMdBootstrap, inspectSessionStartHook, upgradeSessionStartHookCommand, fixClaudeMdBootstrap, fixSessionStartHook, applyOrReportClaudeMdBootstrap, applyOrReportSessionStartHook, resolveWireFlairUrl, planAgentIterations, inferSoleAgentId, fixCommandAgentHint, describeAgentGateFinding, embeddingsSkipRemedy, classifyKeyFile, resolveCollisionSafeName, pruneDateStamp, PRUNED_DIR_NAME, } from "./doctor-client.js";
+import { readClientMcpBlock, checkClaudeMdBootstrap, inspectSessionStartHook, upgradeSessionStartHookCommand, fixClaudeMdBootstrap, fixSessionStartHook, applyOrReportClaudeMdBootstrap, applyOrReportSessionStartHook, resolveWireFlairUrl, planAgentIterations, fixCommandAgentHint, isNodeKeyId, partitionKeyIds, resolveFixAgentId, describeAgentGateFinding, embeddingsSkipRemedy, classifyKeyFile, resolveCollisionSafeName, pruneDateStamp, PRUNED_DIR_NAME, } from "./doctor-client.js";
 import { installHook, uninstallHook, hookStatus, isSupportedHarness, SUPPORTED_HARNESSES, } from "./hook-install.js";
 import { readSecretFileSecure, readAdminPassFileSecure, defaultAdminPassPath, defaultKeysDir, resolveLocalAdminPass, resolveKeyPath, buildEd25519Auth, authFetch, KeyLoadError, isLocalBase, authedRequest, } from "./lib/auth-resolve.js";
 import { resolveSigningIdentity, emitSigningIdentityDebug, } from "./lib/signing-identity.js";
@@ -1503,8 +1503,12 @@ export async function verifySemanticSearch(baseUrl, agentIdOpt, keysDir) {
     if (!agentId) {
         try {
             const keyFiles = readdirSync(keysDir).filter((f) => f.endsWith(".key"));
-            if (keyFiles.length > 0)
-                agentId = keyFiles[0].replace(/\.key$/, "");
+            // Skip node-scoped federation keys (flair#1193): they can't sign, so
+            // picking one here would fail the probe with a decode error that reads
+            // like a semantic-search regression rather than "no agent to sign as".
+            const agentKeyFile = keyFiles.find((f) => !isNodeKeyId(f.replace(/\.key$/, ""), keysDir));
+            if (agentKeyFile)
+                agentId = agentKeyFile.replace(/\.key$/, "");
         }
         catch { /* keysDir missing */ }
     }
@@ -9796,8 +9800,12 @@ program
     await (async () => {
         const agentId = resolveAgentIdOrEnv({}) ?? (() => {
             try {
-                const keyFiles = readdirSync(defaultKeysDir()).filter((f) => f.endsWith(".key"));
-                return keyFiles.length > 0 ? keyFiles[0].replace(/\.key$/, "") : null;
+                const kd = defaultKeysDir();
+                const keyFiles = readdirSync(kd).filter((f) => f.endsWith(".key"));
+                // Node-scoped federation keys aren't agents (flair#1193) — never
+                // pin-refresh a connector as one.
+                const agentKeyFile = keyFiles.find((f) => !isNodeKeyId(f.replace(/\.key$/, ""), kd));
+                return agentKeyFile ? agentKeyFile.replace(/\.key$/, "") : null;
             }
             catch {
                 return null;
@@ -11843,9 +11851,27 @@ program
     const keysDir = defaultKeysDir();
     if (existsSync(keysDir)) {
         const keyFiles = (await import("node:fs")).readdirSync(keysDir).filter((f) => f.endsWith(".key"));
-        if (keyFiles.length > 0) {
-            keyAgentIds = keyFiles.map((f) => f.replace(/\.key$/, ""));
-            console.log(`  ${render.icons.ok} Keys found: ${render.wrap(render.c.bold, String(keyFiles.length))} agent(s) in ${render.wrap(render.c.dim, keysDir)}`);
+        // ~/.flair/keys is shared by agent Ed25519 signing keys and node-scoped
+        // federation keys (flair#1193). Only agent keys are signing identities;
+        // node keys are AES-GCM keystore blobs that must never be parsed as, or
+        // inferred as, an agent. Partition them out here so every downstream
+        // consumer of keyAgentIds (registration checks, --fix inference,
+        // fixCommandAgentHint) is node-free by construction.
+        const { agentKeyIds, nodeKeyIds } = partitionKeyIds(keyFiles.map((f) => f.replace(/\.key$/, "")), keysDir);
+        keyAgentIds = agentKeyIds;
+        if (agentKeyIds.length > 0) {
+            console.log(`  ${render.icons.ok} Keys found: ${render.wrap(render.c.bold, String(agentKeyIds.length))} agent(s) in ${render.wrap(render.c.dim, keysDir)}`);
+            if (nodeKeyIds.length > 0) {
+                console.log(`     ${render.icons.info} ${render.wrap(render.c.dim, `${nodeKeyIds.length} node-scoped federation key(s) present — not agent signing keys; skipping`)}`);
+            }
+        }
+        else if (nodeKeyIds.length > 0) {
+            // Node keys but no agent key: functionally there is no agent identity
+            // here. Report it plainly (not the old DECODER false alarm) and point
+            // at the real remedy. Kept a warn — not an issues++ — so a genuine
+            // federation-only host doesn't newly fail doctor's exit code.
+            console.log(`  ${render.icons.warn} No agent signing key found — only ${render.wrap(render.c.bold, String(nodeKeyIds.length))} node-scoped federation key(s) in ${render.wrap(render.c.dim, keysDir)}`);
+            console.log(`     ${render.wrap(render.c.dim, "These are Fabric node keys, not agent identities. Fix:")} flair init --agent-id <your-agent>`);
         }
         else {
             console.log(`  ${render.icons.error} Keys directory exists but no .key files found`);
@@ -12103,13 +12129,24 @@ program
                             // nothing else identifies one — the only case doctor can
                             // infer without being told (see inferSoleAgentId's doc
                             // comment in doctor-client.ts for why 0/2+ keys don't guess).
-                            const fixAgentId = opts.agent || process.env.FLAIR_AGENT_ID || anyKnownAgentId || inferSoleAgentId(keyAgentIds);
+                            // flair#1193: resolveFixAgentId additionally refuses a
+                            // node-scoped federation id from ANY source (inference, env,
+                            // or a wired block a prior buggy run may have poisoned) — a
+                            // node id can't sign, so wiring it would authenticate the
+                            // connector as a phantom unregistered node.
+                            const fixAgentId = resolveFixAgentId({
+                                optsAgent: opts.agent,
+                                envAgentId: process.env.FLAIR_AGENT_ID,
+                                anyKnownAgentId,
+                                keyAgentIds,
+                                keysDir: defaultKeysDir(),
+                            });
                             if (!fixAgentId) {
                                 if (keyAgentIds.length > 1) {
                                     console.log(`     ${render.icons.warn} Cannot auto-wire ${client.label}: multiple agents found (${[...keyAgentIds].sort().join(", ")}) — pass --agent <id> to choose which one`);
                                 }
                                 else {
-                                    console.log(`     ${render.icons.warn} Cannot auto-wire ${client.label}: no agent registered — run \`flair agent add <id>\` first, then re-run \`flair doctor --fix\``);
+                                    console.log(`     ${render.icons.warn} Cannot auto-wire ${client.label}: no agent identity found in keys/ — run \`flair init --agent <name>\` or \`flair agent add <name>\` before wiring a connector`);
                                 }
                             }
                             else {

package/dist/doctor-client.js

@@ -907,3 +907,78 @@ export function classifyKeyFile(agentId, seedValid, registration, baseUrl) {
         reason: `agent '${agentId}' is not registered on ${baseUrl}${registration?.detail ? ` (${registration.detail})` : ""}`,
     };
 }
+// ── Node-scoped federation keys vs agent signing keys (flair#1193) ─────────
+//
+// `~/.flair/keys/` is a namespace shared by two writers with two file shapes:
+//
+//   • agent Ed25519 signing keys — a 32-byte raw seed at `<name>.key`, ALWAYS
+//     written together with a sibling `<name>.pub` (see the keypair write in
+//     src/cli.ts: the seed and the public key are emitted in the same block).
+//   • node-scoped federation keys — `flair_<hex8>.key`, an AES-256-GCM
+//     keystore blob written by FileKeyStore during Fabric provisioning
+//     (flair#1026). The id is minted as `flair_${randomBytes(4).toString("hex")}`
+//     in resources/Federation.ts, and NO `.pub` is ever written for it.
+//
+// Nothing used to tell them apart, so doctor tried to Ed25519-parse the node
+// blob — a "DECODER routines::unsupported" warning that reads as agent-auth
+// breakage when agent auth is fine — and `doctor --fix` could infer the node
+// id as the sole "agent" and wire it as a connector identity, authenticating
+// as a phantom, unregistered node whose key cannot sign (flair#1193).
+//
+// The guard is STRUCTURAL, not a parse attempt: a node id matches
+// `flair_<hex8>` AND has no sibling `.pub`. We deliberately do NOT classify by
+// parsing the file and treating a decode failure as "must be a node key" —
+// that is the exact fails-open move flair#1026 warns against (a genuinely
+// corrupt agent key would be misread as a node key and silently skipped).
+// A real agent always has a `.pub`; a node key never does, so `.pub` presence
+// is the primary, falsifiable signal and classification never depends on the
+// parse-failure of the thing being classified.
+/** The shape a Fabric node id always has: `flair_` + 8 lowercase hex chars. */
+const NODE_KEY_ID_RE = /^flair_[0-9a-f]{8}$/;
+/**
+ * True iff `id` names a node-scoped federation key rather than an agent
+ * signing key: it is shaped like a node id AND has no sibling `<id>.pub` in
+ * `keysDir`. Both conditions are required — an agent that happened to be named
+ * `flair_deadbeef` would still have a `.pub`, so it is never misclassified.
+ */
+export function isNodeKeyId(id, keysDir) {
+    if (!NODE_KEY_ID_RE.test(id))
+        return false;
+    return !existsSync(join(keysDir, `${id}.pub`));
+}
+/**
+ * Partition `.key`-derived ids into agent signing keys and node-scoped
+ * federation keys (see isNodeKeyId). Node keys must never feed agent handling —
+ * Ed25519 parsing, registration checks, or connector-identity inference
+ * (flair#1193) — so callers keep only `agentKeyIds` for those paths and report
+ * `nodeKeyIds` informatively.
+ */
+export function partitionKeyIds(ids, keysDir) {
+    const agentKeyIds = [];
+    const nodeKeyIds = [];
+    for (const id of ids) {
+        (isNodeKeyId(id, keysDir) ? nodeKeyIds : agentKeyIds).push(id);
+    }
+    return { agentKeyIds, nodeKeyIds };
+}
+/**
+ * Resolve the agent id `doctor --fix` should wire a connector as, or undefined
+ * when none can be safely determined. A node-scoped federation id is NEVER
+ * returned regardless of source (flair#1193): it cannot sign, so wiring it
+ * yields a connector that authenticates as a phantom unregistered node and
+ * fails every read/write. When this returns undefined the caller MUST refuse
+ * and tell the user to create/register an agent — never fall back to a node id.
+ *
+ * `keyAgentIds` is expected to already be node-free (its producer partitions
+ * node keys out at enumeration), so `inferSoleAgentId` never sees one; the
+ * explicit `isNodeKeyId` guard additionally covers `optsAgent` / `envAgentId` /
+ * `anyKnownAgentId`, since a prior buggy run may have poisoned a wired block
+ * with a node id that would otherwise be read back and re-propagated.
+ */
+export function resolveFixAgentId(args) {
+    const { optsAgent, envAgentId, anyKnownAgentId, keyAgentIds, keysDir } = args;
+    const candidate = optsAgent || envAgentId || anyKnownAgentId || inferSoleAgentId(keyAgentIds);
+    if (candidate && isNodeKeyId(candidate, keysDir))
+        return undefined;
+    return candidate;
+}

package/dist/resources/mcp-tools.js

@@ -115,6 +115,30 @@ async function unwrap(value) {
     }
     return value;
 }
+/**
+ * flair#1188 — remove the raw `embedding` vector from a record before it is
+ * returned over the MCP surface. A stored memory carries a 768-float
+ * `embedding` (the HNSW vector); inlined into a tool result that is thousands
+ * of noise tokens per record on chat connectors that have a fixed context
+ * budget, and the caller can never do anything useful with it. Returns a
+ * shallow copy WITHOUT `embedding` (never mutates the source record), and
+ * passes through anything that is not a plain record — null, primitives,
+ * arrays, and the `{ error, status }` shapes `unwrap` produces — untouched.
+ *
+ * `memory_search` already projects with an explicit select that omits
+ * `embedding` (resources/semantic-retrieval-core.ts's DEFAULT_SELECT), and
+ * `bootstrap` uses the same select-without-embedding pushdown, so this is only
+ * needed on the FULL-record read/write paths (memory_get, and the write
+ * responses that echo the stored row).
+ */
+function stripEmbedding(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return value;
+    if (!("embedding" in value))
+        return value;
+    const { embedding, ...rest } = value;
+    return rest;
+}
 // ── Tool implementations (thin wrappers over existing handlers) ──────────────
 //
 // Each takes the resolved agent + the parsed tool arguments and returns a plain
@@ -190,7 +214,10 @@ async function memoryStore(agent, args) {
         }
         body.visibility = args.visibility;
     }
-    return unwrap(await h.post(body));
+    // flair#1188 — memory_store's response goes through the same buildWriteResponse
+    // echo as memory_update; strip the server-regenerated embedding so no write
+    // tool ever inlines the vector. No-op when the response carries none.
+    return stripEmbedding(await unwrap(await h.post(body)));
 }
 /**
  * memory_update — id-targeted, dedup-BYPASSED overwrite/version path (memory-
@@ -240,6 +267,20 @@ async function memoryUpdate(agent, args) {
         delete record.validFrom;
         delete record.validTo;
         delete record.archivedAt;
+        // flair#1189 — retrievalCount and lastRetrieved are RECORD-scoped, not
+        // lineage-scoped: a brand-new successor record has no retrieval history of
+        // its OWN, so it must start with none. Inheriting them from the superseded
+        // record via the `...existing` spread produced a successor whose
+        // lastRetrieved PREDATED its own createdAt ("retrieved 8h before it
+        // existed"), silently corrupting any recency/usage-based ranking that reads
+        // these fields. Reset both here, at succession construction — NOT server-
+        // side, because `supersedes` is a PERMANENT property of every successor and
+        // legitimate later retrievalCount bumps route through put() on a record that
+        // still carries it. Usage/citation-ledger counters (usageCount, the #1147
+        // citation ledger) are a SEPARATE, arguably lineage-scoped question and are
+        // deliberately left untouched here (#1147's usage loop is currently inert).
+        record.retrievalCount = 0;
+        delete record.lastRetrieved;
         // flair#718 authorship-provenance — see memoryStore's comment: forward
         // the resolved OAuth client_id (never forgeable via args) so the NEW
         // version's provenance records which client authored this update.
@@ -247,7 +288,10 @@ async function memoryUpdate(agent, args) {
             record.claimedClient = agent.clientId;
         // A create needs a COLLECTION-bound instance (see resources/in-process.ts).
         const coll = await collectionResource(Cls, delegationContext(agent));
-        return unwrap(await coll.post(record));
+        // flair#1188 — the write response echoes the stored row (Memory.post
+        // regenerates the embedding server-side), so strip the vector before it
+        // returns over the MCP surface. No-op when the response carries none.
+        return stripEmbedding(await unwrap(await coll.post(record)));
     }
     const merged = { ...existing, content, updatedAt: new Date().toISOString() };
     delete merged.embedding;
@@ -264,7 +308,9 @@ async function memoryUpdate(agent, args) {
     // the same unloaded-instance defect on the write. The static form loads the
     // row by `merged.id` and threads the context, then dispatches through
     // Memory.put()'s own ownership gate — no scope change, same as the read.
-    return unwrap(await Cls.put(merged, delegationContext(agent)));
+    // flair#1188 — strip the embedding from the echoed write response (Memory.put
+    // regenerates the vector server-side); no-op when the response carries none.
+    return stripEmbedding(await unwrap(await Cls.put(merged, delegationContext(agent))));
 }
 async function memoryGet(agent, args) {
     const Cls = await handler("Memory");
@@ -286,7 +332,13 @@ async function memoryGet(agent, args) {
     // a plain `{ id, includeTrust }` property — Memory.get()'s wantsTrust() reads
     // it there (the in-process shape alongside the HTTP query-param shape).
     const target = args?.includeTrust === true ? { id: args?.id, includeTrust: true } : args?.id;
-    return unwrap(await Cls.get(target, delegationContext(agent)));
+    const result = await unwrap(await Cls.get(target, delegationContext(agent)));
+    // flair#1188 — a by-id get loads the FULL record, including the 768-float
+    // `embedding` vector (search/bootstrap project it out; a raw get does not).
+    // Strip it by default so a chat connector isn't flooded with thousands of
+    // useless tokens per record; return it only when the caller explicitly opts
+    // in via includeEmbedding.
+    return args?.includeEmbedding === true ? result : stripEmbedding(result);
 }
 async function memoryDelete(agent, args) {
     const Cls = await handler("Memory");
@@ -324,7 +376,15 @@ async function bootstrap(agent, args) {
     // flair#831 — attach the running Flair version to the RESPONSE (not the
     // delegated request body) so the calling agent learns the server version
     // on its very first call.
-    const result = unwrap(await h.post(body));
+    //
+    // flair#1182 — `unwrap` is async: it must be AWAITED before the result is
+    // spread, exactly as every sibling tool does (`await unwrap(...)` in
+    // memory_store / memory_update / memory_get). Without the await, `result` is
+    // the still-pending PROMISE, and `{ ...aPromise }` copies no own-enumerable
+    // keys — so the entire computed payload (resolved agentId, scope, soul,
+    // memories, predicted, the #1182.1 containers, the abstention verdict) was
+    // silently discarded and the caller saw ONLY the injected `flairVersion`.
+    const result = await unwrap(await h.post(body));
     if (result && typeof result === "object" && !Array.isArray(result)) {
         return { ...result, flairVersion: resolveVersion() };
     }
@@ -514,13 +574,14 @@ export const TOOLS = {
     memory_get: {
         def: {
             name: "memory_get",
-            description: "Retrieve a specific memory by ID.",
+            description: "Retrieve a specific memory by ID. The record's raw embedding vector is omitted by default (it is large and not useful to a caller); pass includeEmbedding=true to include it.",
             annotations: { readOnlyHint: true },
             inputSchema: {
                 type: "object",
                 properties: {
                     id: { type: "string", description: "Memory ID" },
                     includeTrust: { type: "boolean", description: "Attach a trust-evidence block (provenance, author, usage, freshness, supersession) to the record. Default false." },
+                    includeEmbedding: { type: "boolean", description: "Include the raw embedding vector (hundreds of floats) in the returned record. Omitted by default because it is large and rarely useful to a caller. Default false." },
                 },
                 required: ["id"],
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.44.4",
+  "version": "0.44.6",
   "packageManager": "bun@1.3.10",
   "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",