@gethmy/mcp 2.13.4 → 2.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.13.4",
+  "version": "2.15.0",
   "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
   "publishConfig": {
     "access": "public"
@@ -16,6 +16,10 @@
     "./src/config.js": {
       "types": "./src/config.ts",
       "default": "./dist/lib/config.js"
+    },
+    "./src/oauth-refresh.js": {
+      "types": "./src/oauth-refresh.ts",
+      "default": "./dist/lib/oauth-refresh.js"
     }
   },
   "bin": {
@@ -55,12 +59,12 @@
     "bun": ">=1.0.0"
   },
   "scripts": {
-    "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": "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 src/oauth-refresh.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 src/__tests__/skills.test.ts src/__tests__/hmy-config.test.ts src/__tests__/tool-dispatch.test.ts src/__tests__/mcp-integration.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__/hmy-config.test.ts src/__tests__/tool-dispatch.test.ts src/__tests__/mcp-integration.test.ts src/__tests__/auto-session.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 typecheck && bun run build"

package/src/api-client.ts

@@ -527,6 +527,70 @@ export class HarmonyApiClient {
     return this.request("GET", `/board/${projectId}${query}`);
   }
 
+  /**
+   * Fetch the FULL board — every non-archived card — by paginating past the
+   * server's default 50-card window (`getBoard` caps at `limit=50` to keep MCP
+   * responses under the token budget).
+   *
+   * Daemon board scans must see the whole board: with the 50-card cap the
+   * entire `Review` column fell outside the first-50-by-position window once a
+   * project crossed 50 cards, silently starving the review pipeline (#628 — a
+   * 272-card project had 0 reviews for ~2 days). This has no LLM-context/token
+   * concern daemon-side, so it walks `offset` until `pagination.hasMore` is
+   * false and concatenates every page's cards.
+   *
+   * Summary mode carries no `cards` array, so callers that only need per-column
+   * counts should keep using `getBoard({ summary: true })`. This is the
+   * card-list path.
+   */
+  async getFullBoard(
+    projectId: string,
+    options?: {
+      columnId?: string;
+      includeArchived?: boolean;
+      labelName?: string;
+      /** Page size for the offset walk. Defaults to 200. */
+      pageSize?: number;
+    },
+  ): Promise<{
+    project: unknown;
+    columns: unknown[];
+    cards: unknown[];
+    labels: unknown[];
+    totalCards: number;
+  }> {
+    const { pageSize = 200, ...boardOpts } = options ?? {};
+    const cards: unknown[] = [];
+    let offset = 0;
+    let last: Awaited<ReturnType<HarmonyApiClient["getBoard"]>> | null = null;
+
+    // Walk pages until the server reports no more. Guard on `hasMore` (not
+    // `cards.length`) so a label-filtered final page shorter than pageSize
+    // terminates cleanly; the empty-page break is a belt-and-braces backstop
+    // against a server that omits `pagination`.
+    for (;;) {
+      const page = await this.getBoard(projectId, {
+        ...boardOpts,
+        limit: pageSize,
+        offset,
+      });
+      last = page;
+      const pageCards = page.cards ?? [];
+      cards.push(...pageCards);
+      const hasMore = page.pagination?.hasMore ?? false;
+      if (!hasMore || pageCards.length === 0) break;
+      offset += pageSize;
+    }
+
+    return {
+      project: last?.project,
+      columns: last?.columns ?? [],
+      cards,
+      labels: last?.labels ?? [],
+      totalCards: last?.pagination?.totalCards ?? cards.length,
+    };
+  }
+
   // ============ CARD OPERATIONS ============
 
   async createCard(
@@ -719,6 +783,17 @@ export class HarmonyApiClient {
     return this.request("GET", `/cards/${cardId}/external-links`);
   }
 
+  async addExternalLink(
+    cardId: string,
+    url: string,
+    title?: string,
+  ): Promise<{ link: CardExternalLinkRow }> {
+    return this.request("POST", `/cards/${cardId}/external-links`, {
+      url,
+      title,
+    });
+  }
+
   // ============ ARTIFACTS (hosted HTML documents) ============
 
   async uploadArtifact(data: {
@@ -842,6 +917,7 @@ export class HarmonyApiClient {
       commentType?: string;
       supersedesId?: string;
       confirmsId?: string;
+      replyToId?: string;
       agentSessionId?: string;
     },
   ): Promise<{ comment: unknown }> {
@@ -851,6 +927,7 @@ export class HarmonyApiClient {
       commentType: opts?.commentType,
       supersedesId: opts?.supersedesId,
       confirmsId: opts?.confirmsId,
+      replyToId: opts?.replyToId,
       agentSessionId: opts?.agentSessionId,
     });
   }
@@ -1871,7 +1948,6 @@ export class HarmonyApiClient {
     name: string;
     description?: string;
     steps?: unknown;
-    stepsVersion?: number;
     triggerType?: string;
   }): Promise<{ playbook: unknown }> {
     return this.request("POST", "/playbooks", data);
@@ -1889,17 +1965,6 @@ export class HarmonyApiClient {
   ): Promise<{ playbook: unknown }> {
     return this.request("PATCH", `/playbooks/${playbookId}`, updates);
   }
-
-  async runPlaybook(playbookId: string): Promise<{ run: unknown }> {
-    return this.request("POST", `/playbooks/${playbookId}/run`);
-  }
-
-  async savePlaybookFromCard(data: {
-    cardId: string;
-    name?: string;
-  }): Promise<{ playbook: unknown }> {
-    return this.request("POST", "/playbooks/from-card", data);
-  }
 }
 
 // Shared types for generateCardPrompt to avoid inline assertions

package/src/auto-session.ts

@@ -25,6 +25,16 @@
 
 import type { HarmonyApiClient } from "./api-client.js";
 
+/**
+ * Status reported for a tracked session. Drives the heartbeat decision: only
+ * `working` sessions are heartbeated by the sweep. `paused`/`blocked`/`waiting`
+ * are intentional non-heartbeat states — the agent has deliberately stopped
+ * making progress (parked for a human, awaiting input, …), so bumping their
+ * `updated_at` would both keep a paused row looking active and mask a genuinely
+ * stalled run.
+ */
+export type SessionStatus = "working" | "blocked" | "waiting" | "paused";
+
 export interface TrackedSession {
   cardId: string;
   startedAt: number;
@@ -33,6 +43,11 @@ export interface TrackedSession {
   isExplicit: boolean;
   agentIdentifier: string;
   agentName: string;
+  /**
+   * Last status reported for the session (default `working`). Only `working`
+   * sessions are heartbeated by the sweep; see `heartbeatActiveSessions`.
+   */
+  status?: SessionStatus;
 }
 
 export type EndSessionCallback = (
@@ -173,7 +188,7 @@ export function initAutoSession(
   // the remote transport, connections arrive faster than the 60s interval and a
   // restart-each-time would keep deferring the sweep indefinitely (starvation).
   if (!inactivityTimer) {
-    inactivityTimer = setInterval(checkInactivity, CHECK_INTERVAL_MS);
+    inactivityTimer = setInterval(sweepTick, CHECK_INTERVAL_MS);
   }
 }
 
@@ -256,6 +271,7 @@ export async function trackActivity(
     isExplicit: false,
     agentIdentifier,
     agentName,
+    status: "working",
   });
 }
 
@@ -283,6 +299,7 @@ export function markExplicit(
       isExplicit: true,
       agentIdentifier: options?.agentIdentifier ?? "explicit",
       agentName: options?.agentName ?? "Explicit Agent",
+      status: "working",
     });
   }
 }
@@ -376,6 +393,79 @@ export function checkInactivity(): void {
   }
 }
 
+/**
+ * Record the latest status reported for a tracked session so the sweep knows
+ * whether to keep heartbeating it. Wired into `harmony_update_agent_progress`
+ * (server.ts): when an agent reports `paused`/`blocked`/`waiting` the heartbeat
+ * stops for that session (those are intentional non-heartbeat states); a later
+ * `working` report resumes it. No-op when the card isn't tracked in the scope.
+ */
+export function noteSessionStatus(
+  cardId: string,
+  status: SessionStatus,
+  scopeId: string = DEFAULT_SCOPE,
+): void {
+  const session = scopes.get(scopeId)?.sessions.get(cardId);
+  if (session) session.status = status;
+}
+
+/**
+ * Heartbeat every tracked `working` session by writing a status-only
+ * `updateAgentProgress`. The backend's `card_agent_context` update trigger
+ * bumps `updated_at` — the field both the kanban card ribbon
+ * (`isAgentContextLive`) and the header "Connected Agents" panel key off to
+ * decide a session is still live.
+ *
+ * WHY (card #608): an interactive MCP client (Claude Code, Cursor, /hmy) opens a
+ * `card_agent_context` row but, unlike the agent daemon's progress-tracker (60s
+ * heartbeat), only writes progress at milestones — often many minutes apart. On
+ * a long run `updated_at` goes stale and the card drops its live indicator
+ * mid-flight. This sweep gives interactive sessions the same ~60s heartbeat.
+ *
+ * Only `working` sessions are heartbeated; `paused`/`blocked`/`waiting` are
+ * intentional non-heartbeat states (see `SessionStatus`). The payload is
+ * status-only (no currentTask/progressPercent) so the heartbeat never clobbers
+ * the real progress the agent last reported — the trigger still bumps
+ * `updated_at`. Covers both auto-started and explicit sessions (both live in
+ * `scope.sessions`).
+ *
+ * No double-heartbeat for the daemon: `packages/harmony-agent` has its own
+ * progress-tracker heartbeat and never routes through mcp-server auto-sessions.
+ */
+export function heartbeatActiveSessions(): void {
+  for (const scope of scopes.values()) {
+    const client = scope.clientGetter?.();
+    if (!client) continue;
+    for (const session of scope.sessions.values()) {
+      // Default-undefined status is treated as `working` (sessions created
+      // before a status was reported).
+      if ((session.status ?? "working") !== "working") continue;
+      client
+        .updateAgentProgress(session.cardId, {
+          agentIdentifier: session.agentIdentifier,
+          agentName: session.agentName,
+          status: "working",
+        })
+        .catch(() => {
+          // Best-effort: a transient failure just defers the bump to the next
+          // sweep. updateAgentProgress is fire-and-forget here.
+        });
+    }
+  }
+}
+
+/**
+ * One tick of the shared 60s sweep: prune idle auto-sessions
+ * (`checkInactivity`) first, then heartbeat the surviving `working` sessions
+ * (`heartbeatActiveSessions`). Order matters — prune before heartbeat so we
+ * never bump a session we're about to end. Exported for tests; in production
+ * the single process-wide timer calls it every CHECK_INTERVAL_MS.
+ */
+export function sweepTick(): void {
+  checkInactivity();
+  heartbeatActiveSessions();
+}
+
 // --- Internal ---
 
 async function autoEndSession(