@gethmy/mcp 2.4.7 → 2.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.4.7",
+  "version": "2.5.1",
   "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
   "publishConfig": {
     "access": "public"
@@ -25,6 +25,7 @@
   "files": [
     "dist",
     "src",
+    "!src/__tests__",
     "README.md"
   ],
   "repository": {
@@ -54,12 +55,12 @@
     "bun": ">=1.0.0"
   },
   "scripts": {
-    "build": "bun build src/index.ts src/cli.ts --outdir dist --target node && bun build src/api-client.ts src/config.ts --outdir dist/lib --root src --target node",
+    "build": "rm -rf dist && bun build src/index.ts src/cli.ts --outdir dist --target node --external @clack/prompts --external @modelcontextprotocol/sdk --external commander --external hono --external picocolors --external zod && bun build src/api-client.ts src/config.ts --outdir dist/lib --root src --target node --external @clack/prompts --external @modelcontextprotocol/sdk --external commander --external hono --external picocolors --external zod",
     "build:bun": "bun build src/index.ts src/http.ts src/remote.ts src/cli.ts --outdir dist --target bun",
     "serve:remote": "bun src/remote.ts",
     "dev": "bun --watch src/index.ts",
     "test": "bun run test:unit && bun run test:integration",
-    "test:unit": "bun test src/__tests__/active-learning.test.ts src/__tests__/context-assembly.test.ts src/__tests__/prompt-builder.test.ts src/__tests__/memory-audit.test.ts",
+    "test:unit": "bun test src/__tests__/active-learning.test.ts src/__tests__/context-assembly.test.ts src/__tests__/prompt-builder.test.ts src/__tests__/memory-audit.test.ts src/__tests__/skills.test.ts src/__tests__/tool-dispatch.test.ts src/__tests__/mcp-integration.test.ts",
     "test:integration": "bun test src/__tests__/integration-memory-system.test.ts src/__tests__/integration-memory-crud.test.ts",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "bun run build"

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> {
@@ -642,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: {
@@ -682,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[] }> {
@@ -699,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);
@@ -714,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()}`);
   }
 
@@ -732,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);
@@ -1067,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 ============
 
   /**
@@ -1087,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;
@@ -1105,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;
@@ -1132,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({
@@ -1206,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,
@@ -1245,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"];
@@ -1260,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,
     };
   }

package/src/memory-floor.ts

@@ -0,0 +1,264 @@
+/**
+ * Memory Utility Floor — write admission control.
+ *
+ * Implements §4.5.1 of docs/superpowers/plans/2026-05-07-memory-architecture-v2.md.
+ *
+ * The Floor is deterministic, regex + length based. No LLM calls.
+ * It runs at every write site (`harmony_remember` and any future Phase 3
+ * write-gate output). Rejected writes return a structured error explaining
+ * which rule fired so callers can adjust.
+ *
+ * Bypasses:
+ *   - `source_trust='document'` rows skip the title-quality regex (legitimate
+ *     long-form prose isn't tag-concat slop). Other rules still apply.
+ *   - Session-scope memories (`scope` starts with `session:`) skip the Floor
+ *     entirely — they're explicitly ephemeral.
+ */
+
+const STOP_WORDS = new Set([
+  "a",
+  "an",
+  "and",
+  "are",
+  "as",
+  "at",
+  "be",
+  "by",
+  "for",
+  "from",
+  "has",
+  "have",
+  "he",
+  "in",
+  "is",
+  "it",
+  "its",
+  "of",
+  "on",
+  "that",
+  "the",
+  "this",
+  "to",
+  "was",
+  "were",
+  "will",
+  "with",
+]);
+
+// ---------------------------------------------------------------------------
+// Rule registry — mirrors §4.5.1
+// ---------------------------------------------------------------------------
+
+export type FloorRuleId =
+  | "tag-concat"
+  | "tag-concat-slash"
+  | "frequency-meta"
+  | "self-referential"
+  | "bare-type-prefix"
+  | "specificity-floor"
+  | "length-floor"
+  | "operational-data-ban";
+
+export interface FloorRejection {
+  rule: FloorRuleId;
+  message: string;
+}
+
+interface FloorInput {
+  title: string;
+  content: string;
+  type: string;
+  scope?: string;
+  source_trust?: string;
+  tags?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Patterns
+// ---------------------------------------------------------------------------
+
+// "Consolidated procedure: procedure, add, user" — comma-separated tag concat
+const TAG_CONCAT_COMMA =
+  /^(Pattern|Procedure|Lesson|Consolidated [a-z]+):\s+[a-z]+(?:,\s*[a-z]+){1,5}$/i;
+
+// "Procedure: Procedure / Card / Mobile / Native" — slash-separated tag concat
+const TAG_CONCAT_SLASH =
+  /^(Pattern|Procedure|Lesson):\s+[a-z]+(?:\s*\/\s*[a-z]+){2,5}$/i;
+
+// "Pattern: recurring procedure (17 instances)"
+const FREQUENCY_META = /^Pattern:\s+recurring\s+\w+\s+\(\d+\s+instances?\)$/i;
+
+// "Type:" / "Memory:" with no real content after the colon
+const BARE_TYPE_PREFIX = /^(Type|Memory):\s*$/i;
+
+// Self-referential: mentions the memory implementation
+const SELF_REFERENTIAL =
+  /\b(memory system|consolidation|harmony_(remember|recall|consolidate|audit|promote|forget|cleanup|backfill|prune)|context.assembly|context-assembly|AGP|active.learning|active-learning|knowledge_entities)\b/i;
+
+// Implementation-detail leaking into a lesson body
+const IMPL_DETAIL =
+  /^\s*(?:[A-Z][^.]*[.,]\s*)?\b(blocks?|prevents?|broken|in.memory only|fixme|todo)\b/i;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function wordCount(s: string): number {
+  return s
+    .split(/\s+/)
+    .map((w) => w.replace(/[^\w]/g, "").toLowerCase())
+    .filter((w) => w.length > 0 && !STOP_WORDS.has(w)).length;
+}
+
+function hasProperNounOrIdentifier(s: string): boolean {
+  // Capitalized word in the middle of the title (not just sentence start)
+  // OR snake_case / camelCase / PascalCase identifier OR backtick-fenced ident.
+  if (/`[^`]+`/.test(s)) return true;
+  if (/\b[A-Z][a-zA-Z0-9]*[A-Z][a-zA-Z0-9]*/.test(s)) return true; // PascalCase / camelCase with caps
+  if (/\b[a-z]+(?:_[a-z]+){1,}/.test(s)) return true; // snake_case
+  // Capitalized non-first word
+  const tokens = s.split(/\s+/);
+  for (let i = 1; i < tokens.length; i++) {
+    const t = tokens[i] ?? "";
+    if (/^[A-Z][a-z]+/.test(t)) return true;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a memory write against the Utility Floor. Returns null if the
+ * write passes; otherwise returns a structured rejection.
+ *
+ * Order is deterministic and matches §4.5.1 numbering:
+ *   1. Title quality gate (tag-concat, frequency-meta, bare-prefix)
+ *   2. Self-referential gate
+ *   3. Implementation-detail gate (lessons only)
+ *   4. Specificity floor
+ *   5. Length floor
+ *   6. Operational-data ban
+ *
+ * Bypasses:
+ *   - `source_trust === 'document'` skips rule 1 (title checks).
+ *   - `scope` starts with `session:` skips all rules — session memories are
+ *     explicitly ephemeral.
+ */
+export function validateMemoryQuality(
+  input: FloorInput,
+): FloorRejection | null {
+  const title = (input.title ?? "").trim();
+  const content = (input.content ?? "").trim();
+  const isDocSource = input.source_trust === "document";
+  const isSessionScope =
+    typeof input.scope === "string" && input.scope.startsWith("session:");
+
+  // Bypass: session-scoped memories are exempt entirely.
+  if (isSessionScope) return null;
+
+  // Rule 6: Operational-data ban (always applies; even before bypass below).
+  // Agent profiling was removed in #195; reject any attempt to revive the dump pattern.
+  if (input.type === "agent" && /^Agent Profile:\s*/i.test(title)) {
+    return {
+      rule: "operational-data-ban",
+      message:
+        "Agent Profile entries are not allowed in knowledge_entities (operational data, not knowledge).",
+    };
+  }
+
+  // Rule 1: Title quality (skipped for doc-source imports).
+  if (!isDocSource) {
+    if (TAG_CONCAT_COMMA.test(title)) {
+      return {
+        rule: "tag-concat",
+        message:
+          "Title is a comma-separated tag concatenation. Provide a content-bearing title (a real sentence, file path, or symbol).",
+      };
+    }
+    if (TAG_CONCAT_SLASH.test(title)) {
+      return {
+        rule: "tag-concat-slash",
+        message:
+          "Title is a slash-separated tag concatenation. Provide a content-bearing title.",
+      };
+    }
+    if (FREQUENCY_META.test(title)) {
+      return {
+        rule: "frequency-meta",
+        message:
+          'Frequency-meta titles ("Pattern: recurring X (N instances)") are not retrievable knowledge. Access counts live in knowledge_entity_audit_log, not in entities.',
+      };
+    }
+    if (BARE_TYPE_PREFIX.test(title)) {
+      return {
+        rule: "bare-type-prefix",
+        message:
+          'Bare "Type:" / "Memory:" prefix without a content-bearing title. Use the type column; put substance in the title.',
+      };
+    }
+  }
+
+  // Rule 2: Self-referential gate (always — except when explicitly typed
+  // 'meta' which is excluded from default retrieval).
+  if (input.type !== "meta") {
+    if (SELF_REFERENTIAL.test(title) || SELF_REFERENTIAL.test(content)) {
+      return {
+        rule: "self-referential",
+        message:
+          "Memory references the memory implementation (operational noise). Operational notes belong in code comments or commit messages, not in retrievable memories.",
+      };
+    }
+  }
+
+  // Rule 3: Implementation-detail-as-lesson gate.
+  if (input.type === "lesson" && IMPL_DETAIL.test(content)) {
+    return {
+      rule: "impl-detail-lesson",
+      message:
+        "Lesson body reads as an implementation TODO/issue, not a learning. Convert to a positive takeaway or move to a code comment.",
+    } as FloorRejection;
+  }
+
+  // Rule 4: Specificity floor (skipped for doc-source imports — they may
+  // legitimately have short heading-style titles).
+  if (!isDocSource) {
+    const titleWordCount = title
+      .split(/\s+/)
+      .filter((w) => w.length > 0).length;
+    if (titleWordCount < 4 && !hasProperNounOrIdentifier(title)) {
+      return {
+        rule: "specificity-floor",
+        message:
+          "Title is too generic — needs ≥4 words OR a proper noun / specific identifier (file path, symbol, etc).",
+      };
+    }
+  }
+
+  // Rule 5: Length floor.
+  if (content.length < 40) {
+    return {
+      rule: "length-floor",
+      message: `Content is too short (${content.length} chars; minimum 40).`,
+    };
+  }
+  if (wordCount(content) < 8) {
+    return {
+      rule: "length-floor",
+      message:
+        "Content is too short after stop-word removal (minimum 8 substantive words).",
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Test whether an entity's stored shape matches Floor-violating patterns.
+ * Used by retrieval-time retroactive filter (§4.5.2) and by the Phase 0
+ * cleanup script.
+ */
+export function classifyExisting(input: FloorInput): FloorRejection | null {
+  return validateMemoryQuality(input);
+}