@tpsdev-ai/flair-mcp 0.53.0 → 0.54.2

package/dist/adapter-surface.d.ts

@@ -1,65 +1,48 @@
 /**
- * adapter-surface.ts — the stdio adapter's declared tool set (flair#1575).
+ * adapter-surface.ts — the stdio adapter's derived tool set (flair#1580).
  *
- * `@tpsdev-ai/flair-mcp` hand-wires each tool via `server.tool(...)` in
- * index.ts. The native `/mcp` handler ships a separate `TOOLS` registry in
- * resources/mcp-tools.ts. Those two surfaces drifted: skill_* landed in
- * TOOLS for 0.52.0 and never reached this package — the surface Claude Code
- * and Cursor actually use.
+ * `@tpsdev-ai/flair-mcp` no longer hand-wires per-tool string literals in
+ * index.ts. The advertised set is STDIO_TOOL_DESCRIPTORS from the descriptor
+ * module vendored at build time into `./tool-descriptors/` (flair#1683;
+ * source of truth: packages/flair-tool-descriptors/src/index.ts) — 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 is the reviewed chokepoint for that seam:
+ * This module remains the reviewed chokepoint for the stdio ↔ TOOLS seam:
  *
- *   1. `ADAPTER_TOOL_NAMES` is the adapter's declared tool set.
- *   2. `parseAdapterToolNames` reads the names actually passed to
- *      `server.tool(...)` in index.ts, so the declaration cannot outrun
- *      registration (or vice versa).
- *   3. `STDIO_ADAPTER_EXEMPTIONS` is the explicit, reviewed list of names
- *      that exist on one surface but not the other. A TOOLS name that is
- *      neither registered here nor exempted is a CI failure — silent drift
- *      of the class that hid skill_*.
- *
- * Deriving the adapter's handlers from TOOLS (so a new registry tool appears
- * here for free) is the durable structural fix; it does not fit this chip
- * because TOOLS is Harper-linked server code and this package talks HTTP via
- * FlairClient. Detection + exemption list ships now; derive is a follow-on.
+ *   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 via `server.tool(...)` in index.ts. */
-export declare const ADAPTER_TOOL_NAMES: readonly ["bootstrap", "flair_orgevent", "flair_workspace_set", "memory_delete", "memory_get", "memory_search", "memory_store", "memory_update", "record_usage", "relationship_store", "skill_get", "skill_search", "skill_store", "soul_get", "soul_set"];
+/** 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 exemptions at the stdio-adapter ↔ server TOOLS seam (flair#1575).
- *
- * A name here is a deliberate, reviewed difference — not silent drift.
- * Adding or removing a name is the control: CI fails if an exemption is
- * unused (the tool appeared on both sides, or vanished from the side it
- * was excused on) or if a non-exempt name exists on only one side.
+ * 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: {
-    /**
-     * Present in resources/mcp-tools.ts `TOOLS`, not wired on the stdio adapter.
-     *
-     * - attention: native /mcp only (flair#677). mcp-tools.ts's module doc
-     *   explicitly does not mirror it into this package.
-     * - memory_basement / memory_restore: archive verbs (flair#1472) landed
-     *   on native /mcp; not yet forwarded over FlairClient.
-     */
-    readonly registryOnly: readonly ["attention", "memory_basement", "memory_restore"];
-    /**
-     * Wired on the stdio adapter, absent from `TOOLS`.
-     *
-     * - relationship_store: the adapter predates the record-types mcp
-     *   declaration. Relationship has no `RECORD_TYPES.mcp` field, so TOOLS
-     *   ships zero relationship_* names. The adapter still exposes the triple
-     *   write (FlairClient.relationship.write).
-     */
-    readonly adapterOnly: readonly ["relationship_store"];
+    readonly registryOnly: string[];
+    readonly adapterOnly: string[];
 };
 /**
- * Collect `server.tool("name", ...)` registrations from adapter source.
- * Plain string scan — the first string literal argument is the tool name.
+ * 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[];
@@ -71,5 +54,14 @@ export interface AdapterRegistryParity {
 /**
  * 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

@@ -1,77 +1,39 @@
 /**
- * adapter-surface.ts — the stdio adapter's declared tool set (flair#1575).
+ * adapter-surface.ts — the stdio adapter's derived tool set (flair#1580).
  *
- * `@tpsdev-ai/flair-mcp` hand-wires each tool via `server.tool(...)` in
- * index.ts. The native `/mcp` handler ships a separate `TOOLS` registry in
- * resources/mcp-tools.ts. Those two surfaces drifted: skill_* landed in
- * TOOLS for 0.52.0 and never reached this package — the surface Claude Code
- * and Cursor actually use.
+ * `@tpsdev-ai/flair-mcp` no longer hand-wires per-tool string literals in
+ * index.ts. The advertised set is STDIO_TOOL_DESCRIPTORS from the descriptor
+ * module vendored at build time into `./tool-descriptors/` (flair#1683;
+ * source of truth: packages/flair-tool-descriptors/src/index.ts) — 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 is the reviewed chokepoint for that seam:
+ * This module remains the reviewed chokepoint for the stdio ↔ TOOLS seam:
  *
- *   1. `ADAPTER_TOOL_NAMES` is the adapter's declared tool set.
- *   2. `parseAdapterToolNames` reads the names actually passed to
- *      `server.tool(...)` in index.ts, so the declaration cannot outrun
- *      registration (or vice versa).
- *   3. `STDIO_ADAPTER_EXEMPTIONS` is the explicit, reviewed list of names
- *      that exist on one surface but not the other. A TOOLS name that is
- *      neither registered here nor exempted is a CI failure — silent drift
- *      of the class that hid skill_*.
- *
- * Deriving the adapter's handlers from TOOLS (so a new registry tool appears
- * here for free) is the durable structural fix; it does not fit this chip
- * because TOOLS is Harper-linked server code and this package talks HTTP via
- * FlairClient. Detection + exemption list ships now; derive is a follow-on.
+ *   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 via `server.tool(...)` in index.ts. */
-export const ADAPTER_TOOL_NAMES = [
-    "bootstrap",
-    "flair_orgevent",
-    "flair_workspace_set",
-    "memory_delete",
-    "memory_get",
-    "memory_search",
-    "memory_store",
-    "memory_update",
-    "record_usage",
-    "relationship_store",
-    "skill_get",
-    "skill_search",
-    "skill_store",
-    "soul_get",
-    "soul_set",
-];
+import { STDIO_TOOL_DESCRIPTORS, SURFACE_EXEMPTIONS, descriptorNames, } from "./tool-descriptors/index.js";
+/** Tools registered on the stdio adapter — derived from the shared descriptor list. */
+export const ADAPTER_TOOL_NAMES = descriptorNames(STDIO_TOOL_DESCRIPTORS);
 /**
- * Reviewed exemptions at the stdio-adapter ↔ server TOOLS seam (flair#1575).
- *
- * A name here is a deliberate, reviewed difference — not silent drift.
- * Adding or removing a name is the control: CI fails if an exemption is
- * unused (the tool appeared on both sides, or vanished from the side it
- * was excused on) or if a non-exempt name exists on only one side.
+ * 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 = {
-    /**
-     * Present in resources/mcp-tools.ts `TOOLS`, not wired on the stdio adapter.
-     *
-     * - attention: native /mcp only (flair#677). mcp-tools.ts's module doc
-     *   explicitly does not mirror it into this package.
-     * - memory_basement / memory_restore: archive verbs (flair#1472) landed
-     *   on native /mcp; not yet forwarded over FlairClient.
-     */
-    registryOnly: ["attention", "memory_basement", "memory_restore"],
-    /**
-     * Wired on the stdio adapter, absent from `TOOLS`.
-     *
-     * - relationship_store: the adapter predates the record-types mcp
-     *   declaration. Relationship has no `RECORD_TYPES.mcp` field, so TOOLS
-     *   ships zero relationship_* names. The adapter still exposes the triple
-     *   write (FlairClient.relationship.write).
-     */
-    adapterOnly: ["relationship_store"],
+    registryOnly: SURFACE_EXEMPTIONS.registryOnly,
+    adapterOnly: SURFACE_EXEMPTIONS.adapterOnly,
 };
 /**
- * Collect `server.tool("name", ...)` registrations from adapter source.
- * Plain string scan — the first string literal argument is the tool name.
+ * 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) {
@@ -82,9 +44,48 @@ export function parseAdapterToolNames(source) {
         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);
@@ -103,3 +104,14 @@ export function adapterRegistryParity(registryNames, adapterNames) {
     ].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 {};