@vellumai/assistant 0.6.3 → 0.6.4

package/src/runtime/routes/__tests__/user-route-dispatcher.test.ts

@@ -14,12 +14,38 @@ mock.module("../../../util/logger.js", () => ({
 }));
 
 import { getWorkspaceRoutesDir } from "../../../util/platform.js";
+import { AssistantEventHub } from "../../assistant-event-hub.js";
+import type { UserRouteContext } from "../user-route-dispatcher.js";
 import { UserRouteDispatcher } from "../user-route-dispatcher.js";
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
+/** Build a minimal UserRouteContext for tests. */
+function makeContext(
+  overrides?: Partial<UserRouteContext>,
+): UserRouteContext {
+  return {
+    assistantEventHub: new AssistantEventHub(),
+    assistantId: "test-assistant",
+    ...overrides,
+  };
+}
+
+/** Create a dispatcher with a stub context and optional overrides. */
+function makeDispatcher(
+  options?: Partial<{
+    handlerTimeoutMs: number;
+    context: UserRouteContext;
+  }>,
+): UserRouteDispatcher {
+  return new UserRouteDispatcher({
+    context: options?.context ?? makeContext(),
+    ...options,
+  });
+}
+
 function makeRequest(
   method: string,
   path = "http://localhost/v1/x/test",
@@ -60,7 +86,7 @@ afterEach(() => {
 
 describe("path traversal", () => {
   test("rejects paths containing '..'", async () => {
-    const dispatcher = new UserRouteDispatcher();
+    const dispatcher = makeDispatcher();
     const res = await dispatcher.dispatch("../etc/passwd", makeRequest("GET"));
     expect(res.status).toBe(400);
     const body = await readErrorBody(res);
@@ -69,7 +95,7 @@ describe("path traversal", () => {
   });
 
   test("rejects embedded '..' segments", async () => {
-    const dispatcher = new UserRouteDispatcher();
+    const dispatcher = makeDispatcher();
     const res = await dispatcher.dispatch(
       "foo/../../etc/passwd",
       makeRequest("GET"),
@@ -84,7 +110,7 @@ describe("path traversal", () => {
 
 describe("missing handler", () => {
   test("returns 404 when no handler file exists", async () => {
-    const dispatcher = new UserRouteDispatcher();
+    const dispatcher = makeDispatcher();
     const res = await dispatcher.dispatch("nonexistent", makeRequest("GET"));
     expect(res.status).toBe(404);
     const body = await readErrorBody(res);
@@ -106,7 +132,7 @@ describe("successful dispatch", () => {
       }`,
     );
 
-    const dispatcher = new UserRouteDispatcher();
+    const dispatcher = makeDispatcher();
     const res = await dispatcher.dispatch("hello", makeRequest("GET"));
     expect(res.status).toBe(200);
     const body = await res.json();
@@ -121,7 +147,7 @@ describe("successful dispatch", () => {
       }`,
     );
 
-    const dispatcher = new UserRouteDispatcher();
+    const dispatcher = makeDispatcher();
     const res = await dispatcher.dispatch("submit", makeRequest("POST"));
     expect(res.status).toBe(201);
     const body = await res.json();
@@ -136,7 +162,7 @@ describe("successful dispatch", () => {
       }`,
     );
 
-    const dispatcher = new UserRouteDispatcher();
+    const dispatcher = makeDispatcher();
     const res = await dispatcher.dispatch("legacy", makeRequest("GET"));
     expect(res.status).toBe(200);
     const body = await res.json();
@@ -157,7 +183,7 @@ describe("index file convention", () => {
       }`,
     );
 
-    const dispatcher = new UserRouteDispatcher();
+    const dispatcher = makeDispatcher();
     const res = await dispatcher.dispatch("my-app", makeRequest("GET"));
     expect(res.status).toBe(200);
     const body = await res.json();
@@ -172,7 +198,7 @@ describe("index file convention", () => {
       }`,
     );
 
-    const dispatcher = new UserRouteDispatcher();
+    const dispatcher = makeDispatcher();
     const res = await dispatcher.dispatch("fallback-app", makeRequest("GET"));
     expect(res.status).toBe(200);
     const body = await res.json();
@@ -193,7 +219,7 @@ describe("index file convention", () => {
       }`,
     );
 
-    const dispatcher = new UserRouteDispatcher();
+    const dispatcher = makeDispatcher();
     const res = await dispatcher.dispatch("dual", makeRequest("GET"));
     expect(res.status).toBe(200);
     const body = await res.json();
@@ -214,7 +240,7 @@ describe("method not allowed", () => {
       }`,
     );
 
-    const dispatcher = new UserRouteDispatcher();
+    const dispatcher = makeDispatcher();
     const res = await dispatcher.dispatch("get-only", makeRequest("POST"));
     expect(res.status).toBe(405);
     expect(res.headers.get("Allow")).toBe("GET");
@@ -228,7 +254,7 @@ describe("method not allowed", () => {
        export function DELETE(request) { return new Response("ok"); }`,
     );
 
-    const dispatcher = new UserRouteDispatcher();
+    const dispatcher = makeDispatcher();
     const res = await dispatcher.dispatch("multi", makeRequest("PUT"));
     expect(res.status).toBe(405);
     const allow = res.headers.get("Allow");
@@ -252,7 +278,7 @@ describe("handler timeout", () => {
     );
 
     // Use a very short timeout for testing
-    const dispatcher = new UserRouteDispatcher({ handlerTimeoutMs: 50 });
+    const dispatcher = makeDispatcher({ handlerTimeoutMs: 50 });
     const res = await dispatcher.dispatch("slow", makeRequest("GET"));
     expect(res.status).toBe(504);
     const body = await readErrorBody(res);
@@ -274,7 +300,7 @@ describe("handler errors", () => {
       }`,
     );
 
-    const dispatcher = new UserRouteDispatcher();
+    const dispatcher = makeDispatcher();
     const res = await dispatcher.dispatch("throws", makeRequest("GET"));
     expect(res.status).toBe(500);
     const body = await readErrorBody(res);
@@ -290,7 +316,7 @@ describe("handler errors", () => {
       }`,
     );
 
-    const dispatcher = new UserRouteDispatcher();
+    const dispatcher = makeDispatcher();
     const res = await dispatcher.dispatch("rejects", makeRequest("GET"));
     expect(res.status).toBe(500);
     const body = await readErrorBody(res);
@@ -311,7 +337,7 @@ describe("mtime cache", () => {
       }`,
     );
 
-    const dispatcher = new UserRouteDispatcher();
+    const dispatcher = makeDispatcher();
 
     // First request — version 1
     const res1 = await dispatcher.dispatch("mutable", makeRequest("GET"));
@@ -349,7 +375,7 @@ describe("subdirectory routing", () => {
       }`,
     );
 
-    const dispatcher = new UserRouteDispatcher();
+    const dispatcher = makeDispatcher();
     const res = await dispatcher.dispatch("api/v1/status", makeRequest("GET"));
     expect(res.status).toBe(200);
     const body = await res.json();
@@ -371,8 +397,113 @@ describe("description metadata", () => {
        }`,
     );
 
-    const dispatcher = new UserRouteDispatcher();
+    const dispatcher = makeDispatcher();
     const res = await dispatcher.dispatch("with-meta", makeRequest("GET"));
     expect(res.status).toBe(200);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Context injection
+// ---------------------------------------------------------------------------
+
+describe("context injection", () => {
+  test("passes UserRouteContext as second argument to handler", async () => {
+    writeHandler(
+      "ctx-echo.ts",
+      `export function GET(request, context) {
+        return Response.json({
+          hasHub: typeof context.assistantEventHub?.publish === "function",
+          assistantId: context.assistantId,
+        });
+      }`,
+    );
+
+    const ctx = makeContext({ assistantId: "custom-id" });
+    const dispatcher = makeDispatcher({ context: ctx });
+    const res = await dispatcher.dispatch("ctx-echo", makeRequest("GET"));
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.hasHub).toBe(true);
+    expect(body.assistantId).toBe("custom-id");
+  });
+
+  test("handler can publish events through injected hub", async () => {
+    writeHandler(
+      "ctx-publish.ts",
+      `export async function POST(request, context) {
+        const body = await request.json();
+        await context.assistantEventHub.publish({
+          id: "test-event-1",
+          assistantId: context.assistantId,
+          conversationId: body.conversationId,
+          emittedAt: new Date().toISOString(),
+          message: { type: "open_conversation", conversationId: body.conversationId },
+        });
+        return Response.json({ published: true });
+      }`,
+    );
+
+    const hub = new AssistantEventHub();
+    const received: unknown[] = [];
+    hub.subscribe(
+      { assistantId: "test-assistant" },
+      (event) => { received.push(event); },
+    );
+
+    const ctx = makeContext({ assistantEventHub: hub });
+    const dispatcher = makeDispatcher({ context: ctx });
+    const req = new Request("http://localhost/v1/x/ctx-publish", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ conversationId: "conv-123" }),
+    });
+    const res = await dispatcher.dispatch("ctx-publish", req);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.published).toBe(true);
+    expect(received).toHaveLength(1);
+    expect((received[0] as { conversationId: string }).conversationId).toBe(
+      "conv-123",
+    );
+  });
+
+  test("legacy handlers that ignore context still work", async () => {
+    writeHandler(
+      "no-ctx.ts",
+      `export function GET(request) {
+        return Response.json({ legacy: true });
+      }`,
+    );
+
+    const dispatcher = makeDispatcher();
+    const res = await dispatcher.dispatch("no-ctx", makeRequest("GET"));
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.legacy).toBe(true);
+  });
+
+  test("context is frozen — mutations throw in strict mode", async () => {
+    writeHandler(
+      "ctx-mutate.ts",
+      `export function GET(request, context) {
+        let threw = false;
+        try {
+          context.assistantId = "hacked";
+        } catch {
+          threw = true;
+        }
+        return Response.json({ threw, assistantId: context.assistantId });
+      }`,
+    );
+
+    const ctx = makeContext({ assistantId: "original" });
+    const dispatcher = makeDispatcher({ context: ctx });
+    const res = await dispatcher.dispatch("ctx-mutate", makeRequest("GET"));
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    // Object.freeze makes property assignment throw in strict mode (ESM)
+    // and silently fail in sloppy mode — either way the value is unchanged.
+    expect(body.assistantId).toBe("original");
+  });
+});

package/src/runtime/routes/app-management-routes.ts

@@ -23,6 +23,7 @@ import { z } from "zod";
 import { packageApp } from "../../bundler/app-bundler.js";
 import { compileApp } from "../../bundler/app-compiler.js";
 import { scanBundle } from "../../bundler/bundle-scanner.js";
+import type { SignatureJson } from "../../bundler/bundle-signer.js";
 import { verifyBundleSignature } from "../../bundler/signature-verifier.js";
 import { compareSemver } from "../../daemon/handlers/shared.js";
 import { defaultGallery } from "../../gallery/default-gallery.js";
@@ -39,11 +40,11 @@ import {
   getApp,
   getAppDirPath,
   getAppPreview,
-  inlineDistAssets,
   isMultifileApp,
   listApps,
   queryAppRecords,
   resolveAppDir,
+  resolveEffectiveAppHtml,
   updateApp,
   updateAppRecord,
 } from "../../memory/app-store.js";
@@ -583,16 +584,15 @@ export function appManagementRouteDefinitions(): RouteDefinition[] {
               return httpError("BAD_REQUEST", "payload is not valid JSON", 400);
             }
 
-            const signatureJson: import("../../bundler/bundle-signer.js").SignatureJson =
-              {
-                algorithm: "ed25519",
-                signer: {
-                  key_id: body.keyId,
-                  display_name: "HTTP Signer",
-                },
-                content_hashes: contentHashes,
-                signature: body.signature,
-              };
+            const signatureJson: SignatureJson = {
+              algorithm: "ed25519",
+              signer: {
+                key_id: body.keyId,
+                display_name: "HTTP Signer",
+              },
+              content_hashes: contentHashes,
+              signature: body.signature,
+            };
             return Response.json({ signed: true, signatureJson });
           }
 
@@ -738,8 +738,6 @@ export function appManagementRouteDefinitions(): RouteDefinition[] {
             return httpError("NOT_FOUND", `App not found: ${appId}`, 404);
           }
 
-          let html = app.htmlDefinition;
-
           if (isMultifileApp(app)) {
             const appDir = getAppDirPath(appId);
             const distIndex = join(appDir, "dist", "index.html");
@@ -752,12 +750,8 @@ export function appManagementRouteDefinitions(): RouteDefinition[] {
                 );
               }
             }
-            if (existsSync(distIndex)) {
-              html = inlineDistAssets(appDir, readFileSync(distIndex, "utf-8"));
-            } else {
-              html = `<p>App compilation failed. Edit a source file to trigger a rebuild.</p>`;
-            }
           }
+          const html = resolveEffectiveAppHtml(app);
 
           const { dirName } = resolveAppDir(app.id);
           return Response.json({

package/src/runtime/routes/attachment-routes.test.ts

@@ -1,6 +1,7 @@
 import {
   mkdirSync,
   mkdtempSync,
+  realpathSync,
   rmSync,
   symlinkSync,
   writeFileSync,
@@ -9,10 +10,15 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterAll, beforeAll, describe, expect, mock, test } from "bun:test";
 
-const testWorkspaceDir = mkdtempSync(
-  join(tmpdir(), "attachment-routes-workspace-"),
+// realpathSync resolves the macOS /var → /private/var symlink so the paths
+// match what resolveAllowedFileBackedAttachmentPath returns (it canonicalizes
+// via realpathSync internally).
+const testWorkspaceDir = realpathSync(
+  mkdtempSync(join(tmpdir(), "attachment-routes-workspace-")),
+);
+const testHomeDir = realpathSync(
+  mkdtempSync(join(tmpdir(), "attachment-routes-home-")),
 );
-const testHomeDir = mkdtempSync(join(tmpdir(), "attachment-routes-home-"));
 
 const attachmentsDir = join(testWorkspaceDir, "data", "attachments");
 const conversationsDir = join(testWorkspaceDir, "conversations");

package/src/runtime/routes/attachment-routes.ts

@@ -1,7 +1,13 @@
 /**
  * Route handlers for attachment upload, download, and deletion.
  */
-import { existsSync, realpathSync, statSync } from "node:fs";
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  realpathSync,
+  statSync,
+} from "node:fs";
 import { join, resolve, sep } from "node:path";
 
 import { z } from "zod";
@@ -19,6 +25,9 @@ import type { RouteDefinition } from "../http-router.js";
 /** 150 MB — base64-encoded 100 MB attachment ≈ 134 MB plus JSON wrapper overhead. */
 const MAX_UPLOAD_BODY_BYTES = 150 * 1024 * 1024;
 
+/** 100 MB — maximum file size for file-backed uploads (matches client memorySafetyLimit). */
+const MAX_FILE_BACKED_UPLOAD_BYTES = 100 * 1024 * 1024;
+
 function resolveCanonicalPath(filePath: string): string {
   try {
     return realpathSync(filePath);
@@ -88,7 +97,160 @@ export function resolveAllowedFileBackedAttachmentPath(
   return null;
 }
 
-export async function handleUploadAttachment(req: Request): Promise<Response> {
+/** 100 MB — maximum file size for binary uploads (multipart / octet-stream). */
+const MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
+
+/**
+ * Build the standard JSON success response for an uploaded attachment.
+ */
+function attachmentResponse(
+  attachment: attachmentsStore.StoredAttachment,
+): Response {
+  return Response.json({
+    id: attachment.id,
+    original_filename: attachment.originalFilename,
+    mime_type: attachment.mimeType,
+    size_bytes: attachment.sizeBytes,
+    kind: attachment.kind,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Content-Type dispatched upload handlers
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle multipart/form-data upload.
+ * Expects: "file" (Blob), "filename" (string), "mimeType" (string).
+ */
+async function handleMultipartUpload(req: Request): Promise<Response> {
+  // Pre-check Content-Length before parsing to reject oversized requests
+  // without buffering the full multipart body into memory. Binary uploads
+  // have no base64 overhead, so use the raw file size limit directly.
+  const contentLength = req.headers.get("content-length");
+  if (contentLength && Number(contentLength) > MAX_UPLOAD_BYTES) {
+    return httpError(
+      "BAD_REQUEST",
+      `File too large (limit: ${MAX_UPLOAD_BYTES / (1024 * 1024)} MB)`,
+      413,
+    );
+  }
+
+  let formData: FormData;
+  try {
+    formData = await req.formData();
+  } catch {
+    return httpError("BAD_REQUEST", "Invalid multipart form data", 400);
+  }
+
+  const file = formData.get("file");
+  if (!file || !(file instanceof Blob)) {
+    return httpError(
+      "BAD_REQUEST",
+      'Multipart upload requires a "file" field',
+      400,
+    );
+  }
+
+  const filename = formData.get("filename");
+  if (!filename || typeof filename !== "string") {
+    return httpError("BAD_REQUEST", "filename field is required", 400);
+  }
+
+  const mimeType = formData.get("mimeType");
+  if (!mimeType || typeof mimeType !== "string") {
+    return httpError("BAD_REQUEST", "mimeType field is required", 400);
+  }
+
+  // Check file part size against the raw file limit (Content-Length may be
+  // absent or inaccurate, so this is the authoritative check).
+  if (file.size > MAX_UPLOAD_BYTES) {
+    return httpError(
+      "BAD_REQUEST",
+      `File is ${Math.round(file.size / (1024 * 1024))} MB which exceeds the ${MAX_UPLOAD_BYTES / (1024 * 1024)} MB upload limit`,
+      413,
+    );
+  }
+
+  const validation = validateAttachmentUpload(filename, mimeType);
+  if (!validation.ok) {
+    return httpError("UNPROCESSABLE_ENTITY", validation.error, 415);
+  }
+
+  const bytes = new Uint8Array(await file.arrayBuffer());
+
+  const attachment = attachmentsStore.uploadAttachmentFromBytes(
+    filename,
+    mimeType,
+    bytes,
+  );
+  return attachmentResponse(attachment);
+}
+
+/**
+ * Handle application/octet-stream upload.
+ * filename and mimeType come from URL query params.
+ */
+async function handleOctetStreamUpload(req: Request): Promise<Response> {
+  // Pre-check Content-Length before buffering to reject oversized requests
+  // without reading the full body into memory.
+  const contentLength = req.headers.get("content-length");
+  if (contentLength && Number(contentLength) > MAX_UPLOAD_BYTES) {
+    return httpError(
+      "BAD_REQUEST",
+      `File too large (limit: ${MAX_UPLOAD_BYTES / (1024 * 1024)} MB)`,
+      413,
+    );
+  }
+
+  const url = new URL(req.url);
+  const filename = url.searchParams.get("filename");
+  if (!filename || typeof filename !== "string") {
+    return httpError(
+      "BAD_REQUEST",
+      "filename query parameter is required",
+      400,
+    );
+  }
+
+  const mimeType = url.searchParams.get("mimeType");
+  if (!mimeType || typeof mimeType !== "string") {
+    return httpError(
+      "BAD_REQUEST",
+      "mimeType query parameter is required",
+      400,
+    );
+  }
+
+  const rawBody = await req.arrayBuffer();
+  // Post-read check (Content-Length may be absent or inaccurate).
+  if (rawBody.byteLength > MAX_UPLOAD_BYTES) {
+    return httpError(
+      "BAD_REQUEST",
+      `File is ${Math.round(rawBody.byteLength / (1024 * 1024))} MB which exceeds the ${MAX_UPLOAD_BYTES / (1024 * 1024)} MB upload limit`,
+      413,
+    );
+  }
+
+  const validation = validateAttachmentUpload(filename, mimeType);
+  if (!validation.ok) {
+    return httpError("UNPROCESSABLE_ENTITY", validation.error, 415);
+  }
+
+  const bytes = new Uint8Array(rawBody);
+
+  const attachment = attachmentsStore.uploadAttachmentFromBytes(
+    filename,
+    mimeType,
+    bytes,
+  );
+  return attachmentResponse(attachment);
+}
+
+/**
+ * Handle application/json upload (existing behaviour — base64 or file-path).
+ */
+async function handleJsonUpload(req: Request): Promise<Response> {
   const rawBody = await req.arrayBuffer();
   if (rawBody.byteLength > MAX_UPLOAD_BODY_BYTES) {
     return httpError(
@@ -124,17 +286,45 @@ export async function handleUploadAttachment(req: Request): Promise<Response> {
 
   // File-backed upload: when filePath is provided and data is empty/missing,
   // register the attachment by path reference instead of requiring base64 data.
-  // This supports retry of file-backed attachments (e.g. recordings) where the
-  // client no longer holds the inline data but the file still exists on disk.
+  // This supports:
+  //   1. Desktop client file-picker uploads — the file is copied into the
+  //      workspace attachments directory so it passes the directory allowlist.
+  //   2. Retry of file-backed attachments (e.g. recordings) where the client
+  //      no longer holds the inline data but the file still exists on disk.
   if (filePath && typeof filePath === "string" && (!data || data === "")) {
-    const resolvedPath = resolveAllowedFileBackedAttachmentPath(filePath);
+    let resolvedPath = resolveAllowedFileBackedAttachmentPath(filePath);
+
+    // If the file isn't in an allowed directory, copy it into the workspace
+    // attachments directory. This handles desktop client file-picker uploads
+    // where the source file lives in an arbitrary user directory (e.g.
+    // ~/Desktop, ~/Downloads). The copy lands in the allowlisted workspace
+    // directory, preserving the security model.
     if (!resolvedPath) {
-      return httpError(
-        "BAD_REQUEST",
-        "filePath is outside allowed upload directories",
-        400,
+      const canonicalSource = resolveCanonicalPath(filePath);
+      if (!existsSync(canonicalSource)) {
+        return httpError("BAD_REQUEST", "filePath does not exist on disk", 400);
+      }
+      const sourceSize = statSync(canonicalSource).size;
+      if (sourceSize > MAX_FILE_BACKED_UPLOAD_BYTES) {
+        const sizeMB = Math.round(sourceSize / (1024 * 1024));
+        return httpError(
+          "BAD_REQUEST",
+          `File is ${sizeMB} MB which exceeds the ${MAX_FILE_BACKED_UPLOAD_BYTES / (1024 * 1024)} MB upload limit`,
+          413,
+        );
+      }
+      const workspaceAttachmentsDir = join(
+        getWorkspaceDir(),
+        "data",
+        "attachments",
       );
+      mkdirSync(workspaceAttachmentsDir, { recursive: true });
+      const destFilename = `${Date.now()}-${filename.replace(/[^a-zA-Z0-9._-]/g, "_")}`;
+      const destPath = join(workspaceAttachmentsDir, destFilename);
+      copyFileSync(canonicalSource, destPath);
+      resolvedPath = resolveCanonicalPath(destPath);
     }
+
     if (!existsSync(resolvedPath)) {
       return httpError("BAD_REQUEST", "filePath does not exist on disk", 400);
     }
@@ -168,13 +358,22 @@ export async function handleUploadAttachment(req: Request): Promise<Response> {
     }
   }
 
-  return Response.json({
-    id: attachment.id,
-    original_filename: attachment.originalFilename,
-    mime_type: attachment.mimeType,
-    size_bytes: attachment.sizeBytes,
-    kind: attachment.kind,
-  });
+  return attachmentResponse(attachment);
+}
+
+export async function handleUploadAttachment(req: Request): Promise<Response> {
+  const contentType = req.headers.get("content-type") ?? "";
+
+  if (contentType.includes("multipart/form-data")) {
+    return handleMultipartUpload(req);
+  }
+
+  if (contentType.includes("application/octet-stream")) {
+    return handleOctetStreamUpload(req);
+  }
+
+  // Default: JSON+base64 (existing behaviour)
+  return handleJsonUpload(req);
 }
 
 export async function handleDeleteAttachment(req: Request): Promise<Response> {
@@ -355,7 +554,7 @@ export function attachmentRouteDefinitions(): RouteDefinition[] {
       method: "POST",
       summary: "Upload attachment",
       description:
-        "Upload an attachment as base64 data or file path reference.",
+        "Upload an attachment. Supports application/json (base64 data or file path reference), multipart/form-data (file + filename + mimeType fields), and application/octet-stream (raw bytes with filename and mimeType query params).",
       tags: ["attachments"],
       requestBody: z.object({
         filename: z.string(),