@gethmy/mcp 2.12.0 → 2.13.1

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.
@@ -150,6 +244,86 @@ function parseLabelList(raw: unknown): string[] | undefined {
   return undefined;
 }
 
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Coerce + validate a required string argument from a (possibly lenient) MCP
+ * caller, throwing a clear, field-attributed error on failure.
+ *
+ * The agent-session tools previously parsed these with a bare
+ * `z.string().parse(args.foo)`. When the field was missing or arrived as a
+ * non-string, Zod surfaced an opaque root-level blob —
+ * `[{"expected":"string","received":"undefined","path":[],...}]` — that names
+ * neither the offending field nor the received value. To an agent that reads
+ * as "the tool rejects every argument shape with an `expected string` error"
+ * (card #530). Instead we name the field, report what we got, and (matching
+ * the `parseLabelList` philosophy for quirky clients) accept the
+ * number/boolean values some MCP clients emit by stringifying scalars.
+ */
+function requireStringArg(
+  raw: unknown,
+  field: string,
+  opts: { max?: number } = {},
+): string {
+  let value: string;
+  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;
+}
+
+/** Coerce + validate a required UUID argument with a field-named error. */
+function requireUuidArg(raw: unknown, field: string): string {
+  const value = requireStringArg(raw, field);
+  if (!UUID_RE.test(value))
+    throw new Error(`${field} must be a valid UUID (received "${value}").`);
+  return value;
+}
+
+/**
+ * Coerce an optional 0–100 percentage. Accepts numeric strings (e.g. "50")
+ * because lenient MCP clients stringify scalar arguments; returns `undefined`
+ * when absent and throws a clear, field-named error when out of range.
+ */
+function optionalPercentArg(raw: unknown, field: string): number | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  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;
+}
+
+/**
+ * Coerce an optional non-negative number argument (e.g.
+ * `estimatedMinutesRemaining`). Accepts numeric strings; returns `undefined`
+ * when absent so the field is omitted from the API payload entirely.
+ */
+function optionalNonNegativeNumberArg(
+  raw: unknown,
+  field: string,
+): number | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  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: string,
   agentIdentifier: string,
@@ -665,7 +839,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 +868,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`.",
@@ -707,7 +940,7 @@ export const 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.",
+      "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: {
@@ -736,6 +969,69 @@ export const 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.",
@@ -2153,8 +2449,6 @@ export function registerHandlers(server: Server, deps: ToolDeps): void {
     // Auto-session pre-hook: track activity on card-related tools
     const toolArgs = args || {};
     const cardIdArg = toolArgs.cardId as string | undefined;
-    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);
       // Resolve MCP client identity per request from the in-scope Server. The
@@ -2690,7 +2984,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
@@ -2701,29 +2995,51 @@ 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,
+        });
       }
 
-      const result = await client.uploadCardAttachment(cardId, {
-        fileName: fileName as string,
-        data,
-        fileType: contentType,
-      });
-      return result;
+      throw new Error("Provide either filePath or base64Data.");
     }
 
     case "harmony_upload_artifact": {
@@ -2737,12 +3053,7 @@ async function handleToolCall(
         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;
@@ -2752,29 +3063,149 @@ async function handleToolCall(
         throw new Error("Provide either filePath or base64Data, not both.");
       }
 
-      let data: string;
-      let inferredTitle = title;
       if (filePath) {
-        const bytes = await readFile(filePath);
-        if (bytes.byteLength === 0) {
-          throw new Error(`File is empty: ${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.`,
+          );
         }
-        data = bytes.toString("base64");
-        inferredTitle = inferredTitle || basename(filePath);
-      } else if (base64Data) {
-        data = base64Data;
-      } else {
-        throw new Error("Provide either filePath or base64Data.");
+        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,
+      });
+    }
 
-      const result = await client.uploadArtifact({
-        title: inferredTitle,
+    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,
-        data,
       });
-      return result;
+    }
+
+    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": {
@@ -3003,13 +3434,15 @@ async function handleToolCall(
 
     // Agent context operations
     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 as string | undefined;
       const addLabels = parseLabelList(args.addLabels);
 
@@ -3096,9 +3529,10 @@ async function handleToolCall(
         agentName,
         status: "working",
         currentTask: args.currentTask as string | undefined,
-        estimatedMinutesRemaining: args.estimatedMinutesRemaining as
-          | number
-          | undefined,
+        estimatedMinutesRemaining: optionalNonNegativeNumberArg(
+          args.estimatedMinutesRemaining,
+          "estimatedMinutesRemaining",
+        ),
         steerable:
           args.steerable === true || args.steerable === "true"
             ? true
@@ -3129,17 +3563,19 @@ async function handleToolCall(
     }
 
     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",
+      );
       // Convert actions parameter to recentActions format and merge with memory actions
       const callerActions = args.actions as
         | { description: string }[]
@@ -3182,9 +3618,10 @@ async function handleToolCall(
         progressPercent,
         currentTask: args.currentTask as string | undefined,
         blockers: args.blockers as string[] | undefined,
-        estimatedMinutesRemaining: args.estimatedMinutesRemaining as
-          | number
-          | undefined,
+        estimatedMinutesRemaining: optionalNonNegativeNumberArg(
+          args.estimatedMinutesRemaining,
+          "estimatedMinutesRemaining",
+        ),
         ...(mergedRecentActions && { recentActions: mergedRecentActions }),
         ...(runActivity.length > 0 && { runActivity }),
       });
@@ -3194,14 +3631,14 @@ async function handleToolCall(
     }
 
     case "harmony_end_agent_session": {
-      const cardId = z.string().uuid().parse(args.cardId);
+      const cardId = requireUuidArg(args.cardId, "cardId");
       const moveToColumn = args.moveToColumn as string | undefined;
       const sessionStatus =
         (args.status as "completed" | "paused") || "completed";
-      const endProgressPercent =
-        args.progressPercent !== undefined
-          ? z.number().min(0).max(100).parse(args.progressPercent)
-          : undefined;
+      const endProgressPercent = optionalPercentArg(
+        args.progressPercent,
+        "progressPercent",
+      );
 
       // Final flush of any pending memory actions before ending the session
       await flushMemoryActions(client, cardId);