@gethmy/mcp 3.2.0 → 3.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "MCP server for Harmony, the shared surface for human–agent teams — agents claim cards, report progress, and move work on your board.",
   "publishConfig": {
     "access": "public"
@@ -24,7 +24,8 @@
   },
   "bin": {
     "harmony-mcp": "dist/cli.js",
-    "gethmy-mcp": "dist/cli.js"
+    "gethmy-mcp": "dist/cli.js",
+    "harmony-run-hook": "dist/run-hook-cli.js"
   },
   "files": [
     "dist",
@@ -59,7 +60,7 @@
     "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 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": "rm -rf dist && bun build src/index.ts src/cli.ts src/run-hook-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",

package/src/api-client.ts

@@ -1213,6 +1213,12 @@ export class HarmonyApiClient {
     data: {
       decision: "continue" | "stop";
       extraTurns: number;
+      /**
+       * Consumption granted with a Continue, in USD (#1058). Optional — an
+       * omitted value makes the daemon fall back to its own configured grant
+       * (`budget.pause.extraBudgetUsd`, else the per-spawn `sdk.maxBudgetUsd`).
+       */
+      extraBudgetUsd?: number;
       message?: string;
     },
   ): Promise<{ id: string; seq: number; createdAt: string }> {
@@ -1232,6 +1238,8 @@ export class HarmonyApiClient {
     decisions: Array<{
       decision: "continue" | "stop";
       extraTurns: number;
+      /** Consumption granted with the Continue, in USD (#1058) — absent on a pre-#1058 row. */
+      extraBudgetUsd?: number;
       message?: string;
       createdAt: string;
     }>;
@@ -1930,9 +1938,19 @@ export class HarmonyApiClient {
     return this.request("GET", `/plans/${planId}`);
   }
 
+  /**
+   * The plan a card belongs to, and the criteria that point back at it from elsewhere.
+   *
+   * `plan`/`tasks` are MEMBERSHIP (`cards.plan_id`). `foreign_criteria` is DELIVERY
+   * (`plan_tasks.card_id`) for the rows where the two disagree — a card in no plan, or a
+   * card in a different one (#1054). It is optional because a harmony-api older than
+   * #1054 does not send it, so a reader must treat its absence as "unknown", never as
+   * "there are none".
+   */
   async getPlanByCardId(cardId: string): Promise<{
     plan: unknown;
     tasks: unknown[];
+    foreign_criteria?: unknown[];
   } | null> {
     return this.request("GET", `/cards/${cardId}/plan`);
   }
@@ -1948,6 +1966,13 @@ export class HarmonyApiClient {
     return this.request("PATCH", `/plans/${planId}`, updates);
   }
 
+  /**
+   * Point a criterion at a card and/or set its status.
+   *
+   * `cardPlanAdopted` reports the second write this route makes (#1054): linking a card
+   * that belongs to no plan also writes `cards.plan_id`, so the two columns cannot drift.
+   * Absent from a harmony-api older than #1054 — read it as "unknown", never as "no".
+   */
   async updatePlanTask(
     planId: string,
     taskId: string,
@@ -1955,7 +1980,7 @@ export class HarmonyApiClient {
       cardId?: string;
       status?: "pending" | "in_progress" | "completed";
     },
-  ): Promise<{ task: unknown }> {
+  ): Promise<{ task: unknown; cardPlanAdopted?: boolean }> {
     return this.request("PATCH", `/plans/${planId}/tasks/${taskId}`, updates);
   }
 
@@ -2374,6 +2399,37 @@ export class HarmonyApiClient {
   ): Promise<{ playbook: unknown }> {
     return this.request("PATCH", `/playbooks/${playbookId}`, updates);
   }
+
+  /**
+   * Delete a playbook (card #856). Irreversible: `playbook_versions` and
+   * `playbook_runs` cascade with it, and every bound card is unbound.
+   *
+   * The unbound cards are the point of the return value — the cards that were
+   * running this playbook stay on the board with their stage pointer cleared,
+   * and the caller has no other way to learn which ones those were.
+   * `unboundCardCount` is exact; `unboundCards` is a capped sample of them.
+   *
+   * The route refuses a caller who is neither the playbook's creator nor a
+   * workspace owner/admin with a 403, distinct from the 404 it answers when the
+   * playbook is already gone. `request` throws on both, so a resolved promise
+   * means the row really was removed.
+   */
+  async deletePlaybook(playbookId: string): Promise<{
+    success: boolean;
+    playbook: { id: string; name: string; workspace_id: string };
+    unboundCardCount: number;
+    unboundCards: Array<{
+      id: string;
+      short_id: number | null;
+      title: string;
+      current_stage: string | null;
+    }>;
+  }> {
+    return this.request(
+      "DELETE",
+      `/playbooks/${encodeURIComponent(playbookId)}`,
+    );
+  }
 }
 
 // Shared types for generateCardPrompt to avoid inline assertions

package/src/auto-session.ts

@@ -24,6 +24,7 @@
  */
 
 import type { HarmonyApiClient } from "./api-client.js";
+import { beginHookTimeline, endHookTimeline } from "./run-event-forwarder.js";
 
 /**
  * Status reported for a tracked session. Drives the heartbeat decision: only
@@ -43,6 +44,17 @@ export interface TrackedSession {
   isExplicit: boolean;
   agentIdentifier: string;
   agentName: string;
+  /**
+   * `card_agent_context.id` for this session, when the start endpoint returned
+   * one. Recorded so the session can be PUBLISHED on disk for the `PostToolUse`
+   * hook to find (#874) — a hook is a separate process and cannot read this
+   * map, so the id has to travel through the filesystem.
+   *
+   * Optional because an older API build may return no id, and because a start
+   * that threw is still tracked locally. Absent means "no tool-call rows for
+   * this session", never an error.
+   */
+  agentSessionId?: string;
   /**
    * Last status reported for the session (default `working`). Only `working`
    * sessions are heartbeated by the sweep; see `heartbeatActiveSessions`.
@@ -290,6 +302,7 @@ export async function trackActivity(
   // rather than letting a surviving client walk the run back to life one cooldown
   // later (card #770). An explicit `/hmy` re-run is unaffected — it starts the
   // session by name and only faces the 10-minute #663 window.
+  let agentSessionId: string | undefined;
   try {
     const started = await client.startAgentSession(cardId, {
       agentIdentifier,
@@ -300,6 +313,7 @@ export async function trackActivity(
     // Refused: don't track it locally either, or the sweep would heartbeat a
     // session that does not exist and `checkInactivity` would later "end" it.
     if (started?.session === null) return;
+    agentSessionId = (started?.session as { id?: string } | undefined)?.id;
   } catch {
     // Session start failed (might already have one), still track locally
   }
@@ -311,8 +325,20 @@ export async function trackActivity(
     isExplicit: false,
     agentIdentifier,
     agentName,
+    agentSessionId,
     status: "working",
   });
+
+  // Publish for the `PostToolUse` hook. An auto-session is a real session with
+  // a real timeline, so it gets tool rows for the same reason an explicit one
+  // does. Best-effort by construction — `beginHookTimeline` returns null rather
+  // than throwing, so a failure here cannot break the tool call that triggered
+  // the auto-start.
+  beginHookTimeline({
+    cardId,
+    agentSessionId,
+    getClient: () => client,
+  });
 }
 
 /**
@@ -551,6 +577,13 @@ async function autoEndSession(
   // cardId concurrently; whichever claims it first runs the end + pipeline,
   // the loser bails so endAgentSession / runEndSessionPipeline fire exactly once.
   if (!scope.sessions.delete(cardId)) return;
+  // Drain and unpublish BEFORE the session row is ended — an append to an ended
+  // session is refused, so the tail of the tool log would be lost otherwise.
+  try {
+    await endHookTimeline(cardId);
+  } catch {
+    // Best-effort telemetry; never blocks the end.
+  }
   try {
     await client.endAgentSession(cardId, { status });
   } catch {

package/src/cli.ts

@@ -211,4 +211,108 @@ program
     });
   });
 
+const hook = program
+  .command("hook")
+  .description(
+    "Manage the PostToolUse hook that streams tool calls to a card's run timeline",
+  );
+
+hook
+  .command("install")
+  .description(
+    "Install the hook into ~/.claude/settings.json (the user layer, never a project)",
+  )
+  .action(async () => {
+    // Imported lazily so `serve` — the hot path — does not parse this module.
+    const { installUserHook } = await import("./hook-install.js");
+    const result = installUserHook();
+    if (!result.ok) {
+      console.error(`Could not install the hook: ${result.error}`);
+      process.exit(1);
+    }
+    console.log(
+      result.changed
+        ? `Installed the Harmony PostToolUse hook in ${result.path}`
+        : `The Harmony PostToolUse hook is already installed in ${result.path}`,
+    );
+    console.log(`  command: ${result.command}`);
+    console.log(
+      "\nTool calls from an MCP session will now appear on the card's run timeline.",
+    );
+    console.log(
+      "The user settings layer is deliberate: a daemon run never loads it, so it",
+    );
+    console.log("cannot double-report the stream it already sends itself.");
+  });
+
+hook
+  .command("uninstall")
+  .description("Remove the hook from ~/.claude/settings.json")
+  .action(async () => {
+    const { uninstallUserHook } = await import("./hook-install.js");
+    const result = uninstallUserHook();
+    if (!result.ok) {
+      console.error(`Could not remove the hook: ${result.error}`);
+      process.exit(1);
+    }
+    console.log(
+      result.changed
+        ? `Removed the Harmony PostToolUse hook from ${result.path}`
+        : "The Harmony PostToolUse hook was not installed.",
+    );
+  });
+
+hook
+  .command("status")
+  .description("Report whether the hook is installed, and any live sessions")
+  .action(async () => {
+    const { hookInstallStatus, userSettingsPath } = await import(
+      "./hook-install.js"
+    );
+    const { readPublishedSessions, runStateDir } = await import(
+      "./run-state.js"
+    );
+    const { readFileSync } = await import("node:fs");
+    const path = userSettingsPath();
+    let status = {
+      installed: false,
+      binary: null as string | null,
+      binaryExists: false,
+    };
+    try {
+      status = hookInstallStatus(JSON.parse(readFileSync(path, "utf-8")));
+    } catch {
+      // A missing or corrupt settings file reads as "not installed".
+    }
+    console.log(
+      `Hook: ${status.installed ? "installed" : "not installed"} (${path})`,
+    );
+    if (status.installed && !status.binaryExists) {
+      console.log(
+        `  ! its hook binary is gone: ${status.binary ?? "unparseable command"}`,
+      );
+      console.log(
+        "  The hook is INERT until you re-run `npx @gethmy/mcp hook install`.",
+      );
+      console.log(
+        "  An upgrade or a cleared npx/bunx cache moves the binary; the installed",
+      );
+      console.log(
+        "  command guards its own paths, so nothing errors in the meantime.",
+      );
+    }
+    console.log(`State: ${runStateDir()}`);
+    const sessions = readPublishedSessions();
+    if (sessions.length === 0) {
+      console.log("Live sessions: none");
+      return;
+    }
+    console.log(`Live sessions: ${sessions.length}`);
+    for (const session of sessions) {
+      console.log(
+        `  card ${session.cardId} · session ${session.agentSessionId} · pid ${session.publisherPid} · ${session.cwd}`,
+      );
+    }
+  });
+
 program.parse();

package/src/comment-session.ts

@@ -0,0 +1,149 @@
+/**
+ * Which session an agent comment names — and when it names none (card #1035).
+ *
+ * ## The question this replaces
+ *
+ * `POST /cards/:id/comments` used to answer "which session?" itself when the
+ * caller sent none: it selected the caller's sessions on the card by `card_id`
+ * + `user_id`. That predicate is true of **every concurrent run of the same
+ * account**, so a second run inherited the first one's attribution — measured
+ * on card #1029, where two findings came back carrying a neighbouring `/hmy`
+ * session's id. The server could not do better, because `user_id` is the only
+ * thing it has and the daemon's API key resolves to the same user as its
+ * launcher's own sessions.
+ *
+ * So the answer moved to the only place that can know it: the process making
+ * the call. This module is that decision, kept pure so it is a table test
+ * rather than a behaviour reconstructed from a live run.
+ *
+ * ## Two sources, and why absence is now an ANSWER rather than a guess
+ *
+ * A caller may hold a session two ways, and both are DECLARATIONS rather than
+ * observations:
+ *
+ * - `tracked` — this process called `harmony_start_agent_session` and kept the
+ *   id (`memorySessions`). It is the interactive `/hmy` path.
+ * - `declared` — the daemon put the run's id in this process's environment
+ *   (`harmonyMcpServer` in `@gethmy/harness`, and `motor-driver.ts` for a stage
+ *   run). It is the daemon path, which needs one because
+ *   `harmony_start_agent_session` is DENIED on a daemon run
+ *   (`STAGE_DAEMON_OWNED_TOOLS`) — the daemon owns the lifecycle, so the agent
+ *   has nothing of its own to track.
+ *
+ * Neither is an inference about the ACCOUNT, and that is the whole change.
+ * The old question — "does this user have a session on this card?" — has an
+ * ambiguous negative, because a process that tracks nothing may still belong to
+ * a user with three live runs. The new question — "was a session declared to
+ * THIS process for THIS card?" — has a definite negative: nothing declared
+ * means this caller holds no session it may claim, which is exactly the
+ * sessionless comment #1033 made legal. There is no third "I do not know"
+ * state left for the server to guess at.
+ *
+ * ## The scope check on `tracked` is load-bearing
+ *
+ * `memorySessions` is keyed by card id alone and lives at module scope, so on
+ * the hosted HTTP transport (`remote.ts`, one process serving every user) a
+ * lookup can return a DIFFERENT user's session for the same card. Claiming it
+ * is not merely wrong attribution — harmony-api verifies an explicit
+ * `agentSessionId` against `user_id` and answers 403 — so the tracked source
+ * carries the scope it was recorded under and is used only when that matches
+ * the caller's. A mismatch is treated as "not mine", never as "theirs".
+ *
+ * ## The card check on `declared` is load-bearing too
+ *
+ * A daemon run comments on its own card and, since #1033, on neighbouring ones
+ * — that is how a finding reaches a card the run does not hold. The run's
+ * session belongs to ONE card, so the declaration carries the card id and is
+ * used only on that card. On any other card the same run is genuinely
+ * sessionless, and says so.
+ */
+
+/** A run's own session, as the daemon declared it to this process. */
+export interface DeclaredRunSession {
+  /** `cards.id` — the card the run holds its session on. */
+  cardId: string;
+  /** `card_agent_context.id` — the run's own session row. */
+  agentSessionId: string;
+}
+
+/** The session this process tracks for a card, and the tenant it belongs to. */
+export interface TrackedCommentSession {
+  /** `card_agent_context.id`, captured when this process started the session. */
+  agentSessionId?: string;
+  /**
+   * The tenant the session was recorded under (`ToolDeps.getScopeId`).
+   * `undefined` on stdio, where the process serves exactly one user.
+   */
+  scopeId?: string;
+}
+
+/** What `harmony_add_comment` should send for `agentSessionId`. */
+export type CommentSessionChoice =
+  | {
+      kind: "session";
+      agentSessionId: string;
+      /** Which declaration named it — for the tool result, so the caller can see. */
+      source: "tracked" | "declared";
+    }
+  | { kind: "sessionless" };
+
+/** The two environment keys the daemon declares a run's session through. */
+export const RUN_SESSION_CARD_ENV = "HARMONY_AGENT_CARD_ID";
+export const RUN_SESSION_ID_ENV = "HARMONY_AGENT_SESSION_ID";
+
+/**
+ * The run this MCP process was started for, if the daemon declared one.
+ *
+ * Read per call rather than latched at startup: the value cannot change under a
+ * stdio server (one process per run), and re-reading keeps this a pure function
+ * of its input, which is what lets the tests drive it with a synthetic
+ * environment instead of `process.env`.
+ *
+ * BOTH keys or nothing. A card id with no session is a run that declared
+ * nothing usable, and a session id with no card cannot be bounded to the card
+ * it belongs to — claiming it on every card is the borrowing this replaces.
+ */
+export function readDeclaredRunSession(
+  env: Record<string, string | undefined> = process.env,
+): DeclaredRunSession | null {
+  const cardId = env[RUN_SESSION_CARD_ENV]?.trim();
+  const agentSessionId = env[RUN_SESSION_ID_ENV]?.trim();
+  if (!cardId || !agentSessionId) return null;
+  return { cardId, agentSessionId };
+}
+
+/**
+ * Decide what a new agent comment on `cardId` is attributed to.
+ *
+ * `tracked` wins over `declared` when both name a session for the card. They
+ * cannot disagree in practice — a daemon run may not open a session of its own
+ * — but if one ever did, the session this process opened is the one it can
+ * prove it owns.
+ */
+export function chooseCommentSession(args: {
+  cardId: string;
+  tracked?: TrackedCommentSession | undefined;
+  /** The caller's tenant (`ToolDeps.getScopeId`); `undefined` on stdio. */
+  callerScopeId?: string | undefined;
+  declared?: DeclaredRunSession | null;
+}): CommentSessionChoice {
+  const tracked = args.tracked;
+  if (tracked?.agentSessionId && tracked.scopeId === args.callerScopeId) {
+    return {
+      kind: "session",
+      agentSessionId: tracked.agentSessionId,
+      source: "tracked",
+    };
+  }
+
+  const declared = args.declared;
+  if (declared && declared.cardId === args.cardId) {
+    return {
+      kind: "session",
+      agentSessionId: declared.agentSessionId,
+      source: "declared",
+    };
+  }
+
+  return { kind: "sessionless" };
+}