@gethmy/mcp 2.13.4 → 2.15.0

package/dist/cli.js

@@ -1457,6 +1457,8 @@ function serializeCommentThread(comments, options = {}) {
     const tags = [];
     if (c.edited_at)
       tags.push("edited");
+    if (c.reply_to_id)
+      tags.push(`reply to ${ref(c.reply_to_id)}`);
     if (c.supersedes_id)
       tags.push(`supersedes ${ref(c.supersedes_id)}`);
     if (c.confirms_id)
@@ -1791,6 +1793,33 @@ class HarmonyApiClient {
     const query = params.toString() ? `?${params.toString()}` : "";
     return this.request("GET", `/board/${projectId}${query}`);
   }
+  async getFullBoard(projectId, options) {
+    const { pageSize = 200, ...boardOpts } = options ?? {};
+    const cards = [];
+    let offset = 0;
+    let last = null;
+    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
+    };
+  }
   async createCard(projectId, data) {
     return this.request("POST", "/cards", { projectId, ...data });
   }
@@ -1868,6 +1897,12 @@ class HarmonyApiClient {
   async getCardExternalLinks(cardId) {
     return this.request("GET", `/cards/${cardId}/external-links`);
   }
+  async addExternalLink(cardId, url, title) {
+    return this.request("POST", `/cards/${cardId}/external-links`, {
+      url,
+      title
+    });
+  }
   async uploadArtifact(data) {
     return this.request("POST", "/artifacts", data);
   }
@@ -1919,6 +1954,7 @@ class HarmonyApiClient {
       commentType: opts?.commentType,
       supersedesId: opts?.supersedesId,
       confirmsId: opts?.confirmsId,
+      replyToId: opts?.replyToId,
       agentSessionId: opts?.agentSessionId
     });
   }
@@ -2371,12 +2407,6 @@ ${planContent.trim()}`;
   async updatePlaybook(playbookId, updates) {
     return this.request("PATCH", `/playbooks/${playbookId}`, updates);
   }
-  async runPlaybook(playbookId) {
-    return this.request("POST", `/playbooks/${playbookId}/run`);
-  }
-  async savePlaybookFromCard(data) {
-    return this.request("POST", "/playbooks/from-card", data);
-  }
 }
 var _promptModules = null;
 async function loadPromptModules() {
@@ -2457,7 +2487,7 @@ function initAutoSession(callback, getClient2, getClientInfo, scopeId = DEFAULT_
   scope.clientGetter = getClient2;
   scope.clientInfoGetter = getClientInfo ?? null;
   if (!inactivityTimer) {
-    inactivityTimer = setInterval(checkInactivity, CHECK_INTERVAL_MS);
+    inactivityTimer = setInterval(sweepTick, CHECK_INTERVAL_MS);
   }
 }
 async function trackActivity(cardId, options) {
@@ -2499,7 +2529,8 @@ async function trackActivity(cardId, options) {
     lastActivityAt: now,
     isExplicit: false,
     agentIdentifier,
-    agentName
+    agentName,
+    status: "working"
   });
 }
 function markExplicit(cardId, options) {
@@ -2518,7 +2549,8 @@ function markExplicit(cardId, options) {
       lastActivityAt: Date.now(),
       isExplicit: true,
       agentIdentifier: options?.agentIdentifier ?? "explicit",
-      agentName: options?.agentName ?? "Explicit Agent"
+      agentName: options?.agentName ?? "Explicit Agent",
+      status: "working"
     });
   }
 }
@@ -2564,6 +2596,31 @@ function checkInactivity() {
     }
   }
 }
+function noteSessionStatus(cardId, status, scopeId = DEFAULT_SCOPE) {
+  const session = scopes.get(scopeId)?.sessions.get(cardId);
+  if (session)
+    session.status = status;
+}
+function heartbeatActiveSessions() {
+  for (const scope of scopes.values()) {
+    const client3 = scope.clientGetter?.();
+    if (!client3)
+      continue;
+    for (const session of scope.sessions.values()) {
+      if ((session.status ?? "working") !== "working")
+        continue;
+      client3.updateAgentProgress(session.cardId, {
+        agentIdentifier: session.agentIdentifier,
+        agentName: session.agentName,
+        status: "working"
+      }).catch(() => {});
+    }
+  }
+}
+function sweepTick() {
+  checkInactivity();
+  heartbeatActiveSessions();
+}
 async function autoEndSession(scope, client3, cardId, status) {
   if (!scope.sessions.delete(cardId))
     return;
@@ -3240,7 +3297,7 @@ Start work on a Harmony card. Card reference: $ARGUMENTS
 ## 1. Find & Fetch Card
 
 Parse the reference and fetch the card:
-- \`#42\` or \`42\` → \`harmony_get_card_by_short_id\` with \`shortId: 42\`
+- \`#42\` or \`42\` → \`harmony_get_card\` with \`shortId: 42\`
 - UUID → \`harmony_get_card\` with \`cardId\`
 - Name/text → \`harmony_search_cards\` with \`query\`
 
@@ -3294,7 +3351,7 @@ If pausing: \`harmony_end_agent_session\` with \`status: "paused"\`
 
 ## Key Tools Reference
 
-**Cards:** \`harmony_get_card\`, \`harmony_get_card_by_short_id\`, \`harmony_search_cards\`, \`harmony_create_card\`, \`harmony_update_card\`, \`harmony_move_card\`, \`harmony_delete_card\`, \`harmony_assign_card\`
+**Cards:** \`harmony_get_card\` (by \`cardId\`, \`shortId\`, or \`shortIds\`), \`harmony_search_cards\`, \`harmony_create_card\`, \`harmony_update_card\`, \`harmony_move_card\`, \`harmony_delete_card\`, \`harmony_assign_card\`
 
 **Subtasks:** \`harmony_create_subtask\`, \`harmony_toggle_subtask\`, \`harmony_delete_subtask\`
 
@@ -3488,6 +3545,37 @@ function requireExactlyOneScope(scope) {
     throw new Error("Provide exactly one of cardId, planId, or workspaceId.");
   }
 }
+var DEPRECATED_TOOL_ALIASES = {
+  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"
+};
+var _warnedDeprecatedTools = new Set;
+function warnDeprecatedTool(oldName) {
+  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.`);
+}
+var DEPRECATED_REMOVED_TOOLS = {
+  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."
+};
+var _warnedRemovedTools = new Set;
+function deprecatedRemovedToolResult(name) {
+  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 };
+}
 var SIGNED_UPLOAD_TIMEOUT_MS = 30000;
 async function putToSignedUrl(uploadUrl, bytes, contentType) {
   let res;
@@ -3815,44 +3903,29 @@ var 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)"
-        }
-      },
-      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: {
+          description: "Short ID (e.g. 42 for card #42) — full detail, project-scoped."
+        },
         shortIds: {
           type: "array",
           items: { type: "number" },
-          description: "Card short ids, e.g. [400, 401, 402]. Max 100 per call."
+          description: "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: {
@@ -4007,174 +4080,144 @@ var TOOLS = {
       required: ["cardId"]
     }
   },
-  harmony_upload_card_attachment: {
-    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.",
+  harmony_upload: {
+    description: '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."
+          description: "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."
+          description: "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."
+          description: "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."
+          description: "Optional MIME type (card_attachment; inferred from the extension when omitted)."
         }
       },
-      required: ["cardId"]
+      required: ["target"]
     }
   },
-  harmony_request_card_attachment_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.",
+  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. `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."
+          description: "Card UUID. Required for card_attachment; one of cardId/planId/workspaceId for artifact."
         },
-        size: {
-          type: "number",
-          description: "File size in bytes (rejected early if over 5MB)."
-        }
-      },
-      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."
+          description: "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."
+          description: "artifact MIME type; only 'text/html' is accepted (the default)."
         },
         size: {
           type: "number",
-          description: "Optional byte size (advisory; re-validated server-side)."
+          description: "File size in bytes (rejected early if over the target's limit)."
         }
       },
-      required: ["cardId", "storagePath", "fileName"]
+      required: ["target"]
     }
   },
-  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`.",
+  harmony_finalize_upload: {
+    description: "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: {
-        cardId: { type: "string", description: "Card UUID" }
-      },
-      required: ["cardId"]
-    }
-  },
-  harmony_upload_artifact: {
-    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.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        title: {
+        target: {
           type: "string",
-          description: "Display title (defaults to the file basename)."
+          enum: ["card_attachment", "artifact"],
+          description: "What to finalize: a card file attachment or a hosted HTML artifact."
         },
-        cardId: { type: "string", description: "Link to this card (UUID)." },
-        planId: { type: "string", description: "Link to this plan (UUID)." },
-        workspaceId: {
+        storagePath: {
           type: "string",
-          description: "Attach to this workspace as a standalone artifact (UUID)."
+          description: "The storagePath returned by harmony_request_upload_url."
         },
-        filePath: {
+        cardId: {
           type: "string",
-          description: "Absolute path to a local .html file the MCP server process can read. Mutually exclusive with base64Data."
+          description: "Card UUID. Required for card_attachment; scope for artifact."
         },
-        base64Data: {
+        planId: { type: "string", description: "Plan UUID (artifact only)." },
+        workspaceId: {
           type: "string",
-          description: "Base64-encoded HTML bytes (a `data:` URL prefix is accepted and stripped). Mutually exclusive with filePath."
-        }
-      },
-      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: {
+          description: "Workspace UUID (artifact only)."
+        },
+        fileName: {
           type: "string",
-          description: "Display title (defaults to the file basename at finalize)."
+          description: "File name including extension (required for card_attachment)."
         },
-        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)."
+          description: "card_attachment MIME type; inferred from the extension when omitted."
         },
-        contentType: {
+        sha256: {
           type: "string",
-          description: "MIME type; only 'text/html' is accepted (the default)."
+          description: "Optional hex SHA-256 of the uploaded bytes; verified against the stored object."
         },
         size: {
           type: "number",
-          description: "File size in bytes (rejected early if over 2MB)."
+          description: "Optional byte size (advisory; re-validated server-side)."
         }
       },
-      required: []
+      required: ["target", "storagePath"]
     }
   },
-  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.",
+  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: {
-        storagePath: {
-          type: "string",
-          description: "The storagePath returned by harmony_request_artifact_upload_url."
-        },
-        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: {
-          type: "string",
-          description: "Attach to this workspace as a standalone artifact (UUID)."
-        },
-        sha256: {
-          type: "string",
-          description: "Optional hex SHA-256 of the uploaded bytes; verified against the stored object."
-        },
-        size: {
-          type: "number",
-          description: "Optional byte size (advisory; re-validated server-side)."
-        }
+        cardId: { type: "string", description: "Card UUID" }
       },
-      required: ["storagePath"]
+      required: ["cardId"]
     }
   },
   harmony_share_artifact: {
@@ -4204,6 +4247,27 @@ var 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"]
+    }
+  },
   harmony_create_subtask: {
     description: "Create a subtask on a card",
     inputSchema: {
@@ -4255,7 +4319,7 @@ var TOOLS = {
     }
   },
   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.",
+    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. To answer an open question, reply to it with replyToId.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4281,6 +4345,10 @@ var TOOLS = {
         confirmsId: {
           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"]
@@ -5151,7 +5219,7 @@ var 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.",
+    description: "List a workspace's playbooks (reusable process definitions). Returns each playbook's name, version, and state. Read-only.",
     inputSchema: {
       type: "object",
       properties: {
@@ -5173,21 +5241,8 @@ var TOOLS = {
       required: ["playbookId"]
     }
   },
-  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).",
+    description: "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: {
@@ -5197,14 +5252,9 @@ var 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" }
         }
       },
@@ -5224,7 +5274,7 @@ var 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: {
@@ -5240,20 +5290,6 @@ var TOOLS = {
       required: ["playbookId"]
     }
   },
-  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"]
-    }
-  },
   harmony_signup: {
     description: "Create a new user account. Returns a JWT session for subsequent authenticated calls. No API key required.",
     inputSchema: {
@@ -5653,23 +5689,33 @@ async function handleToolCall(name, args, deps) {
       });
       return { success: true, ...result, count: result.cards.length };
     }
+    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 result2 = await client3.bulkGetCards(projectId, shortIds);
+        return { success: true, ...result2 };
+      }
+      if (hasShortId) {
+        const shortId = z.number().int().positive().parse(args.shortId);
+        const projectId = args.projectId || getProjectId();
+        const result2 = await client3.getCardByShortId(projectId, shortId);
+        return { success: true, ...result2 };
+      }
       const cardId = z.string().uuid().parse(args.cardId);
       const result = await client3.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 || getProjectId();
-      const result = await client3.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 client3.bulkGetCards(projectId, shortIds);
-      return { success: true, ...result };
-    }
     case "harmony_bulk_archive_cards": {
       const shortIds = z.array(z.number().int().positive()).min(1).max(100).parse(args.shortIds);
       const projectId = getProjectId();
@@ -5769,58 +5815,58 @@ async function handleToolCall(name, args, deps) {
       const result = await client3.getCardAttachments(cardId);
       return result;
     }
-    case "harmony_upload_card_attachment": {
-      const cardId = z.string().uuid().parse(args.cardId);
+    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) {
-        const bytes = await readFileForUpload(filePath, MAX_ATTACHMENT_SIZE, "attachment");
-        const resolvedName = fileName || basename(filePath);
-        const signed = await client3.requestCardAttachmentUploadUrl(cardId, {
-          fileName: resolvedName,
-          fileType: contentType,
-          size: bytes.byteLength
-        });
-        await putToSignedUrl(signed.uploadUrl, bytes, contentType || signed.fileType || "application/octet-stream");
-        return await client3.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 (target === "card_attachment") {
+        const cardId2 = 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) {
+          const bytes = await readFileForUpload(filePath, MAX_ATTACHMENT_SIZE, "attachment");
+          const resolvedName = fileName || basename(filePath);
+          const signed = await client3.requestCardAttachmentUploadUrl(cardId2, {
+            fileName: resolvedName,
+            fileType: contentType,
+            size: bytes.byteLength
+          });
+          await putToSignedUrl(signed.uploadUrl, bytes, contentType || signed.fileType || "application/octet-stream");
+          return await client3.finalizeCardAttachment(cardId2, {
+            storagePath: signed.storagePath,
+            fileName: resolvedName,
+            fileType: contentType || signed.fileType,
+            sha256: sha256Hex(bytes),
+            size: bytes.byteLength
+          });
         }
-        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 (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 client3.uploadCardAttachment(cardId2, {
+            fileName,
+            data: base64Data,
+            fileType: contentType
+          });
         }
-        return await client3.uploadCardAttachment(cardId, {
-          fileName,
-          data: base64Data,
-          fileType: contentType
-        });
+        throw new Error("Provide either filePath or base64Data.");
       }
-      throw new Error("Provide either filePath or base64Data.");
-    }
-    case "harmony_upload_artifact": {
       const title = args.title != null ? z.string().parse(args.title) : undefined;
       const cardId = args.cardId != null ? z.string().uuid().parse(args.cardId) : undefined;
       const planId = args.planId != null ? z.string().uuid().parse(args.planId) : undefined;
       const workspaceId = args.workspaceId != null ? z.string().uuid().parse(args.workspaceId) : 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) {
         const bytes = await readFileForUpload(filePath, MAX_ARTIFACT_SIZE, "artifact");
         const resolvedTitle = title || basename(filePath);
@@ -5845,7 +5891,7 @@ async function handleToolCall(name, args, deps) {
       }
       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.`);
+          throw new Error(`Artifact is over the 2MB limit. Use the harmony_request_upload_url + harmony_finalize_upload handshake for large files.`);
         }
         return await client3.uploadArtifact({
           title,
@@ -5857,7 +5903,26 @@ async function handleToolCall(name, args, deps) {
       }
       throw new Error("Provide either filePath or base64Data.");
     }
-    case "harmony_request_artifact_upload_url": {
+    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 cardId2 = 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 size2 = z.number().positive().parse(args.size);
+        if (size2 > MAX_ATTACHMENT_SIZE) {
+          throw new Error(`Declared size ${size2} bytes is over the ${MAX_ATTACHMENT_SIZE}-byte (5MB) attachment limit.`);
+        }
+        return await client3.requestCardAttachmentUploadUrl(cardId2, {
+          fileName,
+          fileType,
+          size: size2
+        });
+      }
       const title = args.title != null ? z.string().parse(args.title) : undefined;
       const cardId = args.cardId != null ? z.string().uuid().parse(args.cardId) : undefined;
       const planId = args.planId != null ? z.string().uuid().parse(args.planId) : undefined;
@@ -5877,8 +5942,27 @@ async function handleToolCall(name, args, deps) {
         size
       });
     }
-    case "harmony_finalize_artifact": {
+    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 cardId2 = 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 sha2562 = args.sha256 != null ? z.string().parse(args.sha256) : undefined;
+        const size2 = args.size != null ? z.number().positive().parse(args.size) : undefined;
+        return await client3.finalizeCardAttachment(cardId2, {
+          storagePath,
+          fileName,
+          fileType,
+          sha256: sha2562,
+          size: size2
+        });
+      }
       const title = args.title != null ? z.string().parse(args.title) : undefined;
       const cardId = args.cardId != null ? z.string().uuid().parse(args.cardId) : undefined;
       const planId = args.planId != null ? z.string().uuid().parse(args.planId) : undefined;
@@ -5896,35 +5980,6 @@ async function handleToolCall(name, args, deps) {
         workspaceId
       });
     }
-    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 client3.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 client3.finalizeCardAttachment(cardId, {
-        storagePath,
-        fileName,
-        fileType,
-        sha256,
-        size
-      });
-    }
     case "harmony_share_artifact": {
       const artifactId = z.string().uuid().parse(args.artifactId);
       const expiresInDays = args.expiresInDays != null ? z.number().positive().parse(args.expiresInDays) : undefined;
@@ -5937,6 +5992,13 @@ async function handleToolCall(name, args, deps) {
       const result = await client3.getCardExternalLinks(cardId);
       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 client3.addExternalLink(cardId, url, title);
+      return { success: true, ...result };
+    }
     case "harmony_classify_card": {
       const cardId = z.string().uuid().parse(args.cardId);
       const result = await client3.classifyCard(cardId);
@@ -5990,10 +6052,12 @@ async function handleToolCall(name, args, deps) {
       ]).parse(args.commentType) : undefined;
       const supersedesId = args.supersedesId !== undefined ? z.string().uuid().parse(args.supersedesId) : undefined;
       const confirmsId = 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 client3.addComment(cardId, body, {
         commentType,
         supersedesId,
-        confirmsId
+        confirmsId,
+        replyToId
       });
       return { success: true, ...result };
     }
@@ -6193,10 +6257,14 @@ async function handleToolCall(name, args, deps) {
         mergedRecentActions = callerRecentActions;
       }
       const runActivity = (callerActions || []).map((a) => a.description).filter((d) => typeof d === "string" && d.length > 0);
+      const reportedStatus = args.status;
+      if (reportedStatus) {
+        noteSessionStatus(cardId, reportedStatus, deps.getScopeId?.());
+      }
       const result = await client3.updateAgentProgress(cardId, {
         agentIdentifier,
         agentName,
-        status: args.status,
+        status: reportedStatus,
         progressPercent,
         currentTask: args.currentTask,
         blockers: args.blockers,
@@ -6853,21 +6921,16 @@ async function handleToolCall(name, args, deps) {
       const result = await client3.getPlaybook(playbookId);
       return { success: true, playbook: result.playbook, runs: result.runs };
     }
-    case "harmony_run_playbook": {
-      const playbookId = z.string().uuid().parse(args.playbookId);
-      const result = await client3.runPlaybook(playbookId);
-      return { success: true, run: result.run };
-    }
+    case "harmony_run_playbook":
+      return deprecatedRemovedToolResult("harmony_run_playbook");
     case "harmony_create_playbook": {
       const workspaceId = args.workspaceId || getWorkspaceId();
       const name2 = 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 client3.createPlaybook({
         workspaceId,
         name: name2,
         description: args.description,
-        steps: args.steps,
-        stepsVersion
+        steps: args.steps
       });
       return { success: true, playbook: result.playbook };
     }
@@ -6882,14 +6945,8 @@ async function handleToolCall(name, args, deps) {
       });
       return { success: true, playbook: result.playbook };
     }
-    case "harmony_save_card_as_playbook": {
-      const cardId = z.string().uuid().parse(args.cardId);
-      const result = await client3.savePlaybookFromCard({
-        cardId,
-        name: args.name
-      });
-      return { success: true, playbook: result.playbook };
-    }
+    case "harmony_save_card_as_playbook":
+      return deprecatedRemovedToolResult("harmony_save_card_as_playbook");
     case "harmony_signup": {
       const email = z.string().email().max(254).parse(args.email);
       const password = z.string().min(8).max(128).parse(args.password);