ofw-mcp 2.4.4 → 2.6.3

package/dist/tools/calendar.js

@@ -1,9 +1,113 @@
 import { z } from 'zod';
 import { jsonResponse, textResponse } from './_shared.js';
-import { getWriteMode } from '../config.js';
+import { getCalendarWritesAllowed } from '../config.js';
+import { parseLenient } from '@chrischall/mcp-utils';
+// OFW's real event-write API (reverse-engineered from the web app bundle):
+//   POST   /pub/v3/events                       create — 201 with the full event
+//   GET    /pub/v3/events/{eventRecurrenceId}   detail
+//   PUT    /pub/v3/events/{eventRecurrenceId}   update — full payload, not a patch
+//   DELETE /pub/v3/events/{eventRecurrenceId}?includeFuture=<bool>
+// The id in every URL is `eventRecurrenceId` — the same value calendar
+// listings expose as `id`. (`eventId` in the response is a different,
+// internal identifier; never put it in a URL.)
+// Payload gotchas: dates are `YYYY-MM-DD` with separate `HH:mm` times;
+// privacy is `publicFlag` (true = shared with co-parent); parent ids must be
+// OMITTED when unset — the web form's "0" placeholders draw a 409
+// "Must be a parent" from the API.
+const ofwDate = z.looseObject({ dateTime: z.string() });
+const userRef = z.looseObject({ userId: z.number() });
+const eventDetailSchema = z.looseObject({
+    eventRecurrenceId: z.number(),
+    title: z.string(),
+    allDay: z.boolean(),
+    publicFlag: z.boolean(),
+    startDate: ofwDate,
+    endDate: ofwDate,
+    location: z.string().nullish(),
+    notes: z.string().nullish(),
+    reminderMinutes: z.number().nullish(),
+    children: z.array(userRef).nullish(),
+    eventParent: userRef.nullish(),
+    dropOffParent: userRef.nullish(),
+    pickUpParent: userRef.nullish(),
+});
+const eventWriteFields = {
+    startDate: z.string().describe('Start date YYYY-MM-DD'),
+    endDate: z.string().describe('End date YYYY-MM-DD (default: startDate)').optional(),
+    startTime: z.string().describe('Start time HH:mm, 24-hour (required unless allDay)').optional(),
+    endTime: z.string().describe('End time HH:mm, 24-hour (required unless allDay)').optional(),
+    allDay: z.boolean().optional(),
+    privateEvent: z.boolean().describe('true = visible only to you; default false = shared with co-parent').optional(),
+    location: z.string().optional(),
+    notes: z.string().optional(),
+    reminderMinutes: z.number().int().min(0).optional(),
+    children: z.array(z.number()).describe('Child userIds to tag (see ofw_get_profile)').optional(),
+    eventParentId: z.number().describe("userId of the parent the event is 'for'").optional(),
+    dropOffParentId: z.number().describe('userId of the drop-off parent').optional(),
+    pickUpParentId: z.number().describe('userId of the pick-up parent').optional(),
+};
+function buildEventPayload(a) {
+    const allDay = a.allDay ?? false;
+    if (!allDay && (!a.startTime || !a.endTime)) {
+        throw new Error('startTime and endTime (HH:mm) are required unless allDay is true');
+    }
+    const payload = {
+        title: a.title,
+        startDate: a.startDate,
+        endDate: a.endDate ?? a.startDate,
+        // The web form always sends times; for all-day events it uses 01:00/02:00
+        // placeholders that OFW ignores.
+        startTime: a.startTime ?? '01:00',
+        endTime: a.endTime ?? '02:00',
+        allDay,
+        publicFlag: !(a.privateEvent ?? false),
+    };
+    if (a.location)
+        payload.location = a.location;
+    if (a.notes)
+        payload.notes = a.notes;
+    if (a.reminderMinutes !== undefined)
+        payload.reminderMinutes = String(a.reminderMinutes);
+    // Omitted `children` PRESERVES existing tags on PUT; an explicit [] CLEARS
+    // them (verified live 2026-07-13) — so send the array whenever it's defined.
+    if (a.children !== undefined)
+        payload.children = a.children;
+    if (a.eventParentId !== undefined)
+        payload.eventParentId = String(a.eventParentId);
+    if (a.dropOffParentId !== undefined)
+        payload.dropOffParentId = String(a.dropOffParentId);
+    if (a.pickUpParentId !== undefined)
+        payload.pickUpParentId = String(a.pickUpParentId);
+    return payload;
+}
+// Map a detail response back onto write-args so ofw_update_event can send the
+// full payload OFW's PUT expects while the caller only names the changes.
+function detailToWriteArgs(d) {
+    const [startDate, startClock] = d.startDate.dateTime.split('T');
+    const [endDate, endClock] = d.endDate.dateTime.split('T');
+    return {
+        title: d.title,
+        startDate,
+        endDate,
+        startTime: (startClock ?? '01:00:00').slice(0, 5),
+        endTime: (endClock ?? '02:00:00').slice(0, 5),
+        allDay: d.allDay,
+        privateEvent: !d.publicFlag,
+        location: d.location ?? undefined,
+        notes: d.notes ?? undefined,
+        reminderMinutes: d.reminderMinutes ?? undefined,
+        // Untagged (nullish or empty) → undefined, so the merged PUT omits the
+        // field (omission preserves; only a CALLER-supplied [] should clear).
+        children: d.children?.length ? d.children.map((c) => c.userId) : undefined,
+        eventParentId: d.eventParent?.userId,
+        dropOffParentId: d.dropOffParent?.userId,
+        pickUpParentId: d.pickUpParent?.userId,
+    };
+}
 export function registerCalendarTools(server, client) {
-    // Calendar writes land on the court-visible record — OFW_WRITE_MODE 'all' only.
-    const allowWrites = getWriteMode() === 'all';
+    // Calendar writes land on the court-visible record with no draft stage, but
+    // events are reversible — 'all' mode, or 'drafts' + OFW_CALENDAR_WRITES=true.
+    const allowWrites = getCalendarWritesAllowed();
     server.registerTool('ofw_list_events', {
         description: 'List OurFamilyWizard calendar events in a date range',
         annotations: { readOnlyHint: true },
@@ -19,53 +123,65 @@ export function registerCalendarTools(server, client) {
     });
     if (allowWrites)
         server.registerTool('ofw_create_event', {
-            description: 'Create a calendar event in OurFamilyWizard',
+            description: 'Create a calendar event in OurFamilyWizard. Unless privateEvent is true, the event is immediately visible to the co-parent — there is no draft stage.',
             annotations: { destructiveHint: false },
             inputSchema: {
                 title: z.string(),
-                startDate: z.string().describe('ISO datetime string'),
-                endDate: z.string().describe('ISO datetime string'),
-                allDay: z.boolean().optional(),
-                location: z.string().optional(),
-                reminder: z.string().describe('Reminder setting (e.g. "1 hour before")').optional(),
-                privateEvent: z.boolean().optional(),
-                eventFor: z.string().describe('neither | parent1 | parent2').optional(),
-                dropOffParent: z.string().optional(),
-                pickUpParent: z.string().optional(),
-                children: z.array(z.number()).describe('Array of child IDs').optional(),
+                ...eventWriteFields,
             },
         }, async (args) => {
-            const data = await client.request('POST', '/pub/v1/calendar/events', args);
-            return jsonResponse(data);
+            const raw = await client.request('POST', '/pub/v3/events', buildEventPayload(args));
+            const event = parseLenient(eventDetailSchema, raw, { label: 'ofw-mcp', context: 'POST /pub/v3/events', mode: 'strict' });
+            return jsonResponse({
+                note: `Event created. Use eventRecurrenceId ${event.eventRecurrenceId} as eventId for ofw_update_event/ofw_delete_event.`,
+                event,
+            });
         });
     if (allowWrites)
         server.registerTool('ofw_update_event', {
-            description: 'Update an existing OurFamilyWizard calendar event',
+            description: 'Update an existing OurFamilyWizard calendar event. Fetches the event, applies the given changes, and writes the merged result back (OFW has no partial update).',
             annotations: { destructiveHint: true },
             inputSchema: {
-                eventId: z.string(),
+                eventId: z.string().describe('Event id — the `id` from ofw_list_events / eventRecurrenceId from ofw_create_event'),
                 title: z.string().optional(),
-                startDate: z.string().optional(),
-                endDate: z.string().optional(),
-                allDay: z.boolean().optional(),
-                location: z.string().optional(),
-                reminder: z.string().optional(),
-                privateEvent: z.boolean().optional(),
+                startDate: eventWriteFields.startDate.optional(),
+                endDate: eventWriteFields.endDate,
+                startTime: eventWriteFields.startTime,
+                endTime: eventWriteFields.endTime,
+                allDay: eventWriteFields.allDay,
+                privateEvent: eventWriteFields.privateEvent,
+                location: eventWriteFields.location,
+                notes: eventWriteFields.notes,
+                reminderMinutes: eventWriteFields.reminderMinutes,
+                children: z.array(z.number()).describe('Child userIds to tag; pass [] to remove all child tags (omit to keep current tags)').optional(),
+                eventParentId: eventWriteFields.eventParentId,
+                dropOffParentId: eventWriteFields.dropOffParentId,
+                pickUpParentId: eventWriteFields.pickUpParentId,
             },
         }, async (args) => {
-            const { eventId, ...updateData } = args;
-            const data = await client.request('PUT', `/pub/v1/calendar/events/${encodeURIComponent(eventId)}`, updateData);
-            return jsonResponse(data);
+            const { eventId, ...changes } = args;
+            const id = encodeURIComponent(eventId);
+            const rawDetail = await client.request('GET', `/pub/v3/events/${id}`);
+            const current = parseLenient(eventDetailSchema, rawDetail, { label: 'ofw-mcp', context: `GET /pub/v3/events/${eventId}`, mode: 'strict' });
+            const defined = Object.fromEntries(Object.entries(changes).filter(([, v]) => v !== undefined));
+            const merged = { ...detailToWriteArgs(current), ...defined };
+            await client.request('PUT', `/pub/v3/events/${id}`, buildEventPayload(merged));
+            // PUT responses aren't documented — re-fetch the detail as authoritative state.
+            const rawAfter = await client.request('GET', `/pub/v3/events/${id}`);
+            const event = parseLenient(eventDetailSchema, rawAfter, { label: 'ofw-mcp', context: `GET /pub/v3/events/${eventId} (post-update)`, mode: 'strict' });
+            return jsonResponse({ note: 'Event updated; returning re-fetched event state.', event });
         });
     if (allowWrites)
         server.registerTool('ofw_delete_event', {
             description: 'Delete an OurFamilyWizard calendar event',
             annotations: { destructiveHint: true },
             inputSchema: {
-                eventId: z.string().describe('Event ID to delete'),
+                eventId: z.string().describe('Event id — the `id` from ofw_list_events / eventRecurrenceId from ofw_create_event'),
+                includeFuture: z.boolean().describe('For repeating events: also delete future occurrences (default false)').optional(),
             },
         }, async (args) => {
-            await client.request('DELETE', `/pub/v1/calendar/events/${encodeURIComponent(args.eventId)}`);
+            const includeFuture = args.includeFuture ?? false;
+            await client.request('DELETE', `/pub/v3/events/${encodeURIComponent(args.eventId)}?includeFuture=${includeFuture}`);
             return textResponse(`Event ${args.eventId} deleted`);
         });
 }

package/dist/tools/messages.js

@@ -1,11 +1,8 @@
 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, 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 { ApiRecipientSchema, expandPath, jsonResponse, mapRecipients, postMessageAndRefetch, textResponse, verifyWriteLanded } from './_shared.js';
+import { getAttachmentsDir, getDefaultInlineAttachments, getSyncMaxRequests, getWriteMode } from '../config.js';
+import { basename, join } from 'node:path';
+import { ApiRecipientSchema, expandPath, hasRealView, jsonResponse, mapRecipients, postMessageAndRefetch, textResponse, verifyWriteLanded } 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.
@@ -38,6 +35,10 @@ const MessageDetailSchema = z.looseObject({
     from: z.looseObject({ name: z.string().optional() }).optional(),
     files: z.array(z.number()).optional(),
     recipients: z.array(ApiRecipientSchema).optional(),
+    // The detail payload carries its own owning folder ({id, name}). We read the
+    // id to label a live-fetched message sent-vs-inbox instead of blindly
+    // defaulting to inbox — see the folder derivation in ofw_get_message.
+    folder: z.looseObject({ id: z.number() }).optional(),
 });
 // Attachment-backfill detail fetch reads only `files`.
 const DetailFilesSchema = z.looseObject({ files: z.array(z.number()).optional() });
@@ -51,33 +52,6 @@ const UploadedFileSchema = z.looseObject({
     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 = {
-    '.pdf': 'application/pdf',
-    '.png': 'image/png',
-    '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
-    '.gif': 'image/gif',
-    '.webp': 'image/webp',
-    '.heic': 'image/heic',
-    '.txt': 'text/plain',
-    '.md': 'text/markdown',
-    '.csv': 'text/csv',
-    '.html': 'text/html', '.htm': 'text/html',
-    '.json': 'application/json',
-    '.xml': 'application/xml',
-    '.doc': 'application/msword',
-    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
-    '.xls': 'application/vnd.ms-excel',
-    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
-    '.ppt': 'application/vnd.ms-powerpoint',
-    '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
-    '.zip': 'application/zip',
-    '.ics': 'text/calendar',
-};
-function mimeFromName(name) {
-    return MIME_BY_EXT[extname(name).toLowerCase()] ?? 'application/octet-stream';
-}
 // The list endpoint payload (cached as `listData`) reports attachments via
 // `files: <count>` (a number) — the actual fileIds only appear on the detail
 // endpoint as `files: [number, ...]`. Some intermediate shapes return an
@@ -92,7 +66,7 @@ function listDataHintsAtFiles(listData) {
         return ld.files.length > 0;
     return false;
 }
-export function registerMessageTools(server, client) {
+export function registerMessageTools(server, client, cacheProvider, attachmentIO) {
     // 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
@@ -135,9 +109,10 @@ export function registerMessageTools(server, client) {
                 note: 'folderId must be "inbox", "sent", or "both". Numeric OFW folder IDs are not supported by the cache.',
             });
         }
+        const cache = cacheProvider();
         const filter = { folder, since: args.since, until: args.until, q: args.q };
-        const total = countMessages(filter);
-        const messages = listMessages({ ...filter, page, size });
+        const total = await cache.countMessages(filter);
+        const messages = await cache.listMessages({ ...filter, page, size });
         const payload = { messages, total, page, size };
         if (total === 0) {
             payload.note = 'No messages match these filters. If you expected results, check ofw_sync_messages was run, or relax the filters.';
@@ -155,13 +130,14 @@ export function registerMessageTools(server, client) {
         },
     }, async (args) => {
         const id = Number(args.messageId);
+        const cache = cacheProvider();
         // Draft routing: if this id is in the drafts cache, return a
         // MessageRow-shaped synthesis built from the draft. The drafts table
         // is the source of truth for draft bodies (sync keeps it fresh);
         // the messages-table cache for the same id is stale by construction
         // when ofw_get_message was called on a draft id before sync caught
         // up — see syncDrafts, which also evicts these stale rows.
-        const draftRow = getDraft(id);
+        const draftRow = await cache.getDraft(id);
         if (draftRow !== null) {
             return jsonResponse({
                 id: draftRow.id,
@@ -181,9 +157,35 @@ export function registerMessageTools(server, client) {
                 attachments: [],
             });
         }
-        const cached = getMessage(id);
+        const cached = await cache.getMessage(id);
         if (cached && cached.body !== null) {
-            let attachments = listAttachmentsForMessage(id);
+            let row = cached;
+            // Refresh view status for a sent message we still believe is unviewed:
+            // the recipient may have opened it since the last sync, and the detail
+            // endpoint carries the real "First Viewed" timestamp (a list-synced row
+            // only knows the showNeverViewed boolean / epoch placeholder). Best-
+            // effort and one-way — once a real viewed time is cached we stop re-
+            // fetching. Sent-only: re-hitting an unread INBOX detail would mark it
+            // read on OFW.
+            if (cached.folder === 'sent' && !hasRealView(cached.recipients)) {
+                try {
+                    const detail = parseLenient(MessageDetailSchema, await client.request('GET', `/pub/v3/messages/${id}`), { label: 'ofw-mcp', context: 'GET /pub/v3/messages/{id} (view-status refresh)' });
+                    const recipients = mapRecipients(detail.recipients);
+                    // Keep the raw listData read-flag in step with the refreshed
+                    // recipients so `showNeverViewed` can't contradict `viewedAt`.
+                    // (Spreading a null/absent listData is a no-op, so no guard needed.)
+                    row = {
+                        ...cached,
+                        recipients,
+                        listData: { ...cached.listData, showNeverViewed: !hasRealView(recipients) },
+                    };
+                    await cache.upsertMessage(row);
+                }
+                catch {
+                    // Best-effort: fall back to the cached row on any fetch/parse error.
+                }
+            }
+            let attachments = await cache.listAttachmentsForMessage(id);
             // Lazy attachment backfill. The list-endpoint payload (stored in
             // listData) hints at attachments via `files: <count>` but doesn't
             // expose the fileIds — those live only on /pub/v3/messages/{id}.
@@ -191,22 +193,35 @@ export function registerMessageTools(server, client) {
             // attachments table is empty even though OFW has files. Re-hit
             // detail to harvest fileIds (idempotent: body is already cached so
             // OFW state isn't changing).
-            if (attachments.length === 0 && listDataHintsAtFiles(cached.listData)) {
+            if (attachments.length === 0 && listDataHintsAtFiles(row.listData)) {
                 try {
                     const detail = parseLenient(DetailFilesSchema, await client.request('GET', `/pub/v3/messages/${id}`), { label: 'ofw-mcp', context: '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);
+                        await fetchAttachmentMetaForMessage(client, id, detail.files, cache);
+                        attachments = await cache.listAttachmentsForMessage(id);
                     }
                 }
                 catch {
                     // Backfill is best-effort. Fall through with whatever we have.
                 }
             }
-            return jsonResponse({ ...cached, attachments });
+            return jsonResponse({ ...row, attachments });
         }
         const detail = parseLenient(MessageDetailSchema, await client.request('GET', `/pub/v3/messages/${encodeURIComponent(args.messageId)}`), { label: 'ofw-mcp', context: 'GET /pub/v3/messages/{id} (ofw_get_message)' });
-        const folder = cached?.folder ?? 'inbox';
+        // Derive the folder for a live-fetched message. A cached row (reached here
+        // only when its body was NULL) already knows its folder, so keep it.
+        // Otherwise use the detail's own folder id, matched against the sent folder
+        // id persisted by the last resolveFolderIds — a sent message must not be
+        // mislabeled 'inbox' (which would also hide it from ofw_get_unread_sent and
+        // a sent-scoped ofw_list_messages). When that mapping isn't known yet (no
+        // sync has run in this cache), fall back to 'inbox' as before.
+        let folder = cached?.folder ?? 'inbox';
+        if (!cached) {
+            const sentFolderId = await cache.getMeta('sent_folder_id');
+            if (sentFolderId !== null && detail.folder?.id != null && String(detail.folder.id) === sentFolderId) {
+                folder = 'sent';
+            }
+        }
         const row = {
             id: detail.id,
             folder,
@@ -220,11 +235,11 @@ export function registerMessageTools(server, client) {
             chainRootId: cached?.chainRootId ?? null,
             listData: cached?.listData ?? detail,
         };
-        upsertMessage(row);
+        await cache.upsertMessage(row);
         if (Array.isArray(detail.files) && detail.files.length > 0) {
-            await fetchAttachmentMetaForMessage(client, detail.id, detail.files);
+            await fetchAttachmentMetaForMessage(client, detail.id, detail.files, cache);
         }
-        const attachments = listAttachmentsForMessage(detail.id);
+        const attachments = await cache.listAttachmentsForMessage(detail.id);
         return jsonResponse({ ...row, attachments });
     });
     if (allowSend)
@@ -245,6 +260,7 @@ export function registerMessageTools(server, client) {
                 throw new Error(`messageId (${args.messageId}) and draftId (${args.draftId}) refer to different drafts; pass only one.`);
             }
             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
@@ -258,7 +274,7 @@ export function registerMessageTools(server, client) {
             let draftFound = false;
             if (draftRef !== undefined) {
                 draftLookupAttempted = true;
-                const draft = getDraft(draftRef);
+                const draft = await cache.getDraft(draftRef);
                 if (draft !== null) {
                     draftFound = true;
                     subject = subject ?? draft.subject;
@@ -286,11 +302,11 @@ export function registerMessageTools(server, client) {
             let chainRootId = null;
             let rewriteNote = null;
             if (requestedReplyTo !== null) {
-                resolvedReplyTo = findLatestReplyTip(requestedReplyTo);
+                resolvedReplyTo = await cache.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);
+                const parent = await cache.getMessage(resolvedReplyTo);
                 chainRootId = parent?.chainRootId ?? parent?.id ?? requestedReplyTo;
             }
             const myFileIDs = args.myFileIDs ?? [];
@@ -320,13 +336,13 @@ export function registerMessageTools(server, client) {
                     chainRootId,
                     listData: detail,
                 };
-                upsertMessage(persisted);
+                await cache.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({
+                    const existing = await cache.getAttachment(fileId);
+                    await cache.upsertAttachmentForMessage({
                         fileId,
                         fileName: existing?.fileName ?? `file-${fileId}`,
                         label: existing?.label ?? existing?.fileName ?? `file-${fileId}`,
@@ -349,7 +365,7 @@ export function registerMessageTools(server, client) {
             }
             else if (draftRef !== undefined) {
                 await deleteOFWMessages(client, [draftRef]);
-                deleteDraft(draftRef);
+                await cache.deleteDraft(draftRef);
             }
             const responseObj = persisted ?? raw;
             const text = responseObj ? JSON.stringify(responseObj, null, 2) : 'Message sent successfully.';
@@ -366,7 +382,7 @@ export function registerMessageTools(server, client) {
     }, async (args) => {
         const page = args.page ?? 1;
         const size = args.size ?? 50;
-        const drafts = listDrafts({ page, size });
+        const drafts = await cacheProvider().listDrafts({ page, size });
         const payload = drafts.length === 0
             ? { drafts: [], note: 'Cache empty. Call ofw_sync_messages to populate.' }
             : { drafts };
@@ -385,11 +401,12 @@ export function registerMessageTools(server, client) {
                 myFileIDs: z.array(z.number()).describe('Attachment file ids (from ofw_upload_attachment)').optional(),
             },
         }, async (args) => {
+            const cache = cacheProvider();
             const requestedReplyTo = args.replyToId ?? null;
             let resolvedReplyTo = requestedReplyTo;
             let rewriteNote = null;
             if (requestedReplyTo !== null) {
-                resolvedReplyTo = findLatestReplyTip(requestedReplyTo);
+                resolvedReplyTo = await cache.findLatestReplyTip(requestedReplyTo);
                 if (resolvedReplyTo !== requestedReplyTo) {
                     rewriteNote = `replyToId rewritten from ${requestedReplyTo} to ${resolvedReplyTo} (later reply in same thread found in sent cache).`;
                 }
@@ -425,13 +442,13 @@ export function registerMessageTools(server, client) {
                     modifiedAt: detail.date?.dateTime ?? new Date().toISOString(),
                     listData: detail,
                 };
-                upsertDraft(persisted);
+                await cache.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);
+                        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.)`;
                     }
                     catch (e) {
@@ -453,7 +470,7 @@ export function registerMessageTools(server, client) {
             },
         }, async (args) => {
             const data = await deleteOFWMessages(client, [args.messageId]);
-            deleteDraft(args.messageId);
+            await cacheProvider().deleteDraft(args.messageId);
             return data ? jsonResponse(data) : textResponse('Draft deleted.');
         });
     server.registerTool('ofw_get_unread_sent', {
@@ -466,7 +483,7 @@ export function registerMessageTools(server, client) {
     }, async (args) => {
         const page = args.page ?? 1;
         const size = args.size ?? 50;
-        const sent = listMessages({ folder: 'sent', page, size });
+        const sent = await cacheProvider().listMessages({ folder: 'sent', page, size });
         if (sent.length === 0) {
             return jsonResponse({ note: 'Sent cache is empty. Call ofw_sync_messages to populate.' });
         }
@@ -493,16 +510,12 @@ export function registerMessageTools(server, client) {
                 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);
+            // Resolve the upload source through the injected attachment-I/O boundary
+            // (disk read on node; an in-memory source on the hosted connector).
+            const { blob, fileName, mimeType: mime, sizeBytes } = await attachmentIO.resolveUpload(args.path);
             // 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('file', blob, fileName);
             form.append('source', 'message');
             form.append('description', args.description ?? fileName);
             form.append('label', args.label ?? fileName);
@@ -512,12 +525,12 @@ export function registerMessageTools(server, client) {
             // 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({
+            await cacheProvider().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,
+                sizeBytes: typeof meta.sizeInBytes === 'number' ? meta.sizeInBytes : sizeBytes,
                 metadata: meta,
                 messageId: 0,
             });
@@ -525,7 +538,7 @@ export function registerMessageTools(server, client) {
                 fileId: meta.fileId,
                 fileName: meta.fileName ?? fileName,
                 mimeType: meta.fileType ?? mime,
-                sizeBytes: meta.sizeInBytes ?? stat.size,
+                sizeBytes: meta.sizeInBytes ?? sizeBytes,
                 shareClass: meta.shareClass ?? args.shareClass ?? 'PRIVATE',
                 note: 'Pass this fileId to ofw_send_message or ofw_save_draft in myFileIDs to attach it.',
             });
@@ -541,13 +554,14 @@ export function registerMessageTools(server, client) {
         },
     }, async (args) => {
         const fileId = args.fileId;
+        const cache = cacheProvider();
         const inline = args.inline ?? getDefaultInlineAttachments();
-        let cached = getAttachment(fileId);
+        let cached = await cache.getAttachment(fileId);
         if (!cached) {
             // Not in cache. Fetch metadata and store under the messageId=0
             // sentinel — gets re-linked if a message later references this file.
-            await fetchAttachmentMeta(client, fileId, 0);
-            cached = getAttachment(fileId);
+            await fetchAttachmentMeta(client, fileId, 0, cache);
+            cached = await cache.getAttachment(fileId);
             /* v8 ignore next -- fetchAttachmentMeta persists the row it just fetched; a still-null read here is an unreachable storage failure */
             if (!cached)
                 throw new Error(`failed to fetch metadata for fileId ${fileId}`);
@@ -558,10 +572,7 @@ export function registerMessageTools(server, client) {
             let mimeType = cached.mimeType;
             let fileName = cached.fileName;
             if (cached.downloadedPath) {
-                try {
-                    bytes = readFileSync(cached.downloadedPath);
-                }
-                catch { /* on-disk copy missing; fall through */ }
+                bytes = attachmentIO.readDownloaded(cached.downloadedPath);
             }
             if (bytes === null) {
                 const response = await client.requestBinary('GET', `/pub/v1/myfiles/${fileId}/data`);
@@ -604,9 +615,8 @@ export function registerMessageTools(server, client) {
             });
         }
         const response = await client.requestBinary('GET', `/pub/v1/myfiles/${fileId}/data`);
-        mkdirSync(dirname(dest), { recursive: true });
-        writeFileSync(dest, response.body);
-        markAttachmentDownloaded(fileId, dest);
+        attachmentIO.writeDownload(dest, response.body);
+        await cache.markAttachmentDownloaded(fileId, dest);
         return jsonResponse({
             fileId,
             path: dest,
@@ -616,19 +626,21 @@ export function registerMessageTools(server, client) {
         });
     });
     server.registerTool('ofw_sync_messages', {
-        description: 'Sync messages from OurFamilyWizard into the local cache. Returns counts per folder and a list of unread inbox messages whose bodies were NOT fetched (to avoid mark-as-read on OFW). Call ofw_get_message(id) on those to read them. Pass deep:true to walk all OFW pages instead of stopping at the first all-cached page (use to backfill suspected gaps).',
+        description: 'Sync messages from OurFamilyWizard into the local cache. Returns counts per folder and a list of unread inbox messages whose bodies were NOT fetched (to avoid mark-as-read on OFW). Call ofw_get_message(id) on those to read them. EVERY call re-checks the newest page first, so new messages are picked up promptly even while an old-history backfill is still running; only then does it spend what is left of its budget advancing that backfill. Pass deep:true to walk all OFW pages instead of stopping at the first all-cached page (use to backfill suspected gaps). Sync is BOUNDED and RESUMABLE: on hosted deployments a per-call OFW-request budget (env OFW_SYNC_MAX_REQUESTS, or the maxRequests argument) caps how far one call walks; when the budget is hit the response reports done:false with a note — call again with the SAME arguments to resume. done:false means older history is still being backfilled; it does NOT mean recent messages are missing. Local installs are unbounded by default (done is always true).',
         annotations: { readOnlyHint: false },
         inputSchema: {
             folders: z.array(z.enum(['inbox', 'sent', 'drafts'])).describe('Folders to sync (default: all three)').optional(),
             fetchUnreadBodies: z.boolean().describe('If true, also fetch bodies for unread inbox messages (will mark them as read on OFW). Default false.').optional(),
             deep: z.boolean().describe('If true, walk every OFW page until empty regardless of cache state. Use to backfill gaps. Default false.').optional(),
+            maxRequests: z.number().int().min(1).describe('Maximum OFW requests this single call may make before pausing. When hit, the response reports done:false — call again with the same arguments to continue. Omit to use the server default (OFW_SYNC_MAX_REQUESTS, or unbounded on local installs).').optional(),
         },
     }, async (args) => {
         const result = await syncAll(client, {
             folders: args.folders,
             fetchUnreadBodies: args.fetchUnreadBodies,
             deep: args.deep,
-        });
+            maxRequests: args.maxRequests ?? getSyncMaxRequests(),
+        }, cacheProvider());
         return jsonResponse(result);
     });
 }