@gethmy/mcp 2.12.0 → 2.13.0

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)
@@ -3891,7 +3959,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 +3984,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 +4047,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 +4073,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: {
@@ -5550,70 +5725,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);

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.0",
   "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
   "publishConfig": {
     "access": "public"

package/src/api-client.ts

@@ -2,6 +2,9 @@ import {
   type AgentRunEventDraft,
   type Comment,
   getDisplayLinkType,
+  type PlaybookVersionDef,
+  type StageGateEvidenceInsert,
+  type StageGateEvidenceRow,
   serializeCommentThread,
   type WorkspaceAgent,
 } from "@harmony/shared";
@@ -143,6 +146,15 @@ export interface CardAttachment {
   signed_url_expires_in: number;
 }
 
+/** Response of a `*-upload-url` endpoint: a one-shot signed Supabase Storage
+ * URL the caller PUTs raw bytes to, plus the service-chosen path that the
+ * matching `finalize` call validates and registers. */
+export interface SignedUpload {
+  uploadUrl: string;
+  token: string;
+  storagePath: string;
+}
+
 export interface CardExternalLinkRow {
   id: string;
   card_id: string;
@@ -675,6 +687,32 @@ export class HarmonyApiClient {
     return this.request("POST", `/cards/${cardId}/attachments`, data);
   }
 
+  // Step 1 of the direct-to-storage attachment handshake: mint a signed upload
+  // URL for a server-chosen path under the card. The caller PUTs raw bytes to
+  // `uploadUrl`, then calls finalizeCardAttachment with the returned storagePath.
+  async requestCardAttachmentUploadUrl(
+    cardId: string,
+    data: { fileName: string; fileType?: string; size: number },
+  ): Promise<SignedUpload & { fileType: string }> {
+    return this.request("POST", `/cards/${cardId}/attachment-upload-url`, data);
+  }
+
+  // Step 2: validate the uploaded object (size + magic-byte content-type +
+  // optional sha256) and insert the attachment row. The server deletes the
+  // object and rejects on any mismatch.
+  async finalizeCardAttachment(
+    cardId: string,
+    data: {
+      storagePath: string;
+      fileName: string;
+      fileType?: string;
+      sha256?: string;
+      size?: number;
+    },
+  ): Promise<{ attachment: CardAttachment }> {
+    return this.request("POST", `/cards/${cardId}/attachments/finalize`, data);
+  }
+
   async getCardExternalLinks(
     cardId: string,
   ): Promise<{ external_links: CardExternalLinkRow[] }> {
@@ -694,6 +732,35 @@ export class HarmonyApiClient {
     return this.request("POST", "/artifacts", data);
   }
 
+  // Step 1 of the direct-to-storage artifact handshake: mint a signed upload
+  // URL for a server-chosen path. The caller PUTs raw HTML bytes to `uploadUrl`,
+  // then calls finalizeArtifact with the returned storagePath.
+  async requestArtifactUploadUrl(data: {
+    title?: string;
+    cardId?: string;
+    planId?: string;
+    workspaceId?: string;
+    contentType?: string;
+    size?: number;
+  }): Promise<SignedUpload> {
+    return this.request("POST", "/artifacts/upload-url", data);
+  }
+
+  // Step 2: validate the uploaded object (size + HTML magic-byte sniff +
+  // optional sha256) and insert the artifact row. The server deletes the
+  // object and rejects on any mismatch.
+  async finalizeArtifact(data: {
+    storagePath: string;
+    sha256?: string;
+    size?: number;
+    title?: string;
+    cardId?: string;
+    planId?: string;
+    workspaceId?: string;
+  }): Promise<{ artifact: Record<string, unknown> }> {
+    return this.request("POST", "/artifacts/finalize", data);
+  }
+
   async createArtifactShareLink(
     artifactId: string,
     expiresAt?: string,
@@ -1747,6 +1814,40 @@ export class HarmonyApiClient {
     return this.request("GET", `/playbooks/${playbookId}`);
   }
 
+  /**
+   * Fetch the pinned, immutable stage-def snapshot for `(playbookId, version)`.
+   * The agent daemon's stage executor (#514) resolves a card's `current_stage`
+   * against this frozen def — never live `playbooks.steps` — so editing a
+   * Playbook never rewrites an in-flight card.
+   */
+  async getPlaybookVersion(
+    playbookId: string,
+    version: number,
+  ): Promise<{
+    version: PlaybookVersionDef & { playbook_id: string; version: number };
+  }> {
+    return this.request(
+      "GET",
+      `/playbooks/${encodeURIComponent(playbookId)}/versions/${version}`,
+    );
+  }
+
+  /**
+   * Persist a stage gate evidence row (Playbooks P1 #3, card #516). The daemon
+   * collects + evaluates a gate then POSTs the resulting evidence here; the edge
+   * writes it with the service-role client (the table has no INSERT RLS policy,
+   * so this is the only write path). Returns the inserted row.
+   */
+  async recordStageGateEvidence(
+    insert: StageGateEvidenceInsert,
+  ): Promise<{ evidence: StageGateEvidenceRow }> {
+    return this.request(
+      "POST",
+      `/cards/${encodeURIComponent(insert.card_id)}/stage-gate-evidence`,
+      insert,
+    );
+  }
+
   async createPlaybook(data: {
     workspaceId: string;
     name: string;