@tpsdev-ai/flair-mcp 0.10.1 → 0.12.0

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

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * Flair SessionStart hook for Claude Code — auto-recall on session start.
+ *
+ * Claude Code fires `SessionStart` hooks when a session begins (startup,
+ * resume, clear, compact). A hook of `type: "command"` receives the hook
+ * payload as JSON on stdin and may print a JSON object whose
+ * `hookSpecificOutput.additionalContext` string is injected into the model's
+ * context for that session. This binary uses that channel to inject Flair's
+ * `bootstrap` context (soul + relevant memories + predicted context), so a
+ * fresh Claude Code session starts already warmed with the agent's memory —
+ * no manual "call the bootstrap tool" nudge required.
+ *
+ * It complements the MCP server (`flair-mcp`): the MCP server gives the agent
+ * pull tools (memory_search / memory_store / bootstrap on demand) and push
+ * recall, while this hook does a one-shot context push at session start.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * CONFIG (env, read identically to the MCP server)
+ * ------------------------------------------------
+ *   FLAIR_AGENT_ID   (required — absent → no-op)  agent identity
+ *   FLAIR_URL        (default http://localhost:19926 via flair-client)
+ *   FLAIR_KEY_PATH   (default ~/.flair/keys/<agent>.key via flair-client)
+ *   FLAIR_HOOK_TIMEOUT_MS (default 8000; clamped 500..30000)
+ *
+ * USAGE — register in ~/.claude/settings.json:
+ *   {
+ *     "hooks": {
+ *       "SessionStart": [
+ *         { "hooks": [ { "type": "command",
+ *           "command": "FLAIR_AGENT_ID=me npx -y @tpsdev-ai/flair-mcp flair-session-start" } ] }
+ *       ]
+ *     }
+ *   }
+ */
+/** Minimal surface of FlairClient this hook depends on (eases testing). */
+interface BootstrapClient {
+    bootstrap(opts: {
+        maxTokens?: number;
+        channel?: string;
+        subjects?: string[];
+    }): Promise<{
+        context?: string;
+    } | undefined>;
+}
+/**
+ * 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.
+ * NEVER throws — every failure path returns NOOP_OUTPUT.
+ *
+ * @param rawInput   the raw stdin string (may be empty / malformed)
+ * @param makeClient factory for the bootstrap client (defaults to FlairClient)
+ */
+export declare function runHook(rawInput: string, makeClient?: (agentId: string) => BootstrapClient): Promise<string>;
+export {};

package/dist/session-start-hook.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * Flair SessionStart hook for Claude Code — auto-recall on session start.
+ *
+ * Claude Code fires `SessionStart` hooks when a session begins (startup,
+ * resume, clear, compact). A hook of `type: "command"` receives the hook
+ * payload as JSON on stdin and may print a JSON object whose
+ * `hookSpecificOutput.additionalContext` string is injected into the model's
+ * context for that session. This binary uses that channel to inject Flair's
+ * `bootstrap` context (soul + relevant memories + predicted context), so a
+ * fresh Claude Code session starts already warmed with the agent's memory —
+ * no manual "call the bootstrap tool" nudge required.
+ *
+ * It complements the MCP server (`flair-mcp`): the MCP server gives the agent
+ * pull tools (memory_search / memory_store / bootstrap on demand) and push
+ * recall, while this hook does a one-shot context push at session start.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * CONFIG (env, read identically to the MCP server)
+ * ------------------------------------------------
+ *   FLAIR_AGENT_ID   (required — absent → no-op)  agent identity
+ *   FLAIR_URL        (default http://localhost:19926 via flair-client)
+ *   FLAIR_KEY_PATH   (default ~/.flair/keys/<agent>.key via flair-client)
+ *   FLAIR_HOOK_TIMEOUT_MS (default 8000; clamped 500..30000)
+ *
+ * USAGE — register in ~/.claude/settings.json:
+ *   {
+ *     "hooks": {
+ *       "SessionStart": [
+ *         { "hooks": [ { "type": "command",
+ *           "command": "FLAIR_AGENT_ID=me npx -y @tpsdev-ai/flair-mcp flair-session-start" } ] }
+ *       ]
+ *     }
+ *   }
+ */
+import { FlairClient } from "@tpsdev-ai/flair-client";
+import { basename } from "node:path";
+/** Claude Code SessionStart additionalContext hard limit (chars). */
+const MAX_CHARS = 10_000;
+/** Token budget for the bootstrap call — matches the proven prototype. */
+const BOOTSTRAP_MAX_TOKENS = 2000;
+/** Default hard timeout on the bootstrap call (ms). */
+const DEFAULT_TIMEOUT_MS = 8000;
+const TIMEOUT_FLOOR_MS = 500;
+const TIMEOUT_CEILING_MS = 30_000;
+/** Empty, inert hook output. Printing this is always a safe no-op. */
+const NOOP_OUTPUT = "{}";
+/** Resolve the bootstrap timeout from env, clamped to a sane range. */
+function resolveTimeoutMs() {
+    const raw = process.env.FLAIR_HOOK_TIMEOUT_MS;
+    const parsed = raw != null ? Number(raw) : NaN;
+    return Number.isFinite(parsed) && parsed >= TIMEOUT_FLOOR_MS && parsed <= TIMEOUT_CEILING_MS
+        ? parsed
+        : DEFAULT_TIMEOUT_MS;
+}
+/** Read all of stdin as a string. Resolves on EOF, with a short fallback for
+ *  interactive/manual runs where no stdin is piped (so it never hangs). */
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => (data += chunk));
+        process.stdin.on("end", () => resolve(data));
+        process.stdin.on("error", () => resolve(data));
+        // Manual-run fallback: if nothing is piped, don't block forever.
+        setTimeout(() => resolve(data), 200).unref?.();
+    });
+}
+/** Race a promise against a timeout. Rejects with a timeout error if exceeded. */
+function withTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("bootstrap_timeout")), ms);
+        timer.unref?.();
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+/** Build the SessionStart hook output JSON from a context string. */
+function hookOutput(context) {
+    return JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: "SessionStart",
+            additionalContext: context,
+        },
+    });
+}
+/**
+ * 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.
+ * NEVER throws — every failure path returns NOOP_OUTPUT.
+ *
+ * @param rawInput   the raw stdin string (may be empty / malformed)
+ * @param makeClient factory for the bootstrap client (defaults to FlairClient)
+ */
+export async function runHook(rawInput, makeClient = defaultClientFactory) {
+    const agentId = process.env.FLAIR_AGENT_ID;
+    if (!agentId)
+        return NOOP_OUTPUT; // no identity → no-op, never break the session
+    let input = {};
+    try {
+        input = JSON.parse(rawInput || "{}") ?? {};
+    }
+    catch {
+        input = {}; // tolerate malformed stdin
+    }
+    const cwd = typeof input.cwd === "string" && input.cwd ? input.cwd : process.cwd();
+    const project = basename(cwd) || undefined;
+    let context = "";
+    try {
+        const client = makeClient(agentId);
+        const res = await withTimeout(Promise.resolve(client.bootstrap({
+            maxTokens: BOOTSTRAP_MAX_TOKENS,
+            channel: "claude-code",
+            subjects: project ? [project] : undefined,
+        })), resolveTimeoutMs());
+        context = res && res.context ? String(res.context) : "";
+    }
+    catch {
+        return NOOP_OUTPUT; // flair unreachable / auth error / timeout → no-op
+    }
+    if (!context.trim())
+        return NOOP_OUTPUT;
+    if (context.length > MAX_CHARS)
+        context = context.slice(0, MAX_CHARS);
+    return hookOutput(context);
+}
+/** Default client factory — constructs a real FlairClient from FLAIR_* env,
+ *  identical to how src/index.ts builds it. */
+function defaultClientFactory(agentId) {
+    return new FlairClient({
+        agentId,
+        url: process.env.FLAIR_URL,
+        keyPath: process.env.FLAIR_KEY_PATH,
+    });
+}
+/** Entry point. Reads stdin, runs the hook, prints the result, exits 0.
+ *  Wrapped so that even an unexpected throw degrades to a no-op. */
+async function main() {
+    let output = NOOP_OUTPUT;
+    try {
+        output = await runHook(await readStdin());
+    }
+    catch {
+        output = NOOP_OUTPUT;
+    }
+    process.stdout.write(output);
+}
+// Only run when executed as a script, not when imported by tests.
+// import.meta.main is set by Bun and Node 22.x; fall back to an argv check
+// for runtimes that don't populate it.
+const importMeta = import.meta;
+const isMain = importMeta.main === true ||
+    (typeof process !== "undefined" &&
+        process.argv[1] != null &&
+        import.meta.url === `file://${process.argv[1]}`);
+if (isMain) {
+    // .catch is belt-and-suspenders; main() already swallows everything.
+    void main().catch(() => process.stdout.write(NOOP_OUTPUT));
+}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@tpsdev-ai/flair-mcp",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "description": "MCP server for Flair — persistent memory for Claude Code, Cursor, and any MCP client.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "flair-mcp": "dist/index.js"
+    "flair-mcp": "dist/index.js",
+    "flair-session-start": "dist/session-start-hook.js"
   },
   "files": [
     "dist/",
@@ -14,8 +15,9 @@
   ],
   "scripts": {
     "build": "tsc --noCheck",
+    "test": "bun test",
     "prepublishOnly": "npm run build",
-    "postinstall": "node -e \"try{const{chmodSync,statSync}=require('fs');const p='dist/index.js';if(statSync(p).isFile()){chmodSync(p,0o755);console.error('@tpsdev-ai/flair-mcp: chmod +x ' + p + ' OK')}}catch(e){if(e.code!=='ENOENT')console.error('postinstall warn:',e.message)}\""
+    "postinstall": "node -e \"try{const{chmodSync,statSync}=require('fs');for(const p of ['dist/index.js','dist/session-start-hook.js']){try{if(statSync(p).isFile()){chmodSync(p,0o755);console.error('@tpsdev-ai/flair-mcp: chmod +x ' + p + ' OK')}}catch(e){if(e.code!=='ENOENT')console.error('postinstall warn:',e.message)}}}catch(e){console.error('postinstall warn:',e.message)}\""
   },
   "publishConfig": {
     "access": "public"
@@ -25,7 +27,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.27.1",
-    "@tpsdev-ai/flair-client": "0.10.1",
+    "@tpsdev-ai/flair-client": "0.12.0",
     "zod": "4.3.6"
   },
   "license": "Apache-2.0",