@gethmy/mcp 2.13.4 → 2.15.0

package/src/server.ts

@@ -22,6 +22,7 @@ import {
   destroyAutoSession,
   initAutoSession,
   markExplicit,
+  noteSessionStatus,
   shutdownAllSessions,
   trackActivity,
   untrack,
@@ -121,6 +122,65 @@ function requireExactlyOneScope(scope: {
   }
 }
 
+/**
+ * Backward-compat dispatch shim (#605). Consolidated tools dropped the old
+ * names from the advertised TOOLS list (the token win), but `handleToolCall`
+ * still dispatches them so external integrations calling the old names keep
+ * working through a deprecation window. Logged once per name to stderr (never
+ * stdout — that carries the MCP protocol on stdio).
+ */
+const DEPRECATED_TOOL_ALIASES: Record<string, string> = {
+  harmony_get_card_by_short_id: "harmony_get_card",
+  harmony_bulk_get_cards: "harmony_get_card",
+  harmony_upload_artifact: "harmony_upload",
+  harmony_upload_card_attachment: "harmony_upload",
+  harmony_request_artifact_upload_url: "harmony_request_upload_url",
+  harmony_request_card_attachment_upload_url: "harmony_request_upload_url",
+  harmony_finalize_artifact: "harmony_finalize_upload",
+  harmony_finalize_card_attachment: "harmony_finalize_upload",
+};
+const _warnedDeprecatedTools = new Set<string>();
+function warnDeprecatedTool(oldName: string): void {
+  if (_warnedDeprecatedTools.has(oldName)) return;
+  _warnedDeprecatedTools.add(oldName);
+  const replacement = DEPRECATED_TOOL_ALIASES[oldName];
+  console.error(
+    `[harmony-mcp] Tool "${oldName}" is deprecated (still accepted) — ` +
+      `use "${replacement}" instead. The old name is no longer advertised and ` +
+      `will be removed in a future major version.`,
+  );
+}
+
+/**
+ * Removed-capability shim (#612). The legacy steps_version=1 "Automation" macro
+ * was retired when Harmony committed to the single stage-Playbook model. These
+ * tools have no v2 replacement, so — following the #605 hidden-dispatch pattern —
+ * they are dropped from the advertised TOOLS list but their switch cases remain,
+ * returning a one-time deprecation notice (warned once to stderr) instead of an
+ * unknown-tool error, so an integration calling the old name fails legibly.
+ */
+const DEPRECATED_REMOVED_TOOLS: Record<string, string> = {
+  harmony_run_playbook:
+    "Playbooks are stage models run by the board and agent daemon as a card moves through their stages — there is no server-side macro to trigger. This tool no longer runs anything.",
+  harmony_save_card_as_playbook:
+    "The steps_version=1 automation macro was removed. Build a stage playbook with harmony_create_playbook instead.",
+};
+const _warnedRemovedTools = new Set<string>();
+function deprecatedRemovedToolResult(name: string): {
+  success: false;
+  deprecated: true;
+  message: string;
+} {
+  const message = DEPRECATED_REMOVED_TOOLS[name];
+  if (!_warnedRemovedTools.has(name)) {
+    _warnedRemovedTools.add(name);
+    console.error(
+      `[harmony-mcp] Tool "${name}" is deprecated and no longer functional — ${message}`,
+    );
+  }
+  return { success: false, deprecated: true, message };
+}
+
 /** PUT raw bytes straight to a Supabase signed upload URL (the token rides in
  * the URL query). Used by the stdio internal handshake; the hosted server can't
  * read local disk, so there the agent drives this PUT itself via the two-step
@@ -625,49 +685,37 @@ export const TOOLS = {
     },
   },
   harmony_get_card: {
-    description: "Get detailed information about a specific card by UUID",
-    inputSchema: {
-      type: "object",
-      properties: {
-        cardId: { type: "string", description: "Card UUID" },
-      },
-      required: ["cardId"],
-    },
-  },
-  harmony_get_card_by_short_id: {
-    description: "Get a card by its short ID (e.g., #42) within a project",
+    description:
+      "Fetch one or many cards. Provide exactly one of: `cardId` (UUID, full detail), " +
+      "`shortId` (e.g. 42, full detail), or `shortIds` (array, max 100 — compact " +
+      "summaries: id, shortId, title, column, priority, assignee, labels, archived, " +
+      "plus any short ids not found). `shortId`/`shortIds` need project context. " +
+      "Prefer one `shortIds` call over repeated single fetches for multiple cards.",
     inputSchema: {
       type: "object",
       properties: {
-        projectId: {
+        cardId: {
           type: "string",
-          description: "Project ID (optional if context set)",
+          description: "Card UUID — full detail for one card.",
         },
         shortId: {
           type: "number",
-          description: "Short ID number (e.g., 42 for card #42)",
+          description:
+            "Short ID (e.g. 42 for card #42) — full detail, project-scoped.",
         },
-      },
-      required: ["shortId"],
-    },
-  },
-  harmony_bulk_get_cards: {
-    description:
-      "Fetch multiple cards by short id in one call. Returns compact summaries " +
-      "(id, shortId, title, column, priority, assignee, labels, archived) plus " +
-      "any short ids not found. Requires project context. Prefer this over " +
-      "repeated harmony_get_card_by_short_id when referencing multiple cards.",
-    inputSchema: {
-      type: "object",
-      properties: {
         shortIds: {
           type: "array",
           items: { type: "number" },
           description:
-            "Card short ids, e.g. [400, 401, 402]. Max 100 per call.",
+            "Short IDs, e.g. [400, 401, 402] — compact summaries in one call. Max 100.",
+        },
+        projectId: {
+          type: "string",
+          description:
+            "Project ID for shortId/shortIds (optional if context set).",
         },
       },
-      required: ["shortIds"],
+      required: [],
     },
   },
   harmony_bulk_archive_cards: {
@@ -837,186 +885,162 @@ export const TOOLS = {
       required: ["cardId"],
     },
   },
-  harmony_upload_card_attachment: {
+  harmony_upload: {
     description:
-      "Upload a file attachment to a card. Provide `filePath` (local path the server reads, direct-to-storage — local/stdio mode) or `base64Data` (works everywhere, small-file fallback). Max 5MB; allowed: PNG, JPEG, GIF, WebP, HEIC/HEIF, PDF, DOC/DOCX, XLS/XLSX, TXT, CSV. Returns the attachment + a signed URL. Large files on the hosted MCP server: use harmony_request_card_attachment_upload_url + harmony_finalize_card_attachment instead.",
+      'Upload a file in one call. `target: "card_attachment"` attaches a file to a card ' +
+      "(max 5MB; PNG/JPEG/GIF/WebP/HEIC/HEIF/PDF/DOC(X)/XLS(X)/TXT/CSV) — requires cardId. " +
+      '`target: "artifact"` hosts a self-contained HTML doc (text/html, max 2MB) linked to ' +
+      "exactly one of cardId/planId/workspaceId, rendered in-app in a sandboxed iframe. Provide " +
+      "the bytes as `filePath` (local, direct-to-storage) or `base64Data` (small-file fallback). " +
+      "Returns the attachment/artifact + a signed URL (artifact: use harmony_share_artifact for a " +
+      "public link). Large files on the hosted MCP server: use harmony_request_upload_url + " +
+      "harmony_finalize_upload instead.",
     inputSchema: {
       type: "object",
       properties: {
-        cardId: { type: "string", description: "Card UUID" },
+        target: {
+          type: "string",
+          enum: ["card_attachment", "artifact"],
+          description:
+            "What to upload: a card file attachment or a hosted HTML artifact.",
+        },
+        cardId: {
+          type: "string",
+          description:
+            "Card UUID. Required for card_attachment; one of cardId/planId/workspaceId for artifact.",
+        },
+        planId: {
+          type: "string",
+          description:
+            "Plan UUID (artifact only — link the artifact to a plan).",
+        },
+        workspaceId: {
+          type: "string",
+          description: "Workspace UUID (artifact only — standalone artifact).",
+        },
         filePath: {
           type: "string",
           description:
-            "Absolute path to a local file the MCP server process can read. Mutually exclusive with base64Data.",
+            "Absolute path to a local file the server can read. Mutually exclusive with base64Data.",
         },
         base64Data: {
           type: "string",
           description:
-            "Base64-encoded file bytes (a `data:` URL prefix is accepted and stripped). Requires fileName. Mutually exclusive with filePath.",
+            "Base64-encoded bytes (a `data:` URL prefix is accepted and stripped). Mutually exclusive with filePath.",
         },
         fileName: {
           type: "string",
           description:
-            "File name including extension (e.g. 'screenshot.png'). Required with base64Data; defaults to the basename of filePath otherwise.",
+            "File name including extension (card_attachment: required with base64Data, else defaults to the filePath basename).",
+        },
+        title: {
+          type: "string",
+          description:
+            "Artifact display title (defaults to the file basename).",
         },
         contentType: {
           type: "string",
           description:
-            "Optional MIME type (e.g. 'image/png'). Inferred from the file extension when omitted.",
+            "Optional MIME type (card_attachment; inferred from the extension when omitted).",
         },
       },
-      required: ["cardId"],
+      required: ["target"],
     },
   },
-  harmony_request_card_attachment_upload_url: {
+  harmony_request_upload_url: {
     description:
-      "Step 1 of the large-file / hosted-MCP upload handshake (use when the server can't read local disk). Mints a one-shot signed Storage upload URL under the card. Returns { uploadUrl, token, storagePath, fileType }. Then PUT the raw bytes to uploadUrl (no bytes through the model context) and call harmony_finalize_card_attachment with storagePath. Max 5MB; same allowed types as harmony_upload_card_attachment.",
+      "Step 1 of the large-file / hosted-MCP upload handshake (use when the server can't read " +
+      'local disk). Mints a one-shot signed Storage upload URL. `target: "card_attachment"` ' +
+      '(requires cardId, fileName, size; max 5MB) or `target: "artifact"` (one of ' +
+      "cardId/planId/workspaceId; text/html, max 2MB). Returns { uploadUrl, token, storagePath, " +
+      "[fileType] }. Then PUT the raw bytes to uploadUrl (no bytes through the model context) and " +
+      "call harmony_finalize_upload with the storagePath.",
     inputSchema: {
       type: "object",
       properties: {
-        cardId: { type: "string", description: "Card UUID" },
-        fileName: {
+        target: {
           type: "string",
-          description: "File name including extension (e.g. 'screenshot.png').",
+          enum: ["card_attachment", "artifact"],
+          description:
+            "What to upload: a card file attachment or a hosted HTML artifact.",
         },
-        fileType: {
+        cardId: {
           type: "string",
           description:
-            "Optional MIME type (e.g. 'image/png'). Inferred from the file extension when omitted.",
-        },
-        size: {
-          type: "number",
-          description: "File size in bytes (rejected early if over 5MB).",
+            "Card UUID. Required for card_attachment; one of cardId/planId/workspaceId for artifact.",
         },
-      },
-      required: ["cardId", "fileName", "size"],
-    },
-  },
-  harmony_finalize_card_attachment: {
-    description:
-      "Step 2 of the upload handshake. After PUTting the bytes to the signed uploadUrl, call this with storagePath to validate and register the attachment. The server re-downloads the object and enforces size + an allowlisted content-type (magic-byte sniff, never the declared type) + an optional sha256 integrity check, deleting and failing on any mismatch. Returns the attachment + a signed URL.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        cardId: { type: "string", description: "Card UUID" },
-        storagePath: {
+        planId: { type: "string", description: "Plan UUID (artifact only)." },
+        workspaceId: {
           type: "string",
-          description:
-            "The storagePath returned by harmony_request_card_attachment_upload_url.",
+          description: "Workspace UUID (artifact only).",
         },
         fileName: {
           type: "string",
-          description: "File name including extension (e.g. 'screenshot.png').",
+          description:
+            "File name including extension (required for card_attachment).",
         },
+        title: { type: "string", description: "Artifact display title." },
         fileType: {
           type: "string",
           description:
-            "Optional MIME type; inferred from the extension when omitted.",
+            "card_attachment MIME type (inferred from the extension when omitted).",
         },
-        sha256: {
+        contentType: {
           type: "string",
           description:
-            "Optional hex SHA-256 of the uploaded bytes; verified against the stored object.",
+            "artifact MIME type; only 'text/html' is accepted (the default).",
         },
         size: {
           type: "number",
           description:
-            "Optional byte size (advisory; re-validated server-side).",
+            "File size in bytes (rejected early if over the target's limit).",
         },
       },
-      required: ["cardId", "storagePath", "fileName"],
-    },
-  },
-  harmony_classify_card: {
-    description:
-      "Classify a card with the LLM classifier: sets `intent` (plan/think/implement/review), `complexity_score` (0-10), `model_tier` (simple/advanced/research), stamps `classified_at`, and applies the type label (feature/bug/idea). Call right after creating a card to classify it in-flow. Idempotent; never touches the user-owned `model_override`.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        cardId: { type: "string", description: "Card UUID" },
-      },
-      required: ["cardId"],
+      required: ["target"],
     },
   },
-  harmony_upload_artifact: {
+  harmony_finalize_upload: {
     description:
-      "Host a self-contained HTML document (design draft, diagram) and link it to a card, plan, or workspace; rendered in-app in a sandboxed iframe. Provide exactly one of cardId/planId/workspaceId, and the HTML as `filePath` (local, direct-to-storage) or `base64Data` (small-file fallback). text/html only, max 2MB. Returns the artifact + a signed URL; use harmony_share_artifact for a public link. Large files on the hosted MCP server: use harmony_request_artifact_upload_url + harmony_finalize_artifact instead.",
+      "Step 2 of the upload handshake. After PUTting the bytes to the signed uploadUrl, call this " +
+      "with the storagePath to validate and register. The server re-downloads the object and " +
+      "enforces size + content-type (magic-byte sniff, never the declared type) + an optional " +
+      'sha256 integrity check, deleting and failing on any mismatch. `target: "card_attachment"` ' +
+      '(cardId, storagePath, fileName) or `target: "artifact"` (storagePath + the same one of ' +
+      "cardId/planId/workspaceId used for the upload URL). Returns the attachment/artifact + a signed URL.",
     inputSchema: {
       type: "object",
       properties: {
-        title: {
-          type: "string",
-          description: "Display title (defaults to the file basename).",
-        },
-        cardId: { type: "string", description: "Link to this card (UUID)." },
-        planId: { type: "string", description: "Link to this plan (UUID)." },
-        workspaceId: {
+        target: {
           type: "string",
+          enum: ["card_attachment", "artifact"],
           description:
-            "Attach to this workspace as a standalone artifact (UUID).",
+            "What to finalize: a card file attachment or a hosted HTML artifact.",
         },
-        filePath: {
-          type: "string",
-          description:
-            "Absolute path to a local .html file the MCP server process can read. Mutually exclusive with base64Data.",
-        },
-        base64Data: {
+        storagePath: {
           type: "string",
           description:
-            "Base64-encoded HTML bytes (a `data:` URL prefix is accepted and stripped). Mutually exclusive with filePath.",
+            "The storagePath returned by harmony_request_upload_url.",
         },
-      },
-      required: [],
-    },
-  },
-  harmony_request_artifact_upload_url: {
-    description:
-      "Step 1 of the large-file / hosted-MCP artifact upload handshake (use when the server can't read local disk). Mints a one-shot signed Storage upload URL. Provide exactly one of cardId/planId/workspaceId. Returns { uploadUrl, token, storagePath }. Then PUT the HTML bytes to uploadUrl and call harmony_finalize_artifact with storagePath. text/html only, max 2MB.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        title: {
+        cardId: {
           type: "string",
           description:
-            "Display title (defaults to the file basename at finalize).",
+            "Card UUID. Required for card_attachment; scope for artifact.",
         },
-        cardId: { type: "string", description: "Link to this card (UUID)." },
-        planId: { type: "string", description: "Link to this plan (UUID)." },
+        planId: { type: "string", description: "Plan UUID (artifact only)." },
         workspaceId: {
           type: "string",
-          description:
-            "Attach to this workspace as a standalone artifact (UUID).",
-        },
-        contentType: {
-          type: "string",
-          description: "MIME type; only 'text/html' is accepted (the default).",
-        },
-        size: {
-          type: "number",
-          description: "File size in bytes (rejected early if over 2MB).",
+          description: "Workspace UUID (artifact only).",
         },
-      },
-      required: [],
-    },
-  },
-  harmony_finalize_artifact: {
-    description:
-      "Step 2 of the artifact upload handshake. After PUTting the HTML bytes to the signed uploadUrl, call this with storagePath to validate and register the artifact. The server re-downloads the object and enforces size + text/html (magic-byte sniff) + an optional sha256 integrity check, deleting and failing on any mismatch. Pass the same one of cardId/planId/workspaceId used for the upload URL. Returns the artifact + a signed URL; use harmony_share_artifact for a public link.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        storagePath: {
+        fileName: {
           type: "string",
           description:
-            "The storagePath returned by harmony_request_artifact_upload_url.",
+            "File name including extension (required for card_attachment).",
         },
-        title: { type: "string", description: "Display title." },
-        cardId: { type: "string", description: "Link to this card (UUID)." },
-        planId: { type: "string", description: "Link to this plan (UUID)." },
-        workspaceId: {
+        title: { type: "string", description: "Artifact display title." },
+        fileType: {
           type: "string",
           description:
-            "Attach to this workspace as a standalone artifact (UUID).",
+            "card_attachment MIME type; inferred from the extension when omitted.",
         },
         sha256: {
           type: "string",
@@ -1029,7 +1053,18 @@ export const TOOLS = {
             "Optional byte size (advisory; re-validated server-side).",
         },
       },
-      required: ["storagePath"],
+      required: ["target", "storagePath"],
+    },
+  },
+  harmony_classify_card: {
+    description:
+      "Classify a card with the LLM classifier: sets `intent` (plan/think/implement/review), `complexity_score` (0-10), `model_tier` (simple/advanced/research), stamps `classified_at`, and applies the type label (feature/bug/idea). Call right after creating a card to classify it in-flow. Idempotent; never touches the user-owned `model_override`.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string", description: "Card UUID" },
+      },
+      required: ["cardId"],
     },
   },
   harmony_share_artifact: {
@@ -1062,6 +1097,28 @@ export const TOOLS = {
       required: ["cardId"],
     },
   },
+  harmony_add_external_link: {
+    description:
+      "Attach an external reference URL (e.g. a PR/MR link, doc, or dashboard) to a card. Durable — survives description edits. Use this in addition to writing the PR link into the description.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: {
+          type: "string",
+          description: "Card UUID",
+        },
+        url: {
+          type: "string",
+          description: "The URL to attach",
+        },
+        title: {
+          type: "string",
+          description: "Optional human-readable title for the link",
+        },
+      },
+      required: ["cardId", "url"],
+    },
+  },
 
   // Subtask operations
   harmony_create_subtask: {
@@ -1119,7 +1176,7 @@ export const TOOLS = {
   // Comment operations
   harmony_add_comment: {
     description:
-      "Post a comment on a card as the agent — converse with the human in the open: report progress, ask a question, record a decision, or note a finding, instead of editing the card description. Set supersedesId to correct an earlier comment, confirmsId to reaffirm one.",
+      "Post a comment on a card as the agent — converse with the human in the open: report progress, ask a question, record a decision, or note a finding, instead of editing the card description. Set supersedesId to correct an earlier comment, confirmsId to reaffirm one. To answer an open question, reply to it with replyToId.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1147,6 +1204,11 @@ export const TOOLS = {
           type: "string",
           description: "Comment id this comment reaffirms",
         },
+        replyToId: {
+          type: "string",
+          description:
+            "Comment id this is a one-level reply to. To answer an open question, reply to it. If you also set supersedesId/confirmsId, it must equal replyToId.",
+        },
       },
       required: ["cardId", "body"],
     },
@@ -2101,7 +2163,7 @@ export const TOOLS = {
 
   harmony_list_playbook: {
     description:
-      "List a workspace's playbooks (reusable process definitions). Returns each playbook's name, version, steps_version, and state. Read-only.",
+      "List a workspace's playbooks (reusable process definitions). Returns each playbook's name, version, and state. Read-only.",
     inputSchema: {
       type: "object",
       properties: {
@@ -2126,24 +2188,9 @@ export const TOOLS = {
     },
   },
 
-  harmony_run_playbook: {
-    description:
-      "Run a playbook server-side and return the finalized run. Only legacy automation playbooks (steps_version 1) are runnable; stage playbooks (steps_version 2) are rejected. The server drives every step to completion.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        playbookId: {
-          type: "string",
-          description: "Playbook ID to run (UUID)",
-        },
-      },
-      required: ["playbookId"],
-    },
-  },
-
   harmony_create_playbook: {
     description:
-      "Create a new playbook in a workspace. Default steps_version 1 is a legacy automation macro (an array of tool steps); steps_version 2 is the Method stage model (an array of stage objects).",
+      "Create a new playbook (a reusable process definition) in a workspace. A playbook is an ordered set of stages bound to board columns, run by people and the agent daemon as a card moves through them.",
     inputSchema: {
       type: "object",
       properties: {
@@ -2153,16 +2200,9 @@ export const TOOLS = {
         },
         name: { type: "string", description: "Playbook name" },
         description: { type: "string", description: "Playbook description" },
-        stepsVersion: {
-          type: "number",
-          enum: [1, 2],
-          description:
-            "1 = automation macro (tool steps), 2 = Method stage model (stage objects). Default 1.",
-        },
         steps: {
           type: "array",
-          description:
-            "Steps (steps_version 1: tool-step objects) or stages (steps_version 2: stage objects).",
+          description: "The playbook's ordered stage objects.",
           items: { type: "object" },
         },
       },
@@ -2184,7 +2224,7 @@ export const TOOLS = {
         description: { type: "string", description: "New description" },
         steps: {
           type: "array",
-          description: "New steps (v1) or stages (v2) array.",
+          description: "New ordered stage objects.",
           items: { type: "object" },
         },
         enabled: {
@@ -2201,22 +2241,6 @@ export const TOOLS = {
     },
   },
 
-  harmony_save_card_as_playbook: {
-    description:
-      "Save an existing card as a new steps_version 1 (automation) playbook, seeding one create-card step from the card. Returns the created playbook.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        cardId: { type: "string", description: "Card ID to template (UUID)" },
-        name: {
-          type: "string",
-          description: "Name for the new playbook (defaults to the card title)",
-        },
-      },
-      required: ["cardId"],
-    },
-  },
-
   // ============ ONBOARDING TOOLS ============
   harmony_signup: {
     description:
@@ -2807,30 +2831,41 @@ async function handleToolCall(
       return { success: true, ...result, count: result.cards.length };
     }
 
+    // Unified card fetch (#605): cardId (full) | shortId (full) | shortIds (compact).
+    // Old names dispatch here too, behind the deprecation shim.
+    case "harmony_get_card_by_short_id":
+    case "harmony_bulk_get_cards":
     case "harmony_get_card": {
+      if (name !== "harmony_get_card") warnDeprecatedTool(name);
+      const hasShortIds = args.shortIds != null;
+      const hasShortId = args.shortId != null;
+      const hasCardId = args.cardId != null;
+      if ([hasShortIds, hasShortId, hasCardId].filter(Boolean).length !== 1) {
+        throw new Error(
+          "Provide exactly one of: cardId (UUID), shortId (number), or shortIds (number[]).",
+        );
+      }
+      if (hasShortIds) {
+        const shortIds = z
+          .array(z.number().int().positive())
+          .min(1)
+          .max(100)
+          .parse(args.shortIds);
+        const projectId = getProjectId();
+        const result = await client.bulkGetCards(projectId, shortIds);
+        return { success: true, ...result };
+      }
+      if (hasShortId) {
+        const shortId = z.number().int().positive().parse(args.shortId);
+        const projectId = (args.projectId as string) || getProjectId();
+        const result = await client.getCardByShortId(projectId, shortId);
+        return { success: true, ...result };
+      }
       const cardId = z.string().uuid().parse(args.cardId);
       const result = await client.getCard(cardId);
       return { success: true, ...result };
     }
 
-    case "harmony_get_card_by_short_id": {
-      const shortId = z.number().int().positive().parse(args.shortId);
-      const projectId = (args.projectId as string) || getProjectId();
-      const result = await client.getCardByShortId(projectId, shortId);
-      return { success: true, ...result };
-    }
-
-    case "harmony_bulk_get_cards": {
-      const shortIds = z
-        .array(z.number().int().positive())
-        .min(1)
-        .max(100)
-        .parse(args.shortIds);
-      const projectId = getProjectId();
-      const result = await client.bulkGetCards(projectId, shortIds);
-      return { success: true, ...result };
-    }
-
     case "harmony_bulk_archive_cards": {
       const shortIds = z
         .array(z.number().int().positive())
@@ -2978,71 +3013,85 @@ async function handleToolCall(
       return result;
     }
 
-    case "harmony_upload_card_attachment": {
-      const cardId = z.string().uuid().parse(args.cardId);
+    // Unified upload (#605): target = card_attachment | artifact. Old names
+    // (harmony_upload_artifact / harmony_upload_card_attachment) dispatch here
+    // behind the deprecation shim; target is inferred from the old name.
+    case "harmony_upload_card_attachment":
+    case "harmony_upload_artifact":
+    case "harmony_upload": {
+      if (name !== "harmony_upload") warnDeprecatedTool(name);
+      const target =
+        name === "harmony_upload_card_attachment"
+          ? "card_attachment"
+          : name === "harmony_upload_artifact"
+            ? "artifact"
+            : z.enum(["card_attachment", "artifact"]).parse(args.target);
+
       const filePath =
         args.filePath != null ? z.string().parse(args.filePath) : undefined;
       const base64Data =
         args.base64Data != null ? z.string().parse(args.base64Data) : undefined;
-      const fileName =
-        args.fileName != null ? z.string().parse(args.fileName) : undefined;
-      const contentType =
-        args.contentType != null
-          ? z.string().parse(args.contentType)
-          : undefined;
-
       if (filePath && base64Data) {
         throw new Error("Provide either filePath or base64Data, not both.");
       }
 
-      if (filePath) {
-        // Server can read the file → upload direct-to-storage via the handshake
-        // (no base64 through the model context or the edge-fn JSON body).
-        const bytes = await readFileForUpload(
-          filePath,
-          MAX_ATTACHMENT_SIZE,
-          "attachment",
-        );
-        const resolvedName = fileName || basename(filePath);
-        const signed = await client.requestCardAttachmentUploadUrl(cardId, {
-          fileName: resolvedName,
-          fileType: contentType,
-          size: bytes.byteLength,
-        });
-        await putToSignedUrl(
-          signed.uploadUrl,
-          bytes,
-          contentType || signed.fileType || "application/octet-stream",
-        );
-        return await client.finalizeCardAttachment(cardId, {
-          storagePath: signed.storagePath,
-          fileName: resolvedName,
-          fileType: contentType || signed.fileType,
-          sha256: sha256Hex(bytes),
-          size: bytes.byteLength,
-        });
-      }
-
-      if (base64Data) {
-        if (!fileName) {
-          throw new Error("fileName is required when using base64Data.");
-        }
-        if (base64ByteLength(base64Data) > MAX_ATTACHMENT_SIZE) {
-          throw new Error(
-            `File is over the 5MB attachment limit. Use the harmony_request_card_attachment_upload_url + harmony_finalize_card_attachment handshake for large files.`,
+      if (target === "card_attachment") {
+        const cardId = z.string().uuid().parse(args.cardId);
+        const fileName =
+          args.fileName != null ? z.string().parse(args.fileName) : undefined;
+        const contentType =
+          args.contentType != null
+            ? z.string().parse(args.contentType)
+            : undefined;
+
+        if (filePath) {
+          // Server can read the file → upload direct-to-storage via the
+          // handshake (no base64 through the model context or edge-fn body).
+          const bytes = await readFileForUpload(
+            filePath,
+            MAX_ATTACHMENT_SIZE,
+            "attachment",
+          );
+          const resolvedName = fileName || basename(filePath);
+          const signed = await client.requestCardAttachmentUploadUrl(cardId, {
+            fileName: resolvedName,
+            fileType: contentType,
+            size: bytes.byteLength,
+          });
+          await putToSignedUrl(
+            signed.uploadUrl,
+            bytes,
+            contentType || signed.fileType || "application/octet-stream",
           );
+          return await client.finalizeCardAttachment(cardId, {
+            storagePath: signed.storagePath,
+            fileName: resolvedName,
+            fileType: contentType || signed.fileType,
+            sha256: sha256Hex(bytes),
+            size: bytes.byteLength,
+          });
         }
-        return await client.uploadCardAttachment(cardId, {
-          fileName,
-          data: base64Data,
-          fileType: contentType,
-        });
-      }
 
-      throw new Error("Provide either filePath or base64Data.");
-    }
+        if (base64Data) {
+          if (!fileName) {
+            throw new Error("fileName is required when using base64Data.");
+          }
+          if (base64ByteLength(base64Data) > MAX_ATTACHMENT_SIZE) {
+            throw new Error(
+              `File is over the 5MB attachment limit. Use the harmony_request_upload_url + harmony_finalize_upload handshake for large files.`,
+            );
+          }
+          return await client.uploadCardAttachment(cardId, {
+            fileName,
+            data: base64Data,
+            fileType: contentType,
+          });
+        }
+
+        throw new Error("Provide either filePath or base64Data.");
+      }
 
-    case "harmony_upload_artifact": {
+      // target === "artifact"
       const title =
         args.title != null ? z.string().parse(args.title) : undefined;
       const cardId =
@@ -3055,17 +3104,7 @@ async function handleToolCall(
           : undefined;
       requireExactlyOneScope({ cardId, planId, workspaceId });
 
-      const filePath =
-        args.filePath != null ? z.string().parse(args.filePath) : undefined;
-      const base64Data =
-        args.base64Data != null ? z.string().parse(args.base64Data) : undefined;
-      if (filePath && base64Data) {
-        throw new Error("Provide either filePath or base64Data, not both.");
-      }
-
       if (filePath) {
-        // Server can read the file → upload direct-to-storage via the handshake
-        // (no base64 through the model context or the edge-fn JSON body).
         const bytes = await readFileForUpload(
           filePath,
           MAX_ARTIFACT_SIZE,
@@ -3095,7 +3134,7 @@ async function handleToolCall(
       if (base64Data) {
         if (base64ByteLength(base64Data) > MAX_ARTIFACT_SIZE) {
           throw new Error(
-            `Artifact is over the 2MB limit. Use the harmony_request_artifact_upload_url + harmony_finalize_artifact handshake for large files.`,
+            `Artifact is over the 2MB limit. Use the harmony_request_upload_url + harmony_finalize_upload handshake for large files.`,
           );
         }
         return await client.uploadArtifact({
@@ -3110,7 +3149,37 @@ async function handleToolCall(
       throw new Error("Provide either filePath or base64Data.");
     }
 
-    case "harmony_request_artifact_upload_url": {
+    // Unified upload handshake step 1 (#605). Old names shimmed; target inferred.
+    case "harmony_request_artifact_upload_url":
+    case "harmony_request_card_attachment_upload_url":
+    case "harmony_request_upload_url": {
+      if (name !== "harmony_request_upload_url") warnDeprecatedTool(name);
+      const target =
+        name === "harmony_request_card_attachment_upload_url"
+          ? "card_attachment"
+          : name === "harmony_request_artifact_upload_url"
+            ? "artifact"
+            : z.enum(["card_attachment", "artifact"]).parse(args.target);
+
+      if (target === "card_attachment") {
+        const cardId = z.string().uuid().parse(args.cardId);
+        const fileName = z.string().parse(args.fileName);
+        const fileType =
+          args.fileType != null ? z.string().parse(args.fileType) : undefined;
+        const size = z.number().positive().parse(args.size);
+        if (size > MAX_ATTACHMENT_SIZE) {
+          throw new Error(
+            `Declared size ${size} bytes is over the ${MAX_ATTACHMENT_SIZE}-byte (5MB) attachment limit.`,
+          );
+        }
+        return await client.requestCardAttachmentUploadUrl(cardId, {
+          fileName,
+          fileType,
+          size,
+        });
+      }
+
+      // target === "artifact"
       const title =
         args.title != null ? z.string().parse(args.title) : undefined;
       const cardId =
@@ -3143,8 +3212,40 @@ async function handleToolCall(
       });
     }
 
-    case "harmony_finalize_artifact": {
+    // Unified upload handshake step 2 (#605). Old names shimmed; target inferred.
+    case "harmony_finalize_artifact":
+    case "harmony_finalize_card_attachment":
+    case "harmony_finalize_upload": {
+      if (name !== "harmony_finalize_upload") warnDeprecatedTool(name);
+      const target =
+        name === "harmony_finalize_card_attachment"
+          ? "card_attachment"
+          : name === "harmony_finalize_artifact"
+            ? "artifact"
+            : z.enum(["card_attachment", "artifact"]).parse(args.target);
       const storagePath = z.string().parse(args.storagePath);
+
+      if (target === "card_attachment") {
+        const cardId = z.string().uuid().parse(args.cardId);
+        const fileName = z.string().parse(args.fileName);
+        const fileType =
+          args.fileType != null ? z.string().parse(args.fileType) : undefined;
+        const sha256 =
+          args.sha256 != null ? z.string().parse(args.sha256) : undefined;
+        const size =
+          args.size != null
+            ? z.number().positive().parse(args.size)
+            : undefined;
+        return await client.finalizeCardAttachment(cardId, {
+          storagePath,
+          fileName,
+          fileType,
+          sha256,
+          size,
+        });
+      }
+
+      // target === "artifact"
       const title =
         args.title != null ? z.string().parse(args.title) : undefined;
       const cardId =
@@ -3171,43 +3272,6 @@ async function handleToolCall(
       });
     }
 
-    case "harmony_request_card_attachment_upload_url": {
-      const cardId = z.string().uuid().parse(args.cardId);
-      const fileName = z.string().parse(args.fileName);
-      const fileType =
-        args.fileType != null ? z.string().parse(args.fileType) : undefined;
-      const size = z.number().positive().parse(args.size);
-      if (size > MAX_ATTACHMENT_SIZE) {
-        throw new Error(
-          `Declared size ${size} bytes is over the ${MAX_ATTACHMENT_SIZE}-byte (5MB) attachment limit.`,
-        );
-      }
-      return await client.requestCardAttachmentUploadUrl(cardId, {
-        fileName,
-        fileType,
-        size,
-      });
-    }
-
-    case "harmony_finalize_card_attachment": {
-      const cardId = z.string().uuid().parse(args.cardId);
-      const storagePath = z.string().parse(args.storagePath);
-      const fileName = z.string().parse(args.fileName);
-      const fileType =
-        args.fileType != null ? z.string().parse(args.fileType) : undefined;
-      const sha256 =
-        args.sha256 != null ? z.string().parse(args.sha256) : undefined;
-      const size =
-        args.size != null ? z.number().positive().parse(args.size) : undefined;
-      return await client.finalizeCardAttachment(cardId, {
-        storagePath,
-        fileName,
-        fileType,
-        sha256,
-        size,
-      });
-    }
-
     case "harmony_share_artifact": {
       const artifactId = z.string().uuid().parse(args.artifactId);
       const expiresInDays =
@@ -3230,6 +3294,16 @@ async function handleToolCall(
       return result;
     }
 
+    case "harmony_add_external_link": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const url = z.string().min(1).max(2048).parse(args.url);
+      const title = args.title
+        ? z.string().max(200).parse(args.title)
+        : undefined;
+      const result = await client.addExternalLink(cardId, url, title);
+      return { success: true, ...result };
+    }
+
     case "harmony_classify_card": {
       const cardId = z.string().uuid().parse(args.cardId);
       const result = await client.classifyCard(cardId);
@@ -3307,10 +3381,15 @@ async function handleToolCall(
         args.confirmsId !== undefined
           ? z.string().uuid().parse(args.confirmsId)
           : undefined;
+      const replyToId =
+        args.replyToId !== undefined
+          ? z.string().uuid().parse(args.replyToId)
+          : undefined;
       const result = await client.addComment(cardId, body, {
         commentType,
         supersedesId,
         confirmsId,
+        replyToId,
       });
       return { success: true, ...result };
     }
@@ -3606,15 +3685,24 @@ async function handleToolCall(
         .map((a) => a.description)
         .filter((d): d is string => typeof d === "string" && d.length > 0);
 
+      const reportedStatus = args.status as
+        | "working"
+        | "blocked"
+        | "waiting"
+        | "paused"
+        | undefined;
+
+      // Keep the auto-session heartbeat in step with the agent's own status
+      // reports: `paused`/`blocked`/`waiting` stop the 60s heartbeat (intentional
+      // non-heartbeat states), a later `working` resumes it (card #608).
+      if (reportedStatus) {
+        noteSessionStatus(cardId, reportedStatus, deps.getScopeId?.());
+      }
+
       const result = await client.updateAgentProgress(cardId, {
         agentIdentifier,
         agentName,
-        status: args.status as
-          | "working"
-          | "blocked"
-          | "waiting"
-          | "paused"
-          | undefined,
+        status: reportedStatus,
         progressPercent,
         currentTask: args.currentTask as string | undefined,
         blockers: args.blockers as string[] | undefined,
@@ -4717,25 +4805,19 @@ async function handleToolCall(
       return { success: true, playbook: result.playbook, runs: result.runs };
     }
 
-    case "harmony_run_playbook": {
-      const playbookId = z.string().uuid().parse(args.playbookId);
-      const result = await client.runPlaybook(playbookId);
-      return { success: true, run: result.run };
-    }
+    // Deprecated (#612) — dropped from the advertised TOOLS list; the case
+    // remains so an old caller gets a legible notice, not an unknown-tool error.
+    case "harmony_run_playbook":
+      return deprecatedRemovedToolResult("harmony_run_playbook");
 
     case "harmony_create_playbook": {
       const workspaceId = (args.workspaceId as string) || getWorkspaceId();
       const name = z.string().min(1).max(200).parse(args.name);
-      const stepsVersion =
-        args.stepsVersion !== undefined
-          ? z.union([z.literal(1), z.literal(2)]).parse(args.stepsVersion)
-          : undefined;
       const result = await client.createPlaybook({
         workspaceId,
         name,
         description: args.description as string | undefined,
         steps: args.steps,
-        stepsVersion,
       });
       return { success: true, playbook: result.playbook };
     }
@@ -4752,14 +4834,9 @@ async function handleToolCall(
       return { success: true, playbook: result.playbook };
     }
 
-    case "harmony_save_card_as_playbook": {
-      const cardId = z.string().uuid().parse(args.cardId);
-      const result = await client.savePlaybookFromCard({
-        cardId,
-        name: args.name as string | undefined,
-      });
-      return { success: true, playbook: result.playbook };
-    }
+    // Deprecated (#612) — see harmony_run_playbook above.
+    case "harmony_save_card_as_playbook":
+      return deprecatedRemovedToolResult("harmony_save_card_as_playbook");
 
     // ============ ONBOARDING TOOLS ============
     case "harmony_signup": {