@tpsdev-ai/flair 0.52.0 → 0.54.1

package/dist/resources/health.js

@@ -11,7 +11,10 @@ import { REM_DEDUP_STATS_PATH } from "./dedup-cluster.js";
 import { hybridEnabled } from "./bm25.js";
 import { bm25IndexEnabled, bm25IndexStatus } from "./bm25-index-service.js";
 import { normalizeStamp } from "./embedding-space-guard.js";
+import { getModelId } from "./embeddings-provider.js";
+import { describeStampOutstanding, EMBEDDING_STAMP_ID } from "./migrations/stamp-outstanding.js";
 import { buildPublicHealthBody, resolveSearchReadiness } from "./search-readiness.js";
+import { classifyPeerLiveness, federationPeersAllDisconnectedWarning, summarizePeerLiveness, } from "./federation-peer-liveness.js";
 const db = databases;
 const redactHome = (p) => {
     const home = homedir();
@@ -160,6 +163,14 @@ export class HealthDetail extends Resource {
         const stats = { ok: true };
         const nowMs = Date.now();
         const warnings = [];
+        // flair#1073: set while walking memories, consumed after the migrations
+        // snapshot so the outstanding-migration warning can name runner state.
+        // Never copied onto `stats` — it is not part of the /HealthDetail shape.
+        // `memoryScanOk` is the gate (not "mixed spaces"): a uniformly pre-flip
+        // corpus is one space and still outstanding against getModelId().
+        let mixedEmbeddingSpaces = false;
+        let memoryScanOk = false;
+        let memoryModelCounts = {};
         // flair#1326: same search-ready signal as public /Health. HealthDetail
         // stays HTTP 200 (it is a stats dump, not a traffic gate); the field
         // and a warning name the lag so `flair status` / operators can see it.
@@ -258,13 +269,12 @@ export class HealthDetail extends Resource {
             // re-embed) still trips it, and that is exactly when the query-time guard
             // degrades recall to keyword-only.
             const distinctSpaces = new Set(realModels.map((k) => normalizeStamp(k)).filter((s) => s !== null));
-            if (distinctSpaces.size > 1) {
-                const list = realModels.map((k) => `${k}:${modelCounts[k]}`).join(", ");
-                warnings.push({
-                    level: "warn",
-                    message: `multiple embedding models in use (${list}) — cross-model search unreliable; run: flair reembed against one model`,
-                });
-            }
+            // Always keep counts — a uniformly stale pre-flip corpus is one space
+            // and must still name embedding-stamp (Bugbot High on flair#1606).
+            memoryScanOk = true;
+            memoryModelCounts = modelCounts;
+            if (distinctSpaces.size > 1)
+                mixedEmbeddingSpaces = true;
         }
         catch {
             stats.memories = null;
@@ -378,11 +388,16 @@ export class HealthDetail extends Resource {
             }
             else {
                 const inst = instances[0];
+                // flair#1499: derive connected/down from lastSyncAt, not stored
+                // status. Pairing writes `paired`; a recent lastSyncAt is connected.
+                // Revoked rows are counted separately and never drive the >24h warning.
+                const liveness = summarizePeerLiveness(peers, nowMs);
                 const peersBlock = {
-                    total: peers.length,
-                    connected: peers.filter((p) => p.status === "connected").length,
-                    disconnected: peers.filter((p) => p.status === "disconnected").length,
-                    revoked: peers.filter((p) => p.status === "revoked").length,
+                    total: liveness.total,
+                    connected: liveness.connected,
+                    disconnected: liveness.disconnected,
+                    revoked: liveness.revoked,
+                    unknown: liveness.unknown,
                 };
                 const pendingTokens = tokens.filter((t) => !t.consumedBy && t.expiresAt && new Date(t.expiresAt).getTime() > nowMs).length;
                 stats.federation = {
@@ -395,17 +410,13 @@ export class HealthDetail extends Resource {
                             role: p.role,
                             status: p.status,
                             lastSyncAt: p.lastSyncAt ?? null,
+                            liveness: classifyPeerLiveness(p, nowMs),
                         }))
                         : undefined,
                 };
-                if (peers.length > 0 && peersBlock.connected === 0) {
-                    const oldest = peers
-                        .map((p) => (p.lastSyncAt ? new Date(p.lastSyncAt).getTime() : 0))
-                        .reduce((a, b) => (a === 0 ? b : b === 0 ? a : Math.min(a, b)), 0);
-                    if (oldest > 0 && nowMs - oldest > 24 * 3600 * 1000) {
-                        warnings.push({ level: "warn", message: "federation peers all disconnected >24h" });
-                    }
-                }
+                const disconnectWarn = federationPeersAllDisconnectedWarning(liveness);
+                if (disconnectWarn)
+                    warnings.push(disconnectWarn);
                 if (pendingTokens > 0) {
                     warnings.push({ level: "info", message: `${pendingTokens} pairing token(s) unconsumed` });
                 }
@@ -660,9 +671,47 @@ export class HealthDetail extends Resource {
                     message: "migration boot cycle never fired on this instance (cyclePhase=idle) — no migration will run until this is resolved; see `flair doctor`",
                 });
             }
+            if (memoryScanOk) {
+                const stamp = snapshot.migrations.find((m) => m.id === EMBEDDING_STAMP_ID);
+                const outstanding = describeStampOutstanding({
+                    modelCounts: memoryModelCounts,
+                    currentModelId: getModelId(),
+                    migration: stamp,
+                    cyclePhase: snapshot.cyclePhase,
+                    lastCycleError: snapshot.lastCycleError,
+                });
+                if (outstanding.outstanding) {
+                    warnings.push({ level: "warn", message: outstanding.warning });
+                }
+                else if (mixedEmbeddingSpaces) {
+                    const list = Object.entries(memoryModelCounts)
+                        .filter(([k, n]) => k !== "hash-512d" && n > 0)
+                        .map(([k, n]) => `${k}:${n}`)
+                        .join(", ");
+                    warnings.push({
+                        level: "warn",
+                        message: `multiple embedding models in use (${list}) — cross-model search unreliable; run: flair reembed against one model`,
+                    });
+                }
+            }
         }
         catch {
             stats.migrations = null;
+            if (memoryScanOk) {
+                const outstanding = describeStampOutstanding({
+                    modelCounts: memoryModelCounts,
+                    currentModelId: getModelId(),
+                });
+                if (outstanding.outstanding) {
+                    warnings.push({ level: "warn", message: outstanding.warning });
+                }
+                else if (mixedEmbeddingSpaces) {
+                    warnings.push({
+                        level: "warn",
+                        message: `multiple embedding models in use — cross-model search unreliable; run: flair reembed against one model`,
+                    });
+                }
+            }
         }
         // ── Disk ──
         // flair#812: same shared read-only resolution as the migrations section

package/dist/resources/mcp-tools.js

@@ -26,15 +26,12 @@
  * 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.
+ * NOTE (flair#1580): MCP-facing metadata (name, description, inputSchema,
+ * output shape) lives in `@tpsdev-ai/flair-tool-descriptors`. This registry
+ * binds each *native* descriptor to its Harper impl. The stdio adapter binds
+ * the same list (stdio surface) to FlairClient HTTP — tool-set drift is
+ * impossible by construction. One-sided tools (`attention`, archive verbs,
+ * `relationship_store`) are flagged on the descriptor, not hand-exempted.
  */
 /**
  * The delegated handler classes, held in a mutable registry, LAZILY loaded on
@@ -54,8 +51,9 @@
 import { AUTHORITY_FIELDS } from "./authority-field-guard.js";
 import { resolveVersion } from "./version.js";
 import { agentContext, adminContext, collectionResource } from "./in-process.js";
-import { RECORD_USAGE_ID_MERGE_CONTRACT, unionUsageMemoryIds } from "./usage-ids.js";
+import { unionUsageMemoryIds } from "./usage-ids.js";
 import { SKILL_TAG, isSkillWrite } from "./skill-write.js";
+import { NATIVE_TOOL_DESCRIPTORS, toMcpToolDef, } from "@tpsdev-ai/flair-tool-descriptors";
 const H = {};
 const LOADERS = {
     SemanticSearch: async () => (await import("./SemanticSearch.js")).SemanticSearch,
@@ -405,7 +403,8 @@ async function skillSearch(agent, args) {
  * returns the same 404 as an unreadable id. Returning it would (a) make
  * skill_get an alias for memory_get, and (b) reveal a readable non-skill
  * memory's existence through a skill-shaped call; a uniform 404 does neither.
- * The embedding fields are stripped by default, same as memory_get.
+ * The embedding fields are always stripped (flair#1593) — there is no
+ * includeEmbedding opt-in. memory_get keeps that flag (flair#1188).
  */
 async function skillGet(agent, args) {
     const Cls = await handler("Memory");
@@ -419,7 +418,9 @@ async function skillGet(agent, args) {
     // returned (see the doc above).
     if (!isSkillWrite(result))
         return { error: "skill not found", status: 404 };
-    return args?.includeEmbedding === true ? result : stripInternalFields(result);
+    // flair#1593 — always strip. includeEmbedding used to bypass this and
+    // ride the raw vector; nothing in the skill_get contract needs it.
+    return stripInternalFields(result);
 }
 /**
  * memory_update — id-targeted, dedup-BYPASSED overwrite/version path (memory-
@@ -850,24 +851,33 @@ export function mcpToolName(table, toolPrefix, verb) {
     const override = TOOL_NAME_OVERRIDES[table]?.[verb];
     return override ?? `${toolPrefix}_${verb}`;
 }
-export const TOOLS = {
+/**
+ * Bind native descriptors to Harper impls + conformance contracts.
+ * A descriptor without a binding (or a binding without a native descriptor)
+ * throws at module load — the tool set is derived, not hand-copied.
+ */
+function bindNativeTools(bindings) {
+    const tools = {};
+    const missing = [];
+    for (const d of NATIVE_TOOL_DESCRIPTORS) {
+        const b = bindings[d.name];
+        if (!b) {
+            missing.push(d.name);
+            continue;
+        }
+        tools[d.name] = { def: toMcpToolDef(d), impl: b.impl, contract: b.contract };
+    }
+    if (missing.length > 0) {
+        throw new Error(`TOOLS missing Harper bindings for native descriptors: ${missing.join(", ")}`);
+    }
+    const extra = Object.keys(bindings).filter((n) => !Object.prototype.hasOwnProperty.call(tools, n)).sort();
+    if (extra.length > 0) {
+        throw new Error(`TOOLS bindings have no native descriptor: ${extra.join(", ")}`);
+    }
+    return tools;
+}
+export const TOOLS = bindNativeTools({
     memory_search: {
-        def: {
-            name: "memory_search",
-            description: "Search memories by meaning. Understands temporal queries like 'what happened today'. Scoped to your agent's own + granted memories.",
-            annotations: { readOnlyHint: true },
-            inputSchema: {
-                type: "object",
-                properties: {
-                    query: { type: "string", description: "Search query — natural language, semantic matching" },
-                    limit: { type: "number", description: "Max results (default 5)" },
-                    includeTrust: { type: "boolean", description: "Attach a per-result trust-evidence block (provenance, author, usage, freshness, supersession). Default false." },
-                    abstain: { type: "boolean", description: "Opt into first-class abstention: when the best match is below a global confidence threshold, return { abstained: true, reason, bestScore } with no weak matches instead of the N weakest results. Default false." },
-                    includeArchived: { type: "boolean", description: "Include basemented (archived) memories in results. Default false — archived memories are excluded from normal search. When true, archived memories are returned under the SAME read-scope gate as a normal search (never a wider scope)." },
-                },
-                required: ["query"],
-            },
-        },
         impl: memorySearch,
         contract: {
             summary: "{ results: MemoryRecord[] } — semantic hits scoped to the caller's own + granted memories; each hit carries content, never the raw embedding.",
@@ -881,30 +891,6 @@ export const TOOLS = {
         },
     },
     memory_store: {
-        def: {
-            name: "memory_store",
-            description: "Save information to persistent memory. Use for lessons, decisions, preferences, facts. Attributed to your authenticated agent.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    content: { type: "string", description: "What to remember" },
-                    type: { type: "string", enum: ["session", "lesson", "decision", "preference", "fact", "goal"], description: "Memory type (default session)" },
-                    durability: { type: "string", enum: ["permanent", "persistent", "standard", "ephemeral"], description: "permanent > persistent > standard > ephemeral (default standard)" },
-                    tags: { type: "array", items: { type: "string" }, description: "Tag strings" },
-                    visibility: {
-                        type: "string",
-                        enum: ["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.",
-                    },
-                    usedMemoryIds: { type: "array", items: { type: "string" }, description: "IDs of memories that informed this write (citation-on-write). Credited via the same deduped usage ledger as record_usage. Optional." },
-                },
-                required: ["content"],
-            },
-        },
         impl: memoryStore,
         contract: {
             summary: "Write echo { id, written:true, deduplicated } — the new id + confirmation. No internal embedding fields; round-trips via memory_get.",
@@ -916,24 +902,6 @@ export const TOOLS = {
         },
     },
     skill_store: {
-        def: {
-            name: "skill_store",
-            description: "Write a skill (a reusable capability/procedure) as a skill-tagged memory. " +
-                "The `trigger` text is what the skill embeds from (the recall signal — 'when to use this'), " +
-                "and `content` is the full procedure. Skills are forced durability=persistent and are " +
-                "SkillScan-gated before the embed (a dangerous shell/network payload is rejected).",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    content: { type: "string", description: "The full procedure (markdown body of the SKILL.md)" },
-                    trigger: { type: "string", description: "The 'when to use' text — the recall signal the skill embeds from" },
-                    name: { type: "string", description: "Skill name (SKILL.md frontmatter; stored in metadata)" },
-                    description: { type: "string", description: "Skill description (SKILL.md frontmatter; stored in metadata)" },
-                    tags: { type: "array", items: { type: "string" }, description: "Additional tags (the 'skill' tag is added automatically)" },
-                },
-                required: ["content"],
-            },
-        },
         impl: skillStore,
         contract: {
             summary: "Write echo { id, written:true, deduplicated } for the skill-tagged memory. No internal embedding fields; round-trips via memory_get.",
@@ -945,23 +913,6 @@ export const TOOLS = {
         },
     },
     skill_search: {
-        def: {
-            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.",
-            annotations: { readOnlyHint: true },
-            inputSchema: {
-                type: "object",
-                properties: {
-                    task: { type: "string", description: "The task/context to match skills against — natural language; ranked against each skill's trigger" },
-                    limit: { type: "number", description: "Max skills to return (default 5)" },
-                },
-                required: ["task"],
-            },
-        },
         impl: skillSearch,
         contract: {
             summary: "{ results: SkillCard[] } — the skill catalog (lightweight id/name/trigger/description/tags/agentId, " +
@@ -979,25 +930,10 @@ export const TOOLS = {
         },
     },
     skill_get: {
-        def: {
-            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.",
-            annotations: { readOnlyHint: true },
-            inputSchema: {
-                type: "object",
-                properties: {
-                    id: { type: "string", description: "Skill (memory) ID" },
-                    includeEmbedding: { type: "boolean", description: "Include the raw embedding vector (large, rarely useful). Default false." },
-                },
-                required: ["id"],
-            },
-        },
         impl: skillGet,
         contract: {
             summary: "The full skill record { id, agentId, content, trigger, tags, durability, metadata, createdAt, ... } for a " +
-                "skill readable under the caller's read-scope — embedding + embeddingModel stripped by default. A non-owner " +
+                "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).",
             requiredFields: ["id", "agentId", "content", "createdAt"],
             fieldTypes: { id: "string", agentId: "string", content: "string" },
@@ -1007,21 +943,6 @@ export const TOOLS = {
         },
     },
     memory_update: {
-        def: {
-            name: "memory_update",
-            description: "Update an existing memory by ID. Dedup-bypassed (this is an intentional overwrite, not a new write). " +
-                "Default: overwrites the same id in place. Pass preserveHistory=true to instead write a new version " +
-                "linked via `supersedes`, closing the old one's validity window.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    id: { type: "string", description: "ID of the memory to update" },
-                    content: { type: "string", description: "New content" },
-                    preserveHistory: { type: "boolean", description: "Write a new version (supersedes-linked) instead of overwriting in place (default false)" },
-                },
-                required: ["id", "content"],
-            },
-        },
         impl: memoryUpdate,
         contract: {
             summary: "Write echo { id, written:true } for the in-place overwrite (or supersede). No internal embedding fields; the change round-trips via memory_get.",
@@ -1033,20 +954,6 @@ export const TOOLS = {
         },
     },
     memory_basement: {
-        def: {
-            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.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    id: { type: "string", description: "ID of the memory to basement (archive)" },
-                },
-                required: ["id"],
-            },
-        },
         impl: memoryBasement,
         contract: {
             summary: "Write echo of the archived record { id, archived:true, archivedAt, ... }. No internal embedding fields; the flip round-trips via memory_get.",
@@ -1058,19 +965,6 @@ export const TOOLS = {
         },
     },
     memory_restore: {
-        def: {
-            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.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    id: { type: "string", description: "ID of the memory to restore (un-archive)" },
-                },
-                required: ["id"],
-            },
-        },
         impl: memoryRestore,
         contract: {
             summary: "Write echo of the restored record { id, archived:false, ... }. No internal embedding fields; the flip round-trips via memory_get.",
@@ -1082,20 +976,6 @@ export const TOOLS = {
         },
     },
     memory_get: {
-        def: {
-            name: "memory_get",
-            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"],
-            },
-        },
         impl: memoryGet,
         contract: {
             summary: "The full memory record { id, agentId, content, durability, createdAt, ... } for the caller's own id — embedding + embeddingModel stripped by default.",
@@ -1107,16 +987,6 @@ export const TOOLS = {
         },
     },
     memory_delete: {
-        def: {
-            name: "memory_delete",
-            description: "Delete a memory by ID. You can only delete your own memories.",
-            annotations: { destructiveHint: true },
-            inputSchema: {
-                type: "object",
-                properties: { id: { type: "string", description: "Memory ID to delete" } },
-                required: ["id"],
-            },
-        },
         impl: memoryDelete,
         contract: {
             summary: "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.",
@@ -1125,31 +995,6 @@ export const TOOLS = {
         },
     },
     bootstrap: {
-        def: {
-            name: "bootstrap",
-            description: "Get session context: soul + memories + predicted context. Run at session start. Pass subjects for predictive loading.",
-            annotations: { readOnlyHint: true },
-            inputSchema: {
-                type: "object",
-                properties: {
-                    maxTokens: { type: "number", description: "Content-selection budget in tokens (default 4000): the hard cap on how much soul/memory/finding CONTENT is selected. The actual serialized response (reported by tokenEstimate) may exceed this by the structured-container JSON scaffolding — maxTokens bounds what is selected, not the raw output size. Raise it to include more content." },
-                    currentTask: { type: "string", description: "Current task — enables semantic search for relevant memories" },
-                    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.",
-                    },
-                    includeTrust: { type: "boolean", description: "Also return a `trust` array with a per-included-memory trust-evidence block (provenance, author, usage, freshness, supersession). Default false." },
-                    abstain: { type: "boolean", description: "Opt into a task-relevance abstention verdict: also return an `abstention` object ({ abstained, bestScore, threshold }) reporting whether any memory covered `currentTask` above a global confidence threshold. Default false." },
-                    includeContext: { type: "boolean", description: "Also return the prose `context` string — a human-readable mirror of the structured soul/memories/predicted/teammateFindings containers (which are the canonical payload). Default false here: the structured fields already carry everything, so shipping the prose too would double the payload." },
-                    maxEvents: { type: "number", description: "Cap on how many recent org events to return (default 10). Events are counted against maxTokens like every other content section." },
-                    includeEventDetail: { type: "boolean", description: "Also include each org event's verbose `detail` JSON (migration internals, etc.). Default false: bootstrap ships lean events (id/kind/summary/createdAt/targetIds/scope); `detail` mostly restates the summary and is pure bloat for a connector." },
-                },
-            },
-        },
         impl: bootstrap,
         contract: {
             summary: "Session context: { agentId, soul, memories, predicted, teammateFindings, events, sections, tokenEstimate, memoriesIncluded, ..., context, flairVersion }. "
@@ -1159,6 +1004,7 @@ export const TOOLS = {
                 "sections", "tokenEstimate", "maxTokens", "memoriesIncluded", "memoriesAvailable",
                 "memoriesTruncated", "teammateFindingsIncluded", "teammateFindingsTruncated",
                 "teammateFindingsMatched", "context", "flairVersion",
+                "eventWatermark", "eventsHasMore", "eventsRemaining",
                 // flair#1270 — the payload token LEDGER: every token-charged content
                 // class has a counter, so tokenEstimate ≈ scaffoldTokens + soulTokens +
                 // memoryTokens + trustTokens + eventsTokens decomposes from the payload
@@ -1174,6 +1020,7 @@ export const TOOLS = {
                 teammateFindingsMatched: "number", context: "string", flairVersion: "string",
                 soulTokens: "number", memoryTokens: "number", trustTokens: "number",
                 eventsTokens: "number", scaffoldTokens: "number",
+                eventWatermark: "string", eventsHasMore: "boolean", eventsRemaining: "number",
             },
             invariants: {
                 // count == delivered — the historical count/charge/deliver drift.
@@ -1262,18 +1109,6 @@ export const TOOLS = {
         },
     },
     soul_set: {
-        def: {
-            name: "soul_set",
-            description: "Soul changes require operator credentials through the REST API or CLI; runtime tool calls are refused.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    key: { type: "string", description: "Entry key (e.g. 'role', 'standards', 'project')" },
-                    value: { type: "string", description: "Entry value" },
-                },
-                required: ["key", "value"],
-            },
-        },
         impl: soulSet,
         contract: {
             summary: "Refuses runtime Soul writes, including admin-agent delegation, with { error, status:403 }. Operators use the authenticated REST or CLI path.",
@@ -1282,16 +1117,6 @@ export const TOOLS = {
         },
     },
     soul_get: {
-        def: {
-            name: "soul_get",
-            description: "Get a personality or project context entry.",
-            annotations: { readOnlyHint: true },
-            inputSchema: {
-                type: "object",
-                properties: { key: { type: "string", description: "Entry key" } },
-                required: ["key"],
-            },
-        },
         impl: soulGet,
         contract: {
             summary: "The soul entry { id, agentId, key, value, createdAt } for the caller's own `${agentId}:${key}`.",
@@ -1301,22 +1126,6 @@ export const TOOLS = {
         },
     },
     flair_workspace_set: {
-        def: {
-            name: "flair_workspace_set",
-            description: "Set your agent's current workspace state in the Office Space coordination layer. Attributed to you — you can only write your own state.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    ref: { type: "string", description: "Workspace ref — branch, worktree, or task ref" },
-                    label: { type: "string", description: "Human-readable label" },
-                    provider: { type: "string", description: "Provider/runtime (default mcp)" },
-                    task: { type: "string", description: "Task/issue id" },
-                    phase: { type: "string", description: "Current phase (design, implement, review)" },
-                    summary: { type: "string", description: "Short summary of current state" },
-                },
-                required: ["ref"],
-            },
-        },
         impl: workspaceSet,
         contract: {
             summary: "Writes the caller's workspace state keyed `${agentId}:${ref}`, attributed to the caller (never the body). The echo is thin; persistence is verified in storage.",
@@ -1324,21 +1133,6 @@ export const TOOLS = {
         },
     },
     flair_orgevent: {
-        def: {
-            name: "flair_orgevent",
-            description: "Publish an org-wide coordination event (claim/release/status) to the Office Space. Attributed to you — you cannot publish as another agent.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    kind: { type: "string", description: "Event kind (coord.claim, coord.release, status)" },
-                    summary: { type: "string", description: "Short summary of the event" },
-                    detail: { type: "string", description: "Longer detail payload" },
-                    scope: { type: "string", description: "Scope (an agent id, repo, or 'org')" },
-                    targets: { type: "array", items: { type: "string" }, description: "Recipient agent ids" },
-                },
-                required: ["kind", "summary"],
-            },
-        },
         impl: orgEvent,
         contract: {
             summary: "Publishes an org event attributed to the caller (authorId from identity, never the body). The echo is thin; persistence is verified in storage.",
@@ -1346,21 +1140,6 @@ export const TOOLS = {
         },
     },
     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,
         contract: {
             summary: "Grouped-by-source view { entity, windowDays, since, groups:{memory,relationship,workspaceState,presence,orgEvent}, counts } for entity E over N days.",
@@ -1373,21 +1152,6 @@ export const TOOLS = {
         },
     },
     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. " +
-                RECORD_USAGE_ID_MERGE_CONTRACT,
-            inputSchema: {
-                type: "object",
-                properties: {
-                    memoryIds: { type: "array", items: { type: "string" }, description: "IDs of the memories that were used (max 20 per call). Merged with memoryId when both are supplied." },
-                    memoryId: { type: "string", description: "Convenience alias for a single memory id. Merged with memoryIds when both are supplied — not dropped." },
-                    attribution: { type: "string", description: "Optional free-text note on what used it (opaque — stored for audit only, max 500 chars)" },
-                },
-            },
-        },
         impl: recordUsage,
         contract: {
             summary: "Invariant acknowledgement { recorded:true } — byte-identical regardless of how many ids counted (no id enumeration, Sherlock).",
@@ -1396,7 +1160,7 @@ export const TOOLS = {
             invariants: { fullyResolved: true },
         },
     },
-};
+});
 /** The tool definitions for a tools/list response (exactly the 12 curated tools). */
 export function listToolDefs() {
     return Object.values(TOOLS).map((t) => t.def);

package/dist/resources/memory-visibility.js

@@ -6,7 +6,7 @@
  *   - resources/memory-read-scope.ts's resolveReadScope() — the cross-agent
  *     READ scope every read path (Memory.search/get, SemanticSearch,
  *     MemoryBootstrap, the by-id auth-middleware guard) resolves through.
- *   - src/cli.ts's runFederationSyncOnce() — the federation-sync PUSH filter
+ *   - src/commands/federation.ts's runFederationSyncOnce() — the federation-sync PUSH filter
  *     that must not replicate `private` memories to peer instances.
  *
  * Deliberately has ZERO imports — not even "harper". That is
@@ -16,8 +16,8 @@
  * imports `databases` from "harper", and that package's
  * top-level init eagerly resolves storage paths and THROWS when there is no
  * live Harper runtime backing it (confirmed empirically — it takes down
- * even `flair --help`). So src/cli.ts must never import
- * resources/memory-read-scope.ts (or anything else that drags that
+ * even `flair --help`). So the CLI (src/cli.ts / src/commands/federation.ts)
+ * must never import resources/memory-read-scope.ts (or anything else that drags that
  * side-effecting import in) directly. This module is the safe seam: a pure
  * function + constant that both sides can import without dragging in
  * "harper".