@gethmy/mcp 2.11.2 → 2.13.0

package/src/server.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { basename } from "node:path";
 import { syncFull, syncPull, syncPush } from "@harmony/memory";
@@ -67,6 +68,99 @@ import { lintTags, normalizeTags } from "./memory-tags.js";
 import { onboardNewUser } from "./onboard.js";
 import { stripSkillPreamble } from "./skills.js";
 
+// --- Signed-upload handshake (artifacts & card attachments) ---
+// Mirror the edge-fn caps so a too-large `filePath`/`base64Data` fails fast in
+// the client instead of being read fully into memory and round-tripped only to
+// be rejected server-side (closes the #345 "no size pre-check" finding). The
+// finalize endpoint re-enforces these as the real security boundary.
+const MAX_ARTIFACT_SIZE = 2 * 1024 * 1024; // 2 MB — keep in sync with harmony-api
+const MAX_ATTACHMENT_SIZE = 5 * 1024 * 1024; // 5 MB — keep in sync with harmony-api
+
+/** Decoded byte length of a base64 string, tolerating a leading `data:` URL
+ * prefix (the edge fn strips it; we strip a copy only to measure). */
+function base64ByteLength(base64: string): number {
+  const stripped = base64.replace(/^data:[^,]*,/, "");
+  return Buffer.from(stripped, "base64").byteLength;
+}
+
+function sha256Hex(bytes: Buffer): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+/** Read a local file for a direct-to-storage upload, rejecting empty and
+ * over-cap before any network round-trip. `kind` shapes the error copy. */
+async function readFileForUpload(
+  filePath: string,
+  maxSize: number,
+  kind: "attachment" | "artifact",
+): Promise<Buffer> {
+  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;
+}
+
+/** Enforce the exactly-one-of-scope rule shared by the artifact upload,
+ * upload-url, and finalize tools. */
+function requireExactlyOneScope(scope: {
+  cardId?: string;
+  planId?: string;
+  workspaceId?: string;
+}): void {
+  if (
+    [scope.cardId, scope.planId, scope.workspaceId].filter(Boolean).length !== 1
+  ) {
+    throw new Error("Provide exactly one of cardId, planId, or workspaceId.");
+  }
+}
+
+/** PUT raw bytes straight to a Supabase signed upload URL (the token rides in
+ * the URL query). Used by the stdio internal handshake; the hosted server can't
+ * read local disk, so there the agent drives this PUT itself via the two-step
+ * tools. */
+const SIGNED_UPLOAD_TIMEOUT_MS = 30_000;
+
+async function putToSignedUrl(
+  uploadUrl: string,
+  bytes: Uint8Array,
+  contentType: string,
+): Promise<void> {
+  let res: Response;
+  try {
+    res = await fetch(uploadUrl, {
+      method: "PUT",
+      headers: { "Content-Type": contentType },
+      // Cast around the TS 5.7 lib regression where the now-generic
+      // `Uint8Array<ArrayBufferLike>` no longer matches `BodyInit`'s
+      // `ArrayBuffer`-pinned `BufferSource`. The bytes are a valid fetch body.
+      body: bytes as unknown as BodyInit,
+      // Bound the upload so a stalled storage PUT can't hang the call
+      // indefinitely (there is no watchdog at this layer).
+      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}` : ""}`,
+    );
+  }
+}
+
 /**
  * Dependencies injected into tool handlers.
  * Allows the same handlers to be used by both stdio and remote (HTTP) transports.
@@ -665,7 +759,7 @@ export const 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.",
+      "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: {
@@ -694,6 +788,65 @@ export const 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`.",
@@ -705,6 +858,116 @@ export const TOOLS = {
       required: ["cardId"],
     },
   },
+  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 — 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: {
+        title: {
+          type: "string",
+          description: "Display title (defaults to the file basename).",
+        },
+        cardId: { type: "string", description: "Link to this card (UUID)." },
+        planId: { type: "string", description: "Link to this plan (UUID)." },
+        workspaceId: {
+          type: "string",
+          description:
+            "Attach to this workspace as a standalone artifact (UUID).",
+        },
+        filePath: {
+          type: "string",
+          description:
+            "Absolute path to a local .html file the MCP server process can read. Mutually exclusive with base64Data.",
+        },
+        base64Data: {
+          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 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: {
+      type: "object",
+      properties: {
+        artifactId: { type: "string", description: "Artifact UUID" },
+        expiresInDays: {
+          type: "number",
+          description:
+            "Optional expiry in days. Omit for a link that never expires.",
+        },
+      },
+      required: ["artifactId"],
+    },
+  },
   harmony_get_card_external_links: {
     description:
       "Get external URL references attached to a card (links to docs, gists, dashboards, etc.).",
@@ -1754,6 +2017,126 @@ export const TOOLS = {
     },
   },
 
+  // ============ PLAYBOOK TOOLS (Method/Loop layer) ============
+
+  harmony_list_playbook: {
+    description:
+      "List a workspace's playbooks (reusable process definitions). Returns each playbook's name, version, steps_version, and state. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceId: {
+          type: "string",
+          description: "Workspace ID (optional if context set)",
+        },
+      },
+      required: [],
+    },
+  },
+
+  harmony_get_playbook: {
+    description:
+      "Get one playbook by ID, including its steps/stages definition and its recent runs. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        playbookId: { type: "string", description: "Playbook ID (UUID)" },
+      },
+      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).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceId: {
+          type: "string",
+          description: "Workspace ID (optional if context set)",
+        },
+        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).",
+          items: { type: "object" },
+        },
+      },
+      required: ["name"],
+    },
+  },
+
+  harmony_update_playbook: {
+    description:
+      "Update a playbook's name, description, steps/stages, enabled flag, or lifecycle state ('active'|'deprecated').",
+    inputSchema: {
+      type: "object",
+      properties: {
+        playbookId: {
+          type: "string",
+          description: "Playbook ID to update (UUID)",
+        },
+        name: { type: "string", description: "New name" },
+        description: { type: "string", description: "New description" },
+        steps: {
+          type: "array",
+          description: "New steps (v1) or stages (v2) array.",
+          items: { type: "object" },
+        },
+        enabled: {
+          type: "boolean",
+          description: "Enable/disable the playbook",
+        },
+        state: {
+          type: "string",
+          enum: ["active", "deprecated"],
+          description: "Lifecycle state",
+        },
+      },
+      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"],
+    },
+  },
+
   // ============ ONBOARDING TOOLS ============
   harmony_signup: {
     description:
@@ -2523,7 +2906,7 @@ async function handleToolCall(
         args.filePath != null ? z.string().parse(args.filePath) : undefined;
       const base64Data =
         args.base64Data != null ? z.string().parse(args.base64Data) : undefined;
-      let fileName =
+      const fileName =
         args.fileName != null ? z.string().parse(args.fileName) : undefined;
       const contentType =
         args.contentType != null
@@ -2534,28 +2917,232 @@ async function handleToolCall(
         throw new Error("Provide either filePath or base64Data, not both.");
       }
 
-      let data: string;
       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) {
+        // Server can read the file → upload direct-to-storage via the handshake
+        // (no base64 through the model context or the edge-fn JSON body).
+        const bytes = await readFileForUpload(
+          filePath,
+          MAX_ATTACHMENT_SIZE,
+          "attachment",
+        );
+        const resolvedName = fileName || basename(filePath);
+        const signed = await client.requestCardAttachmentUploadUrl(cardId, {
+          fileName: resolvedName,
+          fileType: contentType,
+          size: bytes.byteLength,
+        });
+        await putToSignedUrl(
+          signed.uploadUrl,
+          bytes,
+          contentType || signed.fileType || "application/octet-stream",
+        );
+        return await client.finalizeCardAttachment(cardId, {
+          storagePath: signed.storagePath,
+          fileName: resolvedName,
+          fileType: contentType || signed.fileType,
+          sha256: sha256Hex(bytes),
+          size: bytes.byteLength,
+        });
+      }
+
+      if (base64Data) {
         if (!fileName) {
           throw new Error("fileName is required when using base64Data.");
         }
-        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 client.uploadCardAttachment(cardId, {
+          fileName,
+          data: base64Data,
+          fileType: contentType,
+        });
+      }
+
+      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.");
       }
 
-      const result = await client.uploadCardAttachment(cardId, {
-        fileName: fileName as string,
-        data,
-        fileType: contentType,
+      if (filePath) {
+        // Server can read the file → upload direct-to-storage via the handshake
+        // (no base64 through the model context or the edge-fn JSON body).
+        const bytes = await readFileForUpload(
+          filePath,
+          MAX_ARTIFACT_SIZE,
+          "artifact",
+        );
+        const resolvedTitle = title || basename(filePath);
+        const signed = await client.requestArtifactUploadUrl({
+          title: resolvedTitle,
+          cardId,
+          planId,
+          workspaceId,
+          contentType: "text/html",
+          size: bytes.byteLength,
+        });
+        await putToSignedUrl(signed.uploadUrl, bytes, "text/html");
+        return await client.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.`,
+          );
+        }
+        return await client.uploadArtifact({
+          title,
+          cardId,
+          planId,
+          workspaceId,
+          data: base64Data,
+        });
+      }
+
+      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 client.requestArtifactUploadUrl({
+        title,
+        cardId,
+        planId,
+        workspaceId,
+        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 client.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 client.requestCardAttachmentUploadUrl(cardId, {
+        fileName,
+        fileType,
+        size,
       });
+    }
+
+    case "harmony_finalize_card_attachment": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const storagePath = z.string().parse(args.storagePath);
+      const fileName = z.string().parse(args.fileName);
+      const fileType =
+        args.fileType != null ? z.string().parse(args.fileType) : undefined;
+      const sha256 =
+        args.sha256 != null ? z.string().parse(args.sha256) : undefined;
+      const size =
+        args.size != null ? z.number().positive().parse(args.size) : undefined;
+      return await client.finalizeCardAttachment(cardId, {
+        storagePath,
+        fileName,
+        fileType,
+        sha256,
+        size,
+      });
+    }
+
+    case "harmony_share_artifact": {
+      const artifactId = z.string().uuid().parse(args.artifactId);
+      const expiresInDays =
+        args.expiresInDays != null
+          ? z.number().positive().parse(args.expiresInDays)
+          : undefined;
+      const expiresAt = expiresInDays
+        ? new Date(Date.now() + expiresInDays * 86_400_000).toISOString()
+        : undefined;
+      const result = await client.createArtifactShareLink(
+        artifactId,
+        expiresAt,
+      );
       return result;
     }
 
@@ -4028,6 +4615,68 @@ async function handleToolCall(
       };
     }
 
+    // ============ PLAYBOOK TOOLS (Method/Loop layer) ============
+
+    case "harmony_list_playbook": {
+      const workspaceId = (args.workspaceId as string) || getWorkspaceId();
+      const result = await client.listPlaybooks(workspaceId);
+      return {
+        success: true,
+        playbooks: result.playbooks,
+        count: (result.playbooks as unknown[]).length,
+      };
+    }
+
+    case "harmony_get_playbook": {
+      const playbookId = z.string().uuid().parse(args.playbookId);
+      const result = await client.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 client.runPlaybook(playbookId);
+      return { success: true, run: result.run };
+    }
+
+    case "harmony_create_playbook": {
+      const workspaceId = (args.workspaceId as string) || getWorkspaceId();
+      const name = z.string().min(1).max(200).parse(args.name);
+      const stepsVersion =
+        args.stepsVersion !== undefined
+          ? z.union([z.literal(1), z.literal(2)]).parse(args.stepsVersion)
+          : undefined;
+      const result = await client.createPlaybook({
+        workspaceId,
+        name,
+        description: args.description as string | undefined,
+        steps: args.steps,
+        stepsVersion,
+      });
+      return { success: true, playbook: result.playbook };
+    }
+
+    case "harmony_update_playbook": {
+      const playbookId = z.string().uuid().parse(args.playbookId);
+      const result = await client.updatePlaybook(playbookId, {
+        name: args.name as string | undefined,
+        description: args.description as string | undefined,
+        steps: args.steps,
+        enabled: args.enabled as boolean | undefined,
+        state: args.state as string | undefined,
+      });
+      return { success: true, playbook: result.playbook };
+    }
+
+    case "harmony_save_card_as_playbook": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const result = await client.savePlaybookFromCard({
+        cardId,
+        name: args.name as string | undefined,
+      });
+      return { success: true, playbook: result.playbook };
+    }
+
     // ============ ONBOARDING TOOLS ============
     case "harmony_signup": {
       const email = z.string().email().max(254).parse(args.email);