ofw-mcp 2.4.4 → 2.6.3

package/dist/index.js

@@ -16,6 +16,17 @@ import { registerMessageTools } from './tools/messages.js';
 import { registerCalendarTools } from './tools/calendar.js';
 import { registerExpenseTools } from './tools/expenses.js';
 import { registerJournalTools } from './tools/journal.js';
+import { OFWCache } from './cache/node.js';
+import { getCacheDbPath } from './config.js';
+import { NodeAttachmentIO } from './tools/attachments.js';
+// The stdio server backs the message cache with a local `node:sqlite` file,
+// opened lazily on first use (so the server still boots and answers the host's
+// install-time tools/list probe when no cache path is configured). The hosted
+// Cloudflare connector (a later task) injects a Durable-Object-backed
+// CacheStore + a filesystem-free AttachmentIO into the same registrar instead.
+let nodeCache;
+const nodeCacheProvider = () => (nodeCache ??= OFWCache.open(getCacheDbPath()));
+const nodeAttachmentIO = new NodeAttachmentIO();
 // runMcp builds the McpServer, applies the registrars (with `client` threaded
 // through as deps), prints the banner to stderr, wires SIGINT/SIGTERM graceful
 // shutdown, and connects the stdio transport. The deferred-config-error pattern
@@ -24,11 +35,11 @@ import { registerJournalTools } from './tools/journal.js';
 // always succeeds before any credential check runs.
 await runMcp({
     name: 'ofw',
-    version: '2.4.4', // x-release-please-version
+    version: '2.6.3', // x-release-please-version
     deps: client,
     tools: [
         registerUserTools,
-        registerMessageTools,
+        (server, deps) => registerMessageTools(server, deps, nodeCacheProvider, nodeAttachmentIO),
         registerCalendarTools,
         registerExpenseTools,
         registerJournalTools,

package/dist/ofw-auth.js

@@ -0,0 +1,26 @@
+import { loginWithPassword } from './auth-password.js';
+/**
+ * `ConnectorAuth` for the OurFamilyWizard remote connector: the login page
+ * collects the user's own OFW email/username + password, verifies them via the
+ * same Spring Security form login the stdio server uses (`loginWithPassword` in
+ * `auth-password.js`), and stores `{ username, password }` as the OAuth props
+ * that `worker.ts`'s `buildClient` turns into a per-user `OFWClient` capable of
+ * re-authenticating when its 6h token expires.
+ */
+export const ofwAuth = {
+    service: 'OurFamilyWizard',
+    accent: '#00A9A5',
+    privacyNote: 'Your OFW email and password are stored encrypted and used only to sign in to OurFamilyWizard on your behalf ' +
+        '(OFW sign-in tokens expire every few hours, so your password is needed to renew them).',
+    fields: [
+        { name: 'username', label: 'OFW email or username' },
+        { name: 'password', label: 'OFW password', type: 'password' },
+    ],
+    async login(fields) {
+        // Verify the credentials up front — a bad password throws here, which the
+        // connector surfaces back on the login page. We deliberately discard the
+        // returned token: the per-user client logs in again from the stored creds.
+        await loginWithPassword(fields.username, fields.password);
+        return { username: fields.username, password: fields.password };
+    },
+};

package/dist/sync.js

@@ -1,6 +1,5 @@
-import { setMeta, upsertMessage, getMessage, deleteMessage, setSyncState, upsertDraft, getDraft, deleteDraft, listDraftIds, upsertAttachmentForMessage, } from './cache.js';
 import { z } from 'zod';
-import { ApiRecipientSchema, mapRecipients } from './tools/_shared.js';
+import { ApiRecipientSchema, hasRealView, mapRecipients } from './tools/_shared.js';
 import { parseLenient } from '@chrischall/mcp-utils';
 // Each OFW message detail returns `files: [fileId, ...]`. We fetch the metadata
 // for each file id (cheap JSON call) so the model can see filenames/mime types
@@ -21,9 +20,9 @@ const FileMetaSchema = z.looseObject({
 // Throws on network/HTTP errors — callers in bulk-sync paths wrap this in the
 // best-effort helper below; callers that need the result (download tool) let
 // the throw propagate.
-export async function fetchAttachmentMeta(client, fileId, messageId) {
+export async function fetchAttachmentMeta(client, fileId, messageId, store) {
     const meta = parseLenient(FileMetaSchema, await client.request('GET', `/pub/v1/myfiles/${fileId}`), { label: 'ofw-mcp', context: 'GET /pub/v1/myfiles/{fileId}' });
-    upsertAttachmentForMessage({
+    await store.upsertAttachmentForMessage({
         fileId: meta.fileId ?? fileId,
         fileName: meta.fileName ?? `file-${fileId}`,
         label: meta.label ?? meta.fileName ?? `file-${fileId}`,
@@ -33,17 +32,50 @@ export async function fetchAttachmentMeta(client, fileId, messageId) {
         messageId,
     });
 }
-export async function fetchAttachmentMetaForMessage(client, messageId, fileIds) {
+export async function fetchAttachmentMetaForMessage(client, messageId, fileIds, store) {
     // Fan out in parallel — each fetch is independent and the file id stays
     // in listData on failure (model can retry via ofw_download_attachment,
     // which surfaces the real error). Promise.allSettled so one bad
     // attachment doesn't break the surrounding sync.
-    await Promise.allSettled(fileIds.map((fid) => fetchAttachmentMeta(client, fid, messageId)));
+    await Promise.allSettled(fileIds.map((fid) => fetchAttachmentMeta(client, fid, messageId, store)));
+}
+/**
+ * Build a {@link Budget} that allows `max` requests. `Number.POSITIVE_INFINITY`
+ * (the local-stdio default) never exhausts — `take()` always returns true — so
+ * bounded logic collapses to the original unbounded walk.
+ */
+export function makeBudget(max) {
+    let remaining = max;
+    return {
+        take() {
+            if (remaining <= 0)
+                return false;
+            remaining -= 1;
+            return true;
+        },
+    };
+}
+// Budget-gated attachment-meta backfill. Spends one unit per file id it can
+// afford (in order), skipping the rest, then fetches the affordable ones with
+// the existing best-effort parallel helper. Attachment fetches are best-effort:
+// a skipped file id stays in the message's listData and can be backfilled later
+// by ofw_get_message. Under an infinite budget this fetches every file id — the
+// unbounded behaviour.
+async function fetchAttachmentMetaBudgeted(client, messageId, fileIds, store, budget) {
+    const affordable = [];
+    for (const fid of fileIds) {
+        if (!budget.take())
+            break;
+        affordable.push(fid);
+    }
+    if (affordable.length > 0) {
+        await fetchAttachmentMetaForMessage(client, messageId, affordable, store);
+    }
 }
 const FoldersSchema = z.looseObject({
     systemFolders: z.array(z.looseObject({ id: z.string(), folderType: z.string() })).optional(),
 });
-export async function resolveFolderIds(client) {
+export async function resolveFolderIds(client, store) {
     const data = parseLenient(FoldersSchema, await client.request('GET', '/pub/v1/messageFolders?includeFolderCounts=true'), { label: 'ofw-mcp', context: 'GET /pub/v1/messageFolders' });
     const sys = data.systemFolders ?? [];
     const find = (type) => {
@@ -57,7 +89,11 @@ export async function resolveFolderIds(client) {
         sent: find('SENT_MESSAGES'),
         drafts: find('DRAFTS'),
     };
-    setMeta('drafts_folder_id', ids.drafts);
+    await store.setMeta('drafts_folder_id', ids.drafts);
+    // Persist the sent folder id too: ofw_get_message's live-fetch path uses it to
+    // label an uncached message sent-vs-inbox from the detail payload's own folder
+    // id, instead of hard-defaulting to inbox.
+    await store.setMeta('sent_folder_id', ids.sent);
     return ids;
 }
 // Required fields are the ones the sync loop reads unguarded (id keys the
@@ -75,35 +111,84 @@ const ListResponseSchema = z.looseObject({ data: z.array(ListItemSchema).optiona
 const DetailResponseSchema = z.looseObject({
     body: z.string().optional(),
     files: z.array(z.number()).optional(),
+    // The detail endpoint carries the REAL recipient view timestamps (the list
+    // endpoint only has an epoch placeholder) — used by the view-status refresh.
+    recipients: z.array(ApiRecipientSchema).optional(),
 });
-export async function syncMessageFolder(client, folder, folderId, opts) {
-    let page = 1;
-    let synced = 0;
+const maxId = (a, b) => a === null ? b : b === null ? a : Math.max(a, b);
+/**
+ * Walk one folder's list pages from `startPage` toward older messages, caching
+ * what isn't cached yet. Stops on an empty page, when `stopAtCachedPage` says
+ * we've reached cached history, or when the request budget runs out.
+ */
+async function walkPages(client, folder, folderId, opts, store) {
+    const budget = opts.budget;
+    let page = opts.startPage;
     let newestId = null;
+    let synced = 0;
     const unread = [];
     while (true) {
+        // One unit per list-page fetch. Out of budget → pause and resume at `page`.
+        if (!budget.take()) {
+            return { synced, unread, newestId, done: false, nextPage: page };
+        }
         const path = `/pub/v3/messages?folders=${encodeURIComponent(folderId)}&page=${page}&size=50&sort=date&sortDirection=desc`;
         const list = parseLenient(ListResponseSchema, await client.request('GET', path), { label: 'ofw-mcp', context: `GET /pub/v3/messages?folders={${folder}}` });
         const items = list.data ?? [];
-        if (items.length === 0)
-            break;
+        if (items.length === 0) {
+            return { synced, unread, newestId, done: true, nextPage: null };
+        }
+        // One batch read of this page's ids (S1) instead of a per-item getMessage.
+        const existingById = new Map((await store.getMessages(items.map((it) => it.id))).map((row) => [row.id, row]));
+        // Rows created/updated this page, flushed in ONE batch upsert (S1).
+        const toUpsert = [];
         let pageHadNewItem = false;
+        let pageBudgetHit = false;
         for (const item of items) {
             if (newestId === null || item.id > newestId)
                 newestId = item.id;
-            const existing = getMessage(item.id);
-            if (existing)
+            const existing = existingById.get(item.id);
+            if (existing) {
+                // A sent message's read status changes AFTER it's first cached, when
+                // the recipient opens it — so we can't just skip existing rows. The
+                // list item carries the reliable `showNeverViewed` boolean but only an
+                // epoch placeholder for the timestamp; the real "First Viewed" time is
+                // on the detail endpoint. So when a sent message has flipped to read
+                // and we don't yet hold a real viewed time, re-fetch detail to capture
+                // it (no body re-fetch — only the recipient view fields can change).
+                if (folder === 'sent' && item.showNeverViewed === false && !hasRealView(existing.recipients)) {
+                    if (!budget.take()) {
+                        pageBudgetHit = true;
+                        break;
+                    }
+                    const detail = parseLenient(DetailResponseSchema, await client.request('GET', `/pub/v3/messages/${item.id}`), { label: 'ofw-mcp', context: 'GET /pub/v3/messages/{id} (view-status refresh)' });
+                    toUpsert.push({ ...existing, recipients: mapRecipients(detail.recipients), listData: item });
+                    synced++;
+                }
                 continue;
+            }
             pageHadNewItem = true;
             const isInboxUnread = folder === 'inbox' && item.showNeverViewed === true;
             const shouldFetchBody = !isInboxUnread || opts.fetchUnreadBodies;
             let body = null;
             let fetchedBodyAt = null;
             let detailFileIds = [];
+            // Prefer the DETAIL endpoint's recipients when we fetch it: the list only
+            // ever carries an epoch placeholder for `viewed.dateTime` (even on a read
+            // message), while detail carries the real "First Viewed" time. Building
+            // the row from the list would cache viewedAt:null for a message that was
+            // already read by the time we first saw it — reporting "never viewed" for
+            // a message OFW shows as read, until a later sync's refresh healed it.
+            let detailRecipients;
             if (shouldFetchBody) {
+                if (!budget.take()) {
+                    pageBudgetHit = true;
+                    break;
+                }
                 const detail = parseLenient(DetailResponseSchema, await client.request('GET', `/pub/v3/messages/${item.id}`), { label: 'ofw-mcp', context: 'GET /pub/v3/messages/{id} (sync)' });
                 body = detail.body ?? '';
                 fetchedBodyAt = new Date().toISOString();
+                detailRecipients = detail.recipients;
                 if (Array.isArray(detail.files) && detail.files.length > 0) {
                     detailFileIds = detail.files;
                 }
@@ -122,33 +207,109 @@ export async function syncMessageFolder(client, folder, folderId, opts) {
                 subject: item.subject ?? '(no subject)',
                 fromUser: item.from?.name ?? '',
                 sentAt: item.date?.dateTime ?? new Date().toISOString(),
-                recipients: mapRecipients(item.recipients),
+                recipients: mapRecipients(detailRecipients ?? item.recipients),
                 body,
                 fetchedBodyAt,
                 replyToId: null,
                 chainRootId: null,
                 listData: item,
             };
-            upsertMessage(row);
+            toUpsert.push(row);
             synced++;
             if (detailFileIds.length > 0) {
-                await fetchAttachmentMetaForMessage(client, item.id, detailFileIds);
+                await fetchAttachmentMetaBudgeted(client, item.id, detailFileIds, store, budget);
             }
         }
-        // Stop heuristic: a page with no new items means we've reached cached
-        // history (OFW returns date-desc). A page with even ONE new item could
-        // mean there are more new items on the next page that we haven't seen
-        // yet — keep walking. With `deep: true`, walk every page until OFW
-        // returns an empty page (used to backfill suspected gaps).
-        if (!opts.deep && !pageHadNewItem)
-            break;
+        // Flush the page's rows in one transaction/RPC. Empty array is a no-op.
+        await store.upsertMessages(toUpsert);
+        if (pageBudgetHit) {
+            // Paused mid-page. Resume at THIS page: the partial rows are cached, so
+            // getMessages skips them next time and upserts are idempotent.
+            return { synced, unread, newestId, done: false, nextPage: page };
+        }
+        // Reached cached history (see `stopAtCachedPage`). Report THIS page as the
+        // resume point rather than the next one: it costs one redundant (cheap,
+        // all-cached) fetch if a backfill later starts here, and it cannot skip a
+        // message the way an off-by-one `page + 1` could.
+        if (opts.stopAtCachedPage && !pageHadNewItem) {
+            return { synced, unread, newestId, done: true, nextPage: page };
+        }
         page++;
     }
-    setSyncState(folder, {
+}
+/**
+ * Sync one message folder. Runs two independent passes so that a long backfill
+ * can never starve new messages:
+ *
+ *  1. FORWARD — always from page 1, every call, regardless of how deep a
+ *     backfill is parked. This is what guarantees a message sent or received
+ *     since the last sync is cached by the next ordinary call. Once caught up
+ *     it costs a single request: page 1 holds nothing new, so it stops there.
+ *  2. BACKFILL — resumes the parked cursor (or, for `deep`, walks past where
+ *     the forward pass stopped) with whatever budget the forward pass left,
+ *     and re-parks the cursor if it pauses again.
+ *
+ * Both passes share one budget, and the forward pass draws first: the newest
+ * messages are the ones a caller is most likely to need, and history that has
+ * waited months can wait one more call.
+ */
+export async function syncMessageFolder(client, folder, folderId, opts, store) {
+    // No budget → unbounded (local stdio): every take() succeeds, so an ordinary
+    // sync is byte-for-byte the original unbounded walk (forward pass only).
+    const budget = opts.budget ?? makeBudget(Number.POSITIVE_INFINITY);
+    const saved = await store.getSyncState(folder);
+    const savedResume = saved?.resumePage ?? null;
+    const fwd = await walkPages(client, folder, folderId, {
+        startPage: 1,
+        stopAtCachedPage: true,
+        fetchUnreadBodies: opts.fetchUnreadBodies,
+        budget,
+    }, store);
+    let synced = fwd.synced;
+    const unread = [...fwd.unread];
+    // Never regress the folder's newest id: a pass that only walked cached pages
+    // still saw page 1, but a paused one may not have.
+    let newestId = maxId(saved?.newestId ?? null, fwd.newestId);
+    let done;
+    let resumePage;
+    if (!fwd.done) {
+        // The forward pass itself ran out of budget, so it never reached cached
+        // history — everything from `fwd.nextPage` down is unverified. Park the
+        // backfill at whichever cursor is higher up the folder, so no page that
+        // still owes us messages ends up above the resume point.
+        done = false;
+        resumePage = savedResume === null ? fwd.nextPage : Math.min(fwd.nextPage, savedResume);
+    }
+    else if (fwd.nextPage === null) {
+        // The forward pass walked clean off the end of the folder — by definition
+        // there is no older history left to backfill.
+        done = true;
+        resumePage = null;
+    }
+    else if (savedResume === null && !opts.deep) {
+        // Ordinary incremental sync with no backfill parked: caught up.
+        done = true;
+        resumePage = null;
+    }
+    else {
+        const bf = await walkPages(client, folder, folderId, {
+            startPage: savedResume ?? fwd.nextPage,
+            stopAtCachedPage: false,
+            fetchUnreadBodies: opts.fetchUnreadBodies,
+            budget,
+        }, store);
+        synced += bf.synced;
+        unread.push(...bf.unread);
+        newestId = maxId(newestId, bf.newestId);
+        done = bf.done;
+        resumePage = bf.done ? null : bf.nextPage;
+    }
+    await store.setSyncState(folder, {
         lastSyncAt: new Date().toISOString(),
         newestId,
+        resumePage,
     });
-    return { synced, unread };
+    return { synced, unread, done };
 }
 const DraftListItemSchema = z.looseObject({
     id: z.number(),
@@ -162,13 +323,21 @@ const DraftDetailSchema = z.looseObject({
     body: z.string().optional(),
     subject: z.string().optional(),
 });
-export async function syncDrafts(client, draftsFolderId) {
-    // Walk every page. The reconciliation loop at the bottom deletes any
-    // cached draft that wasn't seen in the listing, so a partial walk would
-    // wrongly evict real drafts beyond the first page.
+export async function syncDrafts(client, draftsFolderId, store, budget) {
+    // No budget → unbounded (local stdio): identical to the original walk.
+    const b = budget ?? makeBudget(Number.POSITIVE_INFINITY);
+    // The reconciliation step below DELETES any cached draft not seen in the
+    // listing, so a partial walk must apply NOTHING. We therefore buffer the
+    // entire walk (all list pages + every detail) BEFORE touching the cache: if
+    // the budget can't fund the whole walk we discard the buffer and defer the
+    // drafts folder to a later call (done:false). The OFW requests already spent
+    // still count against the budget; drafts are few, so a discarded partial is
+    // cheap and — crucially — never evicts a real draft.
     const items = [];
     let page = 1;
     while (true) {
+        if (!b.take())
+            return { synced: 0, done: false };
         const path = `/pub/v3/messages?folders=${encodeURIComponent(draftsFolderId)}&page=${page}&size=50&sort=date&sortDirection=desc`;
         const list = parseLenient(DraftListResponseSchema, await client.request('GET', path), { label: 'ofw-mcp', context: 'GET /pub/v3/messages?folders={drafts}' });
         const pageItems = list.data ?? [];
@@ -177,32 +346,38 @@ export async function syncDrafts(client, draftsFolderId) {
             break;
         page++;
     }
-    const seenIds = new Set();
-    let synced = 0;
+    // Fetch every draft's detail up front, still buffered. OFW's list
+    // `date.dateTime` is NOT a reliable modification timestamp for drafts —
+    // direct UI edits don't bump it — so we can't skip the detail fetch.
+    const rows = [];
     for (const item of items) {
-        seenIds.add(item.id);
-        const modifiedAt = item.date?.dateTime ?? new Date().toISOString();
-        // OFW's list endpoint's `date.dateTime` is NOT a reliable modification
-        // timestamp for drafts — direct UI edits don't bump it — so we can't
-        // use it to skip the detail fetch. Always re-fetch; drafts are few.
-        const existing = getDraft(item.id);
+        if (!b.take())
+            return { synced: 0, done: false };
         const detail = parseLenient(DraftDetailSchema, await client.request('GET', `/pub/v3/messages/${item.id}`), { label: 'ofw-mcp', context: 'GET /pub/v3/messages/{id} (drafts sync)' });
-        const row = {
+        rows.push({
             id: item.id,
             subject: detail.subject ?? item.subject ?? '(no subject)',
             body: detail.body ?? '',
             recipients: mapRecipients(item.recipients),
             replyToId: item.replyToId ?? null,
-            modifiedAt,
+            modifiedAt: item.date?.dateTime ?? new Date().toISOString(),
             listData: item,
-        };
-        upsertDraft(row);
-        // If a stale `messages` row exists for this id (cached by a prior
-        // ofw_get_message call before the drafts table knew about this id),
-        // evict it. The drafts table is the source of truth for drafts; we
-        // don't want ofw_get_message returning a stale messages-table copy.
-        if (getMessage(item.id))
-            deleteMessage(item.id);
+        });
+    }
+    // Budget funded the whole walk — apply atomically. Batch reads (S1) snapshot
+    // pre-upsert state for the synced-count comparison and stale-row eviction.
+    const ids = items.map((it) => it.id);
+    const existingById = new Map((await store.getDrafts(ids)).map((d) => [d.id, d]));
+    await store.upsertDrafts(rows);
+    // If a stale `messages` row exists for a draft id (cached by a prior
+    // ofw_get_message call before the drafts table knew about this id), evict it.
+    // The drafts table is the source of truth for drafts.
+    for (const stale of await store.getMessages(ids)) {
+        await store.deleteMessage(stale.id);
+    }
+    let synced = 0;
+    for (const row of rows) {
+        const existing = existingById.get(row.id);
         if (!existing
             || existing.body !== row.body
             || existing.subject !== row.subject
@@ -210,40 +385,62 @@ export async function syncDrafts(client, draftsFolderId) {
             synced++;
         }
     }
-    for (const id of listDraftIds()) {
+    const seenIds = new Set(ids);
+    for (const id of await store.listDraftIds()) {
         if (!seenIds.has(id))
-            deleteDraft(id);
+            await store.deleteDraft(id);
     }
-    return { synced };
+    return { synced, done: true };
 }
-export async function syncAll(client, opts) {
+export async function syncAll(client, opts, store) {
     const folders = opts.folders ?? ['inbox', 'sent', 'drafts'];
-    const ids = await resolveFolderIds(client);
+    // ONE budget shared across resolveFolderIds and every requested folder, in
+    // order — so the whole invocation stays under the hosting subrequest cap.
+    const budget = makeBudget(opts.maxRequests ?? Number.POSITIVE_INFINITY);
+    // resolveFolderIds always makes exactly one request; the tool guarantees
+    // maxRequests >= 1, so this unit is always available (result intentionally
+    // ignored — we account for it without a branch that can't be reached).
+    budget.take();
+    const ids = await resolveFolderIds(client, store);
     const synced = {};
     let unreadInbox = [];
+    let done = true;
     for (const folder of folders) {
         if (folder === 'inbox') {
             const r = await syncMessageFolder(client, 'inbox', ids.inbox, {
                 fetchUnreadBodies: opts.fetchUnreadBodies ?? false,
                 deep: opts.deep ?? false,
-            });
+                budget,
+            }, store);
             synced.inbox = r.synced;
             unreadInbox = r.unread;
+            if (!r.done)
+                done = false;
         }
         else if (folder === 'sent') {
             const r = await syncMessageFolder(client, 'sent', ids.sent, {
                 fetchUnreadBodies: false,
                 deep: opts.deep ?? false,
-            });
+                budget,
+            }, store);
             synced.sent = r.synced;
+            if (!r.done)
+                done = false;
         }
         else if (folder === 'drafts') {
-            const r = await syncDrafts(client, ids.drafts);
+            const r = await syncDrafts(client, ids.drafts, store, budget);
             synced.drafts = r.synced;
+            if (!r.done)
+                done = false;
         }
     }
-    const note = unreadInbox.length > 0
-        ? `${unreadInbox.length} unread inbox messages cached without bodies. Call ofw_get_message(id) to read them — this will mark them as read on OFW.`
-        : undefined;
-    return { synced, unreadInbox, ...(note ? { note } : {}) };
+    const notes = [];
+    if (unreadInbox.length > 0) {
+        notes.push(`${unreadInbox.length} unread inbox messages cached without bodies. Call ofw_get_message(id) to read them — this will mark them as read on OFW.`);
+    }
+    if (!done) {
+        notes.push('Paused after the request budget to stay within the hosting limit; more pages remain — call ofw_sync_messages again with the same arguments to resume where it left off and continue the backfill.');
+    }
+    const note = notes.length > 0 ? notes.join('\n\n') : undefined;
+    return { synced, unreadInbox, done, ...(note ? { note } : {}) };
 }

package/dist/tools/_shared.js

@@ -15,13 +15,30 @@ export const ApiRecipientSchema = z.looseObject({
 });
 // Translates OFW API recipient shape into the cache's normalized Recipient.
 // Used wherever we surface or persist recipients (sync, get_message, send,
-// save_draft) — all five call sites had near-identical inline mappings.
+// save_draft).
+//
+// `viewedAt` is the recipient's true "First Viewed" time, or null if not yet
+// viewed. Only the DETAIL endpoint (/pub/v3/messages/{id}) carries a real
+// timestamp; the LIST endpoint returns an epoch-zero PLACEHOLDER
+// ("1970-01-01T00:00:00") in the SAME field even for read messages (on the
+// list, read status lives in `showNeverViewed`, not the timestamp). So treat
+// the epoch placeholder as "no real view time" — otherwise a list-sourced row
+// reports a bogus 1970 read time. A detail re-fetch is what fills in the truth.
 export function mapRecipients(items) {
-    return (items ?? []).map((r) => ({
-        userId: r.user?.id ?? 0,
-        name: r.user?.name ?? '',
-        viewedAt: r.viewed?.dateTime ?? null,
-    }));
+    return (items ?? []).map((r) => {
+        const dt = r.viewed?.dateTime;
+        const viewedAt = typeof dt === 'string' && !dt.startsWith('1970-01-01') ? dt : null;
+        return { userId: r.user?.id ?? 0, name: r.user?.name ?? '', viewedAt };
+    });
+}
+// True if any recipient has a *real* "First Viewed" time — i.e. present and
+// not the epoch-zero placeholder. After mapRecipients a fresh `viewedAt` is
+// only ever a real timestamp or null, but a cache row written by older code
+// (which trusted the list endpoint's `viewed`) may still hold the literal
+// "1970-01-01T00:00:00". Treating that as "not viewed" lets sync/get_message
+// re-fetch detail and self-heal the stale row to the real timestamp.
+export function hasRealView(recipients) {
+    return recipients.some((r) => r.viewedAt !== null && !r.viewedAt.startsWith('1970-01-01'));
 }
 // Expand a user-provided path: ~ → home, relative → absolute. Re-exports
 // @chrischall/mcp-utils' `expandPath`.

package/dist/tools/attachments.js

@@ -0,0 +1,66 @@
+// The attachment-I/O boundary for the message tools.
+//
+// `ofw_upload_attachment` reads a local file off disk; `ofw_download_attachment`
+// writes downloaded bytes to disk (and reads them back for the inline-reuse
+// path). Those are the ONLY node:fs touch points in the message tools — they
+// live behind this {@link AttachmentIO} interface so the stdio server can use
+// the disk-backed {@link NodeAttachmentIO} while the hosted Cloudflare
+// connector (a later task) injects an inline, filesystem-free implementation.
+// Keeping the interface here means src/tools/messages.ts imports nothing from
+// node:fs.
+import { readFileSync, statSync, mkdirSync, writeFileSync } from 'node:fs';
+import { basename, dirname, extname } from 'node:path';
+import { fileBlob, expandPath } from '@chrischall/mcp-utils';
+// 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',
+};
+export function mimeFromName(name) {
+    return MIME_BY_EXT[extname(name).toLowerCase()] ?? 'application/octet-stream';
+}
+/** Disk-backed attachment I/O for the stdio/desktop server. */
+export class NodeAttachmentIO {
+    async resolveUpload(path) {
+        const abs = expandPath(path);
+        const stat = statSync(abs); // throws if missing
+        if (!stat.isFile())
+            throw new Error(`Not a file: ${abs}`);
+        const fileName = basename(abs);
+        const mimeType = mimeFromName(fileName);
+        // fileBlob streams the file off disk (a file-backed Blob) instead of buffering it.
+        const blob = await fileBlob(abs, { type: mimeType });
+        return { blob, fileName, mimeType, sizeBytes: stat.size };
+    }
+    readDownloaded(path) {
+        try {
+            return readFileSync(path);
+        }
+        catch {
+            return null;
+        }
+    }
+    writeDownload(dest, bytes) {
+        mkdirSync(dirname(dest), { recursive: true });
+        writeFileSync(dest, bytes);
+    }
+}