@tpsdev-ai/flair-mcp 0.55.2 → 0.57.0

package/README.md

@@ -23,7 +23,7 @@ cat > .mcp.json << 'EOF'
 EOF
 ```
 
-`npx -y @tpsdev-ai/flair-mcp` fetches and runs the server on demand — no global install needed. (`flair init` wires this for you automatically; see below.)
+`npx -y @tpsdev-ai/flair-mcp` fetches and runs the server on demand — no global install needed. (`flair init --agent <id>` attempts to wire detected clients when wiring is enabled; see below.)
 
 ### Prerequisites
 
@@ -48,7 +48,7 @@ Once configured, Claude Code (or any MCP client) gets these tools:
 | `skill_search` | Find skills that apply to a task. Returns a catalog, not the procedure. |
 | `skill_get` | Retrieve the full skill by ID (disclosure after `skill_search`). |
 | `bootstrap` | Cold-start context — soul + recent memories in one call. |
-| `soul_set` | Set personality or project context (included in every bootstrap). |
+| `soul_set` | Soul writes require verified administrator Basic credentials; Ed25519 agent requests are refused. Operators should use the REST API or CLI. |
 | `soul_get` | Get a personality or project context entry. |
 | `record_usage` | Report that recalled memories were actually used (drives `usageCount`). |
 
@@ -68,7 +68,7 @@ Once configured, Claude Code (or any MCP client) gets these tools:
 Claude Code ↔ stdio ↔ flair-mcp ↔ HTTP ↔ Flair (Harper)
 ```
 
-The MCP server is a thin wrapper around `@tpsdev-ai/flair-client`. All memory is stored in your local Flair instance with Ed25519 authentication. Nothing leaves your machine unless you point `FLAIR_URL` at a remote server.
+The MCP server is a thin wrapper around `@tpsdev-ai/flair-client`. All memory is stored in the Flair instance selected by `FLAIR_URL` (defaulting to localhost). Requests are signed with the agent's Ed25519 key whenever one resolves. Only when no key resolves, and both `FLAIR_ADMIN_USER` and `FLAIR_ADMIN_PASSWORD` are set, does the client send admin Basic auth; a key that cannot be parsed is an error, and a rejected signature is not retried with Basic. The MCP client connects to FLAIR_URL; a paired local instance may separately federate eligible memories.
 
 ## Remote Flair
 
@@ -82,14 +82,14 @@ Point to a remote Flair instance:
       "args": ["-y", "@tpsdev-ai/flair-mcp"],
       "env": {
         "FLAIR_AGENT_ID": "my-project",
-        "FLAIR_URL": "http://your-server:19926"
+        "FLAIR_URL": "https://your-server:19926"
       }
     }
   }
 }
 ```
 
-Copy your key from the server: `scp server:~/.flair/keys/my-project.key ~/.flair/keys/`
+The client REFUSES to send admin Basic credentials over plain HTTP to a non-loopback host (the credentials would travel in a request header): use an HTTPS `FLAIR_URL`, or an Ed25519 key, for a remote instance. Copy your key from the server: `scp server:~/.flair/keys/my-project.key ~/.flair/keys/`
 
 ## License
 

package/dist/adapter-tools.js

@@ -6,6 +6,7 @@
  * descriptor with no handler (or a handler with no descriptor) fails at
  * registration, so the surfaces cannot drift by omission.
  */
+import { encodeRecordId } from "./record-id-path.js";
 import { STDIO_TOOL_DESCRIPTORS, toStdioMcpToolDef, } from "./tool-descriptors/index.js";
 import { buildCatchupRequest, summarizeCatchup } from "./catchup.js";
 import { classifyError } from "./errors.js";
@@ -265,7 +266,7 @@ const skill_store = async ({ content, trigger, name, description, tags }, { flai
             tags,
             claimedClient: flair.claimedClient,
         });
-        const result = await flair.request("PUT", `/Memory/${id}`, body);
+        const result = await flair.request("PUT", `/Memory/${encodeRecordId(id)}`, body);
         const writtenId = typeof result?.id === "string" && result.id.length > 0 ? result.id : id;
         const preview = content.length > 120 ? content.slice(0, 120) + "..." : content;
         const lines = [

package/dist/continuity-capture-hook.d.ts

@@ -41,6 +41,13 @@ export interface CaptureDeps {
     sessionDir?: string;
     env?: Record<string, string | undefined>;
     now?: () => Date;
+    /** Test seam (flair#1970): the row whose `id` becomes the `/Memory/<id>` path
+     *  segment. Its id is URL-safe by construction, so a test drives the REAL
+     *  request path with a dot-segment id through this override and checks that
+     *  no request is sent when the id is refused. Production never sets it. */
+    buildRow?: (agentId: string, state: unknown, plan: unknown, now: Date) => {
+        id: string;
+    };
     /** Debug-level warn sink (default: one stderr line). Never stdout. */
     warn?: (message: string) => void;
 }

package/dist/continuity-capture-hook.js

@@ -34,6 +34,7 @@
  *   FLAIR_HOOK_PROBE (probe mode: exit immediately, no stdin read, no writes)
  */
 import { isProbeMode, readEnvOrUnset, stripInterpolationLiteralsFromEnv } from "./env-guard.js";
+import { memoryPutPath } from "./record-id-path.js";
 import { buildJournalRow, bumpSeq, isSafeFileId, planCapture, resolveContinuityTimeoutMs, resolveSessionDir, } from "./continuity.js";
 /** Read all of stdin. Resolves on EOF, with a short fallback for manual runs
  *  where nothing is piped (so it never hangs). */
@@ -121,11 +122,11 @@ export async function runCapture(rawInput, deps = {}) {
     const state = bumpSeq(sessionDir, agentId, harnessSessionId, now());
     if (!state)
         return { wrote: false, reason: "no-state" };
-    const row = buildJournalRow(agentId, state, plan, now());
+    const row = (deps.buildRow ?? buildJournalRow)(agentId, state, plan, now());
     const makeClient = deps.makeClient ?? defaultClientFactory;
     try {
         const client = await makeClient(agentId);
-        await withTimeout(Promise.resolve(client.request("PUT", `/Memory/${row.id}`, row)), resolveContinuityTimeoutMs(env));
+        await withTimeout(Promise.resolve(client.request("PUT", memoryPutPath(row.id), row)), resolveContinuityTimeoutMs(env));
         return { wrote: true, reason: "written" };
     }
     catch (err) {

package/dist/record-id-path.d.ts

@@ -0,0 +1,20 @@
+/**
+ * record-id-path.ts — the one rule for a record id used as the single dynamic
+ * path segment of a `/Memory/<id>` request built inside flair-mcp (flair#1970).
+ *
+ * Self-contained on purpose: this module must load and typecheck WITHOUT
+ * @tpsdev-ai/flair-client's built dist present (the root `bun test` and strict
+ * test-suite typecheck lanes run before the client is built), so it does not
+ * import the client's own `encodeRecordId` — it states the same rule here.
+ */
+/**
+ * Percent-encode an id so it reaches the server as ONE path segment that
+ * decodes back to the id, addressing exactly that record. REFUSES an id that is
+ * exactly `.` or `..`: percent-encoding leaves those unchanged and URL
+ * normalization collapses `/Memory/.` to `/Memory/` and `/Memory/..` to `/`, so
+ * the sent path would not be the id (nor the signed path). Such an id cannot
+ * address its record, so it is an error, not a request.
+ */
+export declare function encodeRecordId(id: string): string;
+/** The PUT path for a row: its id as ONE percent-encoded path segment. */
+export declare function memoryPutPath(id: string): string;

package/dist/record-id-path.js

@@ -0,0 +1,28 @@
+/**
+ * record-id-path.ts — the one rule for a record id used as the single dynamic
+ * path segment of a `/Memory/<id>` request built inside flair-mcp (flair#1970).
+ *
+ * Self-contained on purpose: this module must load and typecheck WITHOUT
+ * @tpsdev-ai/flair-client's built dist present (the root `bun test` and strict
+ * test-suite typecheck lanes run before the client is built), so it does not
+ * import the client's own `encodeRecordId` — it states the same rule here.
+ */
+/**
+ * Percent-encode an id so it reaches the server as ONE path segment that
+ * decodes back to the id, addressing exactly that record. REFUSES an id that is
+ * exactly `.` or `..`: percent-encoding leaves those unchanged and URL
+ * normalization collapses `/Memory/.` to `/Memory/` and `/Memory/..` to `/`, so
+ * the sent path would not be the id (nor the signed path). Such an id cannot
+ * address its record, so it is an error, not a request.
+ */
+export function encodeRecordId(id) {
+    if (id === "." || id === "..") {
+        throw new Error(`record id ${JSON.stringify(id)} is a URL path dot-segment ("." or ".."); ` +
+            `it cannot be addressed as one path segment of /Memory/<id>. Use a different id.`);
+    }
+    return encodeURIComponent(id);
+}
+/** The PUT path for a row: its id as ONE percent-encoded path segment. */
+export function memoryPutPath(id) {
+    return `/Memory/${encodeRecordId(id)}`;
+}

package/dist/session-start-hook.d.ts

@@ -17,11 +17,14 @@
  *
  * NO-OP-ON-ANY-FAILURE GUARANTEE
  * ------------------------------
- * This hook can never block or break Claude Code startup. Every failure mode —
- * missing FLAIR_AGENT_ID, malformed stdin, Flair unreachable, auth error, a
- * hung daemon, an unexpected throw — degrades to printing `{}` (an empty,
- * inert hook output) and exiting 0. It never throws, never writes to stderr in
- * a way that surfaces to the user, and never exits non-zero.
+ * This hook can never block or break Claude Code startup. Every failure mode
+ * (missing FLAIR_AGENT_ID, malformed stdin, Flair unreachable, auth error, a
+ * hung daemon, an unexpected throw) exits 0. Malformed stdin is treated as
+ * empty input and can still yield bootstrap context. A failed bootstrap yields
+ * a continuity resume hint only when the separate lookup finds eligible prior
+ * entries; otherwise stdout is `{}`. The hook attempts one stderr diagnostic
+ * when bootstrap fails (flair#1943). The Codex command retains stderr and the
+ * Claude Code command discards it; delivery depends on stderr being writable.
  *
  * A hard timeout (FLAIR_HOOK_TIMEOUT_MS, default 8s) wraps the bootstrap call
  * so a stalled Flair daemon can't hang session startup; on timeout we no-op.
@@ -96,6 +99,23 @@ interface BootstrapClient extends Partial<PresencePoster> {
  * sharing it; re-exported here unchanged so existing importers keep working.
  */
 export { isProbeMode };
+/** The hook's OWN bootstrap-timer rejection (flair#1943). A dedicated class so
+ *  the classifier recognises its own timeout by IDENTITY, never by reading a
+ *  message. */
+export declare class BootstrapTimeoutError extends Error {
+    constructor();
+}
+export type BootstrapFailureKind = "auth" | "timeout" | "unreachable" | `http-${number}`;
+/**
+ * flair#1943 — classify a bootstrap failure for the one stderr line. Reads a
+ * numeric HTTP status FIRST (`status`, what FlairError carries, then
+ * `status_code`, then `statusCode`); when a status exists the message is never
+ * consulted. With no status, the ONLY timeout is the hook's own bootstrap
+ * timer (a BootstrapTimeoutError) or an error whose name is exactly
+ * `TimeoutError`; everything else is `unreachable`. No kind is ever decided
+ * from message text. Never reads or includes credentials.
+ */
+export declare function classifyBootstrapFailure(err: unknown): BootstrapFailureKind;
 /**
  * Core hook logic, with injectable dependencies so it can be unit-tested
  * without a live Flair daemon. Returns the exact string to print to stdout.

package/dist/session-start-hook.js

@@ -17,11 +17,14 @@
  *
  * NO-OP-ON-ANY-FAILURE GUARANTEE
  * ------------------------------
- * This hook can never block or break Claude Code startup. Every failure mode —
- * missing FLAIR_AGENT_ID, malformed stdin, Flair unreachable, auth error, a
- * hung daemon, an unexpected throw — degrades to printing `{}` (an empty,
- * inert hook output) and exiting 0. It never throws, never writes to stderr in
- * a way that surfaces to the user, and never exits non-zero.
+ * This hook can never block or break Claude Code startup. Every failure mode
+ * (missing FLAIR_AGENT_ID, malformed stdin, Flair unreachable, auth error, a
+ * hung daemon, an unexpected throw) exits 0. Malformed stdin is treated as
+ * empty input and can still yield bootstrap context. A failed bootstrap yields
+ * a continuity resume hint only when the separate lookup finds eligible prior
+ * entries; otherwise stdout is `{}`. The hook attempts one stderr diagnostic
+ * when bootstrap fails (flair#1943). The Codex command retains stderr and the
+ * Claude Code command discards it; delivery depends on stderr being writable.
  *
  * A hard timeout (FLAIR_HOOK_TIMEOUT_MS, default 8s) wraps the bootstrap call
  * so a stalled Flair daemon can't hang session startup; on timeout we no-op.
@@ -120,10 +123,19 @@ function readStdin() {
         setTimeout(() => resolve(data), 200).unref?.();
     });
 }
-/** Race a promise against a timeout. Rejects with a timeout error if exceeded. */
+/** The hook's OWN bootstrap-timer rejection (flair#1943). A dedicated class so
+ *  the classifier recognises its own timeout by IDENTITY, never by reading a
+ *  message. */
+export class BootstrapTimeoutError extends Error {
+    constructor() {
+        super("bootstrap timeout");
+        this.name = "BootstrapTimeoutError";
+    }
+}
+/** Race a promise against a timeout. Rejects with a BootstrapTimeoutError if exceeded. */
 function withTimeout(promise, ms) {
     return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(new Error("bootstrap_timeout")), ms);
+        const timer = setTimeout(() => reject(new BootstrapTimeoutError()), ms);
         timer.unref?.();
         promise.then((value) => {
             clearTimeout(timer);
@@ -134,6 +146,60 @@ function withTimeout(promise, ms) {
         });
     });
 }
+/**
+ * flair#1943 — classify a bootstrap failure for the one stderr line. Reads a
+ * numeric HTTP status FIRST (`status`, what FlairError carries, then
+ * `status_code`, then `statusCode`); when a status exists the message is never
+ * consulted. With no status, the ONLY timeout is the hook's own bootstrap
+ * timer (a BootstrapTimeoutError) or an error whose name is exactly
+ * `TimeoutError`; everything else is `unreachable`. No kind is ever decided
+ * from message text. Never reads or includes credentials.
+ */
+export function classifyBootstrapFailure(err) {
+    const e = err;
+    const status = numericStatus(e);
+    if (status !== undefined)
+        return status === 401 || status === 403 ? "auth" : `http-${status}`;
+    if (err instanceof BootstrapTimeoutError)
+        return "timeout";
+    if (typeof e?.name === "string" && e.name === "TimeoutError")
+        return "timeout";
+    return "unreachable";
+}
+/** The first NUMERIC HTTP status the error carries, checked `status` →
+ *  `status_code` → `statusCode` (flair#1943). */
+function numericStatus(e) {
+    for (const key of ["status", "status_code", "statusCode"]) {
+        const v = e?.[key];
+        if (typeof v === "number" && Number.isFinite(v))
+            return v;
+    }
+    return undefined;
+}
+// flair#1943: one no-op 'error' listener per process, so repeated failed
+// runs in one process never add listeners (and never trigger Node's
+// max-listeners warning on stderr).
+let stderrErrorAbsorbed = false;
+/** The stderr diagnostic for a failed bootstrap. NAMES the actor, the state and
+ *  the remedy; never contains a key, token, password or Authorization value. */
+function reportBootstrapFailure(err) {
+    const kind = classifyBootstrapFailure(err);
+    const line = `flair session-start: bootstrap failed (${kind}); this session starts without bootstrap context. Next: run \`flair doctor\`, and check FLAIR_URL and this agent's key.\n`;
+    try {
+        // Best-effort (flair#1943): a failed stderr write (a closed pipe → EPIPE)
+        // must not change stdout or the exit code. The write may throw
+        // SYNCHRONOUSLY or surface later as an 'error' event on the stream; absorb
+        // both, so the hook still prints its payload and exits 0.
+        if (!stderrErrorAbsorbed) {
+            process.stderr.on("error", () => { });
+            stderrErrorAbsorbed = true;
+        }
+        process.stderr.write(line);
+    }
+    catch {
+        // ignore — the diagnostic is best-effort
+    }
+}
 /** Build the SessionStart hook output JSON from a context string. */
 function hookOutput(context) {
     return JSON.stringify({
@@ -207,8 +273,14 @@ export async function runHook(rawInput, makeClient = defaultClientFactory) {
         })), resolveTimeoutMs());
         context = res && res.context ? String(res.context) : "";
     }
-    catch {
+    catch (err) {
         context = ""; // flair unreachable / auth error / timeout → no bootstrap context
+        // flair#1943: keeping stderr open cannot reveal an error never written to
+        // it. Write ONE line to STDERR (never stdout — that is the hook payload),
+        // so a real failure stays visible instead of being swallowed. stdout and
+        // the exit code are unchanged (the no-op payload), so a failure never
+        // blocks the session.
+        reportBootstrapFailure(err);
     }
     const resumeHint = await resumeHintDone;
     await presenceDone;

package/dist/tool-descriptors/index.js

@@ -51,7 +51,7 @@ export function descriptorNames(descriptors) {
 export const TOOL_DESCRIPTORS = [
     {
         "name": "memory_search",
-        "description": "Search memories by meaning. Understands temporal queries like 'what happened today'. Scoped to your agent's own + granted memories.",
+        "description": "Search memories by meaning. Understands temporal queries like 'what happened today'. Scoped to your agent's own and other agents' non-private memories.",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -80,7 +80,7 @@ export const TOOL_DESCRIPTORS = [
                 "query"
             ]
         },
-        "outputShape": "{ results: MemoryRecord[] } — semantic hits scoped to the caller's own + granted memories; each hit carries content, never the raw embedding.",
+        "outputShape": "{ results: MemoryRecord[] } — semantic hits scoped to the caller's own and other agents' non-private memories; each hit carries content, never the raw embedding.",
         "annotations": {
             "readOnlyHint": true
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair-mcp",
-  "version": "0.55.2",
+  "version": "0.57.0",
   "description": "MCP server for Flair — persistent memory for Claude Code, Cursor, and any MCP client.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.27.1",
-    "@tpsdev-ai/flair-client": "0.55.2",
+    "@tpsdev-ai/flair-client": "0.57.0",
     "zod": "4.3.6"
   },
   "license": "Apache-2.0",