@gethmy/mcp 2.4.6 → 2.5.0

package/src/__tests__/tool-dispatch.test.ts

@@ -0,0 +1,260 @@
+/**
+ * Verification harness for MCP tool dispatch. Card #182.
+ *
+ * Pins the contract between Harmony's MCP server and any MCP client (Claude
+ * Code, Codex, Cursor, etc.). If the dispatch shape drifts, agents lose tools
+ * silently, so this is the floor:
+ *
+ *   1. TOOLS registry is well-formed (shape, names, schemas).
+ *   2. ListTools handler emits the same set TOOLS declares.
+ *   3. CallTool handler routes valid names and isErrors unknown ones.
+ *   4. ListResources / ReadResource cover the published URIs.
+ *   5. Tool ↔ skill name spaces are disjoint.
+ *
+ * Run with: bun test packages/mcp-server/src/__tests__/tool-dispatch.test.ts
+ */
+
+import { beforeAll, describe, expect, test } from "bun:test";
+import {
+  CallToolRequestSchema,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  ReadResourceRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import {
+  RESOURCES,
+  registerHandlers,
+  TOOLS,
+  type ToolDeps,
+} from "../server.js";
+import { SKILL_DEFINITIONS } from "../skills.js";
+
+const TOOL_NAMES = Object.keys(TOOLS);
+
+// ── Fake transport ────────────────────────────────────────────────────────
+
+type Schema = unknown;
+type Handler = (req: unknown) => Promise<unknown>;
+
+class FakeServer {
+  handlers = new Map<Schema, Handler>();
+  setRequestHandler(schema: Schema, handler: Handler): void {
+    this.handlers.set(schema, handler);
+  }
+  call<T = unknown>(schema: Schema, request: unknown): Promise<T> {
+    const handler = this.handlers.get(schema);
+    if (!handler) throw new Error("Handler not registered");
+    return handler(request) as Promise<T>;
+  }
+}
+
+function makeDeps(overrides: Partial<ToolDeps> = {}): ToolDeps {
+  return {
+    getClient: () => ({}) as never,
+    isConfigured: () => true,
+    getActiveProjectId: () => "11111111-1111-1111-1111-111111111111",
+    getActiveWorkspaceId: () => "22222222-2222-2222-2222-222222222222",
+    setActiveProject: () => {},
+    setActiveWorkspace: () => {},
+    getApiUrl: () => "http://localhost",
+    getMemoryDir: () => null,
+    getUserEmail: () => null,
+    saveConfig: () => {},
+    resetClient: () => {},
+    ...overrides,
+  };
+}
+
+// ── Static registry shape ────────────────────────────────────────────────
+
+describe("TOOLS registry", () => {
+  test("is non-empty", () => {
+    expect(TOOL_NAMES.length).toBeGreaterThan(0);
+  });
+
+  test("every name is unique", () => {
+    expect(new Set(TOOL_NAMES).size).toBe(TOOL_NAMES.length);
+  });
+
+  test.each(TOOL_NAMES)("%s is namespaced under harmony_", (name) => {
+    expect(name).toMatch(/^harmony_[a-z0-9_]+$/);
+  });
+
+  test.each(TOOL_NAMES)("%s has description and inputSchema", (name) => {
+    const tool = (
+      TOOLS as Record<string, { description?: unknown; inputSchema?: unknown }>
+    )[name];
+    expect(typeof tool.description).toBe("string");
+    expect((tool.description as string).length).toBeGreaterThan(0);
+    expect(typeof tool.inputSchema).toBe("object");
+    expect(tool.inputSchema).not.toBeNull();
+  });
+
+  test.each(TOOL_NAMES)("%s inputSchema is a JSON Schema object", (name) => {
+    const schema = (
+      TOOLS as Record<
+        string,
+        { inputSchema: { type?: string; properties?: unknown } }
+      >
+    )[name].inputSchema;
+    expect(schema.type).toBe("object");
+    if ("properties" in schema && schema.properties !== undefined) {
+      expect(typeof schema.properties).toBe("object");
+    }
+  });
+});
+
+// ── Skill ↔ tool boundary ────────────────────────────────────────────────
+
+describe("skill ↔ tool namespace boundary", () => {
+  test("skill names and tool names are disjoint", () => {
+    const skillNames = new Set(Object.keys(SKILL_DEFINITIONS));
+    const collisions = TOOL_NAMES.filter((name) => skillNames.has(name));
+    expect(collisions).toEqual([]);
+  });
+});
+
+// ── Dispatch round-trip ──────────────────────────────────────────────────
+
+describe("registerHandlers — ListTools", () => {
+  let server: FakeServer;
+
+  beforeAll(() => {
+    server = new FakeServer();
+    registerHandlers(server as never, makeDeps());
+  });
+
+  test("registers all four request handlers", () => {
+    expect(server.handlers.has(ListToolsRequestSchema)).toBe(true);
+    expect(server.handlers.has(CallToolRequestSchema)).toBe(true);
+    expect(server.handlers.has(ListResourcesRequestSchema)).toBe(true);
+    expect(server.handlers.has(ReadResourceRequestSchema)).toBe(true);
+  });
+
+  test("emits one entry per TOOLS row, with name+description+inputSchema", async () => {
+    const result = await server.call<{
+      tools: Array<{ name: string; description: string; inputSchema: unknown }>;
+    }>(ListToolsRequestSchema, { method: "tools/list" });
+
+    expect(result.tools.length).toBe(TOOL_NAMES.length);
+
+    const emittedNames = result.tools.map((t) => t.name).sort();
+    expect(emittedNames).toEqual([...TOOL_NAMES].sort());
+
+    for (const tool of result.tools) {
+      expect(typeof tool.name).toBe("string");
+      expect(typeof tool.description).toBe("string");
+      expect(typeof tool.inputSchema).toBe("object");
+    }
+  });
+});
+
+describe("registerHandlers — CallTool", () => {
+  let server: FakeServer;
+  let workspaceId: string | null;
+  let projectId: string | null;
+
+  beforeAll(() => {
+    server = new FakeServer();
+    workspaceId = "22222222-2222-2222-2222-222222222222";
+    projectId = "11111111-1111-1111-1111-111111111111";
+    const deps = makeDeps({
+      getActiveWorkspaceId: () => workspaceId,
+      getActiveProjectId: () => projectId,
+    });
+    registerHandlers(server as never, deps);
+  });
+
+  test("routes harmony_get_context and returns active ids", async () => {
+    const result = await server.call<{
+      content: Array<{ type: string; text: string }>;
+      isError?: boolean;
+    }>(CallToolRequestSchema, {
+      method: "tools/call",
+      params: { name: "harmony_get_context", arguments: {} },
+    });
+
+    expect(result.isError).toBeUndefined();
+    expect(result.content[0].type).toBe("text");
+    const payload = JSON.parse(result.content[0].text);
+    expect(payload.success).toBe(true);
+    expect(payload.context.activeWorkspaceId).toBe(workspaceId);
+    expect(payload.context.activeProjectId).toBe(projectId);
+  });
+
+  test("unknown tool name returns isError without throwing", async () => {
+    const result = await server.call<{
+      content: Array<{ type: string; text: string }>;
+      isError?: boolean;
+    }>(CallToolRequestSchema, {
+      method: "tools/call",
+      params: { name: "harmony_does_not_exist", arguments: {} },
+    });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text.toLowerCase()).toContain("error");
+  });
+
+  test("not-configured rejects authenticated tools", async () => {
+    const unconfigured = new FakeServer();
+    registerHandlers(
+      unconfigured as never,
+      makeDeps({ isConfigured: () => false }),
+    );
+
+    const result = await unconfigured.call<{
+      content: Array<{ type: string; text: string }>;
+      isError?: boolean;
+    }>(CallToolRequestSchema, {
+      method: "tools/call",
+      params: { name: "harmony_get_context", arguments: {} },
+    });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("Not configured");
+  });
+});
+
+// ── Resources ────────────────────────────────────────────────────────────
+
+describe("registerHandlers — Resources", () => {
+  let server: FakeServer;
+
+  beforeAll(() => {
+    server = new FakeServer();
+    registerHandlers(server as never, makeDeps());
+  });
+
+  test("ListResources mirrors the static RESOURCES array", async () => {
+    const result = await server.call<{ resources: typeof RESOURCES }>(
+      ListResourcesRequestSchema,
+      { method: "resources/list" },
+    );
+    expect(result.resources).toEqual(RESOURCES);
+  });
+
+  test("ReadResource serves harmony://context as JSON", async () => {
+    const result = await server.call<{
+      contents: Array<{ uri: string; mimeType: string; text: string }>;
+    }>(ReadResourceRequestSchema, {
+      method: "resources/read",
+      params: { uri: "harmony://context" },
+    });
+
+    expect(result.contents[0].uri).toBe("harmony://context");
+    expect(result.contents[0].mimeType).toBe("application/json");
+    const parsed = JSON.parse(result.contents[0].text);
+    expect(parsed).toHaveProperty("configured");
+    expect(parsed).toHaveProperty("activeWorkspaceId");
+    expect(parsed).toHaveProperty("activeProjectId");
+  });
+
+  test("ReadResource on unknown URI throws", async () => {
+    await expect(
+      server.call(ReadResourceRequestSchema, {
+        method: "resources/read",
+        params: { uri: "harmony://nope" },
+      }),
+    ).rejects.toThrow(/Unknown resource/);
+  });
+});

package/src/api-client.ts

@@ -1,3 +1,4 @@
+import { getDisplayLinkType } from "@harmony/shared";
 import { getApiKey, getApiUrl } from "./config.js";
 
 export interface ApiResponse<T = unknown> {
@@ -149,6 +150,10 @@ export class HarmonyApiClient {
     this.apiKey = apiKey;
   }
 
+  getApiKey(): string {
+    return this.apiKey;
+  }
+
   private async request<T>(
     method: string,
     path: string,
@@ -638,34 +643,6 @@ export class HarmonyApiClient {
     return this.request("GET", `/cards/${cardId}/agent-context${query}`);
   }
 
-  // ============ AGENT PERFORMANCE PROFILES ============
-
-  async getAgentProfile(
-    workspaceId: string,
-    agentIdentifier: string,
-  ): Promise<{ profile: unknown }> {
-    const params = new URLSearchParams({
-      workspace_id: workspaceId,
-      agent_identifier: agentIdentifier,
-    });
-    return this.request("GET", `/agent-profiles?${params.toString()}`);
-  }
-
-  async listAgentProfiles(
-    workspaceId: string,
-  ): Promise<{ profiles: unknown[] }> {
-    const params = new URLSearchParams({ workspace_id: workspaceId });
-    return this.request("GET", `/agent-profiles?${params.toString()}`);
-  }
-
-  async refreshAgentProfiles(
-    workspaceId: string,
-  ): Promise<{ refreshed: boolean }> {
-    return this.request("POST", "/agent-profiles/refresh", {
-      workspace_id: workspaceId,
-    });
-  }
-
   // ============ MEMORY OPERATIONS ============
 
   async createMemoryEntity(data: {
@@ -678,6 +655,7 @@ export class HarmonyApiClient {
     content: string;
     metadata?: Record<string, unknown>;
     confidence?: number;
+    importance?: number;
     tags?: string[];
     agent_identifier?: string;
   }): Promise<{ entity: unknown; warnings?: string[] }> {
@@ -695,6 +673,7 @@ export class HarmonyApiClient {
     q?: string;
     limit?: number;
     offset?: number;
+    include_superseded?: boolean;
   }): Promise<{ entities: unknown[]; count: number }> {
     const params = new URLSearchParams();
     params.set("workspace_id", options.workspace_id);
@@ -710,6 +689,7 @@ export class HarmonyApiClient {
     if (options.limit !== undefined) params.set("limit", String(options.limit));
     if (options.offset !== undefined)
       params.set("offset", String(options.offset));
+    if (options.include_superseded) params.set("include_superseded", "true");
     return this.request("GET", `/memory/entities?${params.toString()}`);
   }
 
@@ -728,6 +708,10 @@ export class HarmonyApiClient {
       scope?: string;
       type?: string;
       memory_tier?: string;
+      // AGP lifecycle fields. Backend may not yet whitelist these — extra keys
+      // are dropped server-side, leaving the call as a no-op for those fields.
+      superseded_by?: string | null;
+      version?: number;
     },
   ): Promise<{ entity: unknown; warnings?: string[] }> {
     return this.request("PUT", `/memory/entities/${entityId}`, updates);
@@ -1063,6 +1047,44 @@ export class HarmonyApiClient {
     return this.request("POST", "/api-keys", { name });
   }
 
+  // ============ PROMPT HISTORY (AGP P2) ============
+
+  async recordPromptHistory(data: {
+    cardId: string;
+    generatedPrompt: string;
+    variant: "analysis" | "draft" | "execute";
+    contextIncluded?: Record<string, unknown>;
+    sessionId?: string | null;
+    contentHash?: string;
+    templateVersion?: number;
+    confidence?: number;
+    templateId?: string | null;
+    isPinned?: boolean;
+  }): Promise<{ entry: unknown }> {
+    return this.request("POST", "/prompt-history", data);
+  }
+
+  async recordPromptHistoryFeedback(
+    sessionId: string,
+    outcome: "success" | "blocker" | "neutral",
+  ): Promise<{ adjusted: number }> {
+    return this.request("POST", "/prompt-history/feedback", {
+      sessionId,
+      outcome,
+    });
+  }
+
+  async getPromptHistoryCohort(contentHash: string): Promise<{
+    cohort: Array<{
+      status: string | null;
+      progressPercent: number | null;
+      hadBlockers: boolean;
+    }>;
+  }> {
+    const params = new URLSearchParams({ content_hash: contentHash });
+    return this.request("GET", `/prompt-history/cohort?${params.toString()}`);
+  }
+
   // ============ PROMPT GENERATION ============
 
   /**
@@ -1083,6 +1105,8 @@ export class HarmonyApiClient {
       includeLinks: boolean;
       includeDescription: boolean;
     }>;
+    /** Optional active session ID to associate with the prompt snapshot. */
+    sessionId?: string | null;
   }): Promise<{
     prompt: string;
     variant: string;
@@ -1101,14 +1125,42 @@ export class HarmonyApiClient {
     cardId: string;
     shortId: number;
     title: string;
+    /** Local UUID identifying the persisted snapshot (AGP P2). */
+    promptId: string;
+    /** SHA-256 of the generated prompt body (AGP P2 cohort key). */
+    contentHash: string;
+    /** Template version that produced this prompt. */
+    version: number;
   }> {
-    const { assembleContext, cacheManifest, generatePrompt } =
-      await loadPromptModules();
+    const { generatePrompt } = await loadPromptModules();
 
     // Fetch card data
     const cardResult = await this.getCard(options.cardId);
     const cardData = cardResult.card as CardPromptData;
 
+    // Fetch card reference links so the prompt can render the "Related Cards"
+    // section and the blocker-aware "Recommended Next Step" synthesis.
+    // Best-effort — link fetch failures must not break prompt generation.
+    try {
+      const linksResult = await this.getCardLinks(options.cardId);
+      const rawLinks =
+        (linksResult.links as Array<{
+          link_type: "relates_to" | "blocks" | "duplicates" | "is_part_of";
+          direction: "outgoing" | "incoming";
+          target_card: { short_id: number; title: string } | null;
+        }>) || [];
+      cardData.links = rawLinks
+        .filter((l) => l.target_card)
+        .map((l) => ({
+          target_card: l.target_card as { short_id: number; title: string },
+          direction: l.direction,
+          display_type: getDisplayLinkType(l.link_type, l.direction),
+        }));
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.debug(`[generateCardPrompt] getCardLinks failed: ${msg}`);
+    }
+
     // Try to get column info
     let columnData: { name: string } | null = null;
     const projectIdForBoard = options.projectId || cardData.project_id;
@@ -1128,67 +1180,37 @@ export class HarmonyApiClient {
 
     const variant = options.variant || "execute";
 
-    // Assemble memory context
-    let assembledContextStr: string | undefined;
-    let assemblyId: string | undefined;
+    // Phase 0 (memory architecture v2): full context assembly removed.
+    // Use the basic memory search path so callers still get _some_ memory
+    // hints. Phase 1 will reintroduce a session-scoped working memory layer.
+    const assembledContextStr: string | undefined = undefined;
+    const assemblyId: string | undefined = undefined;
     let memories: MemoryItem[] | undefined;
 
     try {
       if (options.workspaceId && cardData.title) {
-        const cardLabels = (cardData.labels || []).map((l) => l.name);
-        const taskContext = [cardData.title, cardData.description || ""]
-          .filter(Boolean)
-          .join(" ");
-
-        const assembled = await assembleContext({
-          workspaceId: options.workspaceId,
-          projectId: options.projectId,
-          taskContext,
-          cardLabels,
-          cardId: cardData.id,
-          client: this,
-        });
-
-        if (assembled.context) {
-          assembledContextStr = assembled.context;
-          assemblyId = assembled.manifest.assemblyId;
-          cacheManifest(assembled.manifest);
+        const memoryResult = await this.searchMemoryEntities(
+          options.workspaceId,
+          cardData.title,
+          {
+            project_id: options.projectId,
+            limit: 5,
+          },
+        );
+        if (memoryResult.entities?.length > 0) {
+          memories = (memoryResult.entities as MemoryItem[]).map((e) => ({
+            id: e.id,
+            type: e.type,
+            title: e.title,
+            content: e.content,
+            confidence: e.confidence,
+            tags: e.tags || [],
+          }));
         }
       }
     } catch (err) {
-      // Context assembly failed, try legacy fallback
       const msg = err instanceof Error ? err.message : String(err);
-      console.debug(`[generateCardPrompt] Context assembly failed: ${msg}`);
-      try {
-        if (options.workspaceId && cardData.title) {
-          const memoryResult = await this.searchMemoryEntities(
-            options.workspaceId,
-            cardData.title,
-            {
-              project_id: options.projectId,
-              limit: 5,
-            },
-          );
-          if (memoryResult.entities?.length > 0) {
-            memories = (memoryResult.entities as MemoryItem[]).map((e) => ({
-              id: e.id,
-              type: e.type,
-              title: e.title,
-              content: e.content,
-              confidence: e.confidence,
-              tags: e.tags || [],
-            }));
-          }
-        }
-      } catch (fallbackErr) {
-        const fallbackMsg =
-          fallbackErr instanceof Error
-            ? fallbackErr.message
-            : String(fallbackErr);
-        console.debug(
-          `[generateCardPrompt] Memory fallback also failed: ${fallbackMsg}`,
-        );
-      }
+      console.debug(`[generateCardPrompt] Memory search failed: ${msg}`);
     }
 
     const result = generatePrompt({
@@ -1202,6 +1224,30 @@ export class HarmonyApiClient {
       assemblyId,
     });
 
+    // AGP P2: persist a session-linked snapshot. Best-effort — never fail
+    // prompt generation just because logging didn't land.
+    try {
+      await this.recordPromptHistory({
+        cardId: cardData.id,
+        generatedPrompt: result.prompt,
+        variant: variant as "analysis" | "draft" | "execute",
+        contextIncluded: {
+          assemblyId: result.assemblyId ?? null,
+          tokenEstimate: result.tokenEstimate,
+          contextSummary: result.contextSummary,
+        },
+        sessionId: options.sessionId ?? null,
+        contentHash: result.contentHash,
+        templateVersion: result.version,
+        confidence: 0.5,
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.debug(
+        `[generateCardPrompt] prompt_history persistence failed: ${msg}`,
+      );
+    }
+
     return {
       ...result,
       cardId: cardData.id,
@@ -1241,14 +1287,10 @@ interface MemoryItem {
   tags: string[];
 }
 
-// Cached dynamic imports for context-assembly and prompt-builder
+// Cached dynamic import for prompt-builder.
+// Phase 0 (memory architecture v2): context-assembly module deleted; prompt
+// generation falls back to a basic memory search path until Phase 1.
 let _promptModules: {
-  assembleContext: Awaited<
-    typeof import("./context-assembly.js")
-  >["assembleContext"];
-  cacheManifest: Awaited<
-    typeof import("./context-assembly.js")
-  >["cacheManifest"];
   generatePrompt: Awaited<
     typeof import("./prompt-builder.js")
   >["generatePrompt"];
@@ -1256,13 +1298,8 @@ let _promptModules: {
 
 async function loadPromptModules() {
   if (!_promptModules) {
-    const [ca, pb] = await Promise.all([
-      import("./context-assembly.js"),
-      import("./prompt-builder.js"),
-    ]);
+    const pb = await import("./prompt-builder.js");
     _promptModules = {
-      assembleContext: ca.assembleContext,
-      cacheManifest: ca.cacheManifest,
       generatePrompt: pb.generatePrompt,
     };
   }