@tpsdev-ai/flair-mcp 0.57.0 → 0.58.0

package/dist/session-start-hook.js

@@ -21,9 +21,9 @@
  * (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
+ * a pre-compaction record and/or a continuity resume hint only when their
+ * separate lookups find one; 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
@@ -81,6 +81,7 @@ import { basename } from "node:path";
 import { deriveActivity, postPresenceSafe, resolvePresenceTimeoutMs } from "./presence.js";
 import { isProbeMode, readEnvOrUnset, stripInterpolationLiteralsFromEnv } from "./env-guard.js";
 import { buildResumeHint, discoverResume, prepareContinuityBoot, resolveContinuityTimeoutMs, } from "./continuity.js";
+import { fetchPreCompactRecord, formatPreCompactContext, resolvePreCompactLookup } from "./precompact.js";
 /** Claude Code SessionStart additionalContext hard limit (chars). */
 const MAX_CHARS = 10_000;
 /** Token budget for the bootstrap call — matches the proven prototype. */
@@ -212,7 +213,10 @@ function hookOutput(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.
+ * A failed bootstrap can still return a pre-compaction record and a
+ * continuity resume hint. Without bootstrap context, a pre-compaction record
+ * or a resume hint, this returns NOOP_OUTPUT. The entry
+ * point catches unexpected exceptions.
  *
  * @param rawInput   the raw stdin string (may be empty / malformed)
  * @param makeClient factory for the bootstrap client (defaults to FlairClient)
@@ -264,6 +268,18 @@ export async function runHook(rawInput, makeClient = defaultClientFactory) {
     const resumeHintDone = continuity.active && typeof client.request === "function"
         ? withTimeout(discoverResume(client, agentId, continuity.priorPointer).then((result) => buildResumeHint(result)), resolveContinuityTimeoutMs()).catch(() => null)
         : Promise.resolve(null);
+    // Pre-compaction record (flair#2069): decided locally, fetched concurrently,
+    // the marker read and the fetch both bounded by the same continuity timeout;
+    // null (nothing shown) on any failure.
+    const precompactDone = typeof client.request === "function"
+        ? withTimeout((async () => {
+            const lookup = await resolvePreCompactLookup(input, agentId, continuity);
+            if (!lookup)
+                return null;
+            const record = await fetchPreCompactRecord(client, agentId, lookup);
+            return record ? formatPreCompactContext(record) : null;
+        })(), resolveContinuityTimeoutMs()).catch(() => null)
+        : Promise.resolve(null);
     let context = "";
     try {
         const res = await withTimeout(Promise.resolve(client.bootstrap({
@@ -277,16 +293,21 @@ export async function runHook(rawInput, makeClient = defaultClientFactory) {
         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.
+        // so a real failure stays visible instead of being swallowed. A failed
+        // bootstrap contributes no bootstrap context; a continuity resume hint may
+        // still be returned. The entry point preserves a successful exit.
         reportBootstrapFailure(err);
     }
     const resumeHint = await resumeHintDone;
+    const precompactBlock = await precompactDone;
     await presenceDone;
-    // Combine: bootstrap context first, then AT MOST one continuity hint line.
-    // Either piece may be absent; both absent ⇒ the inert no-op output.
+    // Combine: the pre-compaction record FIRST (bounded, so the MAX_CHARS cut
+    // below can only shorten what follows it), then the bootstrap context, then
+    // AT MOST one continuity hint line. Any piece may be absent; all absent ⇒
+    // the inert no-op output.
     const pieces = [];
+    if (precompactBlock)
+        pieces.push(precompactBlock);
     if (context.trim())
         pieces.push(context);
     if (resumeHint)

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 and other agents' non-private memories.",
+        "description": "Search memories by meaning. Understands temporal queries like 'what happened today'. Non-admin callers are scoped to their own and other agents' non-private memories; administrator requests may have broader access.",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -80,7 +80,7 @@ export const TOOL_DESCRIPTORS = [
                 "query"
             ]
         },
-        "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.",
+        "outputShape": "{ results: MemoryRecord[] } — semantic hits subject to the caller's read scope; each hit carries content, never the raw embedding.",
         "annotations": {
             "readOnlyHint": true
         },
@@ -135,7 +135,7 @@ export const TOOL_DESCRIPTORS = [
                         "private",
                         "shared"
                     ],
-                    "description": "Writer-controlled sharing intent. Omit to use the server's durability-keyed default: permanent/persistent -> shared, standard/ephemeral -> private. private — owner-only, never visible to another agent, even one holding a memory grant. shared — visible to the owner and every other agent on this instance. The visibility the write actually landed on is returned in the result."
+                    "description": "Writer-controlled sharing intent. Omit to use the server's durability-keyed default: permanent/persistent -> shared, standard/ephemeral -> private. private — readable by its owner and administrators; other non-admin agents cannot read it, including through a memory grant. shared — visible to the owner and every other agent on this instance. The visibility the write actually landed on is returned in the result."
                 },
                 "usedMemoryIds": {
                     "type": "array",
@@ -189,7 +189,7 @@ export const TOOL_DESCRIPTORS = [
     },
     {
         "name": "skill_search",
-        "description": "Find skills (reusable capabilities/procedures) that apply to a task. Ranks skill-tagged memories by their `trigger` ('when to use') against your task text. Returns a lightweight CATALOG — id, name, trigger, description, tags, agentId — NOT the full procedure (fetch that with skill_get). Scoped to your own + shared skills; another agent's private skill is never returned.",
+        "description": "Find skills (reusable capabilities/procedures) that apply to a task. Ranks skill-tagged memories by their `trigger` ('when to use') against your task text. Returns a lightweight CATALOG — id, name, trigger, description, tags, agentId — NOT the full procedure (fetch that with skill_get). Non-admin callers can retrieve their own and other agents' non-private skills; administrators can also retrieve private skills.",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -206,14 +206,14 @@ export const TOOL_DESCRIPTORS = [
                 "task"
             ]
         },
-        "outputShape": "{ results: SkillCard[] } — the skill catalog (lightweight id/name/trigger/description/tags/agentId, ranked by trigger match); the full procedure and the raw embedding are never on a card. Scoped to the caller's own + non-private skills; another agent's private skill is never returned.",
+        "outputShape": "{ results: SkillCard[] } — the skill catalog (lightweight id/name/trigger/description/tags/agentId, ranked by trigger match); the full procedure and the raw embedding are never on a card. Non-admin callers can retrieve their own and other agents' non-private skills; administrators can also retrieve private skills.",
         "annotations": {
             "readOnlyHint": true
         }
     },
     {
         "name": "skill_get",
-        "description": "Retrieve a full skill by ID — the complete procedure (`content`) plus trigger and metadata. The disclosure step after skill_search's catalog. Read-scoped: you can only get your own or a shared skill, never another agent's private skill. A non-skill id returns not-found. The raw embedding vector is never returned.",
+        "description": "Retrieve a full skill by ID — the complete procedure (`content`) plus trigger and metadata. The disclosure step after skill_search's catalog. Reads follow the caller's authorization: non-admin callers can retrieve their own and other agents' non-private skills; administrators can also retrieve private skills. A non-skill id returns not-found. The raw embedding vector is never returned.",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -226,7 +226,7 @@ export const TOOL_DESCRIPTORS = [
                 "id"
             ]
         },
-        "outputShape": "The full skill record { id, agentId, content, trigger, tags, durability, metadata, createdAt, ... } for a skill readable under the caller's read-scope — embedding + embeddingModel always stripped. A non-owner cannot read another agent's private skill, and a readable non-skill id is not found (both 404).",
+        "outputShape": "The full skill record { id, agentId, content, trigger, tags, durability, metadata, createdAt, ... } for a skill readable under the caller's read-scope — embedding + embeddingModel always stripped. A non-admin caller cannot read another agent's private skill; administrators retain access. A readable non-skill id is reported as not found.",
         "annotations": {
             "readOnlyHint": true
         }
@@ -268,7 +268,7 @@ export const TOOL_DESCRIPTORS = [
     },
     {
         "name": "memory_basement",
-        "description": "Send a memory to the basement (archive it). Sets archived=true and stamps archivedAt. The memory is removed from bootstrap and default search but remains retrievable via memory_get and memory_search(includeArchived:true). Deliberate and GLOBAL — this is a visibility flag, not a deletion: provenance and history are untouched. Scoped to your own memories only.",
+        "description": "Send a memory to the basement (archive it). Sets archived=true and stamps archivedAt. The memory is removed from bootstrap and default search but remains retrievable via memory_get and memory_search(includeArchived:true). Deliberate and GLOBAL — this is a visibility flag, not a deletion: provenance and history are untouched. Non-admin callers can modify only their own memories; administrators can also modify other agents' memories.",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -286,7 +286,7 @@ export const TOOL_DESCRIPTORS = [
     },
     {
         "name": "memory_restore",
-        "description": "Restore a basemented (archived) memory. Clears archived and archivedAt. Deliberate and GLOBAL — this un-retires the memory for EVERY session, not a session-local view (per-session reuse is drawers, which do not exist yet). Scoped to your own memories only.",
+        "description": "Restore a basemented (archived) memory. Clears archived and archivedAt. Deliberate and GLOBAL — this un-retires the memory for EVERY session, not a session-local view (per-session reuse is drawers, which do not exist yet). Non-admin callers can modify only their own memories; administrators can also modify other agents' memories.",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -325,7 +325,7 @@ export const TOOL_DESCRIPTORS = [
                 "id"
             ]
         },
-        "outputShape": "The full memory record { id, agentId, content, durability, createdAt, ... } for the caller's own id — embedding + embeddingModel stripped by default.",
+        "outputShape": "The full memory record { id, agentId, content, durability, createdAt, ... } for the requested ID, subject to the caller's read scope; embedding and embeddingModel are stripped by default.",
         "annotations": {
             "readOnlyHint": true
         },
@@ -336,7 +336,7 @@ export const TOOL_DESCRIPTORS = [
     },
     {
         "name": "memory_delete",
-        "description": "Delete a memory by ID. You can only delete your own memories.",
+        "description": "Delete a memory by ID. Non-admin callers can delete only their own memories; administrators can also delete other agents' memories.",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -349,7 +349,7 @@ export const TOOL_DESCRIPTORS = [
                 "id"
             ]
         },
-        "outputShape": "Deletes the caller's own memory at any durability tier (success echo is thin). Cross-owner deletion returns { error, status:403 } for a non-admin; a deleted row round-trips as gone via memory_get.",
+        "outputShape": "Deletes a memory by ID when authorized, at any durability tier (success echo is thin). Cross-owner deletion returns { error, status:403 } for a non-admin; a deleted row round-trips as gone via memory_get.",
         "annotations": {
             "destructiveHint": true
         }
@@ -490,7 +490,7 @@ export const TOOL_DESCRIPTORS = [
             ]
         },
         "outputShape": "Refuses runtime Soul writes, including admin-agent delegation, with { error, status:403 }. Operators use the authenticated REST or CLI path.",
-        "stdioDescription": "Set a personality or project context entry. Included in every bootstrap."
+        "stdioDescription": "Set a personality or project context entry, included in every bootstrap. Soul writes require verified administrator Basic credentials; Ed25519 agent requests are refused. Operators should use the REST API or CLI."
     },
     {
         "name": "soul_get",
@@ -588,7 +588,7 @@ export const TOOL_DESCRIPTORS = [
     },
     {
         "name": "flair_catchup",
-        "description": "Drain YOUR OWN catch-up feed — org events directed to you (or broadcast) after your durable watermark. Returns a page plus a `nextAfter` cursor: page with `after`, then advance the watermark with `ack`. Owner-scoped: the participant is your signed identity, so you can only ever read your own feed — there is no agentId parameter and any other feed is refused (403). At-least-once: an event may arrive twice (re-delivery is safe), an acked event does not re-deliver, and an un-acked event survives a restart.",
+        "description": "Drain the catch-up feed for the configured `FLAIR_AGENT_ID`: directed or broadcast org events after the effective cursor. Omit `after` to start at that agent's durable watermark, or pass `after` to choose an exclusive cursor. Pass `ack` to advance the watermark before this call reads a page; the response includes `nextAfter` for paging. The tool has no argument to change the agent id. Agent requests are signed for the configured id; verified administrator Basic credentials may read that configured feed. Unacknowledged events remain eligible after restart; acknowledged events are skipped by default, but an explicit older `after` can replay them.",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -606,7 +606,7 @@ export const TOOL_DESCRIPTORS = [
                 }
             }
         },
-        "outputShape": "{ events: OrgEvent[], after, nextAfter, watermark, hasMore, pageSize, acked? } — the caller's own directed + broadcast events after its durable watermark, paged; `ack` advances the watermark monotonically (at-least-once — re-delivery is safe).",
+        "outputShape": "{ events: OrgEvent[], after, nextAfter, watermark, hasMore, pageSize, acked? } — the configured agent's directed and broadcast events after the effective cursor; `ack` advances that agent's durable watermark monotonically.",
         "native": false
     },
     {

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@tpsdev-ai/flair-mcp",
-  "version": "0.57.0",
+  "version": "0.58.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/mcp-shim.cjs",
+    "flair-precompact": "dist/precompact-hook.js",
     "flair-session-start": "dist/session-start-hook.js",
-    "flair-continuity-capture": "dist/continuity-capture-hook.js"
+    "flair-continuity-capture": "dist/continuity-capture-hook.js",
+    "flair-prompt-recall": "dist/prompt-recall-hook.js"
   },
   "files": [
     "dist/",
@@ -19,7 +21,7 @@
     "prebuild": "node ../../scripts/vendor-tool-descriptors.mjs packages/flair-mcp/src/tool-descriptors",
     "test": "bun test",
     "prepack": "npm run build",
-    "postinstall": "node -e \"try{const{chmodSync,statSync}=require('fs');for(const p of ['dist/mcp-shim.cjs','dist/index.js','dist/session-start-hook.js','dist/continuity-capture-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)}\""
+    "postinstall": "node -e \"try{const{chmodSync,statSync}=require('fs');for(const p of ['dist/mcp-shim.cjs','dist/index.js','dist/session-start-hook.js','dist/continuity-capture-hook.js','dist/prompt-recall-hook.js','dist/precompact-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"
@@ -29,7 +31,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.27.1",
-    "@tpsdev-ai/flair-client": "0.57.0",
+    "@tpsdev-ai/flair-client": "0.58.0",
     "zod": "4.3.6"
   },
   "license": "Apache-2.0",