@gethmy/mcp 2.4.6 → 2.5.0

package/src/__tests__/prompt-builder.test.ts

@@ -1,12 +1,17 @@
 import { describe, expect, test } from "bun:test";
+import { HarmonyApiClient } from "../api-client.js";
 import {
   type CardData,
+  computeContentHash,
   generatePrompt,
   getAvailableCategories,
   getAvailableVariants,
   getRoleFraming,
   inferCategoryFromLabels,
   type MemoryData,
+  PROMPT_TEMPLATE_VERSION,
+  type PromptCohortRow,
+  proposePromptVariant,
 } from "../prompt-builder.js";
 
 function makeCard(overrides: Partial<CardData> = {}): CardData {
@@ -503,3 +508,232 @@ describe("utility exports", () => {
     }
   });
 });
+
+// ─── AGP P2: snapshot identity (promptId, contentHash, version) ──────
+
+describe("generatePrompt — AGP P2 snapshot fields", () => {
+  test("returns promptId, contentHash, version", () => {
+    const result = generatePrompt({
+      card: makeCard(),
+      variant: "execute",
+    });
+
+    expect(typeof result.promptId).toBe("string");
+    expect(result.promptId.length).toBeGreaterThan(0);
+    expect(typeof result.contentHash).toBe("string");
+    // sha256 hex = 64 chars
+    expect(result.contentHash).toMatch(/^[0-9a-f]{64}$/);
+    expect(result.version).toBe(PROMPT_TEMPLATE_VERSION);
+  });
+
+  test("identical inputs produce identical contentHash", () => {
+    const a = generatePrompt({ card: makeCard(), variant: "analysis" });
+    const b = generatePrompt({ card: makeCard(), variant: "analysis" });
+    expect(a.contentHash).toBe(b.contentHash);
+  });
+
+  test("different inputs produce different contentHash", () => {
+    const a = generatePrompt({ card: makeCard(), variant: "analysis" });
+    const b = generatePrompt({
+      card: makeCard({ title: "Different title" }),
+      variant: "analysis",
+    });
+    expect(a.contentHash).not.toBe(b.contentHash);
+  });
+
+  test("each call produces a fresh promptId", () => {
+    const a = generatePrompt({ card: makeCard(), variant: "execute" });
+    const b = generatePrompt({ card: makeCard(), variant: "execute" });
+    expect(a.promptId).not.toBe(b.promptId);
+  });
+
+  test("computeContentHash matches generated prompt hash", () => {
+    const result = generatePrompt({ card: makeCard(), variant: "execute" });
+    expect(computeContentHash(result.prompt)).toBe(result.contentHash);
+  });
+});
+
+// ─── AGP P2: persistence wiring via api-client ────────────────────────
+//
+// The api-client wraps generatePrompt() with a best-effort POST to
+// /prompt-history. We unit-test by stubbing `request` so we don't need
+// a live API.
+
+describe("api-client.generateCardPrompt — prompt_history persistence", () => {
+  test("POSTs a prompt-history row with matching contentHash", async () => {
+    const recorded: Array<{ method: string; path: string; body?: unknown }> =
+      [];
+    const client = new HarmonyApiClient({
+      apiUrl: "http://test",
+      apiKey: "test-key",
+    });
+    (client as any).request = async (
+      method: string,
+      path: string,
+      body?: unknown,
+    ) => {
+      recorded.push({ method, path, body });
+      // Minimal stubs for the subset of routes generateCardPrompt hits.
+      if (path.startsWith("/cards/") && method === "GET") {
+        return {
+          card: {
+            id: "card-1",
+            short_id: 7,
+            title: "Test card",
+            description: "desc",
+            priority: "medium",
+            done: false,
+            labels: [],
+            subtasks: [],
+            links: [],
+            project_id: "proj-1",
+            column_id: "col-1",
+          },
+        };
+      }
+      if (path.startsWith("/board/")) {
+        return { columns: [] };
+      }
+      if (path.startsWith("/memory/")) {
+        return { entities: [] };
+      }
+      if (path === "/prompt-history") {
+        return { entry: { id: "ph-1" } };
+      }
+      return {};
+    };
+
+    const result = await client.generateCardPrompt({
+      cardId: "card-1",
+      workspaceId: "ws-1",
+      projectId: "proj-1",
+      variant: "execute",
+    });
+
+    expect(result.contentHash).toMatch(/^[0-9a-f]{64}$/);
+
+    const phCall = recorded.find(
+      (c) => c.method === "POST" && c.path === "/prompt-history",
+    );
+    expect(phCall).toBeDefined();
+    const body = phCall!.body as Record<string, unknown>;
+    expect(body.cardId).toBe("card-1");
+    expect(body.contentHash).toBe(result.contentHash);
+    expect(body.templateVersion).toBe(PROMPT_TEMPLATE_VERSION);
+    expect(body.confidence).toBe(0.5);
+    expect(body.variant).toBe("execute");
+  });
+
+  test("returns successfully when persistence fails (best-effort)", async () => {
+    const client = new HarmonyApiClient({
+      apiUrl: "http://test",
+      apiKey: "test-key",
+    });
+    (client as any).request = async (method: string, path: string) => {
+      if (path.startsWith("/cards/") && method === "GET") {
+        return {
+          card: {
+            id: "card-1",
+            short_id: 7,
+            title: "Test card",
+            description: null,
+            priority: "medium",
+            done: false,
+            labels: [],
+            subtasks: [],
+            links: [],
+            project_id: "proj-1",
+            column_id: "col-1",
+          },
+        };
+      }
+      if (path.startsWith("/board/")) return { columns: [] };
+      if (path.startsWith("/memory/")) return { entities: [] };
+      if (path === "/prompt-history") {
+        throw new Error("network down");
+      }
+      return {};
+    };
+
+    const result = await client.generateCardPrompt({
+      cardId: "card-1",
+      workspaceId: "ws-1",
+      variant: "analysis",
+    });
+    // Generation still succeeds even when logging fails.
+    expect(result.prompt.length).toBeGreaterThan(0);
+    expect(result.contentHash).toMatch(/^[0-9a-f]{64}$/);
+  });
+});
+
+// ─── AGP P2: variant proposal helper (logged-only) ────────────────────
+
+describe("proposePromptVariant", () => {
+  function row(overrides: Partial<PromptCohortRow> = {}): PromptCohortRow {
+    return {
+      status: "completed",
+      progressPercent: 100,
+      hadBlockers: false,
+      ...overrides,
+    };
+  }
+
+  test("returns null when cohort is smaller than 10", async () => {
+    const cohort = Array.from({ length: 5 }, () =>
+      row({ status: "paused", progressPercent: 30 }),
+    );
+    const suggestion = await proposePromptVariant("hash-1", async () => cohort);
+    expect(suggestion).toBeNull();
+  });
+
+  test("returns null when completion rate is acceptable (>=0.4)", async () => {
+    const cohort = [
+      ...Array.from({ length: 5 }, () => row()),
+      ...Array.from({ length: 5 }, () =>
+        row({ status: "paused", progressPercent: 50 }),
+      ),
+    ];
+    const suggestion = await proposePromptVariant("hash-2", async () => cohort);
+    expect(suggestion).toBeNull();
+  });
+
+  test("returns suggestion when cohort is >=10 and completion rate <0.4", async () => {
+    // 2 successes / 10 sessions = 0.2 completion rate, below 0.4 threshold.
+    const cohort = [
+      ...Array.from({ length: 2 }, () => row()),
+      ...Array.from({ length: 8 }, () =>
+        row({ status: "paused", progressPercent: 30, hadBlockers: false }),
+      ),
+    ];
+    const suggestion = await proposePromptVariant("hash-3", async () => cohort);
+    expect(suggestion).not.toBeNull();
+    expect(suggestion!.contentHash).toBe("hash-3");
+    expect(suggestion!.cohortSize).toBe(10);
+    expect(suggestion!.completionRate).toBeCloseTo(0.2, 5);
+    expect(suggestion!.framingHint).toContain("action-forcing");
+  });
+
+  test("returns blocker-flavoured framing hint when blockers dominate", async () => {
+    // 1 success, 9 blocked sessions → completionRate=0.1, blockerRate=0.9
+    const cohort = [
+      row(),
+      ...Array.from({ length: 9 }, () =>
+        row({ status: "paused", progressPercent: 25, hadBlockers: true }),
+      ),
+    ];
+    const suggestion = await proposePromptVariant("hash-4", async () => cohort);
+    expect(suggestion).not.toBeNull();
+    expect(suggestion!.framingHint).toContain("diagnostic");
+  });
+
+  test("blockers count against completion rate", async () => {
+    // Even at 100% status="completed"+100%, blockers should disqualify them
+    // from being counted as success.
+    const cohort = Array.from({ length: 10 }, () =>
+      row({ status: "completed", progressPercent: 100, hadBlockers: true }),
+    );
+    const suggestion = await proposePromptVariant("hash-5", async () => cohort);
+    expect(suggestion).not.toBeNull();
+    expect(suggestion!.completionRate).toBe(0);
+  });
+});

package/src/__tests__/remote-routing.test.ts

@@ -0,0 +1,285 @@
+/**
+ * Routing/auth tests for the remote MCP server (`src/remote.ts`).
+ *
+ * Covers the four session-routing branches mandated by the MCP Streamable
+ * HTTP spec — the regression that surfaced as "Harmony MCP not responding"
+ * after a server restart, OAuth refresh, or stale-session GC was a missing
+ * 404 branch for unknown `Mcp-Session-Id` values.
+ *
+ * These tests stub `globalThis.fetch` so we don't depend on harmony-api
+ * being reachable.
+ *
+ * Run with: bun test packages/mcp-server/src/__tests__/remote-routing.test.ts
+ */
+
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  test,
+} from "bun:test";
+
+const ORIGINAL_FETCH = globalThis.fetch;
+
+// Fixed values used across tests
+const TEST_USER = "user-alpha";
+const OTHER_USER = "user-beta";
+const TEST_WORKSPACE = "ws-1";
+const VALID_TOKEN = "hmy_at_alpha_valid";
+const REFRESHED_TOKEN = "hmy_at_alpha_refreshed";
+const OTHER_USER_TOKEN = "hmy_at_beta_valid";
+const REVOKED_TOKEN = "hmy_at_revoked";
+
+function makeFetchStub() {
+  return async (
+    input: string | URL | Request,
+    init?: RequestInit,
+  ): Promise<Response> => {
+    const url = typeof input === "string" ? input : input.toString();
+    const apiKey =
+      (init?.headers as Record<string, string> | undefined)?.["X-API-Key"] ??
+      "";
+
+    if (url.endsWith("/v1/auth/context")) {
+      const map: Record<
+        string,
+        { userId: string; workspaceId: string | null; source: string } | null
+      > = {
+        [VALID_TOKEN]: {
+          userId: TEST_USER,
+          workspaceId: TEST_WORKSPACE,
+          source: "oauth",
+        },
+        [REFRESHED_TOKEN]: {
+          userId: TEST_USER,
+          workspaceId: TEST_WORKSPACE,
+          source: "oauth",
+        },
+        [OTHER_USER_TOKEN]: {
+          userId: OTHER_USER,
+          workspaceId: "ws-2",
+          source: "oauth",
+        },
+      };
+      const ctx = map[apiKey];
+      if (!ctx) {
+        return new Response(JSON.stringify({ error: "unauthorized" }), {
+          status: 401,
+          headers: { "Content-Type": "application/json" },
+        });
+      }
+      return new Response(JSON.stringify(ctx), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    }
+
+    // Anything else — return a benign 404 so unrelated lookups don't blow up.
+    return new Response("{}", {
+      status: 404,
+      headers: { "Content-Type": "application/json" },
+    });
+  };
+}
+
+let fetchHandler: (req: Request) => Promise<Response>;
+let _sessionsForTests: Map<string, unknown>;
+
+beforeAll(async () => {
+  globalThis.fetch = makeFetchStub() as unknown as typeof fetch;
+  // Import after the stub is in place (module init is synchronous-only.)
+  const mod = await import("../remote.js");
+  fetchHandler = mod.fetchHandler as (req: Request) => Promise<Response>;
+  _sessionsForTests = mod._sessionsForTests as Map<string, unknown>;
+});
+
+afterAll(() => {
+  globalThis.fetch = ORIGINAL_FETCH;
+});
+
+beforeEach(() => {
+  // Refresh the fetch stub each test (preserves across the cache TTL).
+  globalThis.fetch = makeFetchStub() as unknown as typeof fetch;
+});
+
+afterEach(() => {
+  // Wipe sessions between tests so state doesn't leak.
+  _sessionsForTests.clear();
+});
+
+const INIT_BODY = {
+  jsonrpc: "2.0",
+  id: 1,
+  method: "initialize",
+  params: {
+    protocolVersion: "2025-06-18",
+    capabilities: {},
+    clientInfo: { name: "test", version: "0.0.1" },
+  },
+};
+
+const TOOLS_LIST_BODY = {
+  jsonrpc: "2.0",
+  id: 2,
+  method: "tools/list",
+  params: {},
+};
+
+function makePost(
+  body: unknown,
+  opts: { token?: string; sessionId?: string } = {},
+): Request {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    Accept: "application/json, text/event-stream",
+  };
+  if (opts.token) headers.Authorization = `Bearer ${opts.token}`;
+  if (opts.sessionId) headers["Mcp-Session-Id"] = opts.sessionId;
+  return new Request("http://localhost/mcp", {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+  });
+}
+
+describe("remote MCP routing", () => {
+  test("no Authorization header → 401 + WWW-Authenticate", async () => {
+    const res = await fetchHandler(
+      new Request("http://localhost/mcp", { method: "POST" }),
+    );
+    expect(res.status).toBe(401);
+    const wwwAuth = res.headers.get("WWW-Authenticate") ?? "";
+    expect(wwwAuth).toContain("Bearer");
+    expect(wwwAuth).toContain("resource_metadata=");
+  });
+
+  test("invalid bearer on initialize → 401 invalid_token", async () => {
+    const res = await fetchHandler(
+      makePost(INIT_BODY, { token: REVOKED_TOKEN }),
+    );
+    expect(res.status).toBe(401);
+    expect(res.headers.get("WWW-Authenticate") ?? "").toContain(
+      "invalid_token",
+    );
+  });
+
+  test("POST without session id and not initialize → 400", async () => {
+    const res = await fetchHandler(
+      makePost(TOOLS_LIST_BODY, { token: VALID_TOKEN }),
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: { message: string } };
+    expect(body.error.message).toMatch(/Mcp-Session-Id header required/i);
+  });
+
+  test("POST with unknown session id → 404 (forces client re-init)", async () => {
+    const res = await fetchHandler(
+      makePost(TOOLS_LIST_BODY, {
+        token: VALID_TOKEN,
+        sessionId: "ghost-session-id",
+      }),
+    );
+    // This is the spec-mandated behavior that fixes "Harmony MCP not responding".
+    expect(res.status).toBe(404);
+    const body = (await res.json()) as { error: { code: number } };
+    expect(body.error.code).toBe(-32001);
+    expect(res.headers.get("Mcp-Session-Id")).toBe("ghost-session-id");
+  });
+
+  test("initialize succeeds and registers a session", async () => {
+    const res = await fetchHandler(makePost(INIT_BODY, { token: VALID_TOKEN }));
+    expect(res.status).toBe(200);
+    const sid = res.headers.get("mcp-session-id");
+    expect(sid).toBeTruthy();
+    expect(_sessionsForTests.has(sid!)).toBe(true);
+  });
+
+  test("rotated token (same user) is accepted on hot-swap", async () => {
+    // Bootstrap a session.
+    const initRes = await fetchHandler(
+      makePost(INIT_BODY, { token: VALID_TOKEN }),
+    );
+    const sid = initRes.headers.get("mcp-session-id")!;
+
+    // Send a follow-up with the *new* token + same session id.
+    // We're not asserting on the body — just that the rotation didn't
+    // produce a 401/404, which it would if hot-swap were broken.
+    const follow = await fetchHandler(
+      makePost(TOOLS_LIST_BODY, {
+        token: REFRESHED_TOKEN,
+        sessionId: sid,
+      }),
+    );
+    expect(follow.status).not.toBe(401);
+    expect(follow.status).not.toBe(404);
+  });
+
+  test("token from a different user is REJECTED on hot-swap", async () => {
+    const initRes = await fetchHandler(
+      makePost(INIT_BODY, { token: VALID_TOKEN }),
+    );
+    const sid = initRes.headers.get("mcp-session-id")!;
+
+    // Attempt to ride the session with another user's bearer.
+    const hijack = await fetchHandler(
+      makePost(TOOLS_LIST_BODY, {
+        token: OTHER_USER_TOKEN,
+        sessionId: sid,
+      }),
+    );
+    expect(hijack.status).toBe(401);
+    const wwwAuth = hijack.headers.get("WWW-Authenticate") ?? "";
+    expect(wwwAuth).toContain("invalid_token");
+  });
+
+  test("GET without valid session id → 400", async () => {
+    const res = await fetchHandler(
+      new Request("http://localhost/mcp", {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${VALID_TOKEN}`,
+          Accept: "text/event-stream",
+        },
+      }),
+    );
+    // GET without a session id falls into "session required" — 400.
+    expect(res.status).toBe(400);
+  });
+
+  test("GET with unknown session id → 404", async () => {
+    const res = await fetchHandler(
+      new Request("http://localhost/mcp", {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${VALID_TOKEN}`,
+          Accept: "text/event-stream",
+          "Mcp-Session-Id": "ghost",
+        },
+      }),
+    );
+    expect(res.status).toBe(404);
+  });
+
+  test("/.well-known/oauth-protected-resource is unauthenticated", async () => {
+    const res = await fetchHandler(
+      new Request("http://localhost/.well-known/oauth-protected-resource"),
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      authorization_servers: string[];
+      bearer_methods_supported: string[];
+    };
+    expect(body.authorization_servers.length).toBeGreaterThan(0);
+    expect(body.bearer_methods_supported).toContain("header");
+  });
+
+  test("/health is unauthenticated", async () => {
+    const res = await fetchHandler(new Request("http://localhost/health"));
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { status: string };
+    expect(body.status).toBe("ok");
+  });
+});

package/src/__tests__/skills.test.ts

@@ -0,0 +1,111 @@
+/**
+ * Verification harness for skill rendering. Card #182.
+ *
+ * Pins the contract that backs `~/.claude/skills/` delivery: frontmatter shape,
+ * version-marker injection, agent-id substitution. If any of these drift the
+ * MCP bridge installs broken skills silently, so this file is the floor.
+ *
+ * Run with: bun test packages/mcp-server/src/__tests__/skills.test.ts
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  buildSkillFile,
+  SKILL_DEFINITIONS,
+  SKILLS_VERSION,
+} from "../skills.js";
+
+const SKILL_IDS = Object.keys(SKILL_DEFINITIONS);
+const VERSION_MARKER_RE = /<!-- skills-version:(\d+) -->\s*$/;
+
+describe("SKILL_DEFINITIONS", () => {
+  test("registry is non-empty", () => {
+    expect(SKILL_IDS.length).toBeGreaterThan(0);
+  });
+
+  test("SKILLS_VERSION is a numeric string", () => {
+    expect(SKILLS_VERSION).toMatch(/^\d+$/);
+  });
+
+  test.each(SKILL_IDS)("definition %s has required fields", (skillId) => {
+    const skill = SKILL_DEFINITIONS[skillId];
+    expect(skill.name).toBe(skillId);
+    expect(skill.description.length).toBeGreaterThan(0);
+    expect(skill.argumentHint.length).toBeGreaterThan(0);
+    expect(skill.content.length).toBeGreaterThan(0);
+  });
+
+  test("all skill names are unique", () => {
+    const names = SKILL_IDS.map((id) => SKILL_DEFINITIONS[id].name);
+    expect(new Set(names).size).toBe(names.length);
+  });
+});
+
+describe("buildSkillFile()", () => {
+  test.each(SKILL_IDS)("renders %s with valid frontmatter", (skillId) => {
+    const out = buildSkillFile(skillId);
+    const skill = SKILL_DEFINITIONS[skillId];
+
+    expect(out.startsWith("---\n")).toBe(true);
+    expect(out).toContain(`\nname: ${skill.name}\n`);
+    expect(out).toContain(`\ndescription: ${skill.description}\n`);
+    expect(out).toContain(`\nargument-hint: ${skill.argumentHint}\n`);
+    expect(out).toContain("---\n\n");
+  });
+
+  test.each(SKILL_IDS)("appends version marker for %s", (skillId) => {
+    const out = buildSkillFile(skillId);
+    const match = out.match(VERSION_MARKER_RE);
+
+    expect(match).not.toBeNull();
+    expect(match?.[1]).toBe(SKILLS_VERSION);
+  });
+
+  test.each(SKILL_IDS)("embeds skill content for %s", (skillId) => {
+    const out = buildSkillFile(skillId);
+    const content = SKILL_DEFINITIONS[skillId].content;
+
+    expect(out).toContain(content.split("\n")[0]);
+    const lastLine = content.trim().split("\n").at(-1) ?? "";
+    expect(out).toContain(lastLine);
+  });
+
+  test("is deterministic — same input yields same output", () => {
+    const a = buildSkillFile("hmy");
+    const b = buildSkillFile("hmy");
+    expect(a).toBe(b);
+  });
+
+  test("throws on unknown skill id", () => {
+    expect(() => buildSkillFile("does-not-exist")).toThrow(/Unknown skill/);
+  });
+
+  describe("agent-id substitution", () => {
+    test("agentId='claude' replaces placeholder phrases in hmy", () => {
+      const withAgent = buildSkillFile("hmy", "claude");
+      expect(withAgent).not.toContain("Your agent identifier");
+      expect(withAgent).not.toContain("Your agent name");
+      expect(withAgent).toContain("claude-code");
+      expect(withAgent).toContain("Claude Code");
+    });
+
+    test("agentId omitted leaves placeholders untouched", () => {
+      const raw = buildSkillFile("hmy");
+      const hasPlaceholder =
+        raw.includes("Your agent identifier") ||
+        raw.includes("Your agent name");
+      const skillContent = SKILL_DEFINITIONS.hmy.content;
+      const sourceHasPlaceholder =
+        skillContent.includes("Your agent identifier") ||
+        skillContent.includes("Your agent name");
+
+      expect(hasPlaceholder).toBe(sourceHasPlaceholder);
+    });
+
+    test("unknown agentId is treated as no-op", () => {
+      const raw = buildSkillFile("hmy");
+      const unknownAgent = buildSkillFile("hmy", "some-other-agent");
+      expect(unknownAgent).toBe(raw);
+    });
+  });
+});