@gethmy/mcp 2.1.3 → 2.2.1

package/src/server.ts

@@ -59,13 +59,7 @@ import {
 } from "./context-assembly.js";
 import { autoExpandGraph } from "./graph-expansion.js";
 import { runLifecycleMaintenance } from "./lifecycle-maintenance.js";
-import {
-  type CardData,
-  type ColumnData,
-  generatePrompt,
-  type MemoryData,
-  type PromptVariant,
-} from "./prompt-builder.js";
+import type { PromptVariant } from "./prompt-builder.js";
 
 /**
  * Dependencies injected into tool handlers.
@@ -85,6 +79,155 @@ export interface ToolDeps {
   resetClient: () => void;
 }
 
+// --- Memory Session Tracking ---
+// Tracks memory operations per card session for visibility in AgentCardFooter
+
+interface MemorySessionState {
+  cardId: string;
+  agentIdentifier: string;
+  agentName: string;
+  memoryReadCount: number;
+  pendingActions: { action: string; ts: string }[];
+  allActions: { action: string; ts: string }[];
+  dirty: boolean;
+}
+
+const memorySessions = new Map<string, MemorySessionState>();
+
+function initMemorySession(
+  cardId: string,
+  agentIdentifier: string,
+  agentName: string,
+): void {
+  memorySessions.set(cardId, {
+    cardId,
+    agentIdentifier,
+    agentName,
+    memoryReadCount: 0,
+    pendingActions: [],
+    allActions: [],
+    dirty: false,
+  });
+}
+
+function getMemorySession(cardId: string): MemorySessionState | undefined {
+  return memorySessions.get(cardId);
+}
+
+function appendMemoryAction(cardId: string, action: string): void {
+  const session = memorySessions.get(cardId);
+  if (!session) return;
+  const truncated = action.length > 512 ? action.slice(0, 509) + "..." : action;
+  const entry = { action: truncated, ts: new Date().toISOString() };
+  session.pendingActions.push(entry);
+  session.dirty = true;
+}
+
+function incrementMemoryReads(cardId: string): void {
+  const session = memorySessions.get(cardId);
+  if (!session) return;
+  session.memoryReadCount++;
+  session.dirty = true;
+}
+
+/**
+ * Flush pending memory actions to the backend via updateAgentProgress.
+ * Fire-and-forget: errors are logged but never thrown.
+ */
+async function flushMemoryActions(
+  client: HarmonyApiClient,
+  cardId: string,
+): Promise<void> {
+  const session = memorySessions.get(cardId);
+  if (!session || !session.dirty) return;
+
+  try {
+    // Batch reads into a single summary line
+    if (session.memoryReadCount > 0) {
+      session.allActions.push({
+        action: `Recalled ${session.memoryReadCount} memor${session.memoryReadCount === 1 ? "y" : "ies"}`,
+        ts: new Date().toISOString(),
+      });
+      session.memoryReadCount = 0;
+    }
+
+    // Move pending writes to allActions
+    if (session.pendingActions.length > 0) {
+      session.allActions.push(...session.pendingActions);
+      session.pendingActions = [];
+    }
+
+    // Trim to max 10 (drop oldest)
+    if (session.allActions.length > 10) {
+      session.allActions = session.allActions.slice(-10);
+    }
+
+    await client.updateAgentProgress(cardId, {
+      agentIdentifier: session.agentIdentifier,
+      agentName: session.agentName,
+      recentActions: session.allActions,
+    });
+
+    session.dirty = false;
+  } catch (err) {
+    // Fire-and-forget: log but don't propagate
+    console.error("[memory-session] flush failed:", err);
+  }
+}
+
+/**
+ * Merge memory actions into an existing recentActions array from a progress update.
+ * Returns the merged array (caller's actions first, then memory actions appended).
+ */
+function mergeMemoryActionsInto(
+  cardId: string,
+  callerActions: { action: string; ts: string }[],
+): { action: string; ts: string }[] {
+  const session = memorySessions.get(cardId);
+  if (!session) return callerActions;
+
+  // Flush reads into allActions
+  if (session.memoryReadCount > 0) {
+    session.allActions.push({
+      action: `Recalled ${session.memoryReadCount} memor${session.memoryReadCount === 1 ? "y" : "ies"}`,
+      ts: new Date().toISOString(),
+    });
+    session.memoryReadCount = 0;
+  }
+
+  // Move pending to allActions
+  if (session.pendingActions.length > 0) {
+    session.allActions.push(...session.pendingActions);
+    session.pendingActions = [];
+  }
+
+  // Merge: caller actions + memory actions, trim to 10
+  const merged = [...callerActions, ...session.allActions];
+  const trimmed = merged.length > 10 ? merged.slice(-10) : merged;
+
+  // Update allActions to the merged state
+  session.allActions = trimmed;
+  session.dirty = false;
+
+  return trimmed;
+}
+
+/**
+ * Get the first (and typically only) active memory session.
+ * Memory tools don't carry a cardId, so we find the active session.
+ */
+function getActiveMemorySession(): MemorySessionState | undefined {
+  // Return the first active session (there should be at most one)
+  for (const session of memorySessions.values()) {
+    return session;
+  }
+  return undefined;
+}
+
+function cleanupMemorySession(cardId: string): void {
+  memorySessions.delete(cardId);
+}
+
 // Tool definitions
 const TOOLS = {
   // Card operations
@@ -1838,7 +1981,7 @@ async function handleToolCall(
   if (!unauthenticatedTools.includes(name) && !deps.isConfigured()) {
     throw new Error(
       'Not configured. Run "npx @gethmy/mcp setup" to set your API key.\n' +
-        "You can generate an API key at https://gethmy.com → Settings → API Keys.\n" +
+        "You can generate an API key at https://app.gethmy.com → Settings → API Keys.\n" +
         'Or use "harmony_onboard" to create an account and configure automatically.',
     );
   }
@@ -2267,7 +2410,10 @@ async function handleToolCall(
       });
 
       // Mark as explicit so auto-session won't interfere
-      markExplicit(cardId);
+      markExplicit(cardId, { agentIdentifier, agentName });
+
+      // Initialize memory session tracking for action visibility
+      initMemorySession(cardId, agentIdentifier, agentName);
 
       // Prefetch relevant context (non-blocking, best-effort)
       let prefetchedMemoryIds: string[] = [];
@@ -2348,6 +2494,21 @@ async function handleToolCall(
         args.progressPercent !== undefined
           ? z.number().min(0).max(100).parse(args.progressPercent)
           : undefined;
+      // Merge any pending memory actions into the progress update
+      const callerRecentActions = args.recentActions as
+        | { action: string; ts: string }[]
+        | undefined;
+      const memSession = getMemorySession(cardId);
+      let mergedRecentActions: { action: string; ts: string }[] | undefined;
+      if (memSession?.dirty) {
+        mergedRecentActions = mergeMemoryActionsInto(
+          cardId,
+          callerRecentActions || [],
+        );
+      } else if (callerRecentActions) {
+        mergedRecentActions = callerRecentActions;
+      }
+
       const result = await client.updateAgentProgress(cardId, {
         agentIdentifier,
         agentName,
@@ -2363,6 +2524,7 @@ async function handleToolCall(
         estimatedMinutesRemaining: args.estimatedMinutesRemaining as
           | number
           | undefined,
+        ...(mergedRecentActions && { recentActions: mergedRecentActions }),
       });
 
       // Mid-session learning extraction (fire-and-forget)
@@ -2405,6 +2567,10 @@ async function handleToolCall(
           ? z.number().min(0).max(100).parse(args.progressPercent)
           : undefined;
 
+      // Final flush of any pending memory actions before ending the session
+      await flushMemoryActions(client, cardId);
+      cleanupMemorySession(cardId);
+
       const result = await client.endAgentSession(cardId, {
         status: sessionStatus,
         progressPercent: endProgressPercent,
@@ -2527,14 +2693,11 @@ async function handleToolCall(
 
     // Prompt generation
     case "harmony_generate_prompt": {
-      // Get card - either by UUID or short ID
-      let cardData: CardData;
-      let columnData: ColumnData | null = null;
+      // Resolve card ID — either directly or via short ID
+      let cardId: string;
 
       if (args.cardId) {
-        const cardId = z.string().uuid().parse(args.cardId);
-        const cardResult = await client.getCard(cardId);
-        cardData = cardResult.card as CardData;
+        cardId = z.string().uuid().parse(args.cardId);
       } else if (args.shortId !== undefined) {
         const shortId = z.number().int().positive().parse(args.shortId);
         const projectId =
@@ -2545,35 +2708,12 @@ async function handleToolCall(
           );
         }
         const cardResult = await client.getCardByShortId(projectId, shortId);
-        cardData = cardResult.card as CardData;
+        cardId = (cardResult.card as { id: string }).id;
       } else {
         throw new Error("Either cardId or shortId must be provided");
       }
 
-      // Try to get column info from board
-      const projectIdForBoard =
-        (args.projectId as string) ||
-        getActiveProjectId() ||
-        (cardData as unknown as { project_id: string }).project_id;
-      if (projectIdForBoard) {
-        try {
-          const board = await client.getBoard(projectIdForBoard, {
-            summary: true,
-          });
-          const columnId = (cardData as unknown as { column_id: string })
-            .column_id;
-          const column = (
-            board.columns as Array<{ id: string; name: string }>
-          ).find((col) => col.id === columnId);
-          if (column) {
-            columnData = { name: column.name };
-          }
-        } catch {
-          // Column info not available, continue without it
-        }
-      }
-
-      const variant = (args.variant as PromptVariant) || "execute";
+      // Parse MCP-specific context options
       const contextOptions: Record<string, boolean> = {};
       if (args.includeSubtasks !== undefined) {
         contextOptions.includeSubtasks =
@@ -2589,89 +2729,24 @@ async function handleToolCall(
           args.includeDescription === "true";
       }
 
-      // Assemble context using the context assembly engine
-      let assembledContextStr: string | undefined;
-      let assemblyId: string | undefined;
-      let memories: MemoryData[] | undefined;
-
-      try {
-        const workspaceId = deps.getActiveWorkspaceId();
-        if (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,
-            projectId: getActiveProjectId() || undefined,
-            taskContext,
-            cardLabels,
-            cardId: cardData.id,
-            client,
-          });
-
-          if (assembled.context) {
-            assembledContextStr = assembled.context;
-            assemblyId = assembled.manifest.assemblyId;
-            cacheManifest(assembled.manifest);
-          }
-        }
-      } catch {
-        // Context assembly failed, try legacy fallback
-        try {
-          const workspaceId = deps.getActiveWorkspaceId();
-          if (workspaceId && cardData.title) {
-            const memoryResult = await client.searchMemoryEntities(
-              workspaceId,
-              cardData.title,
-              {
-                project_id: getActiveProjectId() || undefined,
-                limit: 5,
-              },
-            );
-            if (memoryResult.entities?.length > 0) {
-              memories = memoryResult.entities.map((e: unknown) => {
-                const entity = e as {
-                  id: string;
-                  type: string;
-                  title: string;
-                  content: string;
-                  confidence: number;
-                  tags: string[];
-                };
-                return {
-                  id: entity.id,
-                  type: entity.type,
-                  title: entity.title,
-                  content: entity.content,
-                  confidence: entity.confidence,
-                  tags: entity.tags || [],
-                };
-              });
-            }
-          }
-        } catch {
-          // Memory fetch also failed, continue without memories
-        }
-      }
-
-      const result = generatePrompt({
-        card: cardData,
-        column: columnData,
-        variant,
-        contextOptions,
+      // Delegate to the shared prompt generation pipeline
+      const result = await client.generateCardPrompt({
+        cardId,
+        workspaceId: deps.getActiveWorkspaceId() || "",
+        projectId:
+          (args.projectId as string) || getActiveProjectId() || undefined,
+        variant: (args.variant as PromptVariant) || "execute",
         customConstraints: args.customConstraints as string | undefined,
-        memories,
-        assembledContext: assembledContextStr,
-        assemblyId,
+        contextOptions,
       });
 
+      // MCP-specific: cache the assembly manifest for the feedback loop
+      if (result.assemblyId) {
+        trackSessionAssembly(cardId, result.assemblyId);
+      }
+
       return {
         success: true,
-        cardId: cardData.id,
-        shortId: cardData.short_id,
-        title: cardData.title,
         ...result,
       };
     }
@@ -2689,6 +2764,8 @@ async function handleToolCall(
       }
       const entityType = (args.type as string) || "context";
       const entityTags = (args.tags as string[]) || [];
+      // Use session's agent identifier if available, otherwise null
+      const activeMemSession = getActiveMemorySession();
       const result = await client.createMemoryEntity({
         workspace_id: workspaceId,
         project_id:
@@ -2704,7 +2781,7 @@ async function handleToolCall(
             ? z.number().min(0).max(1).parse(args.confidence)
             : undefined,
         tags: entityTags.length > 0 ? entityTags : undefined,
-        agent_identifier: "claude-code",
+        agent_identifier: activeMemSession?.agentIdentifier || undefined,
       });
 
       // Fire-and-forget graph expansion: link new entity to semantically similar ones
@@ -2748,6 +2825,12 @@ async function handleToolCall(
         }
       }
 
+      // Track memory write action and flush (fire-and-forget)
+      if (activeMemSession) {
+        appendMemoryAction(activeMemSession.cardId, `Stored memory: ${title}`);
+        flushMemoryActions(client, activeMemSession.cardId).catch(() => {});
+      }
+
       return {
         success: true,
         ...result,
@@ -2830,6 +2913,12 @@ async function handleToolCall(
         ).catch(() => {});
       }
 
+      // Track memory read (batched on flush)
+      const recallMemSession = getActiveMemorySession();
+      if (recallMemSession) {
+        incrementMemoryReads(recallMemSession.cardId);
+      }
+
       return markdown || "No memories found.";
     }
 
@@ -2847,12 +2936,47 @@ async function handleToolCall(
         updates.confidence = z.number().min(0).max(1).parse(args.confidence);
       if (args.metadata !== undefined) updates.metadata = args.metadata;
       const result = await client.updateMemoryEntity(entityId, updates);
+
+      // Track memory write action and flush (fire-and-forget)
+      const updateMemSession = getActiveMemorySession();
+      if (updateMemSession) {
+        const updateTitle = (updates.title as string) || entityId.slice(0, 8);
+        appendMemoryAction(
+          updateMemSession.cardId,
+          `Updated memory: ${updateTitle}`,
+        );
+        flushMemoryActions(client, updateMemSession.cardId).catch(() => {});
+      }
+
       return { success: true, ...result };
     }
 
     case "harmony_forget": {
       const entityId = z.string().uuid().parse(args.entityId);
+
+      // Fetch title before deletion for action tracking
+      let forgetTitle: string | null = null;
+      const forgetMemSession = getActiveMemorySession();
+      if (forgetMemSession) {
+        try {
+          const { entity } = await client.getMemoryEntity(entityId);
+          forgetTitle = (entity as { title?: string })?.title || null;
+        } catch {
+          // Non-fatal: use truncated ID if fetch fails
+        }
+      }
+
       await client.deleteMemoryEntity(entityId);
+
+      // Track memory write action and flush (fire-and-forget)
+      if (forgetMemSession) {
+        appendMemoryAction(
+          forgetMemSession.cardId,
+          `Removed memory: ${forgetTitle || entityId.slice(0, 8)}`,
+        );
+        flushMemoryActions(client, forgetMemSession.cardId).catch(() => {});
+      }
+
       return { success: true };
     }
 
@@ -2880,6 +3004,17 @@ async function handleToolCall(
             ? z.number().min(0).max(1).parse(args.confidence)
             : undefined,
       });
+
+      // Track memory write action and flush (fire-and-forget)
+      const relateMemSession = getActiveMemorySession();
+      if (relateMemSession) {
+        appendMemoryAction(
+          relateMemSession.cardId,
+          `Linked memories: ${relationType}`,
+        );
+        flushMemoryActions(client, relateMemSession.cardId).catch(() => {});
+      }
+
       return { success: true, ...result };
     }
 
@@ -2904,6 +3039,13 @@ async function handleToolCall(
           limit: args.limit as number | undefined,
         },
       );
+
+      // Track memory read (batched on flush)
+      const searchMemSession = getActiveMemorySession();
+      if (searchMemSession) {
+        incrementMemoryReads(searchMemSession.cardId);
+      }
+
       return markdown || "No memories found.";
     }
 
@@ -3039,7 +3181,7 @@ async function handleToolCall(
       });
 
       // Build URL for viewing the plan
-      const planUrl = `https://gethmy.com/plans/${(result.plan as { id: string }).id}`;
+      const planUrl = `https://app.gethmy.com/plans/${(result.plan as { id: string }).id}`;
 
       return {
         success: true,
@@ -3813,13 +3955,17 @@ export class HarmonyMCPServer {
     await this.server.connect(transport);
     console.error("Harmony MCP server running on stdio");
 
-    // Initialize auto-session tracking
+    // Initialize auto-session tracking with MCP client identity detection
     const configDeps = createConfigDeps();
     initAutoSession(
       async (client, cardId, status) => {
         await runEndSessionPipeline(client, configDeps, cardId, status);
       },
       () => getClient(),
+      () => {
+        const cv = this.server.getClientVersion();
+        return cv ? { name: cv.name, version: cv.version } : null;
+      },
     );
 
     // Graceful shutdown: end all auto-sessions

package/src/skills.ts

@@ -251,7 +251,7 @@ Once you have the plan ID, call \`harmony_get_plan\` to fetch the full plan with
 ## [Plan Title]
 **Status:** draft/active/archived | **Phase:** plan/execute/verify/done
 **Tasks:** N total (X pending, Y in_progress, Z completed)
-**URL:** https://gethmy.com/plans/{id}
+**URL:** https://app.gethmy.com/plans/{id}
 \\\`\\\`\\\`
 
 If plan is in execute phase and tasks already have linked cards, note which tasks have cards and which don't.
@@ -285,7 +285,7 @@ Only offer **(A) Single card**, **(C) Analyze only**, or **(D) Skip**.
 #### Option A — Single card
 1. Call \`harmony_create_card\` with:
    - \`title\`: Plan title
-   - \`description\`: Brief 2-3 sentence summary of the plan + \`\\n\\n[View plan](https://gethmy.com/plans/{planId})\`
+   - \`description\`: Brief 2-3 sentence summary of the plan + \`\\n\\n[View plan](https://app.gethmy.com/plans/{planId})\`
    - \`priority\`: based on plan task priorities (use highest)
 2. Call \`harmony_update_plan\` to set \`status: "active"\`, \`workflowPhase: "execute"\`
 
@@ -407,7 +407,7 @@ Call \`harmony_create_plan\` with:
 ### 2B.5 — User Approval
 
 Show the user:
-- Plan URL: \`https://gethmy.com/plans/{id}\`
+- Plan URL: \`https://app.gethmy.com/plans/{id}\`
 - Number of tasks created
 - Brief summary
 

package/src/tui/setup.ts

@@ -41,7 +41,7 @@ export interface SetupOptions {
 const GLOBAL_SKILLS_DIR = join(homedir(), ".agents", "skills");
 
 // API base URL
-const API_URL = "https://gethmy.com/api";
+const API_URL = "https://app.gethmy.com/api";
 
 /**
  * Register MCP server using Claude CLI
@@ -536,7 +536,7 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
   if (!validation.valid) {
     spinner.stop(colors.error("API key validation failed"));
     p.log.error(validation.error || "Could not connect to Harmony API");
-    p.log.info("Get an API key at: https://gethmy.com/user/keys");
+    p.log.info("Get an API key at: https://app.gethmy.com/user/keys");
     process.exit(1);
   }
 
@@ -974,7 +974,7 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
   console.log("");
   console.log(`  ${colors.dim("Add to new project: npx @gethmy/mcp setup")}`);
   console.log(
-    `  ${colors.dim("Need help? Visit https://gethmy.com/docs/mcp")}`,
+    `  ${colors.dim("Need help? Visit https://app.gethmy.com/docs/mcp")}`,
   );
   console.log("");
 }