ofw-mcp 2.3.2 → 2.4.1

package/dist/tools/messages.js

@@ -1,11 +1,56 @@
 import { z } from 'zod';
 import { syncAll, fetchAttachmentMeta, fetchAttachmentMetaForMessage } from '../sync.js';
 import { listMessages, countMessages, listDrafts, getMessage, upsertMessage, upsertDraft, deleteDraft, findLatestReplyTip, listAttachmentsForMessage, getAttachment, upsertAttachmentForMessage, markAttachmentDownloaded, getDraft, } from '../cache.js';
-import { getAttachmentsDir, getDefaultInlineAttachments } from '../config.js';
+import { getAttachmentsDir, getDefaultInlineAttachments, getWriteMode } from '../config.js';
 import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, extname, join } from 'node:path';
 import { fileBlob } from '@chrischall/mcp-utils';
-import { expandPath, jsonResponse, mapRecipients, postMessageAndRefetch, textResponse } from './_shared.js';
+import { ApiRecipientSchema, expandPath, jsonResponse, mapRecipients, postMessageAndRefetch, textResponse, verifyWriteLanded } from './_shared.js';
+import { parseOFW } from '../validate.js';
+// Schemas for the load-bearing fields of each /pub/v3 response this file
+// reads (issue #83). Loose: unknown keys pass through into cached listData.
+const DateSchema = z.looseObject({ dateTime: z.string() });
+// Detail GET after a send/save POST — validated STRICT inside
+// postMessageAndRefetch (write-verification boundary). All fields optional:
+// absence is handled by verifyWriteLanded's WARNING; a present-but-mistyped
+// field throws.
+const SentDetailSchema = z.looseObject({
+    subject: z.string().optional(),
+    body: z.string().optional(),
+    date: DateSchema.optional(),
+    from: z.looseObject({ name: z.string().optional() }).optional(),
+    recipients: z.array(ApiRecipientSchema).optional(),
+});
+const SavedDraftDetailSchema = z.looseObject({
+    subject: z.string().optional(),
+    body: z.string().optional(),
+    date: DateSchema.optional(),
+    replyToId: z.number().nullable().optional(),
+    recipients: z.array(ApiRecipientSchema).optional(),
+});
+// ofw_get_message's uncached detail fetch — lenient: a mismatch warns to
+// stderr and the existing ?? fallbacks keep the tool serving.
+const MessageDetailSchema = z.looseObject({
+    id: z.number(),
+    subject: z.string(),
+    body: z.string().optional(),
+    date: DateSchema,
+    from: z.looseObject({ name: z.string().optional() }).optional(),
+    files: z.array(z.number()).optional(),
+    recipients: z.array(ApiRecipientSchema).optional(),
+});
+// Attachment-backfill detail fetch reads only `files`.
+const DetailFilesSchema = z.looseObject({ files: z.array(z.number()).optional() });
+// Upload response — STRICT: fileId is the whole point of the call; caching
+// or returning an undefined/mistyped fileId produces an unusable attachment.
+const UploadedFileSchema = z.looseObject({
+    fileId: z.number(),
+    fileName: z.string().optional(),
+    label: z.string().optional(),
+    fileType: z.string().optional(),
+    sizeInBytes: z.number().optional(),
+    shareClass: z.string().optional(),
+});
 // Lightweight mime sniff from extension. OFW re-derives mime from the filename
 // server-side anyway, so this is just a polite Content-Type for the Blob.
 const MIME_BY_EXT = {
@@ -48,6 +93,13 @@ function listDataHintsAtFiles(listData) {
     return false;
 }
 export function registerMessageTools(server, client) {
+    // OFW_WRITE_MODE gate (see config.ts). Send lands on the court-visible
+    // record, so it is 'all'-only; draft-level writes (save/delete drafts,
+    // upload attachments) also register under 'drafts'. Read/sync/download
+    // tools always register.
+    const writeMode = getWriteMode();
+    const allowSend = writeMode === 'all';
+    const allowDrafts = writeMode !== 'none';
     server.registerTool('ofw_list_message_folders', {
         description: 'List OurFamilyWizard message folders (inbox, sent, etc.) and their unread counts. Returns folder IDs needed to call ofw_list_messages. Does NOT return message content.',
         annotations: { readOnlyHint: true },
@@ -60,8 +112,8 @@ export function registerMessageTools(server, client) {
         annotations: { readOnlyHint: true },
         inputSchema: {
             folderId: z.string().describe('Folder name: "inbox", "sent", or "both" (default "both")').optional(),
-            page: z.number().describe('Page number (default 1)').optional(),
-            size: z.number().describe('Messages per page (default 50)').optional(),
+            page: z.number().int().min(1).describe('Page number (default 1)').optional(),
+            size: z.number().int().min(1).describe('Messages per page (default 50)').optional(),
             since: z.string().describe('ISO date or datetime — only messages with sent_at >= since (inclusive)').optional(),
             until: z.string().describe('ISO date or datetime — only messages with sent_at < until (exclusive)').optional(),
             q: z.string().describe('Substring match on subject AND body (case-insensitive). Use to find messages on a specific topic.').optional(),
@@ -141,7 +193,7 @@ export function registerMessageTools(server, client) {
             // OFW state isn't changing).
             if (attachments.length === 0 && listDataHintsAtFiles(cached.listData)) {
                 try {
-                    const detail = await client.request('GET', `/pub/v3/messages/${id}`);
+                    const detail = parseOFW(DetailFilesSchema, await client.request('GET', `/pub/v3/messages/${id}`), 'GET /pub/v3/messages/{id} (attachment backfill)');
                     if (Array.isArray(detail.files) && detail.files.length > 0) {
                         await fetchAttachmentMetaForMessage(client, id, detail.files);
                         attachments = listAttachmentsForMessage(id);
@@ -153,7 +205,7 @@ export function registerMessageTools(server, client) {
             }
             return jsonResponse({ ...cached, attachments });
         }
-        const detail = await client.request('GET', `/pub/v3/messages/${encodeURIComponent(args.messageId)}`);
+        const detail = parseOFW(MessageDetailSchema, await client.request('GET', `/pub/v3/messages/${encodeURIComponent(args.messageId)}`), 'GET /pub/v3/messages/{id} (ofw_get_message)');
         const folder = cached?.folder ?? 'inbox';
         const row = {
             id: detail.id,
@@ -175,127 +227,141 @@ export function registerMessageTools(server, client) {
         const attachments = listAttachmentsForMessage(detail.id);
         return jsonResponse({ ...row, attachments });
     });
-    server.registerTool('ofw_send_message', {
-        description: 'Send a message via OurFamilyWizard. To send an existing draft, pass messageId — subject/body/recipientIds become optional overrides (missing fields default to the draft\'s cached values) and the draft is deleted after sending. To send a fresh message, supply subject/body/recipientIds directly. draftId is the legacy spelling of messageId and works the same way. If replyToId is provided, the cache may rewrite it to the latest reply in the same thread (a note is included in the response when this happens). Attach files by passing their fileIds (from ofw_upload_attachment) in myFileIDs. After sending, the tool re-fetches the message from OFW to populate the local cache and link attachments to the new message id.',
-        annotations: { destructiveHint: true },
-        inputSchema: {
-            subject: z.string().describe('Message subject. Required unless messageId/draftId references a cached draft.').optional(),
-            body: z.string().describe('Message body text. Required unless messageId/draftId references a cached draft.').optional(),
-            recipientIds: z.array(z.number()).describe('Array of recipient user IDs (get from ofw_get_profile). Required unless messageId/draftId references a cached draft.').optional(),
-            replyToId: z.number().describe('ID of the message being replied to').optional(),
-            messageId: z.number().describe('ID of an existing draft to send. When set, missing subject/body/recipientIds default to the draft\'s cached values, and the draft is deleted after sending.').optional(),
-            draftId: z.number().describe('Legacy synonym for messageId. If both are passed they must be equal.').optional(),
-            myFileIDs: z.array(z.number()).describe('Attachment file ids (from ofw_upload_attachment) to attach to the message').optional(),
-        },
-    }, async (args) => {
-        if (args.messageId !== undefined && args.draftId !== undefined && args.messageId !== args.draftId) {
-            throw new Error(`messageId (${args.messageId}) and draftId (${args.draftId}) refer to different drafts; pass only one.`);
-        }
-        const draftRef = args.messageId ?? args.draftId;
-        // Best-effort draft lookup: when draftRef points at a cached draft, use
-        // its stored fields (including replyToId) as defaults for anything the
-        // caller didn't supply. The "missing draft" case only matters when we
-        // actually NEED the defaults — a caller passing all fields explicitly
-        // can use draftId as a pure delete-target even on an empty cache.
-        let subject = args.subject;
-        let body = args.body;
-        let recipientIds = args.recipientIds;
-        let draftReplyToId = null;
-        let draftLookupAttempted = false;
-        let draftFound = false;
-        if (draftRef !== undefined) {
-            draftLookupAttempted = true;
-            const draft = getDraft(draftRef);
-            if (draft !== null) {
-                draftFound = true;
-                subject = subject ?? draft.subject;
-                body = body ?? draft.body;
-                recipientIds = recipientIds ?? draft.recipients.map((r) => r.userId);
-                draftReplyToId = draft.replyToId;
+    if (allowSend)
+        server.registerTool('ofw_send_message', {
+            description: 'Send a message via OurFamilyWizard. To send an existing draft, pass messageId — subject/body/recipientIds become optional overrides (missing fields default to the draft\'s cached values) and the draft is deleted after sending. To send a fresh message, supply subject/body/recipientIds directly. draftId is the legacy spelling of messageId and works the same way. If replyToId is provided, the cache may rewrite it to the latest reply in the same thread (a note is included in the response when this happens). Attach files by passing their fileIds (from ofw_upload_attachment) in myFileIDs. After sending, the tool re-fetches the message from OFW to populate the local cache and link attachments to the new message id.',
+            annotations: { destructiveHint: true },
+            inputSchema: {
+                subject: z.string().describe('Message subject. Required unless messageId/draftId references a cached draft.').optional(),
+                body: z.string().describe('Message body text. Required unless messageId/draftId references a cached draft.').optional(),
+                recipientIds: z.array(z.number()).describe('Array of recipient user IDs (get from ofw_get_profile). Required unless messageId/draftId references a cached draft.').optional(),
+                replyToId: z.number().describe('ID of the message being replied to').optional(),
+                messageId: z.number().describe('ID of an existing draft to send. When set, missing subject/body/recipientIds default to the draft\'s cached values, and the draft is deleted after sending.').optional(),
+                draftId: z.number().describe('Legacy synonym for messageId. If both are passed they must be equal.').optional(),
+                myFileIDs: z.array(z.number()).describe('Attachment file ids (from ofw_upload_attachment) to attach to the message').optional(),
+            },
+        }, async (args) => {
+            if (args.messageId !== undefined && args.draftId !== undefined && args.messageId !== args.draftId) {
+                throw new Error(`messageId (${args.messageId}) and draftId (${args.draftId}) refer to different drafts; pass only one.`);
             }
-        }
-        if (subject === undefined || body === undefined || recipientIds === undefined) {
-            if (draftLookupAttempted && !draftFound) {
-                throw new Error(`draft ${draftRef} not found in local cache. Call ofw_sync_messages first, or supply subject/body/recipientIds explicitly.`);
+            const draftRef = args.messageId ?? args.draftId;
+            // Best-effort draft lookup: when draftRef points at a cached draft, use
+            // its stored fields (including replyToId) as defaults for anything the
+            // caller didn't supply. The "missing draft" case only matters when we
+            // actually NEED the defaults — a caller passing all fields explicitly
+            // can use draftId as a pure delete-target even on an empty cache.
+            let subject = args.subject;
+            let body = args.body;
+            let recipientIds = args.recipientIds;
+            let draftReplyToId = null;
+            let draftLookupAttempted = false;
+            let draftFound = false;
+            if (draftRef !== undefined) {
+                draftLookupAttempted = true;
+                const draft = getDraft(draftRef);
+                if (draft !== null) {
+                    draftFound = true;
+                    subject = subject ?? draft.subject;
+                    body = body ?? draft.body;
+                    recipientIds = recipientIds ?? draft.recipients.map((r) => r.userId);
+                    draftReplyToId = draft.replyToId;
+                }
             }
-            const missing = [
-                subject === undefined ? 'subject' : null,
-                body === undefined ? 'body' : null,
-                recipientIds === undefined ? 'recipientIds' : null,
-            ].filter((n) => n !== null).join(', ');
-            throw new Error(`ofw_send_message requires ${missing}. Pass it directly, or pass messageId to default missing fields from a cached draft.`);
-        }
-        // Inherit the draft's replyToId when the caller didn't supply one. A
-        // reply-draft saved with replyToId would otherwise be sent as a
-        // top-level message — silently losing the thread.
-        const requestedReplyTo = args.replyToId ?? draftReplyToId ?? null;
-        let resolvedReplyTo = requestedReplyTo;
-        let chainRootId = null;
-        let rewriteNote = null;
-        if (requestedReplyTo !== null) {
-            resolvedReplyTo = findLatestReplyTip(requestedReplyTo);
-            if (resolvedReplyTo !== requestedReplyTo) {
-                rewriteNote = `replyToId rewritten from ${requestedReplyTo} to ${resolvedReplyTo} (later reply in same thread found in sent cache).`;
+            if (subject === undefined || body === undefined || recipientIds === undefined) {
+                if (draftLookupAttempted && !draftFound) {
+                    throw new Error(`draft ${draftRef} not found in local cache. Call ofw_sync_messages first, or supply subject/body/recipientIds explicitly.`);
+                }
+                const missing = [
+                    subject === undefined ? 'subject' : null,
+                    body === undefined ? 'body' : null,
+                    recipientIds === undefined ? 'recipientIds' : null,
+                ].filter((n) => n !== null).join(', ');
+                throw new Error(`ofw_send_message requires ${missing}. Pass it directly, or pass messageId to default missing fields from a cached draft.`);
             }
-            const parent = getMessage(resolvedReplyTo);
-            chainRootId = parent?.chainRootId ?? parent?.id ?? requestedReplyTo;
-        }
-        const myFileIDs = args.myFileIDs ?? [];
-        const { id: newId, detail, raw } = await postMessageAndRefetch(client, {
-            subject,
-            body,
-            recipientIds,
-            attachments: { myFileIDs },
-            draft: false,
-            includeOriginal: resolvedReplyTo !== null,
-            replyToId: resolvedReplyTo,
-        });
-        let persisted = null;
-        if (newId !== null) {
-            persisted = {
-                id: newId,
-                folder: 'sent',
-                subject: detail.subject ?? subject,
-                fromUser: detail.from?.name ?? '',
-                sentAt: detail.date?.dateTime ?? new Date().toISOString(),
-                recipients: mapRecipients(detail.recipients),
-                body: detail.body ?? body,
-                fetchedBodyAt: new Date().toISOString(),
+            // Inherit the draft's replyToId when the caller didn't supply one. A
+            // reply-draft saved with replyToId would otherwise be sent as a
+            // top-level message — silently losing the thread.
+            const requestedReplyTo = args.replyToId ?? draftReplyToId ?? null;
+            let resolvedReplyTo = requestedReplyTo;
+            let chainRootId = null;
+            let rewriteNote = null;
+            if (requestedReplyTo !== null) {
+                resolvedReplyTo = findLatestReplyTip(requestedReplyTo);
+                if (resolvedReplyTo !== requestedReplyTo) {
+                    rewriteNote = `replyToId rewritten from ${requestedReplyTo} to ${resolvedReplyTo} (later reply in same thread found in sent cache).`;
+                }
+                const parent = getMessage(resolvedReplyTo);
+                chainRootId = parent?.chainRootId ?? parent?.id ?? requestedReplyTo;
+            }
+            const myFileIDs = args.myFileIDs ?? [];
+            const { id: newId, detail, raw } = await postMessageAndRefetch(client, {
+                subject,
+                body,
+                recipientIds,
+                attachments: { myFileIDs },
+                draft: false,
+                includeOriginal: resolvedReplyTo !== null,
                 replyToId: resolvedReplyTo,
-                chainRootId,
-                listData: detail,
-            };
-            upsertMessage(persisted);
-            // Link attached files to the new message in the attachments cache.
-            // We may not have full metadata if the upload happened in a prior
-            // session — fall back to what we know.
-            for (const fileId of myFileIDs) {
-                const existing = getAttachment(fileId);
-                upsertAttachmentForMessage({
-                    fileId,
-                    fileName: existing?.fileName ?? `file-${fileId}`,
-                    label: existing?.label ?? existing?.fileName ?? `file-${fileId}`,
-                    mimeType: existing?.mimeType ?? 'application/octet-stream',
-                    sizeBytes: existing?.sizeBytes ?? null,
-                    metadata: existing?.metadata ?? {},
-                    messageId: newId,
-                });
+            }, SentDetailSchema, 'ofw_send_message');
+            let persisted = null;
+            let verifyNote = null;
+            if (newId !== null) {
+                verifyNote = verifyWriteLanded('message', { subject, body }, detail);
+                persisted = {
+                    id: newId,
+                    folder: 'sent',
+                    subject: detail.subject ?? subject,
+                    fromUser: detail.from?.name ?? '',
+                    sentAt: detail.date?.dateTime ?? new Date().toISOString(),
+                    recipients: mapRecipients(detail.recipients),
+                    body: detail.body ?? body,
+                    fetchedBodyAt: new Date().toISOString(),
+                    replyToId: resolvedReplyTo,
+                    chainRootId,
+                    listData: detail,
+                };
+                upsertMessage(persisted);
+                // Link attached files to the new message in the attachments cache.
+                // We may not have full metadata if the upload happened in a prior
+                // session — fall back to what we know.
+                for (const fileId of myFileIDs) {
+                    const existing = getAttachment(fileId);
+                    upsertAttachmentForMessage({
+                        fileId,
+                        fileName: existing?.fileName ?? `file-${fileId}`,
+                        label: existing?.label ?? existing?.fileName ?? `file-${fileId}`,
+                        mimeType: existing?.mimeType ?? 'application/octet-stream',
+                        sizeBytes: existing?.sizeBytes ?? null,
+                        metadata: existing?.metadata ?? {},
+                        messageId: newId,
+                    });
+                }
             }
-        }
-        if (draftRef !== undefined) {
-            await deleteOFWMessages(client, [draftRef]);
-            deleteDraft(draftRef);
-        }
-        const responseObj = persisted ?? raw;
-        const text = responseObj ? JSON.stringify(responseObj, null, 2) : 'Message sent successfully.';
-        return textResponse(rewriteNote ? `${rewriteNote}\n\n${text}` : text);
-    });
+            // Only clean up the draft once the send is confirmed (the POST response
+            // carried an id). On the unconfirmed path the draft is the user's only
+            // copy of the message — keep it.
+            let unconfirmedNote = null;
+            if (newId === null) {
+                const draftClause = draftRef !== undefined
+                    ? `Draft ${draftRef} was NOT deleted — check`
+                    : 'Check';
+                unconfirmedNote = `WARNING: OFW's send response did not include a message id, so the send could not be confirmed. ${draftClause} ourfamilywizard.com to see whether the message went out before retrying.`;
+            }
+            else if (draftRef !== undefined) {
+                await deleteOFWMessages(client, [draftRef]);
+                deleteDraft(draftRef);
+            }
+            const responseObj = persisted ?? raw;
+            const text = responseObj ? JSON.stringify(responseObj, null, 2) : 'Message sent successfully.';
+            const notes = [rewriteNote, verifyNote, unconfirmedNote].filter((n) => n !== null).join('\n\n');
+            return textResponse(notes ? `${notes}\n\n${text}` : text);
+        });
     server.registerTool('ofw_list_drafts', {
         description: 'List draft messages from the local OurFamilyWizard cache. Call ofw_sync_messages first if the cache is empty.',
         annotations: { readOnlyHint: true },
         inputSchema: {
-            page: z.number().describe('Page number (default 1)').optional(),
-            size: z.number().describe('Drafts per page (default 50)').optional(),
+            page: z.number().int().min(1).describe('Page number (default 1)').optional(),
+            size: z.number().int().min(1).describe('Drafts per page (default 50)').optional(),
         },
     }, async (args) => {
         const page = args.page ?? 1;
@@ -306,92 +372,96 @@ export function registerMessageTools(server, client) {
             : { drafts };
         return jsonResponse(payload);
     });
-    server.registerTool('ofw_save_draft', {
-        description: 'Save a message as a draft in OurFamilyWizard. Recipients are optional. Pass messageId to replace an existing draft — note that under the hood this creates a NEW draft and deletes the old one (OFW\'s update-in-place endpoint silently no-ops while echoing the posted body, so we don\'t use it); the response.id will be the NEW id, not the messageId you passed, and the change is documented in a transparency NOTE in the response. If replyToId is provided, the cache may rewrite it to the latest reply in the thread (note included in response). Attach files by passing their fileIds (from ofw_upload_attachment) in myFileIDs. After saving, the tool re-fetches the draft from OFW to populate the local cache from authoritative server state.',
-        annotations: { readOnlyHint: false },
-        inputSchema: {
-            subject: z.string().describe('Message subject'),
-            body: z.string().describe('Message body text'),
-            recipientIds: z.array(z.number()).describe('Array of recipient user IDs (optional for drafts)').optional(),
-            messageId: z.number().describe('ID of an existing draft to replace (the new draft will have a new id; the old is deleted)').optional(),
-            replyToId: z.number().describe('ID of the message this draft replies to').optional(),
-            myFileIDs: z.array(z.number()).describe('Attachment file ids (from ofw_upload_attachment)').optional(),
-        },
-    }, async (args) => {
-        const requestedReplyTo = args.replyToId ?? null;
-        let resolvedReplyTo = requestedReplyTo;
-        let rewriteNote = null;
-        if (requestedReplyTo !== null) {
-            resolvedReplyTo = findLatestReplyTip(requestedReplyTo);
-            if (resolvedReplyTo !== requestedReplyTo) {
-                rewriteNote = `replyToId rewritten from ${requestedReplyTo} to ${resolvedReplyTo} (later reply in same thread found in sent cache).`;
+    if (allowDrafts)
+        server.registerTool('ofw_save_draft', {
+            description: 'Save a message as a draft in OurFamilyWizard. Recipients are optional. Pass messageId to replace an existing draft — note that under the hood this creates a NEW draft and deletes the old one (OFW\'s update-in-place endpoint silently no-ops while echoing the posted body, so we don\'t use it); the response.id will be the NEW id, not the messageId you passed, and the change is documented in a transparency NOTE in the response. If replyToId is provided, the cache may rewrite it to the latest reply in the thread (note included in response). Attach files by passing their fileIds (from ofw_upload_attachment) in myFileIDs. After saving, the tool re-fetches the draft from OFW to populate the local cache from authoritative server state.',
+            annotations: { readOnlyHint: false },
+            inputSchema: {
+                subject: z.string().describe('Message subject'),
+                body: z.string().describe('Message body text'),
+                recipientIds: z.array(z.number()).describe('Array of recipient user IDs (optional for drafts)').optional(),
+                messageId: z.number().describe('ID of an existing draft to replace (the new draft will have a new id; the old is deleted)').optional(),
+                replyToId: z.number().describe('ID of the message this draft replies to').optional(),
+                myFileIDs: z.array(z.number()).describe('Attachment file ids (from ofw_upload_attachment)').optional(),
+            },
+        }, async (args) => {
+            const requestedReplyTo = args.replyToId ?? null;
+            let resolvedReplyTo = requestedReplyTo;
+            let rewriteNote = null;
+            if (requestedReplyTo !== null) {
+                resolvedReplyTo = findLatestReplyTip(requestedReplyTo);
+                if (resolvedReplyTo !== requestedReplyTo) {
+                    rewriteNote = `replyToId rewritten from ${requestedReplyTo} to ${resolvedReplyTo} (later reply in same thread found in sent cache).`;
+                }
             }
-        }
-        const myFileIDs = args.myFileIDs ?? [];
-        // Deliberately do NOT pass `args.messageId` to OFW's POST payload.
-        // OFW's update-by-messageId path silently no-ops on subsequent
-        // updates while echoing the posted body in the immediate GET — so
-        // there is no honest way to detect a failure from the response.
-        // We always create a fresh draft; if the caller provided a
-        // messageId, we delete the old draft afterward (the "replace" path).
-        const payload = {
-            subject: args.subject,
-            body: args.body,
-            recipientIds: args.recipientIds ?? [],
-            attachments: { myFileIDs },
-            draft: true,
-            includeOriginal: resolvedReplyTo !== null,
-            replyToId: resolvedReplyTo,
-        };
-        const { id: newId, detail, raw } = await postMessageAndRefetch(client, payload);
-        let persisted = null;
-        let replaceNote = null;
-        if (newId !== null) {
-            persisted = {
-                id: newId,
-                subject: detail.subject ?? args.subject,
-                body: detail.body ?? '',
-                recipients: mapRecipients(detail.recipients),
-                replyToId: detail.replyToId ?? resolvedReplyTo,
-                modifiedAt: detail.date?.dateTime ?? new Date().toISOString(),
-                listData: detail,
+            const myFileIDs = args.myFileIDs ?? [];
+            // Deliberately do NOT pass `args.messageId` to OFW's POST payload.
+            // OFW's update-by-messageId path silently no-ops on subsequent
+            // updates while echoing the posted body in the immediate GET — so
+            // there is no honest way to detect a failure from the response.
+            // We always create a fresh draft; if the caller provided a
+            // messageId, we delete the old draft afterward (the "replace" path).
+            const payload = {
+                subject: args.subject,
+                body: args.body,
+                recipientIds: args.recipientIds ?? [],
+                attachments: { myFileIDs },
+                draft: true,
+                includeOriginal: resolvedReplyTo !== null,
+                replyToId: resolvedReplyTo,
             };
-            upsertDraft(persisted);
-            // Replace-path: caller passed messageId, so they want the old draft
-            // gone. Delete it after the new one is safely created+cached.
-            if (args.messageId !== undefined && args.messageId !== newId) {
-                try {
-                    await deleteOFWMessages(client, [args.messageId]);
-                    deleteDraft(args.messageId);
-                    replaceNote = `NOTE: ofw_save_draft replaced draft ${args.messageId} via create-then-delete. The new draft id is ${newId}; the old draft has been deleted. (OFW's update-in-place endpoint silently no-ops on subsequent updates, so we never use it. If you cached the old id anywhere, replace it with the new one.)`;
-                }
-                catch (e) {
-                    replaceNote = `WARNING: New draft ${newId} created successfully, but failed to delete the old draft (${args.messageId}): ${e.message}. You may want to clean it up manually with ofw_delete_draft.`;
+            const { id: newId, detail, raw } = await postMessageAndRefetch(client, payload, SavedDraftDetailSchema, 'ofw_save_draft');
+            let persisted = null;
+            let replaceNote = null;
+            let verifyNote = null;
+            if (newId !== null) {
+                verifyNote = verifyWriteLanded('draft', { subject: args.subject, body: args.body }, detail);
+                persisted = {
+                    id: newId,
+                    subject: detail.subject ?? args.subject,
+                    body: detail.body ?? '',
+                    recipients: mapRecipients(detail.recipients),
+                    replyToId: detail.replyToId ?? resolvedReplyTo,
+                    modifiedAt: detail.date?.dateTime ?? new Date().toISOString(),
+                    listData: detail,
+                };
+                upsertDraft(persisted);
+                // Replace-path: caller passed messageId, so they want the old draft
+                // gone. Delete it after the new one is safely created+cached.
+                if (args.messageId !== undefined && args.messageId !== newId) {
+                    try {
+                        await deleteOFWMessages(client, [args.messageId]);
+                        deleteDraft(args.messageId);
+                        replaceNote = `NOTE: ofw_save_draft replaced draft ${args.messageId} via create-then-delete. The new draft id is ${newId}; the old draft has been deleted. (OFW's update-in-place endpoint silently no-ops on subsequent updates, so we never use it. If you cached the old id anywhere, replace it with the new one.)`;
+                    }
+                    catch (e) {
+                        replaceNote = `WARNING: New draft ${newId} created successfully, but failed to delete the old draft (${args.messageId}): ${e.message}. You may want to clean it up manually with ofw_delete_draft.`;
+                    }
                 }
             }
-        }
-        const responseObj = persisted ?? raw;
-        const text = responseObj ? JSON.stringify(responseObj, null, 2) : 'Draft saved.';
-        const notes = [rewriteNote, replaceNote].filter((n) => n !== null).join('\n\n');
-        return textResponse(notes ? `${notes}\n\n${text}` : text);
-    });
-    server.registerTool('ofw_delete_draft', {
-        description: 'Delete a draft message from OurFamilyWizard. Also removes the draft from the local cache.',
-        annotations: { destructiveHint: true },
-        inputSchema: {
-            messageId: z.number().describe('Draft message ID to delete'),
-        },
-    }, async (args) => {
-        const data = await deleteOFWMessages(client, [args.messageId]);
-        deleteDraft(args.messageId);
-        return data ? jsonResponse(data) : textResponse('Draft deleted.');
-    });
+            const responseObj = persisted ?? raw;
+            const text = responseObj ? JSON.stringify(responseObj, null, 2) : 'Draft saved.';
+            const notes = [rewriteNote, verifyNote, replaceNote].filter((n) => n !== null).join('\n\n');
+            return textResponse(notes ? `${notes}\n\n${text}` : text);
+        });
+    if (allowDrafts)
+        server.registerTool('ofw_delete_draft', {
+            description: 'Delete a draft message from OurFamilyWizard. Also removes the draft from the local cache.',
+            annotations: { destructiveHint: true },
+            inputSchema: {
+                messageId: z.number().describe('Draft message ID to delete'),
+            },
+        }, async (args) => {
+            const data = await deleteOFWMessages(client, [args.messageId]);
+            deleteDraft(args.messageId);
+            return data ? jsonResponse(data) : textResponse('Draft deleted.');
+        });
     server.registerTool('ofw_get_unread_sent', {
         description: 'List sent messages that have not been read by one or more recipients. Reads from local cache; call ofw_sync_messages first if cache is stale.',
         annotations: { readOnlyHint: true },
         inputSchema: {
-            page: z.number().describe('Page (default 1)').optional(),
-            size: z.number().describe('Per page (default 50)').optional(),
+            page: z.number().int().min(1).describe('Page (default 1)').optional(),
+            size: z.number().int().min(1).describe('Per page (default 50)').optional(),
         },
     }, async (args) => {
         const page = args.page ?? 1;
@@ -412,53 +482,54 @@ export function registerMessageTools(server, client) {
         }
         return jsonResponse(unread);
     });
-    server.registerTool('ofw_upload_attachment', {
-        description: 'Upload a local file to OurFamilyWizard\'s "My Files" so it can be attached to a message. Returns the fileId — pass that to ofw_send_message or ofw_save_draft in myFileIDs to attach it. The file is uploaded as PRIVATE (visible only to you) by default; pass shareClass:"SHARED" to share with co-parents directly via the My Files area.',
-        annotations: { destructiveHint: false },
-        inputSchema: {
-            path: z.string().describe('Absolute path to the local file to upload. Tilde (~) is expanded.'),
-            shareClass: z.enum(['PRIVATE', 'SHARED']).describe('Share class (default PRIVATE)').optional(),
-            label: z.string().describe('Display label for the file in OFW (default: filename)').optional(),
-            description: z.string().describe('Description shown in OFW My Files (default: filename)').optional(),
-        },
-    }, async (args) => {
-        const abs = expandPath(args.path);
-        const stat = statSync(abs); // throws if missing
-        if (!stat.isFile())
-            throw new Error(`Not a file: ${abs}`);
-        const fileName = basename(abs);
-        const mime = mimeFromName(fileName);
-        // Build the multipart payload matching the OFW web UI's request shape.
-        const form = new FormData();
-        // fileBlob streams the file off disk (a file-backed Blob) instead of buffering it.
-        form.append('file', await fileBlob(abs, { type: mime }), fileName);
-        form.append('source', 'message');
-        form.append('description', args.description ?? fileName);
-        form.append('label', args.label ?? fileName);
-        form.append('fileName', fileName);
-        form.append('shareClass', args.shareClass ?? 'PRIVATE');
-        const meta = await client.request('POST', '/pub/v3/myfiles/multipart', form);
-        // Cache metadata so subsequent ofw_get_message calls can surface it and
-        // ofw_download_attachment can short-circuit. messageId is 0 (the
-        // not-yet-linked sentinel) until a message actually references this file.
-        upsertAttachmentForMessage({
-            fileId: meta.fileId,
-            fileName: meta.fileName ?? fileName,
-            label: meta.label ?? args.label ?? fileName,
-            mimeType: meta.fileType ?? mime,
-            sizeBytes: typeof meta.sizeInBytes === 'number' ? meta.sizeInBytes : stat.size,
-            metadata: meta,
-            messageId: 0,
-        });
-        return jsonResponse({
-            fileId: meta.fileId,
-            fileName: meta.fileName ?? fileName,
-            mimeType: meta.fileType ?? mime,
-            sizeBytes: meta.sizeInBytes ?? stat.size,
-            shareClass: meta.shareClass ?? args.shareClass ?? 'PRIVATE',
-            note: 'Pass this fileId to ofw_send_message or ofw_save_draft in myFileIDs to attach it.',
+    if (allowDrafts)
+        server.registerTool('ofw_upload_attachment', {
+            description: 'Upload a local file to OurFamilyWizard\'s "My Files" so it can be attached to a message. Returns the fileId — pass that to ofw_send_message or ofw_save_draft in myFileIDs to attach it. The file is uploaded as PRIVATE (visible only to you) by default; pass shareClass:"SHARED" to share with co-parents directly via the My Files area.',
+            annotations: { destructiveHint: false },
+            inputSchema: {
+                path: z.string().describe('Absolute path to the local file to upload. Tilde (~) is expanded.'),
+                shareClass: z.enum(['PRIVATE', 'SHARED']).describe('Share class (default PRIVATE)').optional(),
+                label: z.string().describe('Display label for the file in OFW (default: filename)').optional(),
+                description: z.string().describe('Description shown in OFW My Files (default: filename)').optional(),
+            },
+        }, async (args) => {
+            const abs = expandPath(args.path);
+            const stat = statSync(abs); // throws if missing
+            if (!stat.isFile())
+                throw new Error(`Not a file: ${abs}`);
+            const fileName = basename(abs);
+            const mime = mimeFromName(fileName);
+            // Build the multipart payload matching the OFW web UI's request shape.
+            const form = new FormData();
+            // fileBlob streams the file off disk (a file-backed Blob) instead of buffering it.
+            form.append('file', await fileBlob(abs, { type: mime }), fileName);
+            form.append('source', 'message');
+            form.append('description', args.description ?? fileName);
+            form.append('label', args.label ?? fileName);
+            form.append('fileName', fileName);
+            form.append('shareClass', args.shareClass ?? 'PRIVATE');
+            const meta = parseOFW(UploadedFileSchema, await client.request('POST', '/pub/v3/myfiles/multipart', form), 'POST /pub/v3/myfiles/multipart (ofw_upload_attachment)', 'strict');
+            // Cache metadata so subsequent ofw_get_message calls can surface it and
+            // ofw_download_attachment can short-circuit. messageId is 0 (the
+            // not-yet-linked sentinel) until a message actually references this file.
+            upsertAttachmentForMessage({
+                fileId: meta.fileId,
+                fileName: meta.fileName ?? fileName,
+                label: meta.label ?? args.label ?? fileName,
+                mimeType: meta.fileType ?? mime,
+                sizeBytes: typeof meta.sizeInBytes === 'number' ? meta.sizeInBytes : stat.size,
+                metadata: meta,
+                messageId: 0,
+            });
+            return jsonResponse({
+                fileId: meta.fileId,
+                fileName: meta.fileName ?? fileName,
+                mimeType: meta.fileType ?? mime,
+                sizeBytes: meta.sizeInBytes ?? stat.size,
+                shareClass: meta.shareClass ?? args.shareClass ?? 'PRIVATE',
+                note: 'Pass this fileId to ofw_send_message or ofw_save_draft in myFileIDs to attach it.',
+            });
         });
-    });
     server.registerTool('ofw_download_attachment', {
         description: 'Download an OFW message attachment by fileId. By default, bytes are saved to disk (~/Downloads/ofw-mcp/) and the response carries the absolute path, mime type, and size for the caller to read back. Pass inline:true to skip disk entirely and return the bytes as MCP content blocks — images come back as ImageContent (the model sees them directly); other files come back as an EmbeddedResource blob. Use inline for small files where you want the model to read content immediately and the host is sandboxed; use disk for large files or when you want a persistent local copy. The default for `inline` can be flipped server-side via the OFW_INLINE_ATTACHMENTS env var (set to "true" to make inline the default). fileId comes from attachments[].fileId on ofw_get_message. Override disk destination with OFW_ATTACHMENTS_DIR or saveTo. Re-downloading to the same path is a no-op (disk mode only).',
         annotations: { readOnlyHint: false },