ofw-mcp 2.6.6 → 2.7.0

package/dist/config.js

@@ -110,3 +110,28 @@ export function getSyncMaxRequests() {
         return Number.POSITIVE_INFINITY;
     return n;
 }
+/** Default for getFreshnessTtlSeconds() when OFW_FRESHNESS_TTL_SECONDS is unset. */
+export const DEFAULT_FRESHNESS_TTL_SECONDS = 300;
+/**
+ * How long a folder's verified-against-OFW state stays labelled `fresh`.
+ *
+ * Read tools serve from the local cache, so every read result carries a
+ * `freshness` block saying when the data was last actually compared against
+ * OFW. Past this age the block downgrades to `unverified` and grows a warning,
+ * because a co-parent can send a message — or edit a draft in the OFW web app,
+ * which bumps no timestamp at all — at any moment without us hearing about it.
+ *
+ * Set OFW_FRESHNESS_TTL_SECONDS to a positive integer to tune it. Anything
+ * else (unset / blank / zero / negative / non-integer) falls back to the
+ * default: a bad value must not silently widen the window in which stale data
+ * is presented as current.
+ */
+export function getFreshnessTtlSeconds() {
+    const raw = readEnvVar('OFW_FRESHNESS_TTL_SECONDS');
+    if (raw === undefined)
+        return DEFAULT_FRESHNESS_TTL_SECONDS;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0)
+        return DEFAULT_FRESHNESS_TTL_SECONDS;
+    return n;
+}

package/dist/index.js

@@ -35,7 +35,7 @@ const nodeAttachmentIO = new NodeAttachmentIO();
 // always succeeds before any credential check runs.
 await runMcp({
     name: 'ofw',
-    version: '2.6.6', // x-release-please-version
+    version: '2.7.0', // x-release-please-version
     deps: client,
     tools: [
         registerUserTools,

package/dist/sync.js

@@ -126,17 +126,19 @@ async function walkPages(client, folder, folderId, opts, store) {
     let page = opts.startPage;
     let newestId = null;
     let synced = 0;
+    let pagesFetched = 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 };
+            return { synced, unread, newestId, pagesFetched, 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}}` });
+        pagesFetched++;
         const items = list.data ?? [];
         if (items.length === 0) {
-            return { synced, unread, newestId, done: true, nextPage: null };
+            return { synced, unread, newestId, pagesFetched, 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]));
@@ -225,14 +227,14 @@ async function walkPages(client, folder, folderId, opts, store) {
         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 };
+            return { synced, unread, newestId, pagesFetched, 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 };
+            return { synced, unread, newestId, pagesFetched, done: true, nextPage: page };
         }
         page++;
     }
@@ -273,12 +275,29 @@ export async function syncMessageFolder(client, folder, folderId, opts, store) {
     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);
+        if (fwd.pagesFetched === 0) {
+            // The budget was already spent when the forward pass started, so it
+            // fetched nothing and observed NOTHING about this folder. Leave the
+            // parked cursor exactly as it was: moving it on zero information is a
+            // pure loss.
+            //
+            // This was a real starvation bug. `fwd.nextPage` is just the start page
+            // (1) when nothing was fetched, so the `Math.min` below would silently
+            // reset a deep backfill — e.g. resumePage 87 → 1 — discarding 86 pages
+            // of progress. On the hosted Worker (OFW_SYNC_MAX_REQUESTS=40) a user
+            // with enough drafts to consume the whole budget, with drafts running
+            // first, hit this on EVERY call: inbox/sent never got budget, their
+            // cursor was reset every time, and the backfill could never advance.
+            resumePage = savedResume;
+        }
+        else {
+            // The forward pass did look, and ran out before reaching 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.
+            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
@@ -304,12 +323,16 @@ export async function syncMessageFolder(client, folder, folderId, opts, store) {
         done = bf.done;
         resumePage = bf.done ? null : bf.nextPage;
     }
-    await store.setSyncState(folder, {
-        lastSyncAt: new Date().toISOString(),
-        newestId,
-        resumePage,
-    });
-    return { synced, unread, done };
+    const now = new Date().toISOString();
+    await store.setSyncState(folder, { lastSyncAt: now, newestId, resumePage });
+    // The FORWARD pass is what proves our picture of the present is current: it
+    // always starts at page 1 and stops only once it reaches cached history. Its
+    // completion — not the backfill's — is what makes reads `fresh`. Same `now`
+    // as lastSyncAt so a verified folder never looks a millisecond behind its own
+    // sync (buildFreshness downgrades when lastSyncAt runs ahead of verifiedAt).
+    if (fwd.done)
+        await markFolderVerified(store, folder, now);
+    return { synced, unread, done, verified: fwd.done };
 }
 const DraftListItemSchema = z.looseObject({
     id: z.number(),
@@ -323,9 +346,69 @@ const DraftDetailSchema = z.looseObject({
     body: z.string().optional(),
     subject: z.string().optional(),
 });
+/**
+ * Meta key holding whether the drafts cache has been compared against OFW.
+ * `'fresh'` only after a COMPLETE drafts walk; `'unverified'` whenever a walk
+ * was deferred for budget. Read by ofw_list_drafts / ofw_get_message to stamp
+ * each draft's `cacheStatus`, and by the destructive draft tools to decide how
+ * loudly to warn. Absent (never synced) reads as unverified.
+ */
+export const DRAFTS_CACHE_STATUS_KEY = 'drafts_cache_status';
+export async function getDraftsCacheStatus(store) {
+    return (await store.getMeta(DRAFTS_CACHE_STATUS_KEY)) === 'fresh' ? 'fresh' : 'unverified';
+}
+export async function setDraftsCacheStatus(store, status) {
+    await store.setMeta(DRAFTS_CACHE_STATUS_KEY, status);
+}
+/**
+ * Meta key holding when a folder was last actually COMPARED against OFW.
+ *
+ * Deliberately distinct from `sync_state.last_sync_at`, which is written on
+ * every call including one that paused mid-walk — so `last_sync_at` alone
+ * cannot mean "this folder is current", only "we tried". This key advances
+ * only when the folder was verified:
+ *
+ *   inbox/sent  the FORWARD pass completed, i.e. it walked from page 1 down to
+ *               cached history (or off the end of the folder). That is exactly
+ *               the pass that proves no new message is missing. A parked
+ *               BACKFILL does not hold it back: incomplete old history says
+ *               nothing about whether our picture of the present is current,
+ *               and letting it downgrade every read would make the whole
+ *               freshness signal noise during a long backfill.
+ *   drafts      the full walk + reconciliation ran (the same moment
+ *               DRAFTS_CACHE_STATUS_KEY goes 'fresh').
+ *
+ * Absent = never verified, which reads as `stale`, not `fresh`.
+ */
+export function folderVerifiedAtKey(folder) {
+    return `folder_verified_at:${folder}`;
+}
+export async function getFolderVerifiedAt(store, folder) {
+    return (await store.getMeta(folderVerifiedAtKey(folder))) ?? null;
+}
+export async function markFolderVerified(store, folder, at = new Date().toISOString()) {
+    await store.setMeta(folderVerifiedAtKey(folder), at);
+}
 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);
+    // Deferring means we never compared the drafts cache to OFW on this call.
+    // Mark it unverified so reads can say so and the destructive draft tools
+    // know the cache is not a trustworthy base — the count we return here is
+    // "nothing applied", NOT "nothing changed on the server".
+    const defer = async () => {
+        await setDraftsCacheStatus(store, 'unverified');
+        // Record the ATTEMPT but not a verification: buildFreshness compares the
+        // two and downgrades when a sync ran without verifying this folder, so a
+        // deferred walk actively marks reads unverified rather than leaving them
+        // coasting on an older stamp.
+        await store.setSyncState('drafts', {
+            lastSyncAt: new Date().toISOString(),
+            newestId: null,
+            resumePage: null,
+        });
+        return { synced: 0, done: false };
+    };
     // 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
@@ -337,7 +420,7 @@ export async function syncDrafts(client, draftsFolderId, store, budget) {
     let page = 1;
     while (true) {
         if (!b.take())
-            return { synced: 0, done: false };
+            return defer();
         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 ?? [];
@@ -352,7 +435,7 @@ export async function syncDrafts(client, draftsFolderId, store, budget) {
     const rows = [];
     for (const item of items) {
         if (!b.take())
-            return { synced: 0, done: false };
+            return defer();
         const detail = parseLenient(DraftDetailSchema, await client.request('GET', `/pub/v3/messages/${item.id}`), { label: 'ofw-mcp', context: 'GET /pub/v3/messages/{id} (drafts sync)' });
         rows.push({
             id: item.id,
@@ -390,10 +473,29 @@ export async function syncDrafts(client, draftsFolderId, store, budget) {
         if (!seenIds.has(id))
             await store.deleteDraft(id);
     }
+    // The complete walk fetched every draft's DETAIL and reconciled deletions, so
+    // the cache is now known-equal to the server. Only here is `synced: 0`
+    // truthful as "verified no changes" — and only here may reads report the
+    // drafts as server-confirmed.
+    const now = new Date().toISOString();
+    await setDraftsCacheStatus(store, 'fresh');
+    await store.setSyncState('drafts', { lastSyncAt: now, newestId: null, resumePage: null });
+    await markFolderVerified(store, 'drafts', now);
     return { synced, done: true };
 }
 export async function syncAll(client, opts, store) {
-    const folders = opts.folders ?? ['inbox', 'sent', 'drafts'];
+    const requested = opts.folders ?? ['inbox', 'sent', 'drafts'];
+    // Drafts go FIRST. They are the only folder a destructive tool
+    // (ofw_save_draft / ofw_delete_draft) reads as its base, and they are cheap
+    // and bounded — one list page plus one detail per draft. Running them last,
+    // behind inbox and sent, meant a bounded call (the Worker's
+    // OFW_SYNC_MAX_REQUESTS=40) spent its whole budget backfilling history and
+    // deferred drafts on every single call, so server-side draft edits stayed
+    // invisible indefinitely while the response reported `drafts: 0`.
+    const folders = [
+        ...requested.filter((f) => f === 'drafts'),
+        ...requested.filter((f) => f !== 'drafts'),
+    ];
     // 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);
@@ -405,6 +507,22 @@ export async function syncAll(client, opts, store) {
     const synced = {};
     let unreadInbox = [];
     let done = true;
+    let draftsUnverified = false;
+    const refreshed = [];
+    const notRefreshed = [];
+    // Same rule for every folder: a count is reported, and the folder is listed
+    // as refreshed, ONLY when it was actually diffed against OFW. A folder the
+    // budget never reached reports no number at all — `inbox: 0` reads as
+    // "verified, no new messages", and that lie is the whole bug this guards.
+    const record = (folder, verified, count) => {
+        if (verified) {
+            synced[folder] = count;
+            refreshed.push(folder);
+        }
+        else {
+            notRefreshed.push(folder);
+        }
+    };
     for (const folder of folders) {
         if (folder === 'inbox') {
             const r = await syncMessageFolder(client, 'inbox', ids.inbox, {
@@ -412,7 +530,7 @@ export async function syncAll(client, opts, store) {
                 deep: opts.deep ?? false,
                 budget,
             }, store);
-            synced.inbox = r.synced;
+            record('inbox', r.verified, r.synced);
             unreadInbox = r.unread;
             if (!r.done)
                 done = false;
@@ -423,24 +541,44 @@ export async function syncAll(client, opts, store) {
                 deep: opts.deep ?? false,
                 budget,
             }, store);
-            synced.sent = r.synced;
+            record('sent', r.verified, r.synced);
             if (!r.done)
                 done = false;
         }
         else if (folder === 'drafts') {
             const r = await syncDrafts(client, ids.drafts, store, budget);
-            synced.drafts = r.synced;
-            if (!r.done)
+            // Only report a drafts count when the walk actually compared against
+            // OFW. A deferred walk applied nothing, and reporting its `0` as
+            // `drafts: 0` reads as "verified, no changes" — the exact lie that let a
+            // server-side draft edit be overwritten. Omit the number instead.
+            record('drafts', r.done, r.synced);
+            if (!r.done) {
+                draftsUnverified = true;
                 done = false;
+            }
         }
     }
     const notes = [];
+    if (draftsUnverified) {
+        notes.push('The drafts folder was NOT checked against OurFamilyWizard on this call (the request budget ran out first), so no drafts count is reported and the cached drafts are marked "unverified". Cached draft bodies may be behind the server. Call ofw_sync_messages again — or ofw_sync_messages with folders:["drafts"] — before editing or deleting a draft.');
+    }
     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 (notRefreshed.length > 0) {
+        notes.push(`NOT checked against OurFamilyWizard on this call: ${notRefreshed.join(', ')}. No count is reported for ${notRefreshed.length > 1 ? 'those folders' : 'that folder'} — absence of a count means "not looked at", not "no changes". Cached contents may be behind the server; call ofw_sync_messages again to finish, or ofw_check_freshness for a cheap live confirmation.`);
+    }
     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 } : {}) };
+    return {
+        synced,
+        unreadInbox,
+        done,
+        syncComplete: done,
+        refreshed,
+        notRefreshed,
+        ...(note ? { note } : {}),
+    };
 }

package/dist/tools/_shared.js

@@ -6,6 +6,13 @@ import { parseLenient } from '@chrischall/mcp-utils';
 export const jsonResponse = textResult;
 // Raw-string tool result. Wrapper over @chrischall/mcp-utils' `rawTextResult`.
 export const textResponse = rawTextResult;
+// A STRUCTURED failure: the machine-readable payload of `jsonResponse` plus
+// `isError`, so a refusal can carry recovery data (e.g. the server draft body
+// we declined to overwrite) without being mistaken for a successful write.
+// mcp-utils' `errorResult` only carries a string.
+export function jsonErrorResponse(data) {
+    return { ...textResult(data), isError: true };
+}
 // OFW API shape for `recipients[]` on message/draft list and detail
 // responses. Used wherever we validate the response of a `/pub/v3/messages*`
 // call. Loose: unknown keys pass through (and survive into cached listData).
@@ -74,23 +81,35 @@ function scrapeSaysRead(listData) {
  * resync (which re-scrapes the list flags) can never flip a read message back
  * to unread:
  *
- *  - INBOX: the account holder is the recipient. When we know our own id
- *    (`selfUserId`), that recipient's `viewedAt` is authoritative; otherwise any
- *    recipient's `viewedAt` stands in (1:1 co-parent messaging). Fetching the
- *    body marks the message read on OFW, so a non-null `fetchedBodyAt` is also
- *    read=true. The stale scrape flag is only a last-resort fallback.
+ *  - INBOX: the account holder is the recipient, so ANY recipient's `viewedAt`
+ *    counts. OFW co-parent threads are 1:1 — the sole inbox recipient is us —
+ *    so this is exact, not an approximation. Fetching the body marks the message
+ *    read on OFW, so a non-null `fetchedBodyAt` is also read=true. The stale
+ *    scrape flag is only a last-resort fallback.
  *  - SENT: "read" means a *recipient* has opened it — tracked via their
  *    `viewedAt` (the detail endpoint's real timestamp) — never our own body
  *    fetch, which is always set for sent messages.
+ *
+ * This deliberately does NOT discriminate by the account holder's own userId.
+ * An earlier `selfUserId` parameter did, but nothing ever passed it, so the
+ * branch was dead in production. Reviving it is not as simple as threading the
+ * argument through, for two reasons:
+ *   1. No non-mutating endpoint exposes our numeric id. /pub/v2/profiles returns
+ *      name/address/contact and no id at all; /pub/v1/users/useraccountstatus
+ *      updates last-seen status as a side effect, and view timestamps are
+ *      evidentiary in custody matters — not something to touch for a read flag.
+ *   2. Rows cached before the `user.userId` parse fix (see ApiRecipientSchema)
+ *      normalized every recipient to `userId: 0`, so an id match would silently
+ *      fail on historical data until a full re-sync.
+ * If OFW ever adds third-party recipients (lawyer, parenting coordinator), both
+ * problems need solving together — a bare parameter would regress to dead code.
  */
-export function deriveRead(row, selfUserId) {
+export function deriveRead(row) {
+    const viewedByAnyone = row.recipients.some((r) => r.viewedAt !== null);
     if (row.folder === 'inbox') {
-        const viewed = selfUserId !== undefined
-            ? row.recipients.some((r) => r.userId === selfUserId && r.viewedAt !== null)
-            : row.recipients.some((r) => r.viewedAt !== null);
-        return viewed || row.fetchedBodyAt !== null || scrapeSaysRead(row.listData);
+        return viewedByAnyone || row.fetchedBodyAt !== null || scrapeSaysRead(row.listData);
     }
-    return row.recipients.some((r) => r.viewedAt !== null) || scrapeSaysRead(row.listData);
+    return viewedByAnyone || scrapeSaysRead(row.listData);
 }
 /**
  * Return the row augmented with an authoritative top-level `read` boolean and a
@@ -99,8 +118,8 @@ export function deriveRead(row, selfUserId) {
  * carrying `listData.read: false` alongside a populated recipient `viewedAt`).
  * A non-object `listData` (null / legacy string) is passed through untouched.
  */
-export function withReadState(row, selfUserId) {
-    const read = deriveRead(row, selfUserId);
+export function withReadState(row) {
+    const read = deriveRead(row);
     const listData = (typeof row.listData === 'object' && row.listData !== null)
         ? { ...row.listData, read, showNeverViewed: !read }
         : row.listData;

package/dist/tools/attachments.js

@@ -38,8 +38,69 @@ const MIME_BY_EXT = {
 export function mimeFromName(name) {
     return MIME_BY_EXT[extname(name).toLowerCase()] ?? 'application/octet-stream';
 }
+const OCTET_STREAM = 'application/octet-stream';
+// The media types a host's inline image renderer accepts. Anything else — even
+// a valid image type like image/heic — must go back as an EmbeddedResource, and
+// a parameter suffix (image/png;charset=UTF-8) is rejected outright, which is
+// exactly the bug this normalization boundary exists to prevent.
+const HOST_RENDERABLE_IMAGE_MIMES = new Set([
+    'image/png', 'image/jpeg', 'image/gif', 'image/webp',
+]);
+/**
+ * Strip a MIME type down to its bare `type/subtype`: drop any `;`-delimited
+ * parameters (`charset`, `name`, …), lowercase, and trim. An empty/absent value
+ * becomes `application/octet-stream`. OFW hands back `image/png;charset=UTF-8`
+ * on binary attachments, and a host's image renderer rejects the parameter
+ * suffix — so no derived MIME must ever carry one.
+ */
+export function normalizeMimeType(raw) {
+    if (!raw)
+        return OCTET_STREAM;
+    const bare = raw.split(';', 1)[0].trim().toLowerCase();
+    return bare || OCTET_STREAM;
+}
+/**
+ * Detect a host-renderable image type from the leading bytes (magic numbers).
+ * OFW's `Content-Type` is unreliable for binaries (it tacks a text `charset`
+ * onto them), so the actual bytes are the authoritative signal. Returns the
+ * bare media type, or null when the bytes aren't a PNG/JPEG/GIF/WEBP.
+ */
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const JPEG_MAGIC = Buffer.from([0xff, 0xd8, 0xff]);
+export function sniffImageMime(bytes) {
+    if (bytes.length >= 8 && bytes.subarray(0, 8).equals(PNG_MAGIC))
+        return 'image/png';
+    if (bytes.length >= 3 && bytes.subarray(0, 3).equals(JPEG_MAGIC))
+        return 'image/jpeg';
+    if (bytes.length >= 6 && bytes.toString('ascii', 0, 4) === 'GIF8')
+        return 'image/gif';
+    if (bytes.length >= 12 &&
+        bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP') {
+        return 'image/webp';
+    }
+    return null;
+}
+/**
+ * Resolve the MIME type to report for downloaded bytes, in priority order:
+ * magic-number sniff (bytes never lie) → parameter-stripped upstream header →
+ * filename extension. The result is always bare (never carries a `;` parameter).
+ */
+export function resolveDownloadMime(bytes, headerMime, fileName) {
+    const sniffed = sniffImageMime(bytes);
+    if (sniffed)
+        return sniffed;
+    const fromHeader = normalizeMimeType(headerMime);
+    if (fromHeader !== OCTET_STREAM)
+        return fromHeader;
+    return mimeFromName(fileName);
+}
+/** True only for the bare media types a host renders as inline ImageContent. */
+export function isHostRenderableImage(mime) {
+    return HOST_RENDERABLE_IMAGE_MIMES.has(mime);
+}
 /** Disk-backed attachment I/O for the stdio/desktop server. */
 export class NodeAttachmentIO {
+    supportsDisk = true;
     async resolveUpload(path) {
         const abs = expandPath(path);
         const stat = statSync(abs); // throws if missing

package/dist/tools/draft-freshness.js

@@ -0,0 +1,166 @@
+import { z } from 'zod';
+import { parseLenient } from '@chrischall/mcp-utils';
+import { ApiRecipientSchema, mapRecipients } from './_shared.js';
+/** Thrown when the freshness check itself could not be completed. */
+export class DraftFreshnessError extends Error {
+}
+// FNV-1a (64-bit) over a canonical encoding. Not cryptographic — this is a
+// change detector, and it is never the sole guard: an unsupplied token falls
+// back to a full field-by-field comparison against the cached base.
+// BigInt keeps it byte-identical on node and on the Workers runtime.
+const FNV_OFFSET = 0xcbf29ce484222325n;
+const FNV_PRIME = 0x100000001b3n;
+const MASK64 = 0xffffffffffffffffn;
+function fnv1a64(s) {
+    let h = FNV_OFFSET;
+    for (let i = 0; i < s.length; i++) {
+        h = (h ^ BigInt(s.charCodeAt(i))) * FNV_PRIME & MASK64;
+    }
+    return h.toString(16).padStart(16, '0');
+}
+/**
+ * A stable content revision for a draft. Callers get this back from
+ * `ofw_list_drafts` / `ofw_get_message` and pass it to `ofw_save_draft` /
+ * `ofw_delete_draft` as `expectedRevision`.
+ *
+ * Recipients reduce to a SORTED set of user ids: their display names and
+ * `viewedAt` are presentation detail that differs between a list-sourced and a
+ * detail-sourced copy of the same draft, and would otherwise produce a false
+ * STALE. Fields are length-prefixed so content cannot shift across a field
+ * boundary without changing the hash.
+ */
+export function draftRevision(d) {
+    const ids = [...new Set(d.recipients.map((r) => r.userId))].sort((a, b) => a - b);
+    const parts = [d.subject, d.body, String(d.replyToId ?? ''), ids.join(',')];
+    return `r1:${fnv1a64(parts.map((p) => `${p.length}:${p}`).join('|'))}`;
+}
+const ServerDraftSchema = z.looseObject({
+    subject: z.string().optional(),
+    body: z.string().optional(),
+    replyToId: z.number().nullable().optional(),
+    recipients: z.array(ApiRecipientSchema).optional(),
+});
+function isNotFound(e) {
+    return e instanceof Error && /OFW API error: 404\b/.test(e.message);
+}
+/**
+ * Read a draft's AUTHORITATIVE state straight from OFW, bypassing the cache.
+ *
+ * Returns `null` when the draft no longer exists (404). Any other failure
+ * throws `DraftFreshnessError`: a freshness check that could not run must
+ * abort the write, never wave it through — see the callers in messages.ts.
+ */
+export async function fetchServerDraft(client, id) {
+    let raw;
+    try {
+        raw = await client.request('GET', `/pub/v3/messages/${id}`);
+    }
+    catch (e) {
+        if (isNotFound(e))
+            return null;
+        throw new DraftFreshnessError(`could not read the current state of draft ${id} from OurFamilyWizard: ${e.message}`);
+    }
+    // An empty/null body is OFW's other way of saying "no such message". Treat
+    // it as MISSING — which still ABORTS the write — rather than letting the
+    // strict parse throw an opaque shape error.
+    if (raw === null || raw === undefined)
+        return null;
+    const detail = parseLenient(ServerDraftSchema, raw, {
+        label: 'ofw-mcp',
+        context: 'GET /pub/v3/messages/{id} (draft freshness check)',
+        mode: 'strict',
+    });
+    return {
+        subject: detail.subject ?? '',
+        body: detail.body ?? '',
+        replyToId: detail.replyToId ?? null,
+        recipients: mapRecipients(detail.recipients),
+    };
+}
+function diffFields(a, b) {
+    const changed = [];
+    if (a.subject !== b.subject)
+        changed.push('subject');
+    if (a.body !== b.body)
+        changed.push('body');
+    if (a.replyToId !== b.replyToId)
+        changed.push('replyToId');
+    const ids = (d) => [...new Set(d.recipients.map((r) => r.userId))].sort((x, y) => x - y).join(',');
+    if (ids(a) !== ids(b))
+        changed.push('recipients');
+    return changed;
+}
+/**
+ * Decide whether it is safe to destroy the server's copy of a draft.
+ *
+ * Two independent ways to earn FRESH, in priority order:
+ *
+ *  1. `expectedRevision` matches the live server revision. The caller has named
+ *     the exact server state it edited from, which is what optimistic
+ *     concurrency asserts. A stale cached copy alongside a matching token is
+ *     not evidence of a conflict, so the token wins.
+ *  2. No token supplied → the cached base must match the server EXACTLY. This
+ *     is the safe default: "no token" never means "force".
+ *
+ * Everything else — server ahead of cache, no cached base to compare, draft
+ * gone from the server — refuses.
+ */
+export function checkDraftFreshness(input) {
+    const { server, cached, expectedRevision } = input;
+    if (server === null) {
+        return {
+            verdict: 'MISSING',
+            reason: 'The draft no longer exists on OurFamilyWizard — it may have been sent or deleted elsewhere.',
+            changedFields: [],
+        };
+    }
+    if (expectedRevision !== undefined) {
+        const actual = draftRevision(server);
+        if (expectedRevision === actual) {
+            return { verdict: 'FRESH', reason: 'expectedRevision matches the live server draft.', changedFields: [] };
+        }
+        return {
+            verdict: 'STALE',
+            reason: `expectedRevision ${expectedRevision} does not match the live server draft (${actual}) — it changed after you read it.`,
+            changedFields: cached === null ? [] : diffFields(server, cached),
+        };
+    }
+    if (cached === null) {
+        return {
+            verdict: 'STALE',
+            reason: 'This draft is not in the local cache, so there is no base to confirm the edit against.',
+            changedFields: [],
+        };
+    }
+    const changedFields = diffFields(server, cached);
+    if (changedFields.length === 0) {
+        return { verdict: 'FRESH', reason: 'The cached draft matches the live server draft.', changedFields: [] };
+    }
+    return {
+        verdict: 'STALE',
+        reason: `The draft on OurFamilyWizard differs from the cached copy (${changedFields.join(', ')}) — it was edited outside this tool.`,
+        changedFields,
+    };
+}
+/**
+ * Build the structured refusal returned when a destructive draft op is blocked.
+ * ALWAYS carries the current server body when there is one, so the content we
+ * declined to overwrite is recoverable from the tool result itself.
+ */
+export function staleDraftPayload(input) {
+    const { error, draftId, verdict, server, cached } = input;
+    return {
+        error,
+        draftId,
+        verdict: verdict.verdict,
+        reason: verdict.reason,
+        ...(verdict.changedFields.length > 0 ? { changedFields: verdict.changedFields } : {}),
+        ...(server !== null
+            ? { serverBody: server.body, serverSubject: server.subject, serverRevision: draftRevision(server) }
+            : {}),
+        ...(cached !== null ? { cachedBody: cached.body } : {}),
+        recovery: server === null
+            ? 'The draft is gone from OurFamilyWizard. Nothing was changed. If you still want this content saved, call ofw_save_draft WITHOUT messageId to create a new draft.'
+            : 'Nothing was changed. Merge your edit into serverBody above, then retry with expectedRevision set to serverRevision. Pass force:true only if you intend to discard the server copy shown here.',
+    };
+}