agentmail-toolkit 0.5.1 → 0.6.0

package/dist/mcp.cjs

@@ -97,14 +97,22 @@ var GetAttachmentParams = import_zod.z.object({
   threadId: ThreadIdSchema,
   attachmentId: AttachmentIdSchema
 });
-var AttachmentSchema = import_zod.z.object({
+var AttachmentBaseSchema = import_zod.z.object({
   filename: import_zod.z.string().optional().describe("Filename"),
   contentType: import_zod.z.string().optional().describe("MIME type of the attachment"),
   contentDisposition: import_zod.z.enum(["inline", "attachment"]).optional().describe("Content disposition"),
-  contentId: import_zod.z.string().optional().describe("Content ID for inline attachments"),
-  content: import_zod.z.string().optional().describe("Base64 encoded content. Exactly one of content or url must be provided"),
-  url: import_zod.z.url().optional().describe("Publicly accessible URL to fetch the attachment from. Exactly one of content or url must be provided")
+  contentId: import_zod.z.string().optional().describe("Content ID for inline attachments")
 });
+var AttachmentSchema = import_zod.z.union([
+  import_zod.z.strictObject({
+    ...AttachmentBaseSchema.shape,
+    content: import_zod.z.string().describe("Base64 encoded content")
+  }),
+  import_zod.z.strictObject({
+    ...AttachmentBaseSchema.shape,
+    url: import_zod.z.url().describe("Publicly accessible URL to fetch the attachment from")
+  })
+]).describe("Attachment: provide exactly one of content (base64) or url");
 var BaseMessageParams = import_zod.z.object({
   inboxId: InboxIdSchema,
   text: import_zod.z.string().optional().describe("Plain text body"),
@@ -126,6 +134,15 @@ var ReplyToMessageParams = BaseMessageParams.extend({
   cc: import_zod.z.array(import_zod.z.string()).optional().describe("Override CC recipients. Cannot be combined with replyAll"),
   bcc: import_zod.z.array(import_zod.z.string()).optional().describe("Override BCC recipients. Cannot be combined with replyAll"),
   replyTo: import_zod.z.array(import_zod.z.string()).optional().describe("Reply-to addresses")
+  // Mirrors the API's ReplyMessageSchema refine (agentmail-api schemas/message.ts),
+  // predicate and error text both - reject the combination locally instead of
+  // round-tripping a request the API will reject. NOTE: the MCP SDK validates
+  // tools/call args against a z.object it rebuilds from the raw shape, which
+  // drops root-level refines - runTool in mcp.ts re-parses with this schema so
+  // the refine is enforced on that path too.
+}).refine((data) => !(data.replyAll && (data.to || data.cc || data.bcc)), {
+  message: "Cannot specify to, cc, or bcc when replyAll is true",
+  path: ["replyAll"]
 });
 var ForwardMessageParams = SendMessageParams.extend({
   messageId: MessageIdSchema
@@ -184,20 +201,18 @@ var AuthMeParams = import_zod.z.object({});
 var import_zod2 = require("zod");
 var isoDate = () => import_zod2.z.iso.datetime().describe("ISO 8601 datetime");
 var MetadataSchema = import_zod2.z.record(import_zod2.z.string(), import_zod2.z.union([import_zod2.z.string(), import_zod2.z.number(), import_zod2.z.boolean()]));
-var PaginationSchema = import_zod2.z.looseObject({
+var PaginationSchema = import_zod2.z.object({
   count: import_zod2.z.number().describe("Number of items returned"),
   limit: import_zod2.z.number().optional().describe("Limit of number of items returned"),
   nextPageToken: import_zod2.z.string().optional().describe("Page token for pagination")
 });
-var VoidResultSchema = import_zod2.z.looseObject({
+var VoidResultSchema = import_zod2.z.object({
   success: import_zod2.z.literal(true)
 });
-var InboxSchema = import_zod2.z.looseObject({
-  podId: import_zod2.z.string(),
+var InboxSchema = import_zod2.z.object({
   inboxId: import_zod2.z.string(),
   email: import_zod2.z.string(),
   displayName: import_zod2.z.string().optional(),
-  clientId: import_zod2.z.string().optional(),
   metadata: MetadataSchema.optional().describe("Custom metadata attached to the inbox"),
   updatedAt: isoDate(),
   createdAt: isoDate()
@@ -205,7 +220,7 @@ var InboxSchema = import_zod2.z.looseObject({
 var ListInboxesResponseSchema = PaginationSchema.extend({
   inboxes: import_zod2.z.array(InboxSchema)
 });
-var AttachmentMetaSchema = import_zod2.z.looseObject({
+var AttachmentMetaSchema = import_zod2.z.object({
   attachmentId: import_zod2.z.string(),
   filename: import_zod2.z.string().optional(),
   size: import_zod2.z.number(),
@@ -216,10 +231,9 @@ var AttachmentMetaSchema = import_zod2.z.looseObject({
 var AttachmentResponseSchema = AttachmentMetaSchema.extend({
   downloadUrl: import_zod2.z.string().describe("URL to download the attachment"),
   expiresAt: isoDate().describe("Time at which the download URL expires"),
-  text: import_zod2.z.string().optional().describe("Extracted text (PDF/DOCX only, toolkit-added)"),
-  extractionError: import_zod2.z.string().optional().describe("Set when PDF/DOCX text extraction failed or was skipped (toolkit-added)")
+  text: import_zod2.z.string().optional().describe("Extracted text (PDF/DOCX only, toolkit-added; absent when extraction was skipped or failed - see download URL)")
 });
-var ThreadItemSchema = import_zod2.z.looseObject({
+var ThreadItemSchema = import_zod2.z.object({
   inboxId: import_zod2.z.string(),
   threadId: import_zod2.z.string(),
   labels: import_zod2.z.array(import_zod2.z.string()),
@@ -237,7 +251,7 @@ var ThreadItemSchema = import_zod2.z.looseObject({
   updatedAt: isoDate(),
   createdAt: isoDate()
 });
-var MessageItemSchema = import_zod2.z.looseObject({
+var MessageItemSchema = import_zod2.z.object({
   inboxId: import_zod2.z.string(),
   threadId: import_zod2.z.string(),
   messageId: import_zod2.z.string(),
@@ -252,7 +266,9 @@ var MessageItemSchema = import_zod2.z.looseObject({
   attachments: import_zod2.z.array(AttachmentMetaSchema).optional(),
   inReplyTo: import_zod2.z.string().optional(),
   references: import_zod2.z.array(import_zod2.z.string()).optional(),
-  headers: import_zod2.z.record(import_zod2.z.string(), import_zod2.z.string()).optional(),
+  // Raw RFC-822 `headers` deliberately excluded: they carry personal identifiers
+  // (Received-chain IPs, Return-Path) a model never needs — flagged by OpenAI app
+  // review. Threading works via inReplyTo/references.
   size: import_zod2.z.number(),
   updatedAt: isoDate(),
   createdAt: isoDate()
@@ -270,25 +286,43 @@ var ThreadSchema = ThreadItemSchema.extend({
 var ListThreadsResponseSchema = PaginationSchema.extend({
   threads: import_zod2.z.array(ThreadItemSchema)
 });
-var SearchThreadsResponseSchema = ListThreadsResponseSchema;
+var HighlightsSchema = import_zod2.z.object({
+  from: import_zod2.z.array(import_zod2.z.string()).optional().describe("Matched fragments from the sender address"),
+  recipients: import_zod2.z.array(import_zod2.z.string()).optional().describe("Matched fragments from recipient addresses"),
+  subject: import_zod2.z.array(import_zod2.z.string()).optional().describe("Matched fragments from the subject"),
+  text: import_zod2.z.array(import_zod2.z.string()).optional().describe("Matched fragments from the body")
+});
+var SearchThreadsResponseSchema = PaginationSchema.extend({
+  threads: import_zod2.z.array(
+    ThreadItemSchema.extend({
+      highlights: HighlightsSchema.optional().describe("Matched fragments per field, present when the query matched an indexed field")
+    })
+  )
+});
 var ListMessagesResponseSchema = PaginationSchema.extend({
   messages: import_zod2.z.array(MessageItemSchema)
 });
-var SearchMessagesResponseSchema = ListMessagesResponseSchema;
-var UpdateThreadResponseSchema = import_zod2.z.looseObject({
+var SearchMessagesResponseSchema = PaginationSchema.extend({
+  messages: import_zod2.z.array(
+    MessageItemSchema.extend({
+      highlights: HighlightsSchema.optional().describe("Matched fragments per field, present when the query matched an indexed field")
+    })
+  )
+});
+var UpdateThreadResponseSchema = import_zod2.z.object({
   threadId: import_zod2.z.string(),
   labels: import_zod2.z.array(import_zod2.z.string())
 });
-var UpdateMessageResponseSchema = import_zod2.z.looseObject({
+var UpdateMessageResponseSchema = import_zod2.z.object({
   messageId: import_zod2.z.string(),
   labels: import_zod2.z.array(import_zod2.z.string())
 });
-var SendMessageResponseSchema = import_zod2.z.looseObject({
+var SendMessageResponseSchema = import_zod2.z.object({
   messageId: import_zod2.z.string(),
   threadId: import_zod2.z.string()
 });
 var DraftSendStatusSchema = import_zod2.z.enum(["scheduled", "sending", "failed"]);
-var DraftItemSchema = import_zod2.z.looseObject({
+var DraftItemSchema = import_zod2.z.object({
   inboxId: import_zod2.z.string(),
   draftId: import_zod2.z.string(),
   labels: import_zod2.z.array(import_zod2.z.string()),
@@ -304,7 +338,6 @@ var DraftItemSchema = import_zod2.z.looseObject({
   updatedAt: isoDate()
 });
 var DraftSchema = DraftItemSchema.extend({
-  clientId: import_zod2.z.string().optional(),
   replyTo: import_zod2.z.array(import_zod2.z.string()).optional(),
   text: import_zod2.z.string().optional(),
   html: import_zod2.z.string().optional(),
@@ -315,7 +348,7 @@ var ListDraftsResponseSchema = PaginationSchema.extend({
   drafts: import_zod2.z.array(DraftItemSchema)
 });
 var ScopeTypeSchema = import_zod2.z.enum(["organization", "pod", "inbox"]);
-var IdentitySchema = import_zod2.z.looseObject({
+var IdentitySchema = import_zod2.z.object({
   scopeType: ScopeTypeSchema,
   scopeId: import_zod2.z.string(),
   organizationId: import_zod2.z.string(),
@@ -341,7 +374,11 @@ function apiErrorMessage(error) {
   }
   const base = detail ?? error.message;
   const bounded = typeof base === "string" && base.length > MAX_ERROR_BODY_LENGTH ? base.slice(0, MAX_ERROR_BODY_LENGTH) + "\u2026" : base;
-  return error.statusCode ? `${bounded} (HTTP ${error.statusCode})` : bounded;
+  const withStatus = error.statusCode ? `${bounded} (HTTP ${error.statusCode})` : bounded;
+  if (error.statusCode === 401) return `${withStatus} \u2014 credentials are missing or invalid; reconnect or provide a valid API key`;
+  if (error.statusCode === 403) return `${withStatus} \u2014 the authenticated credential lacks permission for this action`;
+  if (error.statusCode === 429) return `${withStatus} \u2014 rate limited; wait before retrying`;
+  return withStatus;
 }
 function errorMessage(error) {
   if (error instanceof import_agentmail.AgentMailError) return apiErrorMessage(error);
@@ -469,11 +506,11 @@ async function getAttachment(client, args) {
   const attachment = await client.inboxes.threads.getAttachment(inboxId, threadId, attachmentId);
   if (!attachment.downloadUrl.startsWith("https://")) {
     console.error("[agentmail-toolkit] attachment download URL is not https, skipping extraction", { attachmentId });
-    return { ...attachment, extractionError: "download URL is not https" };
+    return attachment;
   }
   if (attachment.size > MAX_ATTACHMENT_BYTES) {
     console.error("[agentmail-toolkit] attachment too large to extract, skipping", { attachmentId, size: attachment.size });
-    return { ...attachment, extractionError: "attachment exceeds size cap" };
+    return attachment;
   }
   const response = await fetch(attachment.downloadUrl, { signal: AbortSignal.timeout(15e3), redirect: "error" });
   if (!response.ok) {
@@ -482,12 +519,12 @@ async function getAttachment(client, args) {
   const contentLength = Number(response.headers.get("content-length"));
   if (contentLength && contentLength > MAX_ATTACHMENT_BYTES) {
     console.error("[agentmail-toolkit] content-length exceeds cap, skipping", { attachmentId, contentLength });
-    return { ...attachment, extractionError: "content-length exceeds size cap" };
+    return attachment;
   }
   const arrayBuffer = await response.arrayBuffer();
   if (arrayBuffer.byteLength > MAX_ATTACHMENT_BYTES) {
     console.error("[agentmail-toolkit] downloaded attachment exceeds cap, skipping", { attachmentId, size: arrayBuffer.byteLength });
-    return { ...attachment, extractionError: "downloaded attachment exceeds size cap" };
+    return attachment;
   }
   const fileBytes = new Uint8Array(arrayBuffer);
   const detectedType = detectFileType(fileBytes);
@@ -502,7 +539,7 @@ async function getAttachment(client, args) {
       attachmentId,
       error: err instanceof Error ? err.message : String(err)
     });
-    return { ...attachment, extractionError: err instanceof Error ? err.message : String(err) };
+    return attachment;
   }
 }
 async function listMessages(client, args) {
@@ -955,6 +992,47 @@ var ListToolkit = class extends BaseToolkit {
 };
 
 // src/mcp.ts
+var toolsByName = new Map(tools.map((tool) => [tool.name, tool]));
+async function runTool(tool, client, args) {
+  const preflight = tool.paramsSchema.safeParse(normalize(args));
+  if (!preflight.success) {
+    const message = preflight.error.issues.map((issue) => issue.message).join("; ");
+    return {
+      content: [{ type: "text", text: `Invalid arguments: ${message}` }],
+      isError: true
+    };
+  }
+  const { isError, result, statusCode, body } = await safeFunc(tool.func, client, preflight.data);
+  if (isError) {
+    console.error("[agentmail-toolkit] tool error", {
+      tool: tool.name,
+      statusCode,
+      body: truncateForLog(body)
+    });
+    return {
+      content: [{ type: "text", text: String(result) }],
+      isError: true
+    };
+  }
+  const parsed = import_zod3.z.object(tool.outputSchema.shape).safeParse(normalize(result));
+  if (!parsed.success) {
+    console.error("[agentmail-toolkit] output schema mismatch", {
+      tool: tool.name,
+      issues: parsed.error.issues
+    });
+    return {
+      content: [{ type: "text", text: `Internal error: ${tool.name} result did not match its declared output schema` }],
+      isError: true
+    };
+  }
+  const structuredContent = parsed.data;
+  const text = JSON.stringify(structuredContent);
+  return {
+    structuredContent,
+    content: [{ type: "text", text }],
+    isError: false
+  };
+}
 var AgentMailToolkit = class extends ListToolkit {
   buildTool(tool) {
     return {
@@ -963,41 +1041,36 @@ var AgentMailToolkit = class extends ListToolkit {
       description: tool.description,
       inputSchema: tool.paramsSchema.shape,
       outputSchema: tool.outputSchema.shape,
-      callback: async (args) => {
-        const { isError, result, statusCode, body } = await safeFunc(tool.func, this.client, args);
-        if (isError) {
-          console.error("[agentmail-toolkit] tool error", {
-            tool: tool.name,
-            statusCode,
-            body: truncateForLog(body)
-          });
-          return {
-            content: [{ type: "text", text: String(result) }],
-            isError: true
-          };
-        }
-        const parsed = import_zod3.z.object(tool.outputSchema.shape).safeParse(normalize(result));
-        if (!parsed.success) {
-          console.error("[agentmail-toolkit] output schema mismatch", {
-            tool: tool.name,
-            issues: parsed.error.issues
-          });
-          return {
-            content: [{ type: "text", text: `Internal error: ${tool.name} result did not match its declared output schema` }],
-            isError: true
-          };
-        }
-        const structuredContent = parsed.data;
-        const text = JSON.stringify(structuredContent);
-        return {
-          structuredContent,
-          content: [{ type: "text", text }],
-          isError: false
-        };
-      },
+      callback: async (args) => runTool(tool, this.client, args),
       annotations: tool.annotations
     };
   }
+  /**
+   * Invoke a tool by name with a per-call client, bypassing the client bound
+   * at construction, and return the same MCP CallToolResult a tools/call
+   * would.
+   *
+   * This lets a host that serves many users (e.g. a hosted MCP server) build
+   * the toolkit ONCE and hand each request its own client, instead of
+   * constructing a fresh toolkit per request and again per tool call - which,
+   * under long-lived/streaming connections, retains a per-call object graph
+   * and drives heap growth.
+   *
+   * An unknown tool name returns an isError result rather than throwing, so a
+   * bad name can never crash the caller. `args` is assumed already validated
+   * against the tool's paramsSchema (the MCP SDK validates tools/call
+   * arguments before dispatch).
+   */
+  async invoke(name, client, args) {
+    const tool = toolsByName.get(name);
+    if (!tool) {
+      return {
+        content: [{ type: "text", text: `Unknown tool: ${name}` }],
+        isError: true
+      };
+    }
+    return runTool(tool, client, args);
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {