@gethmy/mcp 2.12.0 → 2.13.1

package/dist/index.js

@@ -985,6 +985,7 @@ var init_oauth_refresh = __esm(() => {
 });
 
 // src/server.ts
+import { createHash as createHash4 } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { basename } from "node:path";
 // ../memory/dist/sync.js
@@ -1491,6 +1492,9 @@ var TIMINGS = {
   QUERY_STALE_TIME: 1000 * 60 * 5,
   QUERY_GC_TIME: 1000 * 60 * 60 * 24
 };
+// ../harmony-shared/dist/stageHandoff.js
+var HANDOFF_MARKER = "harmony:stage-handoff";
+var HANDOFF_BLOCK_RE = new RegExp("```json\\s*\\n//\\s*" + HANDOFF_MARKER + "\\s*\\n([\\s\\S]*?)\\n```", "m");
 // src/api-client.ts
 init_config();
 var RETRY_CONFIG = {
@@ -1850,12 +1854,24 @@ class HarmonyApiClient {
   async uploadCardAttachment(cardId, data) {
     return this.request("POST", `/cards/${cardId}/attachments`, data);
   }
+  async requestCardAttachmentUploadUrl(cardId, data) {
+    return this.request("POST", `/cards/${cardId}/attachment-upload-url`, data);
+  }
+  async finalizeCardAttachment(cardId, data) {
+    return this.request("POST", `/cards/${cardId}/attachments/finalize`, data);
+  }
   async getCardExternalLinks(cardId) {
     return this.request("GET", `/cards/${cardId}/external-links`);
   }
   async uploadArtifact(data) {
     return this.request("POST", "/artifacts", data);
   }
+  async requestArtifactUploadUrl(data) {
+    return this.request("POST", "/artifacts/upload-url", data);
+  }
+  async finalizeArtifact(data) {
+    return this.request("POST", "/artifacts/finalize", data);
+  }
   async createArtifactShareLink(artifactId, expiresAt) {
     return this.request("POST", `/artifacts/${artifactId}/share`, {
       expires_at: expiresAt
@@ -2333,6 +2349,12 @@ ${planContent.trim()}`;
   async getPlaybook(playbookId) {
     return this.request("GET", `/playbooks/${playbookId}`);
   }
+  async getPlaybookVersion(playbookId, version) {
+    return this.request("GET", `/playbooks/${encodeURIComponent(playbookId)}/versions/${version}`);
+  }
+  async recordStageGateEvidence(insert) {
+    return this.request("POST", `/cards/${encodeURIComponent(insert.card_id)}/stage-gate-evidence`, insert);
+  }
   async createPlaybook(data) {
     return this.request("POST", "/playbooks", data);
   }
@@ -3431,6 +3453,52 @@ async function refreshSkills(opts = {}) {
 }
 
 // src/server.ts
+var MAX_ARTIFACT_SIZE = 2 * 1024 * 1024;
+var MAX_ATTACHMENT_SIZE = 5 * 1024 * 1024;
+function base64ByteLength(base64) {
+  const stripped = base64.replace(/^data:[^,]*,/, "");
+  return Buffer.from(stripped, "base64").byteLength;
+}
+function sha256Hex(bytes) {
+  return createHash4("sha256").update(bytes).digest("hex");
+}
+async function readFileForUpload(filePath, maxSize, kind) {
+  const bytes = await readFile(filePath);
+  if (bytes.byteLength === 0) {
+    throw new Error(`File is empty: ${filePath}`);
+  }
+  if (bytes.byteLength > maxSize) {
+    const mb = Math.round(maxSize / (1024 * 1024));
+    throw new Error(`File is ${bytes.byteLength} bytes, over the ${maxSize}-byte (${mb}MB) ${kind} limit.`);
+  }
+  return bytes;
+}
+function requireExactlyOneScope(scope) {
+  if ([scope.cardId, scope.planId, scope.workspaceId].filter(Boolean).length !== 1) {
+    throw new Error("Provide exactly one of cardId, planId, or workspaceId.");
+  }
+}
+var SIGNED_UPLOAD_TIMEOUT_MS = 30000;
+async function putToSignedUrl(uploadUrl, bytes, contentType) {
+  let res;
+  try {
+    res = await fetch(uploadUrl, {
+      method: "PUT",
+      headers: { "Content-Type": contentType },
+      body: bytes,
+      signal: AbortSignal.timeout(SIGNED_UPLOAD_TIMEOUT_MS)
+    });
+  } catch (err) {
+    if (err instanceof DOMException && err.name === "TimeoutError") {
+      throw new Error(`Direct storage upload timed out after ${SIGNED_UPLOAD_TIMEOUT_MS}ms.`);
+    }
+    throw err;
+  }
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    throw new Error(`Direct storage upload failed: ${res.status}${detail ? ` — ${detail}` : ""}`);
+  }
+}
 var memorySessions = new Map;
 function parseLabelList(raw) {
   if (raw === undefined || raw === null)
@@ -3456,6 +3524,45 @@ function parseLabelList(raw) {
   }
   return;
 }
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function requireStringArg(raw, field, opts = {}) {
+  let value;
+  if (typeof raw === "string")
+    value = raw.trim();
+  else if (typeof raw === "number" || typeof raw === "boolean")
+    value = String(raw);
+  else
+    throw new Error(`${field} is required and must be a string (received ${raw === undefined || raw === null ? "nothing" : typeof raw}).`);
+  if (value.length === 0)
+    throw new Error(`${field} is required and must not be empty.`);
+  if (opts.max && value.length > opts.max)
+    throw new Error(`${field} must be at most ${opts.max} characters (received ${value.length}).`);
+  return value;
+}
+function requireUuidArg(raw, field) {
+  const value = requireStringArg(raw, field);
+  if (!UUID_RE.test(value))
+    throw new Error(`${field} must be a valid UUID (received "${value}").`);
+  return value;
+}
+function optionalPercentArg(raw, field) {
+  if (raw === undefined || raw === null)
+    return;
+  const n = typeof raw === "number" ? raw : Number(raw);
+  if (!Number.isFinite(n))
+    throw new Error(`${field} must be a number between 0 and 100.`);
+  if (n < 0 || n > 100)
+    throw new Error(`${field} must be between 0 and 100 (received ${n}).`);
+  return n;
+}
+function optionalNonNegativeNumberArg(raw, field) {
+  if (raw === undefined || raw === null)
+    return;
+  const n = typeof raw === "number" ? raw : Number(raw);
+  if (!Number.isFinite(n) || n < 0)
+    throw new Error(`${field} must be a non-negative number.`);
+  return n;
+}
 function initMemorySession(cardId, agentIdentifier, agentName, agentSessionId) {
   memorySessions.set(cardId, {
     cardId,
@@ -3891,7 +3998,7 @@ var TOOLS = {
     }
   },
   harmony_upload_card_attachment: {
-    description: "Upload a file attachment to a card (e.g. a pasted screenshot or a document). Provide the file either as `filePath` (a local path the MCP server can read — works in local/stdio mode) or as `base64Data` (raw base64 bytes — works everywhere, including remote mode). Max 5MB. Allowed: PNG, JPEG, GIF, WebP, HEIC/HEIF, PDF, DOC/DOCX, XLS/XLSX, TXT, CSV. Returns the stored attachment with a short-lived signed URL.",
+    description: "Upload a file attachment to a card (e.g. a pasted screenshot or a document). Provide the file either as `filePath` (a local path the MCP server can read — works in local/stdio mode) or as `base64Data` (raw base64 bytes — works everywhere, including remote mode). With `filePath` the server uploads direct-to-storage (no base64 through the model context); `base64Data` is the small-file fallback. Max 5MB. Allowed: PNG, JPEG, GIF, WebP, HEIC/HEIF, PDF, DOC/DOCX, XLS/XLSX, TXT, CSV. Returns the stored attachment with a short-lived signed URL. For large files on the hosted MCP server (where only base64Data works), prefer the two-step harmony_request_card_attachment_upload_url + harmony_finalize_card_attachment handshake, which keeps bytes out of the model context.",
     inputSchema: {
       type: "object",
       properties: {
@@ -3916,6 +4023,58 @@ var TOOLS = {
       required: ["cardId"]
     }
   },
+  harmony_request_card_attachment_upload_url: {
+    description: "Step 1 of the agent-driven card-attachment upload — use this for large files or when running against the hosted MCP server (which cannot read your local disk). Mints a one-shot signed Supabase Storage upload URL for a server-chosen path under the card. Provide cardId, fileName (with extension), the byte size, and optionally fileType. Returns { uploadUrl, token, storagePath, fileType }. Next: PUT the raw bytes straight to uploadUrl (e.g. `curl -X PUT --data-binary @file.png '<uploadUrl>'`) — no bytes pass through the model context — then call harmony_finalize_card_attachment with the returned storagePath. Max 5MB; allowed: PNG, JPEG, GIF, WebP, HEIC/HEIF, PDF, DOC/DOCX, XLS/XLSX, TXT, CSV.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string", description: "Card UUID" },
+        fileName: {
+          type: "string",
+          description: "File name including extension (e.g. 'screenshot.png')."
+        },
+        fileType: {
+          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)."
+        }
+      },
+      required: ["cardId", "fileName", "size"]
+    }
+  },
+  harmony_finalize_card_attachment: {
+    description: "Step 2 of the agent-driven card-attachment upload. After PUTting the bytes to the signed uploadUrl from harmony_request_card_attachment_upload_url, call this with the returned 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), and — when you pass sha256 — an integrity check, deleting the object and failing on any mismatch. Returns the stored attachment with a short-lived signed URL.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string", description: "Card UUID" },
+        storagePath: {
+          type: "string",
+          description: "The storagePath returned by harmony_request_card_attachment_upload_url."
+        },
+        fileName: {
+          type: "string",
+          description: "File name including extension (e.g. 'screenshot.png')."
+        },
+        fileType: {
+          type: "string",
+          description: "Optional MIME type; inferred from the extension when omitted."
+        },
+        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)."
+        }
+      },
+      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), and `model_tier` (simple/advanced/research), stamps `classified_at`, and applies the canonical type label (feature/bug/idea). Use this right after creating a card (e.g. in the `hmy-new` flow) so it's classified in-flow instead of waiting for it to surface on the web board. Idempotent — safe to re-run. Never touches the user-owned `model_override`.",
     inputSchema: {
@@ -3927,7 +4086,7 @@ var TOOLS = {
     }
   },
   harmony_upload_artifact: {
-    description: "Host a self-contained HTML document (e.g. a visual design draft or diagram) in Harmony and link it to a card, a plan, or a workspace. The file is stored privately and rendered in-app inside a sandboxed cross-origin iframe. Provide exactly one of cardId, planId, or workspaceId. Supply the HTML as `filePath` (a local path the MCP server can read) or `base64Data`. Only text/html, max 2MB. Returns the stored artifact with a short-lived signed URL; call harmony_share_artifact to mint a public link.",
+    description: "Host a self-contained HTML document (e.g. a visual design draft or diagram) in Harmony and link it to a card, a plan, or a workspace. The file is stored privately and rendered in-app inside a sandboxed cross-origin iframe. Provide exactly one of cardId, planId, or workspaceId. Supply the HTML as `filePath` (a local path the MCP server can read — uploaded direct-to-storage, no base64 through the model context) or `base64Data` (the small-file fallback). Only text/html, max 2MB. Returns the stored artifact with a short-lived signed URL; call harmony_share_artifact to mint a public link. For large files on the hosted MCP server (where only base64Data works), prefer the two-step harmony_request_artifact_upload_url + harmony_finalize_artifact handshake, which keeps bytes out of the model context.",
     inputSchema: {
       type: "object",
       properties: {
@@ -3953,6 +4112,61 @@ var TOOLS = {
       required: []
     }
   },
+  harmony_request_artifact_upload_url: {
+    description: "Step 1 of the agent-driven artifact upload — use this for large files or when running against the hosted MCP server (which cannot read your local disk), instead of streaming base64 through the model context. Mints a one-shot signed Supabase Storage upload URL for a server-chosen path. Provide exactly one of cardId/planId/workspaceId, optionally a title and the byte size. Returns { uploadUrl, token, storagePath }. Next: PUT the raw HTML bytes straight to uploadUrl (e.g. `curl -X PUT --data-binary @doc.html '<uploadUrl>'`), then call harmony_finalize_artifact with the returned storagePath. Only text/html, max 2MB.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: {
+          type: "string",
+          description: "Display title (defaults to the file basename at finalize)."
+        },
+        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)."
+        },
+        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)."
+        }
+      },
+      required: []
+    }
+  },
+  harmony_finalize_artifact: {
+    description: "Step 2 of the agent-driven artifact upload. After PUTting the HTML bytes to the signed uploadUrl from harmony_request_artifact_upload_url, call this with the returned storagePath to validate and register the artifact. The server re-downloads the object and enforces size, the text/html content-type (magic-byte sniff), and — when you pass sha256 — an integrity check, deleting the object and failing on any mismatch. Provide the same one of cardId/planId/workspaceId used for the upload URL. Returns the stored artifact with a short-lived signed URL; call harmony_share_artifact to mint a public link.",
+    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)."
+        }
+      },
+      required: ["storagePath"]
+    }
+  },
   harmony_share_artifact: {
     description: "Create a public, unauthenticated share link for a hosted artifact. Anyone with the link can view the rendered HTML without a Harmony account. Returns the share token and the full public URL.",
     inputSchema: {
@@ -5196,7 +5410,6 @@ function registerHandlers(server, deps) {
     const { name, arguments: args } = request.params;
     const toolArgs = args || {};
     const cardIdArg = toolArgs.cardId;
-    const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
     if (cardIdArg && UUID_RE.test(cardIdArg) && deps.isConfigured()) {
       const isAutoStartTrigger = AUTO_START_TRIGGERS.has(name);
       const cv = server.getClientVersion?.();
@@ -5550,70 +5763,157 @@ async function handleToolCall(name, args, deps) {
       const cardId = z.string().uuid().parse(args.cardId);
       const filePath = args.filePath != null ? z.string().parse(args.filePath) : undefined;
       const base64Data = args.base64Data != null ? z.string().parse(args.base64Data) : undefined;
-      let fileName = args.fileName != null ? z.string().parse(args.fileName) : 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.");
       }
-      let data;
       if (filePath) {
-        const bytes = await readFile(filePath);
-        if (bytes.byteLength === 0) {
-          throw new Error(`File is empty: ${filePath}`);
-        }
-        data = bytes.toString("base64");
-        fileName = fileName || basename(filePath);
-      } else if (base64Data) {
+        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.");
         }
-        data = base64Data;
-      } else {
-        throw new Error("Provide either filePath or 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.`);
+        }
+        return await client3.uploadCardAttachment(cardId, {
+          fileName,
+          data: base64Data,
+          fileType: contentType
+        });
       }
-      const result = await client3.uploadCardAttachment(cardId, {
-        fileName,
-        data,
-        fileType: contentType
-      });
-      return result;
+      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;
-      const anchors = [cardId, planId, workspaceId].filter(Boolean);
-      if (anchors.length !== 1) {
-        throw new Error("Provide exactly one of cardId, planId, or workspaceId.");
-      }
+      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.");
       }
-      let data;
-      let inferredTitle = title;
       if (filePath) {
-        const bytes = await readFile(filePath);
-        if (bytes.byteLength === 0) {
-          throw new Error(`File is empty: ${filePath}`);
+        const bytes = await readFileForUpload(filePath, MAX_ARTIFACT_SIZE, "artifact");
+        const resolvedTitle = title || basename(filePath);
+        const signed = await client3.requestArtifactUploadUrl({
+          title: resolvedTitle,
+          cardId,
+          planId,
+          workspaceId,
+          contentType: "text/html",
+          size: bytes.byteLength
+        });
+        await putToSignedUrl(signed.uploadUrl, bytes, "text/html");
+        return await client3.finalizeArtifact({
+          storagePath: signed.storagePath,
+          sha256: sha256Hex(bytes),
+          size: bytes.byteLength,
+          title: resolvedTitle,
+          cardId,
+          planId,
+          workspaceId
+        });
+      }
+      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.`);
         }
-        data = bytes.toString("base64");
-        inferredTitle = inferredTitle || basename(filePath);
-      } else if (base64Data) {
-        data = base64Data;
-      } else {
-        throw new Error("Provide either filePath or base64Data.");
+        return await client3.uploadArtifact({
+          title,
+          cardId,
+          planId,
+          workspaceId,
+          data: base64Data
+        });
       }
-      const result = await client3.uploadArtifact({
-        title: inferredTitle,
+      throw new Error("Provide either filePath or base64Data.");
+    }
+    case "harmony_request_artifact_upload_url": {
+      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 contentType = args.contentType != null ? z.string().parse(args.contentType) : undefined;
+      const size = args.size != null ? z.number().positive().parse(args.size) : undefined;
+      if (size != null && size > MAX_ARTIFACT_SIZE) {
+        throw new Error(`Declared size ${size} bytes is over the ${MAX_ARTIFACT_SIZE}-byte (2MB) artifact limit.`);
+      }
+      return await client3.requestArtifactUploadUrl({
+        title,
         cardId,
         planId,
         workspaceId,
-        data
+        contentType,
+        size
+      });
+    }
+    case "harmony_finalize_artifact": {
+      const storagePath = z.string().parse(args.storagePath);
+      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 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.finalizeArtifact({
+        storagePath,
+        sha256,
+        size,
+        title,
+        cardId,
+        planId,
+        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
       });
-      return result;
     }
     case "harmony_share_artifact": {
       const artifactId = z.string().uuid().parse(args.artifactId);
@@ -5775,9 +6075,11 @@ async function handleToolCall(name, args, deps) {
       return { success: true, ...result };
     }
     case "harmony_start_agent_session": {
-      const cardId = z.string().uuid().parse(args.cardId);
-      const agentIdentifier = z.string().min(1).max(100).parse(args.agentIdentifier);
-      const agentName = z.string().min(1).max(100).parse(args.agentName);
+      const cardId = requireUuidArg(args.cardId, "cardId");
+      const agentIdentifier = requireStringArg(args.agentIdentifier, "agentIdentifier", { max: 100 });
+      const agentName = requireStringArg(args.agentName, "agentName", {
+        max: 100
+      });
       const moveToColumn = args.moveToColumn;
       const addLabels = parseLabelList(args.addLabels);
       let movedTo = null;
@@ -5838,7 +6140,7 @@ async function handleToolCall(name, args, deps) {
         agentName,
         status: "working",
         currentTask: args.currentTask,
-        estimatedMinutesRemaining: args.estimatedMinutesRemaining,
+        estimatedMinutesRemaining: optionalNonNegativeNumberArg(args.estimatedMinutesRemaining, "estimatedMinutesRemaining"),
         steerable: args.steerable === true || args.steerable === "true" ? true : undefined
       });
       markExplicit(cardId, {
@@ -5858,10 +6160,12 @@ async function handleToolCall(name, args, deps) {
       };
     }
     case "harmony_update_agent_progress": {
-      const cardId = z.string().uuid().parse(args.cardId);
-      const agentIdentifier = z.string().min(1).max(100).parse(args.agentIdentifier);
-      const agentName = z.string().min(1).max(100).parse(args.agentName);
-      const progressPercent = args.progressPercent !== undefined ? z.number().min(0).max(100).parse(args.progressPercent) : undefined;
+      const cardId = requireUuidArg(args.cardId, "cardId");
+      const agentIdentifier = requireStringArg(args.agentIdentifier, "agentIdentifier", { max: 100 });
+      const agentName = requireStringArg(args.agentName, "agentName", {
+        max: 100
+      });
+      const progressPercent = optionalPercentArg(args.progressPercent, "progressPercent");
       const callerActions = args.actions;
       const now = new Date().toISOString();
       const callerRecentActions = [
@@ -5886,17 +6190,17 @@ async function handleToolCall(name, args, deps) {
         progressPercent,
         currentTask: args.currentTask,
         blockers: args.blockers,
-        estimatedMinutesRemaining: args.estimatedMinutesRemaining,
+        estimatedMinutesRemaining: optionalNonNegativeNumberArg(args.estimatedMinutesRemaining, "estimatedMinutesRemaining"),
         ...mergedRecentActions && { recentActions: mergedRecentActions },
         ...runActivity.length > 0 && { runActivity }
       });
       return { success: true, midSessionLearnings: 0, ...result };
     }
     case "harmony_end_agent_session": {
-      const cardId = z.string().uuid().parse(args.cardId);
+      const cardId = requireUuidArg(args.cardId, "cardId");
       const moveToColumn = args.moveToColumn;
       const sessionStatus = args.status || "completed";
-      const endProgressPercent = args.progressPercent !== undefined ? z.number().min(0).max(100).parse(args.progressPercent) : undefined;
+      const endProgressPercent = optionalPercentArg(args.progressPercent, "progressPercent");
       await flushMemoryActions(client3, cardId);
       cleanupMemorySession(cardId);
       let result = { session: null };

package/dist/lib/api-client.js

@@ -944,6 +944,9 @@ var TIMINGS = {
   QUERY_STALE_TIME: 1000 * 60 * 5,
   QUERY_GC_TIME: 1000 * 60 * 60 * 24
 };
+// ../harmony-shared/dist/stageHandoff.js
+var HANDOFF_MARKER = "harmony:stage-handoff";
+var HANDOFF_BLOCK_RE = new RegExp("```json\\s*\\n//\\s*" + HANDOFF_MARKER + "\\s*\\n([\\s\\S]*?)\\n```", "m");
 // src/api-client.ts
 init_config();
 var RETRY_CONFIG = {
@@ -1303,12 +1306,24 @@ class HarmonyApiClient {
   async uploadCardAttachment(cardId, data) {
     return this.request("POST", `/cards/${cardId}/attachments`, data);
   }
+  async requestCardAttachmentUploadUrl(cardId, data) {
+    return this.request("POST", `/cards/${cardId}/attachment-upload-url`, data);
+  }
+  async finalizeCardAttachment(cardId, data) {
+    return this.request("POST", `/cards/${cardId}/attachments/finalize`, data);
+  }
   async getCardExternalLinks(cardId) {
     return this.request("GET", `/cards/${cardId}/external-links`);
   }
   async uploadArtifact(data) {
     return this.request("POST", "/artifacts", data);
   }
+  async requestArtifactUploadUrl(data) {
+    return this.request("POST", "/artifacts/upload-url", data);
+  }
+  async finalizeArtifact(data) {
+    return this.request("POST", "/artifacts/finalize", data);
+  }
   async createArtifactShareLink(artifactId, expiresAt) {
     return this.request("POST", `/artifacts/${artifactId}/share`, {
       expires_at: expiresAt
@@ -1786,6 +1801,12 @@ ${planContent.trim()}`;
   async getPlaybook(playbookId) {
     return this.request("GET", `/playbooks/${playbookId}`);
   }
+  async getPlaybookVersion(playbookId, version) {
+    return this.request("GET", `/playbooks/${encodeURIComponent(playbookId)}/versions/${version}`);
+  }
+  async recordStageGateEvidence(insert) {
+    return this.request("POST", `/cards/${encodeURIComponent(insert.card_id)}/stage-gate-evidence`, insert);
+  }
   async createPlaybook(data) {
     return this.request("POST", "/playbooks", data);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.12.0",
+  "version": "2.13.1",
   "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
   "publishConfig": {
     "access": "public"