ofw-mcp 2.9.2 → 2.10.0

package/dist/tools/messages.js

@@ -8,7 +8,7 @@ import { buildInlineDelivery, tryExtract } from './delivery.js';
 import { resolveDownloadMime } from './attachments.js';
 import { getAllowMarkRead, getAttachmentsDir, getAutoRefreshStaleReads, getDefaultInlineAttachments, getFetchUnreadBodies, getSyncMaxRequests, getWriteMode, } from '../config.js';
 import { basename, join } from 'node:path';
-import { ApiRecipientSchema, deriveRead, expandPath, hasRealView, jsonErrorResponse, jsonResponse, mapRecipients, postMessageAndRefetch, textResponse, verifyWriteLanded, withReadState } from './_shared.js';
+import { ApiRecipientSchema, deriveRead, expandPath, hasRealView, jsonErrorResponse, jsonResponse, mapRecipients, postMessageAndRefetch, reportsThreaded, reportsUnthreaded, textResponse, threadedReplyTo, verifyWriteLanded, withReadState } from './_shared.js';
 import { parseLenient } from '@chrischall/mcp-utils';
 // Schemas for the load-bearing fields of each /pub/v3 response this file
 // reads (issue #83). Loose: unknown keys pass through into cached listData.
@@ -23,12 +23,24 @@ const SentDetailSchema = z.looseObject({
     date: DateSchema.optional(),
     from: z.looseObject({ name: z.string().optional() }).optional(),
     recipients: z.array(ApiRecipientSchema).optional(),
+    // The threading echo, in BOTH spellings plus showContext — OFW reports the
+    // reply target inconsistently across payloads (see ThreadingEcho in
+    // _shared.ts). Backs the `threaded` verdict on ofw_send_message.
+    replyToId: z.number().nullable().optional(),
+    inReplyTo: z.number().nullable().optional(),
+    showContext: z.boolean().optional(),
 });
 const SavedDraftDetailSchema = z.looseObject({
     subject: z.string().optional(),
     body: z.string().optional(),
     date: DateSchema.optional(),
+    // All three threading-echo fields. Reading ONLY `replyToId` here fired a
+    // false "OurFamilyWizard did not thread this draft" warning on nearly every
+    // threaded save, while the same payload's `inReplyTo`/`showContext` showed
+    // the draft WAS threaded — see threadedReplyTo in _shared.ts.
     replyToId: z.number().nullable().optional(),
+    inReplyTo: z.number().nullable().optional(),
+    showContext: z.boolean().optional(),
     recipients: z.array(ApiRecipientSchema).optional(),
     // Read to audit whether requested myFileIDs actually attached (Defect 3).
     files: z.array(z.number()).optional(),
@@ -357,6 +369,11 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         if (draftRow !== null) {
             const { freshness, serverConfirmed, cacheStatus } = await draftsFreshness(cache);
             return jsonResponse({
+                // Stable identity FIRST — the id below changes on every edit
+                // (create-then-delete), so callers should key off draftKey. Null when
+                // this draft was never written through this tool (e.g. authored in
+                // the web app).
+                draftKey: (await cache.getDraftLineageById(draftRow.id))?.draftKey ?? null,
                 id: draftRow.id,
                 folder: 'drafts',
                 subject: draftRow.subject,
@@ -373,13 +390,9 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                 listData: draftRow.listData,
                 attachments: [],
                 // Concurrency token — pass as expectedRevision to ofw_save_draft /
-                // ofw_delete_draft to assert you are editing THIS version.
+                // ofw_delete_draft / ofw_send_message to assert you are acting on
+                // THIS version.
                 revision: draftRevision(draftRow),
-                // Stable logical identity. Survives the create-then-delete id churn of
-                // editing AND the transition to sent — pass it to ofw_status to ask
-                // "what happened to the thing I was working on?". Null when this draft
-                // was never written through this tool (e.g. authored in the web app).
-                draftKey: (await cache.getDraftLineageById(draftRow.id))?.draftKey ?? null,
                 cacheStatus,
                 // False = this draft's existence and unsent status are remembered from
                 // a cache, not confirmed on OFW. Call ofw_check_freshness before
@@ -489,16 +502,19 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
     });
     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.',
+            description: 'Send a message via OurFamilyWizard — the ONE irreversible operation here, so it carries the strongest guard. TO SEND AN EXISTING DRAFT (the safe default): pass draftId (or messageId — same thing). The tool re-reads the draft from OFW and sends the SERVER\'S version, so what goes out is what is on OurFamilyWizard, not what this session remembers — subject/body act only as explicit overrides. It is guarded exactly like ofw_save_draft: pass expectedRevision to assert which version you are sending; if the draft changed on OFW since you read it — or no longer exists (it may already have been SENT) — the send is REFUSED with the current server content echoed back, and nothing goes out. RECIPIENTS: OurFamilyWizard does not persist recipients on drafts, so recipientIds is usually still required at send time (ids from ofw_get_profile). After the send is CONFIRMED (OFW returned the new message id and the re-fetched sent record matches what was posted), the source draft is deleted automatically; pass deleteDraftOnSuccess:false to keep it. On ANY failure or ambiguity the draft is never deleted — the response carries draftRetained:true with the reason. TO COMPOSE FROM SCRATCH: supply subject/body/recipientIds with no draftId. If replyToId is provided (or inherited from the draft), the cache may rewrite it to the latest reply in the same thread (a note is included when this happens). ATTACHMENTS: when sending by draftId, the server draft\'s own attachments carry over automatically; myFileIDs (from ofw_upload_attachment) overrides or attaches files on a fresh compose. The response leads with sentMessageId and the stable draftKey, and reports threaded (whether OFW actually linked the reply) and draftDeleted.',
             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(),
+                subject: z.string().describe('Message subject. Required unless draftId/messageId is given (then it overrides the server draft\'s subject).').optional(),
+                body: z.string().describe('Message body text. Required unless draftId/messageId is given (then it overrides the server draft\'s body — omit it to send exactly what is on OurFamilyWizard).').optional(),
+                recipientIds: z.array(z.number()).describe('Array of recipient user IDs (get from ofw_get_profile). Usually required even when sending a draft: OurFamilyWizard does not persist recipients on drafts.').optional(),
+                replyToId: z.number().describe('ID of the message being replied to. Defaults to the draft\'s stored reply target when sending by draftId.').optional(),
+                draftId: z.number().describe('ID of an existing draft to send. The draft is re-read from OurFamilyWizard and its SERVER content is sent; missing subject/body default from it. Guarded: a draft that changed since you read it, or that was already sent/deleted, refuses rather than sending blind.').optional(),
+                messageId: z.number().describe('Synonym for draftId (if both are passed they must be equal).').optional(),
+                expectedRevision: z.string().describe('With draftId: the `revision` from ofw_list_drafts / ofw_get_message / ofw_check_freshness for that draft. Asserts you are sending THAT version; if the draft changed on OFW since, the send is refused and the current server content returned. Omit and the tool compares the server against the local cache instead — omitting never means "send whatever is there now".').optional(),
+                deleteDraftOnSuccess: z.boolean().describe('Default true. Delete the source draft after — and ONLY after — the send is confirmed (new message id returned and the re-fetched sent record checks out). Set false to keep the draft. On a failed or unverifiable send the draft is ALWAYS kept, regardless of this flag.').optional(),
+                force: z.boolean().describe('Default false. Send even when the draft changed on OurFamilyWizard since you read it, or its current state could not be read. Only use after showing the user the conflict.').optional(),
+                myFileIDs: z.array(z.number()).describe('Attachment file ids (from ofw_upload_attachment) to attach to the message. When sending by draftId, omit it to carry the server draft\'s own attachments over; passing it overrides them.').optional(),
             },
         }, async (args) => {
             if (args.messageId !== undefined && args.draftId !== undefined && args.messageId !== args.draftId) {
@@ -506,38 +522,67 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             }
             const draftRef = args.messageId ?? args.draftId;
             const cache = cacheProvider();
-            // 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.
+            const deleteOnSuccess = args.deleteDraftOnSuccess ?? true;
             let subject = args.subject;
             let body = args.body;
             let recipientIds = args.recipientIds;
             let draftReplyToId = null;
-            let draftLookupAttempted = false;
-            let draftFound = false;
+            let guardNote = null;
+            let serverDraft;
             if (draftRef !== undefined) {
-                draftLookupAttempted = true;
-                const draft = await cache.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 cachedDraft = await cache.getDraft(draftRef);
+                // The guard runs whenever this call would TRUST the draft (a content
+                // field defaults from it) or DESTROY it (delete after send). Only a call
+                // that overrides every field AND keeps the draft touches nothing that
+                // needs guarding. Sending is the one irreversible operation here, so it
+                // is never less protected than ofw_save_draft.
+                const needsContent = subject === undefined || body === undefined || recipientIds === undefined;
+                if (needsContent || deleteOnSuccess) {
+                    const guard = await guardDestructiveDraftOp({
+                        cache,
+                        draftId: draftRef,
+                        expectedRevision: args.expectedRevision,
+                        force: args.force ?? false,
+                        action: 'send',
+                    });
+                    if (!guard.ok)
+                        return guard.response;
+                    guardNote = guard.note;
+                    serverDraft = guard.server;
+                }
+                // Content defaults come from the SERVER draft the guard just read — the
+                // point of sending by id is that the artifact sent is the artifact on
+                // the server. The cached row is a fallback only for the force paths
+                // where the server copy could not be read (or the guard was skipped).
+                const base = serverDraft ?? cachedDraft;
+                if (base != null) {
+                    subject = subject ?? base.subject;
+                    body = body ?? base.body;
+                    draftReplyToId = base.replyToId;
+                }
+                if (recipientIds === undefined) {
+                    // OFW does not persist recipients on drafts (the server copy routinely
+                    // reports []), so take any NON-EMPTY recipient set we have — server
+                    // first, then cache — and otherwise require the caller to supply one.
+                    // Defaulting to [] would "send" to nobody.
+                    const source = [serverDraft ?? null, cachedDraft].find((s) => s !== null && s !== undefined && s.recipients.some((r) => r.userId !== 0));
+                    if (source != null) {
+                        recipientIds = [...new Set(source.recipients.map((r) => r.userId).filter((id) => id !== 0))];
+                    }
                 }
             }
             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 hint = draftRef === undefined
+                    ? 'Pass them directly, or pass draftId to send an existing draft.'
+                    : missing === 'recipientIds'
+                        ? `Draft ${draftRef} carries no stored recipients — OurFamilyWizard does not persist recipients on drafts, so they must be supplied at send time. Get the co-parent's user id from ofw_get_profile and pass recipientIds.`
+                        : `Draft ${draftRef}'s content was not readable from OurFamilyWizard or the local cache, so it cannot supply the missing fields. Pass them explicitly.`;
+                throw new Error(`ofw_send_message requires ${missing}. ${hint}`);
             }
             // Inherit the draft's replyToId when the caller didn't supply one. A
             // reply-draft saved with replyToId would otherwise be sent as a
@@ -554,7 +599,10 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                 const parent = await cache.getMessage(resolvedReplyTo);
                 chainRootId = parent?.chainRootId ?? parent?.id ?? requestedReplyTo;
             }
-            const myFileIDs = args.myFileIDs ?? [];
+            // Attachments carry over from the SERVER draft the guard read — sending
+            // "the draft as it exists on the server" includes its files, or the send
+            // would silently strip them. Explicit myFileIDs still overrides.
+            const myFileIDs = args.myFileIDs ?? serverDraft?.files ?? [];
             const { id: newId, detail, raw } = await postMessageAndRefetch(client, {
                 subject,
                 body,
@@ -567,19 +615,65 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             let persisted = null;
             let verifyNote = null;
             let sentDraftKey = null;
+            let threaded = false;
+            let threadNote = null;
             if (newId !== null) {
                 verifyNote = verifyWriteLanded('message', { subject, body }, detail);
+                // Threading verdict, from OFW's own echo on the re-fetched sent record.
+                // Both directions demand POSITIVE evidence (see reportsUnthreaded): a
+                // bare `replyToId: null` — OFW's normal shape even on threaded items —
+                // and a total absence of echo fields are both "not echoed", NOT
+                // "dropped". A warning the caller can see is false is a warning it
+                // learns to skip.
+                const echoed = threadedReplyTo(detail);
+                if (resolvedReplyTo === null) {
+                    threaded = reportsThreaded(detail);
+                }
+                else if (reportsThreaded(detail)) {
+                    threaded = true;
+                    if (echoed !== null && echoed !== resolvedReplyTo) {
+                        threadNote = `NOTE: the sent message threads to ${echoed}, not the requested ${resolvedReplyTo} — OurFamilyWizard re-targeted the reply within the thread.`;
+                    }
+                }
+                else if (reportsUnthreaded(detail)) {
+                    threaded = false;
+                    threadNote = `WARNING: the sent message came back UNTHREADED — replyToId ${resolvedReplyTo} was posted but OurFamilyWizard reports no reply linkage on the sent record, so it went out as a new top-level conversation. Verify on ourfamilywizard.com.`;
+                }
+                else {
+                    threaded = true;
+                }
+                // Recipient confirmation is part of "the send is confirmed" (it gates
+                // the draft delete below). Only a NON-EMPTY echo can disconfirm: an
+                // omitted or empty recipients array is "not echoed" (OFW routinely
+                // echoes [] the way it does on drafts), and crying wolf on it would
+                // retain the draft after every ordinary send.
+                const storedRecipients = mapRecipients(detail.recipients);
+                if (Array.isArray(detail.recipients) && detail.recipients.length > 0) {
+                    const landed = new Set(storedRecipients.map((r) => r.userId));
+                    const missingRecipients = recipientIds.filter((rid) => !landed.has(rid));
+                    if (missingRecipients.length > 0) {
+                        verifyNote = [
+                            verifyNote,
+                            `WARNING: the sent record does not list requested recipient id(s) ${missingRecipients.join(', ')}, so the send could not be fully confirmed. Verify on ourfamilywizard.com.`,
+                        ].filter((n) => n !== null).join('\n\n');
+                    }
+                }
                 persisted = {
                     id: newId,
                     folder: 'sent',
                     subject: detail.subject ?? subject,
                     fromUser: detail.from?.name ?? '',
                     sentAt: detail.date?.dateTime ?? new Date().toISOString(),
-                    recipients: mapRecipients(detail.recipients),
+                    recipients: storedRecipients,
                     body: detail.body ?? body,
                     fetchedBodyAt: new Date().toISOString(),
-                    replyToId: resolvedReplyTo,
-                    chainRootId,
+                    // Prefer OFW's own echo of where the reply landed; keep what was
+                    // posted when OFW echoed nothing (sent rows feed findLatestReplyTip,
+                    // and a null would break the chain for a message that IS threaded).
+                    // A positively UNTHREADED send stores null — the chain link OFW says
+                    // does not exist must not be invented.
+                    replyToId: threaded ? echoed ?? resolvedReplyTo : null,
+                    chainRootId: threaded ? chainRootId : null,
                     listData: detail,
                 };
                 await cache.upsertMessage(persisted);
@@ -614,25 +708,66 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                     });
                 }
             }
-            // 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.
+            // Clean up the draft ONLY once the send is confirmed: OFW returned the new
+            // message id AND the re-fetched sent record raised no verification warning
+            // (subject/body landed, requested recipients listed). On any failure or
+            // ambiguity the draft is the user's only reliable copy — keep it and say
+            // why, never silently.
             let unconfirmedNote = null;
+            let draftDeleted = false;
+            let draftRetainedReason = 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.`;
+                if (draftRef !== undefined) {
+                    draftRetainedReason = 'the send could not be confirmed (OFW returned no message id), so the draft is your only reliable copy of the message';
+                }
             }
             else if (draftRef !== undefined) {
-                await deleteOFWMessages(client, [draftRef]);
-                await cache.deleteDraft(draftRef);
+                if (verifyNote !== null) {
+                    draftRetainedReason = 'the sent record could not be fully verified against what was posted (see WARNING above) — the draft is kept until you confirm the send on ourfamilywizard.com';
+                }
+                else if (!deleteOnSuccess) {
+                    draftRetainedReason = 'deleteDraftOnSuccess:false — kept by request';
+                }
+                else {
+                    try {
+                        await deleteOFWMessages(client, [draftRef]);
+                        await cache.deleteDraft(draftRef);
+                        draftDeleted = true;
+                    }
+                    catch (e) {
+                        draftRetainedReason = `the send succeeded but the draft delete failed (${e.message}) — remove it with ofw_delete_draft once you have verified the sent message`;
+                    }
+                }
             }
+            const retainNote = draftRef !== undefined && newId !== null && !draftDeleted
+                ? `NOTE: draft ${draftRef} was retained: ${draftRetainedReason}.`
+                : null;
+            // Leads with the stable identifiers (sentMessageId, draftKey) — the
+            // volatile ids and the full sent row follow.
             const responseObj = persisted === null
-                ? raw
-                : { ...persisted, ...(sentDraftKey !== null ? { draftKey: sentDraftKey, previousId: draftRef } : {}) };
+                ? (draftRef !== undefined
+                    ? { sendConfirmed: false, draftDeleted: false, draftRetained: true, draftRetainedReason, raw }
+                    : raw)
+                : {
+                    sentMessageId: newId,
+                    draftKey: sentDraftKey,
+                    threaded,
+                    ...(draftRef !== undefined
+                        ? {
+                            draftDeleted,
+                            ...(draftDeleted ? {} : { draftRetained: true, draftRetainedReason }),
+                            previousId: draftRef,
+                        }
+                        : {}),
+                    ...persisted,
+                };
             const text = responseObj ? JSON.stringify(responseObj, null, 2) : 'Message sent successfully.';
-            const notes = [rewriteNote, verifyNote, unconfirmedNote].filter((n) => n !== null).join('\n\n');
+            const notes = [guardNote, rewriteNote, verifyNote, threadNote, unconfirmedNote, retainNote]
+                .filter((n) => n !== null).join('\n\n');
             return textResponse(notes ? `${notes}\n\n${text}` : text);
         });
     async function guardDestructiveDraftOp(input) {
@@ -658,7 +793,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             // `.message`, which every Error carries.)
             const reason = e.message;
             if (force) {
-                return { ok: true, note: `WARNING: force:true — proceeded with ${action} on draft ${draftId} even though its current state could not be read from OurFamilyWizard (${reason}). Any newer server-side version was destroyed and is NOT recoverable from this response.` };
+                return { ok: true, note: `WARNING: force:true — proceeded with ${action} on draft ${draftId} even though its current state could not be read from OurFamilyWizard (${reason}). Any newer server-side version was destroyed and is NOT recoverable from this response.`, server: undefined };
             }
             return {
                 ok: false,
@@ -678,7 +813,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             const note = verdict.metadataOnly
                 ? `NOTE: draft ${draftId} was treated as current for this ${action}. Since you read it, OurFamilyWizard normalized connector-authored metadata (${verdict.changedFields.join(', ')}); the subject, body and recipients are unchanged, so this is not a conflict.`
                 : null;
-            return { ok: true, note };
+            return { ok: true, note, server };
         }
         if (force) {
             // Loud, and the overwritten content rides along in the response so it is
@@ -690,6 +825,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             return {
                 ok: true,
                 note: `WARNING: force:true overrode a ${verdict.verdict} freshness verdict on draft ${draftId}. ${verdict.reason} ${echoed}\n\n${JSON.stringify({ overwrittenServerDraft: server === null ? null : { ...server, revision: draftRevision(server) } }, null, 2)}`,
+                server,
             };
         }
         return {
@@ -704,17 +840,41 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         };
     }
     server.registerTool('ofw_list_drafts', {
-        description: 'List draft messages from the local OurFamilyWizard cache. Returns an explicit `complete` boolean describing the RESULT SET: true means "these are ALL the drafts on OurFamilyWizard as of freshness.asOf" — check it before saying "you have N drafts". Each draft carries its `draftKey` (stable across the create-then-delete churn of editing) when one is known. An empty result from a cache that is not verified-fresh is REFUSED (result:"UNVERIFIED_EMPTY"); pass autoRefresh:true to sync and answer instead. For a live, one-call answer prefer ofw_status(includeDraftInventory:true).',
+        description: 'List draft messages, verified against OurFamilyWizard in ONE call: when the local drafts cache is not verified-fresh, a cheap drafts sync runs first by default (verify:true), so the answer is server-confirmed without a second call. Pass verify:false to answer purely from the cache (no OFW requests). Returns an explicit `complete` boolean describing the RESULT SET: true means "these are ALL the drafts on OurFamilyWizard as of freshness.asOf" — check it before saying "you have N drafts". Each draft carries its `draftKey` (stable across the create-then-delete churn of editing) when one is known. An empty result from a cache that is not verified-fresh is REFUSED (result:"UNVERIFIED_EMPTY"); pass autoRefresh:true to sync and answer instead.',
         annotations: { readOnlyHint: false },
         inputSchema: {
             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(),
+            verify: z.boolean().describe('Default true: when the drafts cache is not verified-fresh, run a drafts sync first (cheap — one list page plus one detail per draft) so the response is server-confirmed in one call. Set false to serve straight from the local cache with no OFW requests.').optional(),
             autoRefresh: z.boolean().describe(AUTO_REFRESH_DESC).optional(),
         },
     }, async (args) => {
         const page = args.page ?? 1;
         const size = args.size ?? 50;
         const cache = cacheProvider();
+        // Auto-verify (default on): drafts change rarely but INVISIBLY — a web-app
+        // edit bumps no timestamp — so an aged cache used to answer "unverified,
+        // don't state a count" and force a second call. The drafts walk is cheap
+        // enough to just run it. Two honesty rules: `autoVerified` is derived from
+        // the POST-sync cache status, because a budget-paused walk applies nothing
+        // and claiming autoVerified next to serverConfirmed:false would be one
+        // payload contradicting itself; and a sync that CANNOT run (OFW/network
+        // down) degrades to the honestly-labelled cache answer below rather than
+        // turning a previously infallible cache read into a hard error.
+        let autoVerified = false;
+        let verifyNote = null;
+        if (args.verify ?? true) {
+            const { cacheStatus } = await draftsFreshness(cache);
+            if (cacheStatus !== 'fresh') {
+                try {
+                    await syncAll(client, { folders: ['drafts'], maxRequests: getSyncMaxRequests() }, cache);
+                    autoVerified = await getDraftsCacheStatus(cache) === 'fresh';
+                }
+                catch (e) {
+                    verifyNote = `The automatic drafts verification could not reach OurFamilyWizard (${e.message}). Answering from the local cache — the freshness block below labels its age, and an empty result will still be refused rather than reported as an absence.`;
+                }
+            }
+        }
         const { value, refreshed, unverifiedEmpty } = await guardedCacheRead({
             client,
             cache,
@@ -748,7 +908,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                 freshness: value.freshness,
                 refreshed,
                 remedy: 'Call ofw_sync_messages(folders:["drafts"]) and retry, re-call with autoRefresh:true, or use ofw_status(includeDraftInventory:true) for a single live answer.',
-                extra: { page, size },
+                extra: { page, size, ...(verifyNote !== null ? { verifyNote } : {}) },
             });
         }
         const { drafts, total, freshness, serverConfirmed } = value;
@@ -771,11 +931,17 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         if (refreshed) {
             payload.autoRefreshed = true;
         }
+        if (autoVerified) {
+            payload.autoVerified = true;
+        }
+        if (verifyNote !== null) {
+            payload.verifyNote = verifyNote;
+        }
         return jsonResponse(payload);
     });
     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 that also lists which fields (subject/body/recipients/replyToId/attachments) were carried over. 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, and the returned `revision` reflects that authoritative state (so it will match on your next edit). FIELD PRESERVATION: the response echoes the effective threading (replyToId/inReplyTo) and, whenever OFW did not carry over a requested replyToId, recipient or attachment, a `warnings[]` entry naming what was dropped — never a silent null. SAFETY: because replacing DESTROYS the old draft rather than merging, passing messageId first re-reads that draft from OFW and REFUSES the write if its subject/body/recipients changed since you read it (drafts edited in the OFW web app do not bump any timestamp, so the local cache can be silently behind). A pure replyToId normalization by OFW is NOT treated as a conflict. The refusal returns the current server body under serverBody — merge your edit into it and retry with expectedRevision.',
+            description: 'Save a message as a draft in OurFamilyWizard. RECIPIENTS: OurFamilyWizard does NOT persist recipients on drafts — recipientIds are accepted but the saved draft comes back with none (documented OFW behavior, noted once in the response, not warned about; supply recipientIds at send time instead). IDENTITY: the response leads with `draftKey`, the stable identity that survives editing — key off it, because the `id` changes on EVERY edit (replacing a draft creates a NEW draft and deletes the old one; OFW\'s update-in-place endpoint silently no-ops, so we never use it). Pass messageId to replace an existing draft; the response.id will be the NEW id, and a transparency NOTE documents the swap and which fields were carried over. THREADING: if replyToId is provided, the cache may rewrite it to the latest reply in the thread (note included). The threading verdict is read from OFW\'s full echo (replyToId/inReplyTo/showContext) — a warning appears ONLY when the reply linkage was genuinely dropped or re-targeted, and the response\'s top-level replyToId/inReplyTo always agree with its listData. Attach files via myFileIDs (from ofw_upload_attachment). After saving, the tool re-fetches the draft from OFW, and the returned `revision` reflects that authoritative state (so it will match on your next edit). SAFETY: because replacing DESTROYS the old draft rather than merging, passing messageId first re-reads that draft from OFW and REFUSES the write if its subject/body/recipients changed since you read it (drafts edited in the OFW web app do not bump any timestamp, so the local cache can be silently behind). A pure replyToId normalization by OFW is NOT treated as a conflict. The refusal returns the current server body under serverBody — merge your edit into it and retry with expectedRevision.',
             annotations: { readOnlyHint: false },
             inputSchema: {
                 subject: z.string().describe('Message subject'),
@@ -833,6 +999,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             let persisted = null;
             let replaceNote = null;
             let verifyNote = null;
+            let recipientsNote = null;
             let newRevision = null;
             let draftKey = null;
             // Fields accepted on the write that the saved draft must carry — or their
@@ -845,9 +1012,12 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                 // normalizes/drops threading after a save, and masking that with our own
                 // intent (the old `detail.replyToId ?? resolvedReplyTo`) both returned a
                 // revision that was stale on arrival (Defect 1) and hid a dropped reply
-                // link (Defect 3). `?? null` keeps a genuinely-echoed value and reflects a
-                // null/absent one honestly.
-                const effectiveReplyTo = detail.replyToId ?? null;
+                // link (Defect 3). The echo is read via threadedReplyTo because OFW
+                // reports the target as `inReplyTo` on payloads where `replyToId` is
+                // null — reading only `replyToId` fired a false "did not thread" warning
+                // on nearly every threaded save while the same response's listData
+                // showed inReplyTo populated.
+                const effectiveReplyTo = threadedReplyTo(detail);
                 const storedRecipients = mapRecipients(detail.recipients);
                 persisted = {
                     id: newId,
@@ -892,26 +1062,40 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                 });
                 // Audit every field the caller supplied against what actually landed, so a
                 // silent normalization becomes a visible warning rather than a surprise.
-                if (resolvedReplyTo !== null && effectiveReplyTo !== resolvedReplyTo) {
+                // The verdict comes from the FULL threading echo (replyToId, inReplyTo,
+                // showContext) — a draft reporting inReplyTo (or showContext:true) IS
+                // threaded, and warning about it anyway is the false positive that
+                // trained callers to skim warnings. The "dropped" warning demands
+                // POSITIVE evidence (reportsUnthreaded): a bare `replyToId: null` or a
+                // detail omitting every echo field is "not echoed", never "dropped".
+                // The stored replyToId is still the server echo (null when unreported) —
+                // masking it with intent was Defect 1, and the revision must hash what
+                // the next sync will read.
+                if (resolvedReplyTo !== null && effectiveReplyTo !== resolvedReplyTo && reportsUnthreaded(detail)) {
+                    const rewrittenFrom = requestedReplyTo !== resolvedReplyTo ? ` (rewritten from ${requestedReplyTo})` : '';
+                    warnings.push(`replyToId was requested as ${resolvedReplyTo}${rewrittenFrom} but the saved draft came back with replyToId null — OurFamilyWizard did not thread this draft (its inReplyTo/showContext are empty). The subject and body were saved; only the reply linkage was dropped. If threading matters, verify on ourfamilywizard.com.`);
+                }
+                else if (resolvedReplyTo !== null && effectiveReplyTo !== null && effectiveReplyTo !== resolvedReplyTo) {
+                    // OFW RE-TARGETED the link to another message in the thread — the
+                    // draft IS threaded, just not to the requested id, and the inReplyTo
+                    // in this response reflects where it actually landed.
                     const rewrittenFrom = requestedReplyTo !== resolvedReplyTo ? ` (rewritten from ${requestedReplyTo})` : '';
-                    // Two different outcomes reach this branch, and they need different
-                    // warnings. OFW either DROPPED the link (null) or RE-TARGETED it to
-                    // another message in the thread. Describing both as "did not thread
-                    // this draft (its inReplyTo/showContext will be empty)" contradicted
-                    // the non-null inReplyTo the same response echoes — and a warning the
-                    // caller can see is false is a warning it learns to skip.
-                    const outcome = effectiveReplyTo === null
-                        ? 'OurFamilyWizard did not thread this draft (its inReplyTo/showContext will be empty). The subject and body were saved; only the reply linkage was dropped.'
-                        : `OurFamilyWizard re-targeted the reply to message ${effectiveReplyTo} instead. The draft IS threaded — to that message, not the one requested — and the inReplyTo in this response reflects where it actually landed.`;
-                    warnings.push(`replyToId was requested as ${resolvedReplyTo}${rewrittenFrom} but the saved draft came back with replyToId ${effectiveReplyTo === null ? 'null' : effectiveReplyTo} — ${outcome} If threading matters, verify on ourfamilywizard.com.`);
+                    warnings.push(`replyToId was requested as ${resolvedReplyTo}${rewrittenFrom} but the saved draft came back with replyToId ${effectiveReplyTo} — OurFamilyWizard re-targeted the reply to message ${effectiveReplyTo} instead. The draft IS threaded — to that message, not the one requested. If threading matters, verify on ourfamilywizard.com.`);
                 }
-                // Only warn on recipients/attachments when the detail actually reported
-                // them — an omitted array is "not echoed", not "dropped", and crying wolf
-                // there would desensitize the caller to the real drops.
-                if (args.recipientIds !== undefined && Array.isArray(detail.recipients)) {
+                // Recipients: OFW does NOT persist recipients on drafts — the saved copy
+                // routinely comes back with [] no matter what was posted. That is
+                // documented OFW behavior (and doubles as an accidental-send guard), so
+                // it gets a one-line NOTE, not a per-call WARNING that cries wolf on
+                // every save. A PARTIAL echo (some stored, but not what was asked) is a
+                // genuine drop and still warns. Both only when the detail actually
+                // reported recipients — an omitted array is "not echoed", not "dropped".
+                if (args.recipientIds !== undefined && args.recipientIds.length > 0 && Array.isArray(detail.recipients)) {
                     const requested = [...new Set(args.recipientIds)].sort((a, b) => a - b);
                     const stored = [...new Set(storedRecipients.map((r) => r.userId))].sort((a, b) => a - b);
-                    if (requested.join(',') !== stored.join(',')) {
+                    if (stored.length === 0) {
+                        recipientsNote = 'NOTE: OurFamilyWizard does not persist recipients on drafts — the recipientIds you passed were accepted but are not stored on the draft (documented OFW behavior, not an error; it also means a draft cannot be sent by accident). Supply recipientIds when you send: ofw_send_message requires them when the draft carries none.';
+                    }
+                    else if (requested.join(',') !== stored.join(',')) {
                         warnings.push(`recipientIds were requested as [${requested.join(', ')}] but the saved draft has [${stored.join(', ')}]. Verify the recipients on ourfamilywizard.com.`);
                     }
                 }
@@ -928,7 +1112,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                     try {
                         await deleteOFWMessages(client, [args.messageId]);
                         await cache.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.) Fields carried over to the new draft: subject, body, recipients (${persisted.recipients.length}), replyToId (${persisted.replyToId === null ? 'none' : persisted.replyToId}), attachments (${myFileIDs.length}).${warnings.length > 0 ? ' See warnings above for any field OurFamilyWizard did not carry over.' : ''}`;
+                        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. The draftKey is UNCHANGED — key off it rather than the volatile id, which changes on every edit. (OFW's update-in-place endpoint silently no-ops on subsequent updates, so we never use it.) Fields carried over to the new draft: subject, body, recipients (${persisted.recipients.length}), replyToId (${persisted.replyToId === null ? 'none' : persisted.replyToId}), attachments (${myFileIDs.length}).${warnings.length > 0 ? ' See warnings above for any field OurFamilyWizard did not carry over.' : ''}`;
                     }
                     catch (e) {
                         // Partial-failure safety: the new draft is already created and
@@ -940,28 +1124,29 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             }
             // The draft was just re-fetched from OFW by postMessageAndRefetch, so this
             // one row IS server-confirmed regardless of the drafts folder's overall
-            // cache freshness. `inReplyTo` echoes the effective threading alongside the
-            // volatile `id`, and `warnings` names any requested field that did not land.
+            // cache freshness. The response LEADS with `draftKey` (stable across the
+            // create-then-delete id churn of editing — key off it, not `id`) and the
+            // `revision` concurrency token; the volatile `id` is carried further down
+            // as an implementation detail. `inReplyTo` echoes the effective threading,
+            // and `warnings` names any requested field that did not land.
             const responseObj = persisted !== null
                 ? {
+                    draftKey,
+                    revision: newRevision,
                     ...persisted,
                     inReplyTo: persisted.replyToId,
-                    revision: newRevision,
-                    // The id above is volatile — it changes on every edit. `draftKey` is
-                    // not: pass it to ofw_status to resolve the chain's CURRENT id, or to
-                    // find out that the draft was sent and when.
-                    draftKey,
                     previousId: args.messageId ?? null,
                     cacheStatus: 'fresh',
                     serverConfirmed: true,
                     ...(warnings.length > 0 ? { warnings } : {}),
+                    ...(recipientsNote !== null ? { recipientsNote } : {}),
                 }
                 : raw;
             const text = responseObj ? JSON.stringify(responseObj, null, 2) : 'Draft saved.';
             const warnNote = warnings.length > 0
                 ? `WARNING: ${warnings.join('\n\n')}`
                 : null;
-            const notes = [forceNote, rewriteNote, verifyNote, warnNote, replaceNote]
+            const notes = [forceNote, rewriteNote, verifyNote, warnNote, recipientsNote, replaceNote]
                 .filter((n) => n !== null).join('\n\n');
             return textResponse(notes ? `${notes}\n\n${text}` : text);
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ofw-mcp",
-  "version": "2.9.2",
+  "version": "2.10.0",
   "license": "MIT",
   "mcpName": "io.github.chrischall/ofw-mcp",
   "description": "OurFamilyWizard MCP server for Claude — developed and maintained by AI (Claude Code)",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/ofw-mcp",
     "source": "github"
   },
-  "version": "2.9.2",
+  "version": "2.10.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "ofw-mcp",
-      "version": "2.9.2",
+      "version": "2.10.0",
       "transport": {
         "type": "stdio"
       },