ofw-mcp 2.6.7 → 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.7', // 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(),
@@ -334,6 +357,38 @@ 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);
@@ -342,7 +397,16 @@ export async function syncDrafts(client, draftsFolderId, store, budget) {
     // 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 store.setMeta(DRAFTS_CACHE_STATUS_KEY, 'unverified');
+        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
@@ -411,8 +475,12 @@ export async function syncDrafts(client, draftsFolderId, store, budget) {
     }
     // 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".
-    await store.setMeta(DRAFTS_CACHE_STATUS_KEY, 'fresh');
+    // 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) {
@@ -440,6 +508,21 @@ export async function syncAll(client, opts, store) {
     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, {
@@ -447,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;
@@ -458,7 +541,7 @@ 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;
         }
@@ -468,9 +551,8 @@ export async function syncAll(client, opts, store) {
             // 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.
-            if (r.done)
-                synced.drafts = r.synced;
-            else {
+            record('drafts', r.done, r.synced);
+            if (!r.done) {
                 draftsUnverified = true;
                 done = false;
             }
@@ -483,9 +565,20 @@ export async function syncAll(client, opts, store) {
     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/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/freshness.js

@@ -0,0 +1,147 @@
+import { getFolderVerifiedAt } from '../sync.js';
+import { getFreshnessTtlSeconds } from '../config.js';
+const RANK = { fresh: 0, unverified: 1, stale: 2 };
+function worst(a, b) {
+    return RANK[a] >= RANK[b] ? a : b;
+}
+/** Human-readable age: seconds under a minute, else whole minutes. */
+function describeAge(seconds) {
+    return seconds < 60 ? `${seconds} sec ago` : `${Math.round(seconds / 60)} min ago`;
+}
+/**
+ * Build the `freshness` block that every message/draft/folder read carries.
+ *
+ * The point is that the DATA announces its own age and reliability, so a
+ * caller cannot assert current state without either a fresh read or an
+ * explicit staleness caveat it has to surface. Nothing here depends on the
+ * model remembering to re-check.
+ *
+ * Across multiple folders the block reports the WORST staleness and the OLDEST
+ * asOf: a response is only as trustworthy as its least-verified input.
+ */
+export async function buildFreshness(store, opts) {
+    const now = opts.now ?? new Date();
+    const ttl = opts.ttlSeconds ?? getFreshnessTtlSeconds();
+    // A cache read backed by NO folder has verified nothing, so nothing in the
+    // per-folder loop below can downgrade the 'fresh' initializer — it would
+    // return `staleness: 'fresh'` alongside `asOf: null`, self-contradictory by
+    // this module's own definition and the one shape that carries no warning at
+    // all. Reachable via ofw_sync_messages({folders: []}). Fail to `stale`: an
+    // empty scope is the least evidence possible, not the most.
+    // (A LIVE read with no folders is different and legitimate — that is
+    // ofw_list_message_folders, whose data came straight off the wire.)
+    const emptyScope = opts.source === 'cache' && opts.folders.length === 0;
+    let staleness = emptyScope ? 'stale' : 'fresh';
+    let oldestVerifiedAt = null;
+    let sawNeverVerified = false;
+    let lastServerSyncAt = null;
+    let historyComplete = true;
+    // An empty scope verified nothing, so it cannot claim a complete sync.
+    let syncComplete = !emptyScope;
+    const deferred = [];
+    const backfilling = [];
+    for (const folder of opts.folders) {
+        const verifiedAt = await getFolderVerifiedAt(store, folder);
+        const state = await store.getSyncState(folder);
+        if (state !== null && (lastServerSyncAt === null || state.lastSyncAt > lastServerSyncAt)) {
+            lastServerSyncAt = state.lastSyncAt;
+        }
+        // A parked backfill means old history is incomplete. It does NOT downgrade
+        // staleness: the forward pass runs from page 1 on every call, so the
+        // present is current even while history is still being walked. Letting a
+        // months-long backfill mark every read `unverified` would train the caller
+        // to ignore the warning entirely.
+        if (state !== null && state.resumePage !== null) {
+            historyComplete = false;
+            syncComplete = false;
+            backfilling.push(folder);
+        }
+        if (verifiedAt === null) {
+            sawNeverVerified = true;
+            staleness = worst(staleness, 'stale');
+            syncComplete = false;
+            continue;
+        }
+        if (oldestVerifiedAt === null || verifiedAt < oldestVerifiedAt)
+            oldestVerifiedAt = verifiedAt;
+        // A sync ran AFTER the last verification of this folder — i.e. it was
+        // attempted and skipped (budget exhausted before reaching it). Recency of
+        // the older stamp must not keep it `fresh`; the skip is itself evidence
+        // that we do not currently know this folder's state.
+        if (state !== null && state.lastSyncAt > verifiedAt) {
+            staleness = worst(staleness, 'unverified');
+            syncComplete = false;
+            deferred.push(folder);
+            continue;
+        }
+        // Clamp at 0: a verifiedAt in the future (clock skew between the machine
+        // that wrote it and this one) must not read as a large negative age that
+        // can never exceed the threshold — that would be a silent false `fresh`.
+        const age = Math.max(0, Math.floor((now.getTime() - Date.parse(verifiedAt)) / 1000));
+        if (age > ttl)
+            staleness = worst(staleness, 'unverified');
+    }
+    // A live read is current by construction — that is the whole point of paying
+    // for it — so it reports fresh regardless of what the cache looks like.
+    if (opts.source === 'live') {
+        const asOf = now.toISOString();
+        const block = {
+            source: 'live',
+            asOf,
+            ageSeconds: 0,
+            staleness: 'fresh',
+            lastServerSyncAt,
+            syncComplete,
+            historyComplete,
+        };
+        const liveReasons = [];
+        if (sawNeverVerified) {
+            liveReasons.push('the surrounding cache has never been checked against OurFamilyWizard, so anything you did NOT fetch in this call is unverified');
+        }
+        if (backfilling.length > 0) {
+            liveReasons.push(`older history is still being backfilled for ${backfilling.join(', ')}, so older messages may be missing from the cache`);
+        }
+        if (liveReasons.length > 0) {
+            block.warning = `Fetched live from OurFamilyWizard, so this data is current. Note that ${liveReasons.join('; ')}.`;
+        }
+        return block;
+    }
+    const asOf = sawNeverVerified ? null : oldestVerifiedAt;
+    const ageSeconds = asOf === null
+        ? null
+        : Math.max(0, Math.floor((now.getTime() - Date.parse(asOf)) / 1000));
+    const block = {
+        source: 'cache',
+        asOf,
+        ageSeconds,
+        staleness,
+        lastServerSyncAt,
+        syncComplete,
+        historyComplete,
+    };
+    const reasons = [];
+    if (emptyScope) {
+        reasons.push('this result is backed by no synced folder at all, so nothing about it has been verified');
+    }
+    if (sawNeverVerified) {
+        reasons.push('this data has never been checked against OurFamilyWizard');
+    }
+    if (deferred.length > 0) {
+        reasons.push(`the last sync did not finish checking ${deferred.join(', ')}`);
+    }
+    // Reported independently of the deferral: a response can be BOTH deferred
+    // and badly aged, and naming only the deferral understates how old it is.
+    if (asOf !== null && ageSeconds !== null && ageSeconds > ttl) {
+        reasons.push(`that is past the ${ttl}s freshness threshold`);
+    }
+    if (backfilling.length > 0) {
+        reasons.push(`older history is still being backfilled for ${backfilling.join(', ')}`);
+    }
+    if (reasons.length > 0) {
+        const served = asOf === null
+            ? 'Served from cache that was never verified against OurFamilyWizard'
+            : `Served from cache last verified ${describeAge(ageSeconds)}`;
+        block.warning = `${served}; ${reasons.join('; ')}. Re-read before asserting current state — call ofw_check_freshness for a cheap live confirmation, or ofw_sync_messages to refresh.`;
+    }
+    return block;
+}