@tpsdev-ai/flair-mcp 0.52.0 → 0.54.1

package/README.md

@@ -44,6 +44,9 @@ Once configured, Claude Code (or any MCP client) gets these tools:
 | `memory_store` | Save a memory with type (lesson/decision/fact) and durability. Optional `usedMemoryIds` cites memories that informed the write. |
 | `memory_get` | Retrieve a specific memory by ID. |
 | `memory_delete` | Delete a memory. |
+| `skill_store` | Write a skill (trigger + procedure) as a skill-tagged memory. |
+| `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_get` | Get a personality or project context entry. |

package/dist/adapter-surface.d.ts

@@ -0,0 +1,66 @@
+/**
+ * adapter-surface.ts — the stdio adapter's derived tool set (flair#1580).
+ *
+ * `@tpsdev-ai/flair-mcp` no longer hand-wires per-tool string literals in
+ * index.ts. The advertised set is STDIO_TOOL_DESCRIPTORS from the shared
+ * `@tpsdev-ai/flair-tool-descriptors` module — the same descriptors the
+ * server TOOLS registry binds to Harper impls. Drift is impossible by
+ * construction: a new both-surface descriptor appears here once a
+ * FlairClient handler is bound.
+ *
+ * This module remains the reviewed chokepoint for the stdio ↔ TOOLS seam:
+ *
+ *   1. `ADAPTER_TOOL_NAMES` is DERIVED from STDIO_TOOL_DESCRIPTORS.
+ *   2. `parseAdapterToolNames` still scans for leftover string-literal
+ *      tool names passed to the MCP SDK — hand-wiring is now a CI failure,
+ *      not the registration path.
+ *   3. `STDIO_ADAPTER_EXEMPTIONS` is DERIVED from descriptor surface flags
+ *      (the #1578 list, now structural rather than hand-synced).
+ */
+/** Tools registered on the stdio adapter — derived from the shared descriptor list. */
+export declare const ADAPTER_TOOL_NAMES: string[];
+export type AdapterToolName = (typeof ADAPTER_TOOL_NAMES)[number];
+/**
+ * Reviewed one-sided tools at the stdio-adapter ↔ server TOOLS seam.
+ * Derived from descriptor `native` / `stdio` flags (flair#1580) — the same
+ * names #1578 listed by hand (attention, archive verbs, relationship_store).
+ */
+export declare const STDIO_ADAPTER_EXEMPTIONS: {
+    readonly registryOnly: string[];
+    readonly adapterOnly: string[];
+};
+/**
+ * Collect leftover string-literal tool registrations from adapter source.
+ * After #1580 the derived registrar uses `server.tool(d.name, ...)`, so this
+ * scan should return empty. A new literal is a CI failure.
+ * Does not use `new RegExp` built from runtime input (CodeQL js/regex-injection).
+ */
+export declare function parseAdapterToolNames(source: string): string[];
+/**
+ * Handler keys from `STDIO_TOOL_HANDLERS` in adapter-tools.ts source.
+ * Root unit tests must not import adapter-tools.ts — that module loads
+ * `@tpsdev-ai/flair-client` (built later in the unit lane).
+ */
+export declare function parseStdioHandlerNames(source: string): string[];
+export interface AdapterRegistryParity {
+    /** TOOLS names the adapter neither registers nor exempts. */
+    missingFromAdapter: string[];
+    /** Adapter names that are neither in TOOLS nor adapter-only exempted. */
+    extraOnAdapter: string[];
+    /** Exemption entries that no longer describe a real one-sided difference. */
+    staleExemptions: string[];
+}
+/**
+ * Compare the stdio adapter's tool set to the server TOOLS registry.
+ * Equal after applying the reviewed exemption list — otherwise drift.
+ * Kept from #1578 as the migration tripwire; #1580 also asserts
+ * derived set == descriptor set structurally.
+ */
+export declare function adapterRegistryParity(registryNames: readonly string[], adapterNames: readonly string[]): AdapterRegistryParity;
+/**
+ * Structural #1580 assert: the bound handler set equals the stdio descriptor set.
+ */
+export declare function derivedDescriptorParity(handlerNames: readonly string[], descriptorNamesList?: readonly string[]): {
+    missingHandlers: string[];
+    extraHandlers: string[];
+};

package/dist/adapter-surface.js

@@ -0,0 +1,116 @@
+/**
+ * adapter-surface.ts — the stdio adapter's derived tool set (flair#1580).
+ *
+ * `@tpsdev-ai/flair-mcp` no longer hand-wires per-tool string literals in
+ * index.ts. The advertised set is STDIO_TOOL_DESCRIPTORS from the shared
+ * `@tpsdev-ai/flair-tool-descriptors` module — the same descriptors the
+ * server TOOLS registry binds to Harper impls. Drift is impossible by
+ * construction: a new both-surface descriptor appears here once a
+ * FlairClient handler is bound.
+ *
+ * This module remains the reviewed chokepoint for the stdio ↔ TOOLS seam:
+ *
+ *   1. `ADAPTER_TOOL_NAMES` is DERIVED from STDIO_TOOL_DESCRIPTORS.
+ *   2. `parseAdapterToolNames` still scans for leftover string-literal
+ *      tool names passed to the MCP SDK — hand-wiring is now a CI failure,
+ *      not the registration path.
+ *   3. `STDIO_ADAPTER_EXEMPTIONS` is DERIVED from descriptor surface flags
+ *      (the #1578 list, now structural rather than hand-synced).
+ */
+import { STDIO_TOOL_DESCRIPTORS, SURFACE_EXEMPTIONS, descriptorNames, } from "@tpsdev-ai/flair-tool-descriptors";
+/** Tools registered on the stdio adapter — derived from the shared descriptor list. */
+export const ADAPTER_TOOL_NAMES = descriptorNames(STDIO_TOOL_DESCRIPTORS);
+/**
+ * Reviewed one-sided tools at the stdio-adapter ↔ server TOOLS seam.
+ * Derived from descriptor `native` / `stdio` flags (flair#1580) — the same
+ * names #1578 listed by hand (attention, archive verbs, relationship_store).
+ */
+export const STDIO_ADAPTER_EXEMPTIONS = {
+    registryOnly: SURFACE_EXEMPTIONS.registryOnly,
+    adapterOnly: SURFACE_EXEMPTIONS.adapterOnly,
+};
+/**
+ * Collect leftover string-literal tool registrations from adapter source.
+ * After #1580 the derived registrar uses `server.tool(d.name, ...)`, so this
+ * scan should return empty. A new literal is a CI failure.
+ * Does not use `new RegExp` built from runtime input (CodeQL js/regex-injection).
+ */
+export function parseAdapterToolNames(source) {
+    const names = [];
+    const re = /server\.tool\(\s*"([a-z][a-z0-9_]*)"/g;
+    let match;
+    while ((match = re.exec(source)) !== null)
+        names.push(match[1]);
+    return names;
+}
+/**
+ * Handler keys from `STDIO_TOOL_HANDLERS` in adapter-tools.ts source.
+ * Root unit tests must not import adapter-tools.ts — that module loads
+ * `@tpsdev-ai/flair-client` (built later in the unit lane).
+ */
+export function parseStdioHandlerNames(source) {
+    const marker = "export const STDIO_TOOL_HANDLERS";
+    const start = source.indexOf(marker);
+    if (start < 0)
+        return [];
+    const open = source.indexOf("{", start);
+    if (open < 0)
+        return [];
+    let depth = 0;
+    let close = -1;
+    for (let i = open; i < source.length; i++) {
+        const c = source[i];
+        if (c === "{")
+            depth++;
+        else if (c === "}") {
+            depth--;
+            if (depth === 0) {
+                close = i;
+                break;
+            }
+        }
+    }
+    if (close < 0)
+        return [];
+    const names = [];
+    for (const line of source.slice(open + 1, close).split("\n")) {
+        const m = line.match(/^\s*([a-z][a-z0-9_]*)\s*,?\s*$/);
+        if (m)
+            names.push(m[1]);
+    }
+    return names.sort();
+}
+/**
+ * Compare the stdio adapter's tool set to the server TOOLS registry.
+ * Equal after applying the reviewed exemption list — otherwise drift.
+ * Kept from #1578 as the migration tripwire; #1580 also asserts
+ * derived set == descriptor set structurally.
+ */
+export function adapterRegistryParity(registryNames, adapterNames) {
+    const registry = new Set(registryNames);
+    const adapter = new Set(adapterNames);
+    const registryOnly = new Set(STDIO_ADAPTER_EXEMPTIONS.registryOnly);
+    const adapterOnly = new Set(STDIO_ADAPTER_EXEMPTIONS.adapterOnly);
+    const missingFromAdapter = [...registry]
+        .filter((name) => !adapter.has(name) && !registryOnly.has(name))
+        .sort();
+    const extraOnAdapter = [...adapter]
+        .filter((name) => !registry.has(name) && !adapterOnly.has(name))
+        .sort();
+    const staleExemptions = [
+        ...[...registryOnly].filter((name) => !registry.has(name) || adapter.has(name)),
+        ...[...adapterOnly].filter((name) => !adapter.has(name) || registry.has(name)),
+    ].sort();
+    return { missingFromAdapter, extraOnAdapter, staleExemptions };
+}
+/**
+ * Structural #1580 assert: the bound handler set equals the stdio descriptor set.
+ */
+export function derivedDescriptorParity(handlerNames, descriptorNamesList = ADAPTER_TOOL_NAMES) {
+    const handlers = new Set(handlerNames);
+    const descriptors = new Set(descriptorNamesList);
+    return {
+        missingHandlers: [...descriptors].filter((n) => !handlers.has(n)).sort(),
+        extraHandlers: [...handlers].filter((n) => !descriptors.has(n)).sort(),
+    };
+}

package/dist/adapter-tools.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Stdio adapter bindings (flair#1580).
+ *
+ * The tool SET is derived from STDIO_TOOL_DESCRIPTORS. This module only
+ * supplies FlairClient HTTP handlers — one per stdio descriptor. A new
+ * descriptor with no handler (or a handler with no descriptor) fails at
+ * registration, so the surfaces cannot drift by omission.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { FlairClient } from "@tpsdev-ai/flair-client";
+import { type PresenceActivity } from "./presence.js";
+export interface AdapterContext {
+    flair: FlairClient;
+    agentId: string;
+    heartbeat: (activity?: PresenceActivity) => void;
+    rememberTask: (task: string | undefined) => void;
+}
+type ToolResult = {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+    structuredContent?: Record<string, unknown>;
+};
+type StdioHandler = (args: Record<string, any>, ctx: AdapterContext) => Promise<ToolResult>;
+/** FlairClient bindings keyed by descriptor name — the adapter-side impl map. */
+export declare const STDIO_TOOL_HANDLERS: Record<string, StdioHandler>;
+export declare function stdioHandlerNames(): string[];
+/**
+ * Register every stdio descriptor on the MCP server. The advertised set is
+ * STDIO_TOOL_DESCRIPTORS — not a hand-written per-tool literal list.
+ */
+export declare function registerStdioTools(server: McpServer, ctx: AdapterContext): string[];
+export {};

package/dist/adapter-tools.js

@@ -0,0 +1,381 @@
+/**
+ * Stdio adapter bindings (flair#1580).
+ *
+ * The tool SET is derived from STDIO_TOOL_DESCRIPTORS. This module only
+ * supplies FlairClient HTTP handlers — one per stdio descriptor. A new
+ * descriptor with no handler (or a handler with no descriptor) fails at
+ * registration, so the surfaces cannot drift by omission.
+ */
+import { STDIO_TOOL_DESCRIPTORS, toStdioMcpToolDef, } from "@tpsdev-ai/flair-tool-descriptors";
+import { buildCatchupRequest, summarizeCatchup } from "./catchup.js";
+import { classifyError } from "./errors.js";
+import { jsonSchemaToZodShape } from "./json-schema-zod.js";
+import { deriveActivity } from "./presence.js";
+import { buildRecordUsageBody, citationIds, withCiteNudge } from "./usage.js";
+import { buildSkillSearchBody, buildSkillStoreBody, formatSkillCatalog, isSkillRecord, projectSkillSearchResponse, stripInternalMemoryFields, } from "./skills.js";
+function errorResult(err, flairUrl) {
+    return { content: [{ type: "text", text: classifyError(err, flairUrl) }], isError: true };
+}
+const memory_search = async ({ query, limit }, { flair, heartbeat }) => {
+    heartbeat();
+    try {
+        const results = await flair.memory.search(query, { limit: limit ?? 5 });
+        if (results.length === 0) {
+            return { content: [{ type: "text", text: "No relevant memories found." }] };
+        }
+        const text = results
+            .map((r, i) => {
+            const date = r.createdAt ? r.createdAt.slice(0, 10) : "";
+            const idStr = r.id ? `id:${r.id}` : "";
+            const meta = [date, r.type, idStr].filter(Boolean).join(", ");
+            return `${i + 1}. ${r.content}${meta ? ` (${meta})` : ""}`;
+        })
+            .join("\n");
+        return { content: [{ type: "text", text: withCiteNudge(text) }] };
+    }
+    catch (err) {
+        return errorResult(err, flair.url);
+    }
+};
+const memory_store = async ({ content, type, durability, tags, visibility, usedMemoryIds }, { flair, heartbeat }) => {
+    heartbeat();
+    try {
+        const result = await flair.memory.write(content, {
+            type: (type ?? "session"),
+            durability: (durability ?? "standard"),
+            tags,
+            visibility: visibility,
+            dedup: true,
+            dedupThreshold: 0.95,
+            usedMemoryIds: citationIds(usedMemoryIds),
+        });
+        const deduplicated = result.deduplicated === true;
+        const matchedId = result.matchedId;
+        const effectiveVisibility = result.visibility;
+        const preview = content.length > 120 ? content.slice(0, 120) + "..." : content;
+        const tagStr = tags && tags.length > 0 ? tags.join(", ") : "none";
+        const lines = [
+            `Memory stored (id: ${result.id})`,
+            `Preview: ${preview}`,
+            `Size: ${content.length} chars`,
+            `Tags: ${tagStr}`,
+            `Type: ${type ?? "session"}, Durability: ${durability ?? "standard"}, Visibility: ${effectiveVisibility ?? "(server default)"}`,
+        ];
+        if (deduplicated && matchedId) {
+            lines.push("", `Note: similar to existing memory id=${matchedId} — both are kept. ` +
+                `If this was meant to UPDATE that memory rather than add a new one, use memory_update instead.`);
+        }
+        return {
+            content: [{ type: "text", text: lines.join("\n") }],
+            structuredContent: { deduplicated, id: result.id, written: true, ...(deduplicated ? { matchedId } : {}) },
+        };
+    }
+    catch (err) {
+        return errorResult(err, flair.url);
+    }
+};
+const memory_update = async ({ id, content, preserveHistory, usedMemoryIds }, { flair, heartbeat }) => {
+    heartbeat();
+    try {
+        const result = await flair.memory.update(id, content, {
+            preserveHistory,
+            usedMemoryIds: citationIds(usedMemoryIds),
+        });
+        const text = preserveHistory
+            ? `Memory updated: new version stored (id: ${result.id}), supersedes ${id}.`
+            : `Memory updated (id: ${id}).`;
+        return {
+            content: [{ type: "text", text }],
+            structuredContent: { id: result.id, supersedes: preserveHistory ? id : undefined, written: true },
+        };
+    }
+    catch (err) {
+        return errorResult(err, flair.url);
+    }
+};
+const memory_get = async ({ id }, { flair, heartbeat }) => {
+    heartbeat();
+    try {
+        const mem = await flair.memory.get(id);
+        if (!mem)
+            return { content: [{ type: "text", text: `Memory ${id} not found.` }] };
+        return { content: [{ type: "text", text: `${mem.content}\n\n(type: ${mem.type}, durability: ${mem.durability}, created: ${mem.createdAt})` }] };
+    }
+    catch (err) {
+        return errorResult(err, flair.url);
+    }
+};
+const memory_delete = async ({ id }, { flair, heartbeat }) => {
+    heartbeat();
+    try {
+        await flair.memory.delete(id);
+        return { content: [{ type: "text", text: `Memory ${id} deleted.` }] };
+    }
+    catch (err) {
+        return errorResult(err, flair.url);
+    }
+};
+const relationship_store = async ({ subject, predicate, object, confidence, validFrom, validTo, source }, { flair, heartbeat }) => {
+    heartbeat();
+    try {
+        const result = await flair.relationship.write({ subject, predicate, object, confidence, validFrom, validTo, source });
+        const confStr = confidence !== undefined ? ` (confidence: ${confidence})` : "";
+        return {
+            content: [{ type: "text", text: `Relationship recorded: ${subject} → ${predicate} → ${object}${confStr} (id: ${result.id})` }],
+            structuredContent: { id: result.id, subject, predicate, object, written: true },
+        };
+    }
+    catch (err) {
+        return errorResult(err, flair.url);
+    }
+};
+const bootstrap = async ({ maxTokens, currentTask, channel, surface, subjects }, { flair, heartbeat, rememberTask }) => {
+    if (currentTask)
+        rememberTask(currentTask);
+    heartbeat(deriveActivity({ channel, surface }));
+    try {
+        const result = await flair.bootstrap({ maxTokens, currentTask, channel, surface, subjects });
+        if (!result.context) {
+            return { content: [{ type: "text", text: "No context available." }] };
+        }
+        return { content: [{ type: "text", text: withCiteNudge(result.context) }] };
+    }
+    catch (err) {
+        return errorResult(err, flair.url);
+    }
+};
+const soul_set = async ({ key, value }, { flair, heartbeat }) => {
+    heartbeat();
+    try {
+        await flair.soul.set(key, value);
+        return { content: [{ type: "text", text: `Soul entry '${key}' set.` }] };
+    }
+    catch (err) {
+        return errorResult(err, flair.url);
+    }
+};
+const soul_get = async ({ key }, { flair, heartbeat }) => {
+    heartbeat();
+    try {
+        const entry = await flair.soul.get(key);
+        if (!entry)
+            return { content: [{ type: "text", text: `No soul entry for '${key}'.` }] };
+        return { content: [{ type: "text", text: entry.value }] };
+    }
+    catch (err) {
+        return errorResult(err, flair.url);
+    }
+};
+const flair_workspace_set = async ({ ref, label, provider, task, phase, summary }, { flair, agentId, heartbeat }) => {
+    heartbeat();
+    try {
+        const body = {
+            id: `${agentId}:${ref}`,
+            ref,
+            provider: provider ?? "mcp",
+            timestamp: new Date().toISOString(),
+        };
+        if (label)
+            body.label = label;
+        if (task)
+            body.taskId = task;
+        if (phase)
+            body.phase = phase;
+        if (summary)
+            body.summary = summary;
+        await flair.request("POST", "/WorkspaceState", body);
+        return { content: [{ type: "text", text: `Workspace state set: ref=${ref}${phase ? `, phase=${phase}` : ""} (attributed to ${agentId}).` }] };
+    }
+    catch (err) {
+        return errorResult(err, flair.url);
+    }
+};
+const flair_orgevent = async ({ kind, summary, detail, scope, targets }, { flair, agentId, heartbeat }) => {
+    heartbeat();
+    try {
+        const body = { kind, summary };
+        if (detail)
+            body.detail = detail;
+        if (scope)
+            body.scope = scope;
+        if (targets && targets.length > 0)
+            body.targetIds = targets;
+        const result = await flair.request("POST", "/OrgEvent", body);
+        const targetStr = targets && targets.length > 0 ? ` → ${targets.join(", ")}` : "";
+        const idStr = result?.id ? ` (id: ${result.id})` : "";
+        return { content: [{ type: "text", text: `OrgEvent published: kind=${kind}${targetStr} (attributed to ${agentId})${idStr}.` }] };
+    }
+    catch (err) {
+        return errorResult(err, flair.url);
+    }
+};
+const flair_catchup = async (args, { flair, agentId, heartbeat }) => {
+    heartbeat();
+    try {
+        // Owner-scope by construction: the request path is built from the CALLER's
+        // own agentId (identity), never a tool argument — `args` is consulted only
+        // for after/limit/ack. There is deliberately no agentId/participantId
+        // parameter, so a caller cannot name another feed (the server also refuses
+        // a cross-agent read with 403).
+        const request = buildCatchupRequest(agentId, args);
+        if (request.ackPosition) {
+            // Advance-on-ack (monotonic, re-ack safe) BEFORE the read, so a caller
+            // draining page N while acking page N-1 reads page N — and an ack never
+            // hides an event that was in the same response.
+            await flair.request("POST", request.ackPath, { position: request.ackPosition });
+        }
+        const page = await flair.request("GET", request.getPath);
+        const { text, structuredContent } = summarizeCatchup(page, request.ackPosition);
+        return { content: [{ type: "text", text }], structuredContent };
+    }
+    catch (err) {
+        return errorResult(err, flair.url);
+    }
+};
+const record_usage = async ({ memoryId, memoryIds, attribution }, { flair, heartbeat }) => {
+    heartbeat();
+    try {
+        const body = buildRecordUsageBody({ memoryId, memoryIds, attribution });
+        if (!body) {
+            return {
+                content: [{ type: "text", text: "record_usage requires memoryId or memoryIds." }],
+                isError: true,
+            };
+        }
+        const result = await flair.request("POST", "/RecordUsage", body);
+        const text = result?.recorded === true ? "Usage recorded." : "Usage request accepted.";
+        return {
+            content: [{ type: "text", text }],
+            structuredContent: { recorded: result?.recorded === true },
+        };
+    }
+    catch (err) {
+        return errorResult(err, flair.url);
+    }
+};
+const skill_store = async ({ content, trigger, name, description, tags }, { flair, heartbeat }) => {
+    heartbeat();
+    try {
+        const { id, body } = buildSkillStoreBody({
+            agentId: flair.agentId,
+            content,
+            trigger,
+            name,
+            description,
+            tags,
+            claimedClient: flair.claimedClient,
+        });
+        const result = await flair.request("PUT", `/Memory/${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 = [
+            `Skill stored (id: ${writtenId})`,
+            `Preview: ${preview}`,
+            name ? `Name: ${name}` : undefined,
+            trigger ? `Trigger: ${trigger}` : undefined,
+        ].filter((line) => line != null);
+        return {
+            content: [{ type: "text", text: lines.join("\n") }],
+            structuredContent: { id: writtenId, written: true },
+        };
+    }
+    catch (err) {
+        return errorResult(err, flair.url);
+    }
+};
+const skill_search = async ({ task, limit }, { flair, heartbeat }) => {
+    heartbeat();
+    try {
+        const raw = await flair.request("POST", "/SemanticSearch", buildSkillSearchBody({ task, limit: limit ?? 5 }));
+        const projected = projectSkillSearchResponse(raw);
+        if (!projected || typeof projected !== "object" || !Array.isArray(projected.results)) {
+            return { content: [{ type: "text", text: "No matching skills found." }] };
+        }
+        const results = projected.results;
+        return {
+            content: [{ type: "text", text: formatSkillCatalog(results) }],
+            structuredContent: { results },
+        };
+    }
+    catch (err) {
+        return errorResult(err, flair.url);
+    }
+};
+const skill_get = async ({ id }, { flair, heartbeat }) => {
+    heartbeat();
+    try {
+        const mem = await flair.memory.get(id);
+        if (!mem || !isSkillRecord(mem)) {
+            return { content: [{ type: "text", text: `Skill ${id} not found.` }] };
+        }
+        const record = stripInternalMemoryFields(mem);
+        const trigger = typeof record.trigger === "string" && record.trigger.length > 0 ? record.trigger : "";
+        const text = [
+            record.content,
+            "",
+            `(id: ${record.id}${trigger ? `, trigger: ${trigger}` : ""}, tags: ${Array.isArray(record.tags) ? record.tags.join(", ") : "skill"}, created: ${record.createdAt ?? ""})`,
+        ].join("\n");
+        return {
+            content: [{ type: "text", text }],
+            structuredContent: record,
+        };
+    }
+    catch (err) {
+        return errorResult(err, flair.url);
+    }
+};
+/** FlairClient bindings keyed by descriptor name — the adapter-side impl map. */
+export const STDIO_TOOL_HANDLERS = {
+    memory_search,
+    memory_store,
+    memory_update,
+    memory_get,
+    memory_delete,
+    relationship_store,
+    bootstrap,
+    soul_set,
+    soul_get,
+    flair_workspace_set,
+    flair_orgevent,
+    flair_catchup,
+    record_usage,
+    skill_store,
+    skill_search,
+    skill_get,
+};
+export function stdioHandlerNames() {
+    return Object.keys(STDIO_TOOL_HANDLERS).sort();
+}
+/**
+ * Register every stdio descriptor on the MCP server. The advertised set is
+ * STDIO_TOOL_DESCRIPTORS — not a hand-written per-tool literal list.
+ */
+export function registerStdioTools(server, ctx) {
+    const registered = [];
+    const missing = [];
+    for (const d of STDIO_TOOL_DESCRIPTORS) {
+        const handler = STDIO_TOOL_HANDLERS[d.name];
+        if (!handler) {
+            missing.push(d.name);
+            continue;
+        }
+        const def = toStdioMcpToolDef(d);
+        const shape = jsonSchemaToZodShape(def.inputSchema);
+        const cb = async (args) => handler(args, ctx);
+        if (d.annotations) {
+            server.tool(d.name, def.description, shape, d.annotations, cb);
+        }
+        else {
+            server.tool(d.name, def.description, shape, cb);
+        }
+        registered.push(d.name);
+    }
+    if (missing.length > 0) {
+        throw new Error(`stdio adapter missing FlairClient bindings for descriptors: ${missing.join(", ")}`);
+    }
+    const extra = Object.keys(STDIO_TOOL_HANDLERS).filter((n) => !registered.includes(n)).sort();
+    if (extra.length > 0) {
+        throw new Error(`stdio adapter bindings have no stdio descriptor: ${extra.join(", ")}`);
+    }
+    return registered;
+}

package/dist/catchup.d.ts

@@ -0,0 +1,58 @@
+/**
+ * catchup.ts — pure helpers for the flair_catchup stdio binding (flair#1583).
+ *
+ * Owner-scope is enforced BY CONSTRUCTION: the participantId in the request
+ * path is always the caller's own agentId (from `FLAIR_AGENT_ID` / the signed
+ * identity), never a tool argument. The descriptor advertises no `agentId` /
+ * `participantId` property, so there is nothing to name another agent's feed
+ * with — and the server independently refuses a cross-agent read (403). This
+ * module is HTTP-/Harper-free (plain helpers + types) so the flair-mcp
+ * package stays FlairClient-only.
+ */
+/**
+ * `GET /OrgEventCatchup/{participantId}` response shape
+ * (resources/OrgEventCatchup.ts). `position` is stamped onto every event
+ * (see org-event-catchup-lib.ts `withEventPosition`), and is what a caller
+ * passes back as `ack` once it has processed the event.
+ */
+export interface CatchupPage {
+    events?: Array<Record<string, unknown>> | null;
+    /** Resolved exclusive cursor this page was read after. */
+    after?: string | null;
+    /** Cursor to continue a drain — the last event's position (or `after` when the page is empty). */
+    nextAfter?: string | null;
+    /** Durable watermark at read time (null when the caller has none yet). */
+    watermark?: string | null;
+    hasMore?: boolean;
+    pageSize?: number;
+}
+export interface CatchupArgs {
+    after?: unknown;
+    limit?: unknown;
+    ack?: unknown;
+}
+export interface CatchupRequest {
+    /** Owner-scoped base path — the caller's own participantId. */
+    path: string;
+    /** GET path (base + optional query). */
+    getPath: string;
+    /** POST path for the ack (same owner-scoped base). */
+    ackPath: string;
+    /** Non-empty ack position, or null when the caller did not ack. */
+    ackPosition: string | null;
+}
+/**
+ * Build the owner-scoped catchup request from tool args. `participantId` is
+ * ALWAYS `agentId` — the args cannot redirect it.
+ */
+export declare function buildCatchupRequest(agentId: string, args: CatchupArgs): CatchupRequest;
+export interface CatchupSummary {
+    text: string;
+    structuredContent: Record<string, unknown>;
+}
+/**
+ * Project a catchup page into the caller-facing text summary plus the
+ * structured echo (the machine-readable payload). Never throws on a
+ * malformed/absent page — it degrades to "no new events".
+ */
+export declare function summarizeCatchup(page: CatchupPage | undefined, acked: string | null): CatchupSummary;