ofw-mcp 2.8.0 → 2.9.0

package/dist/cache/store.js

@@ -32,6 +32,14 @@ function draftFromDb(r) {
         listData: JSON.parse(r.list_data_json),
     };
 }
+function lineageFromDb(r) {
+    return {
+        id: r.id,
+        draftKey: r.draft_key,
+        previousId: r.previous_id,
+        recordedAt: r.recorded_at,
+    };
+}
 function attachmentFromDb(r) {
     return {
         fileId: r.file_id,
@@ -93,6 +101,17 @@ export const SCHEMA_STATEMENTS = [
      key TEXT PRIMARY KEY,
      value TEXT NOT NULL
    )`,
+    // v3: draft identity chain. One row per OFW id, all the ids of one logical
+    // document sharing a `draft_key`. Survives ofw_save_draft's create-then-delete
+    // replacement AND the transition to a sent message, so "what happened to the
+    // draft I was editing?" is answerable without guessing which id is current.
+    `CREATE TABLE IF NOT EXISTS draft_lineage (
+     id INTEGER PRIMARY KEY,
+     draft_key TEXT NOT NULL,
+     previous_id INTEGER,
+     recorded_at TEXT NOT NULL
+   )`,
+    `CREATE INDEX IF NOT EXISTS idx_draft_lineage_key ON draft_lineage(draft_key, recorded_at, id)`,
     // v2: attachments table. Idempotent — IF NOT EXISTS.
     `CREATE TABLE IF NOT EXISTS attachments (
      file_id INTEGER PRIMARY KEY,
@@ -119,7 +138,7 @@ export const MIGRATIONS = [
     'ALTER TABLE sync_state ADD COLUMN resume_page INTEGER',
 ];
 /** The schema version stamped into the `meta` table on open. */
-export const SCHEMA_VERSION = '2';
+export const SCHEMA_VERSION = '3';
 // Build the WHERE clause + bound params for message queries. listMessages and
 // countMessages share this so the filter semantics can't drift.
 function buildMessageFilter(opts) {
@@ -302,6 +321,11 @@ export class OFWCacheCore {
         const rows = this.db.all('SELECT * FROM drafts ORDER BY modified_at DESC, id DESC LIMIT ? OFFSET ?', [opts.size, offset]);
         return rows.map(draftFromDb);
     }
+    countDrafts() {
+        const r = this.db.get('SELECT COUNT(*) as n FROM drafts', []);
+        /* v8 ignore next -- SELECT COUNT(*) always returns exactly one row; the ?./?? are defensive */
+        return r?.n ?? 0;
+    }
     deleteDraft(id) {
         this.db.run('DELETE FROM drafts WHERE id = ?', [id]);
     }
@@ -309,6 +333,45 @@ export class OFWCacheCore {
         const rows = this.db.all('SELECT id FROM drafts', []);
         return rows.map((r) => r.id);
     }
+    /**
+     * Link an id into a draft's identity chain. Upserts on id: re-recording the
+     * same id (e.g. a retried save) rewrites its link rather than duplicating it,
+     * so `getDraftLineage` can never report one id twice.
+     */
+    recordDraftLineage(row) {
+        this.db.run(`INSERT INTO draft_lineage (id, draft_key, previous_id, recorded_at) VALUES (?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET
+         draft_key=excluded.draft_key,
+         previous_id=excluded.previous_id,
+         recorded_at=excluded.recorded_at`, [row.id, requireString('draft_lineage.draftKey', row.draftKey), nullish(row.previousId),
+            requireString('draft_lineage.recordedAt', row.recordedAt)]);
+    }
+    getDraftLineageById(id) {
+        const r = this.db.get('SELECT * FROM draft_lineage WHERE id = ?', [id]);
+        return r ? lineageFromDb(r) : null;
+    }
+    /**
+     * Batch read — one query for a whole page of drafts. On the Durable Object
+     * backend each cache call is a subrequest, so a per-draft lookup would spend
+     * the caller's sync budget on bookkeeping.
+     */
+    getDraftLineageByIds(ids) {
+        if (ids.length === 0)
+            return [];
+        const placeholders = ids.map(() => '?').join(', ');
+        const rows = this.db.all(`SELECT * FROM draft_lineage WHERE id IN (${placeholders})`, ids);
+        return rows.map(lineageFromDb);
+    }
+    /**
+     * Every link in one chain, OLDEST FIRST — so the last element is the chain's
+     * current id. Ordered by recorded_at then id: two links written inside the
+     * same millisecond tie-break on id, and OFW mints ids monotonically, so the
+     * newer replacement always sorts last.
+     */
+    getDraftLineage(draftKey) {
+        const rows = this.db.all('SELECT * FROM draft_lineage WHERE draft_key = ? ORDER BY recorded_at ASC, id ASC', [draftKey]);
+        return rows.map(lineageFromDb);
+    }
     getSyncState(folder) {
         const r = this.db.get('SELECT last_sync_at, newest_id, resume_page FROM sync_state WHERE folder = ?', [folder]);
         if (!r)
@@ -444,12 +507,27 @@ export class LocalCacheStore {
     async listDrafts(opts) {
         return this.core.listDrafts(opts);
     }
+    async countDrafts() {
+        return this.core.countDrafts();
+    }
     async deleteDraft(id) {
         this.core.deleteDraft(id);
     }
     async listDraftIds() {
         return this.core.listDraftIds();
     }
+    async recordDraftLineage(row) {
+        this.core.recordDraftLineage(row);
+    }
+    async getDraftLineageById(id) {
+        return this.core.getDraftLineageById(id);
+    }
+    async getDraftLineageByIds(ids) {
+        return this.core.getDraftLineageByIds(ids);
+    }
+    async getDraftLineage(draftKey) {
+        return this.core.getDraftLineage(draftKey);
+    }
     async getSyncState(folder) {
         return this.core.getSyncState(folder);
     }

package/dist/config.js

@@ -124,6 +124,24 @@ export function getAllowMarkRead() {
 export function getFetchUnreadBodies() {
     return parseBoolEnv('OFW_FETCH_UNREAD_BODIES');
 }
+/**
+ * Default for the read tools' `autoRefresh` arg.
+ *
+ * When a cached read comes back EMPTY and the cache is not `fresh`, the tools
+ * refuse to report that emptiness (see UNVERIFIED_EMPTY in tools/messages.ts):
+ * an empty result from a 207-minute-old cache is shaped identically to a
+ * verified "nothing there", and answering "no, it wasn't sent" from one is how
+ * a false negative becomes a confident statement about a legal record.
+ *
+ * The refusal names its remedy, so the default (false) costs one extra call.
+ * Set OFW_AUTO_REFRESH=true and the tools instead sync the backing folders
+ * themselves and answer from the refreshed cache — same guarantee, no round
+ * trip. Never silently degrades: if the refresh does not make the read
+ * verifiable, the refusal still fires.
+ */
+export function getAutoRefreshStaleReads() {
+    return parseBoolEnv('OFW_AUTO_REFRESH');
+}
 // Default for ofw_download_attachment's `inline` arg when the caller doesn't
 // pass one. Set OFW_INLINE_ATTACHMENTS=true to have attachments returned as
 // MCP content blocks by default (skipping disk) — useful on sandboxed MCP

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.8.0', // x-release-please-version
+    version: '2.9.0', // x-release-please-version
     deps: client,
     tools: [
         registerUserTools,

package/dist/sync.js

@@ -94,6 +94,10 @@ export async function resolveFolderIds(client, store) {
     // 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);
+    // And inbox, which completes the map a lifecycle probe needs to turn a detail
+    // payload's own folder id into "draft" / "sent" / "received" (see
+    // tools/lifecycle.ts). Without all three, a probe can only say "unknown".
+    await store.setMeta('inbox_folder_id', ids.inbox);
     return ids;
 }
 // Required fields are the ones the sync loop reads unguarded (id keys the

package/dist/tools/draft-freshness.js

@@ -39,23 +39,40 @@ const ServerDraftSchema = z.looseObject({
     body: z.string().optional(),
     replyToId: z.number().nullable().optional(),
     recipients: z.array(ApiRecipientSchema).optional(),
+    // Read for the LIFECYCLE answer (see tools/lifecycle.ts): which folder OFW
+    // itself says this id lives in right now. `existsOnServer` alone cannot
+    // distinguish "still a draft" from "was sent" — a sent draft still exists.
+    // `id` accepts BOTH spellings deliberately. This schema is parsed in
+    // `mode: 'strict'` because it backs the destructive-draft guard, so a
+    // present-but-mistyped field THROWS — and OFW is already inconsistent about
+    // this exact field: the folders listing (`FoldersSchema` in sync.ts) types it
+    // `z.string()`, while message detail has been observed returning a number.
+    // Pinning one spelling here would turn a harmless representation change into
+    // a hard failure of ofw_save_draft / ofw_delete_draft, which is the opposite
+    // of what a strict boundary is for: it exists to stop us acting on a response
+    // we cannot interpret, not to reject one we can. `folderId` is normalized to
+    // a string below, so both spellings compare correctly downstream.
+    folder: z.looseObject({
+        id: z.union([z.string(), z.number()]).optional(),
+        name: z.string().optional(),
+    }).nullable().optional(),
+    date: z.looseObject({ dateTime: z.string().optional() }).nullable().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.
+ * Read a message's AUTHORITATIVE state straight from OFW, bypassing the cache.
  *
- * Returns `null` when the draft no longer exists (404). Any other failure
- * throws, and the callers in messages.ts abort on ALL of them: a freshness
- * check that could not run must never wave the write through.
+ * Returns `null` when it no longer exists (404, or an empty body — OFW's other
+ * way of saying "no such message"). Any other failure throws.
  *
- * Most failures throw `DraftFreshnessError` from this function, but not all —
- * a strict `parseLenient` mismatch on the response throws `McpToolError`
- * instead. Callers must not assume the narrower type (the catch blocks read
- * only `.message`, which every Error carries).
+ * Most failures throw `DraftFreshnessError`, but not all — a strict
+ * `parseLenient` mismatch throws `McpToolError` instead. Callers must not assume
+ * the narrower type (the catch blocks read only `.message`, which every Error
+ * carries).
  */
-export async function fetchServerDraft(client, id) {
+export async function fetchMessageSnapshot(client, id) {
     let raw;
     try {
         raw = await client.request('GET', `/pub/v3/messages/${id}`);
@@ -76,12 +93,28 @@ export async function fetchServerDraft(client, id) {
         mode: 'strict',
     });
     return {
-        subject: detail.subject ?? '',
-        body: detail.body ?? '',
-        replyToId: detail.replyToId ?? null,
-        recipients: mapRecipients(detail.recipients),
+        content: {
+            subject: detail.subject ?? '',
+            body: detail.body ?? '',
+            replyToId: detail.replyToId ?? null,
+            recipients: mapRecipients(detail.recipients),
+        },
+        folderId: detail.folder?.id === undefined ? null : String(detail.folder.id),
+        folderName: detail.folder?.name ?? null,
+        dateTime: detail.date?.dateTime ?? null,
     };
 }
+/**
+ * The content-only view of {@link fetchMessageSnapshot}, used by the
+ * destructive-draft guard, which cares what the draft SAYS, not where it lives.
+ *
+ * Returns `null` when the draft no longer exists. Any other failure throws, and
+ * the callers in messages.ts abort on ALL of them: a freshness check that could
+ * not run must never wave the write through.
+ */
+export async function fetchServerDraft(client, id) {
+    return (await fetchMessageSnapshot(client, id))?.content ?? null;
+}
 /**
  * The fields whose divergence constitutes a REAL conflict — the actual message
  * content a caller would lose if we overwrote a copy edited elsewhere. Anything

package/dist/tools/lifecycle.js

@@ -0,0 +1,277 @@
+import { resolveFolderIds } from '../sync.js';
+import { draftRevision, fetchMessageSnapshot } from './draft-freshness.js';
+import { deriveRead } from './_shared.js';
+/** OFW's `folderType` discriminator for each folder we track. */
+export const FOLDER_TYPE = {
+    inbox: 'INBOX',
+    sent: 'SENT_MESSAGES',
+    drafts: 'DRAFTS',
+};
+/** Where each folder's id is persisted in the `meta` table. */
+const FOLDER_ID_META_KEY = {
+    inbox: 'inbox_folder_id',
+    sent: 'sent_folder_id',
+    drafts: 'drafts_folder_id',
+};
+const FOLDERS = ['inbox', 'sent', 'drafts'];
+/** Read whatever folder ids past syncs persisted. No requests. */
+export async function readFolderIdMap(store) {
+    return {
+        inbox: await store.getMeta(FOLDER_ID_META_KEY.inbox),
+        sent: await store.getMeta(FOLDER_ID_META_KEY.sent),
+        drafts: await store.getMeta(FOLDER_ID_META_KEY.drafts),
+    };
+}
+/**
+ * Persist folder ids harvested from a folders listing the caller ALREADY
+ * fetched.
+ *
+ * `ofw_check_freshness` asked about folders and ids in one call hits
+ * `/pub/v1/messageFolders?includeFolderCounts=true` for the counts, and then
+ * `ensureFolderIdMap` hit the very same endpoint again to learn the ids. The
+ * response in hand already carries them; taking them makes the second call a
+ * no-op instead of a duplicate round trip.
+ */
+export async function persistFolderIds(store, systemFolders) {
+    for (const folder of FOLDERS) {
+        const entry = systemFolders.find((f) => f.folderType === FOLDER_TYPE[folder]);
+        if (entry !== undefined)
+            await store.setMeta(FOLDER_ID_META_KEY[folder], entry.id);
+    }
+}
+/**
+ * The folder map, resolving it live when the cache has never held all three.
+ *
+ * Costs at most ONE request, and only when the map is genuinely incomplete —
+ * without it every probe degrades to `unknown`, which is a refusal to answer,
+ * not an answer. A failed resolve is swallowed: we fall back to the partial
+ * cached map and let classification say `unknown` honestly, rather than failing
+ * a whole status call over a folder listing.
+ */
+export async function ensureFolderIdMap(client, store) {
+    const cached = await readFolderIdMap(store);
+    if (cached.inbox !== null && cached.sent !== null && cached.drafts !== null) {
+        return { map: cached, requests: 0 };
+    }
+    try {
+        const ids = await resolveFolderIds(client, store);
+        return { map: { inbox: ids.inbox, sent: ids.sent, drafts: ids.drafts }, requests: 1 };
+    }
+    catch {
+        return { map: cached, requests: 1 };
+    }
+}
+/**
+ * Map a live snapshot to a lifecycle state. Pure — the request already happened.
+ *
+ * A null snapshot means OFW returned 404 / an empty body, i.e. `deleted`. An
+ * unmappable folder is `unknown` rather than being guessed at: guessing here is
+ * exactly how "still a draft" gets asserted about something that was sent.
+ */
+export function classifyState(snapshot, map) {
+    if (snapshot === null)
+        return 'deleted';
+    const { folderId } = snapshot;
+    if (folderId === null)
+        return 'unknown';
+    if (map.drafts !== null && folderId === map.drafts)
+        return 'draft';
+    if (map.sent !== null && folderId === map.sent)
+        return 'sent';
+    if (map.inbox !== null && folderId === map.inbox)
+        return 'received';
+    return 'unknown';
+}
+/**
+ * Would probing this id stamp the record?
+ *
+ * A probe is `GET /pub/v3/messages/{id}`, and for an UNREAD INBOX message that
+ * marks it read on OFW and writes a co-parent-visible "First Viewed" time —
+ * court-visible and irreversible. Everything else is free of side effects:
+ *
+ *   - a cached DRAFT: drafts have no read state at all;
+ *   - a cached SENT message: its view times belong to the recipient, and our
+ *     own fetch never writes one;
+ *   - a cached inbox message already derived as read: the stamp exists, and
+ *     `deriveRead` is monotonic so it cannot be added twice.
+ *
+ * An id with NO cached row returns true — whether it would stamp is exactly
+ * what cannot be known without making the request that stamps it.
+ */
+export function probeWouldStamp(cachedDraft, cachedMessage) {
+    if (cachedDraft !== null)
+        return false;
+    if (cachedMessage === null)
+        return true;
+    if (cachedMessage.folder === 'sent')
+        return false;
+    return !deriveRead(cachedMessage);
+}
+const SKIP_NOTE = 'Verifying this id requires fetching its detail from OurFamilyWizard, which would mark an unread inbox message as READ and stamp a co-parent-visible "First Viewed" time on the record. Ids already cached as drafts, as sent, or as already-read inbox messages are probed freely because none of those can stamp anything. Run ofw_sync_messages (it walks list pages, not bodies) or pass allowMarkRead:true.';
+function stateNote(state, cachedAsDraft, folderName) {
+    if (state === 'deleted') {
+        return cachedAsDraft
+            ? 'This draft is in the local cache but NO LONGER EXISTS on OurFamilyWizard — it was sent or deleted elsewhere. Do not describe it as still unsent.'
+            : 'Not found on OurFamilyWizard.';
+    }
+    if (state === 'sent') {
+        return cachedAsDraft
+            ? 'This id is cached as a DRAFT but OurFamilyWizard now has it in Sent — it was SENT (see sentAt). It is no longer a draft; saying it is still unsent would be false.'
+            : 'This id is a sent message on OurFamilyWizard.';
+    }
+    if (state === 'received') {
+        return cachedAsDraft
+            ? 'This id is cached as a draft but OurFamilyWizard has it in the Inbox. Run ofw_sync_messages to reconcile.'
+            : 'This id is an inbox message on OurFamilyWizard.';
+    }
+    if (state === 'unknown') {
+        return `OurFamilyWizard did not report a folder this tool can map${folderName === null ? '' : ` (it reported "${folderName}")`}, so what this id has become is NOT established. Treat it as unverified rather than assuming it is unchanged.`;
+    }
+    return undefined;
+}
+/**
+ * Probe a batch of ids live and return one lifecycle verdict each.
+ *
+ * Skips are decided BEFORE anything is fetched, so a call whose every id is
+ * refused spends zero OFW requests — including the folder-map resolve, which
+ * only happens when at least one id will actually be probed. Costs at most one
+ * request for the map plus one per probed id.
+ */
+export async function probeIds(client, store, ids, opts) {
+    // THREE cache reads for the whole batch, not three per id. On the Durable
+    // Object backend every cache call is a subrequest counting against the same
+    // hosting cap as the OFW fetches, so a per-id lookup would spend the caller's
+    // budget on bookkeeping before a single probe ran.
+    const draftsById = new Map((await store.getDrafts(ids)).map((d) => [d.id, d]));
+    const messagesById = new Map((await store.getMessages(ids)).map((m) => [m.id, m]));
+    const prepared = ids.map((id) => {
+        const cachedDraft = draftsById.get(id) ?? null;
+        const cachedMessage = cachedDraft === null ? messagesById.get(id) ?? null : null;
+        return {
+            id,
+            cachedDraft,
+            cachedMessage,
+            skip: !opts.allowMarkRead && probeWouldStamp(cachedDraft, cachedMessage),
+        };
+    });
+    let requests = 0;
+    let map = { inbox: null, sent: null, drafts: null };
+    if (prepared.some((p) => !p.skip)) {
+        const resolved = await ensureFolderIdMap(client, store);
+        map = resolved.map;
+        requests += resolved.requests;
+    }
+    const keyById = new Map((await store.getDraftLineageByIds(ids)).map((l) => [l.id, l.draftKey]));
+    const items = [];
+    for (const p of prepared) {
+        if (p.skip) {
+            items.push({ id: p.id, skipped: true, reason: 'WOULD_MARK_READ', note: SKIP_NOTE });
+            continue;
+        }
+        const probe = await probeOne(client, p, map, keyById.get(p.id) ?? null);
+        requests += probe.requests;
+        items.push(probe.item);
+    }
+    return { items, requests };
+}
+/**
+ * The live half of one probe. Never throws: a probe that could not run comes
+ * back as an error item, because a check that failed must never read as
+ * "in sync".
+ */
+async function probeOne(client, prepared, map, draftKey) {
+    const { id, cachedDraft } = prepared;
+    let snapshot;
+    try {
+        snapshot = await fetchMessageSnapshot(client, id);
+    }
+    catch (e) {
+        return {
+            requests: 1,
+            item: {
+                id,
+                error: 'FRESHNESS_CHECK_FAILED',
+                message: e.message,
+                inSync: null,
+                note: 'The freshness check itself failed, so nothing is confirmed either way.',
+            },
+        };
+    }
+    const state = classifyState(snapshot, map);
+    const cacheRevision = cachedDraft === null ? null : draftRevision(cachedDraft);
+    const serverRevision = snapshot === null ? null : draftRevision(snapshot.content);
+    const viewedAt = snapshot?.content.recipients.find((r) => r.viewedAt !== null)?.viewedAt ?? null;
+    // `inSync` compares the CACHED DRAFT against the server, and it is FALSE the
+    // moment the entity stops being what the cache says it is — even when every
+    // byte of content still matches. A sent draft keeps its subject and body
+    // verbatim, so a revision-only comparison reported inSync:true for exactly
+    // the case this whole mechanism exists to catch.
+    //
+    // `null` means "not compared", the same thing it means on the folder
+    // verdicts: there is no cached draft to compare, or the content matches but
+    // OFW did not tell us where the message now lives. Never `false` for those —
+    // false claims a drift was detected.
+    let inSync;
+    if (cachedDraft === null)
+        inSync = null;
+    else if (snapshot === null)
+        inSync = false;
+    else if (cacheRevision !== serverRevision)
+        inSync = false;
+    else if (state === 'draft')
+        inSync = true;
+    else if (state === 'unknown')
+        inSync = null;
+    else
+        inSync = false;
+    // State and content are INDEPENDENT signals, so both are reported. An
+    // unmappable folder must not swallow "this was edited on OFW", and a content
+    // match must not swallow "this is no longer a draft".
+    const notes = [];
+    const stateN = stateNote(state, cachedDraft !== null, snapshot?.folderName ?? null);
+    if (stateN !== undefined)
+        notes.push(stateN);
+    if (snapshot !== null && cachedDraft === null) {
+        notes.push('Not in the drafts cache, so there is no cached copy to compare its content against (inSync is null, not false).');
+    }
+    else if (snapshot !== null && cacheRevision !== serverRevision) {
+        notes.push('Content differs from the cache — it was edited on OurFamilyWizard since the last sync. Run ofw_sync_messages before reading or writing it.');
+    }
+    return {
+        requests: 1,
+        item: {
+            id,
+            state,
+            folder: snapshot?.folderName ?? null,
+            sentAt: state === 'sent' ? snapshot?.dateTime ?? null : null,
+            viewedAt,
+            existsOnServer: snapshot !== null,
+            cacheRevision,
+            serverRevision,
+            inSync,
+            ...(draftKey !== null ? { draftKey } : {}),
+            ...(notes.length > 0 ? { note: notes.join(' ') } : {}),
+        },
+    };
+}
+/**
+ * Resolve a stable {@link import('../cache/store.js').DraftLineageRow} key to
+ * the chain's CURRENT id.
+ *
+ * Returns null when the key was never recorded — an unknown key must not
+ * silently resolve to nothing-in-particular.
+ */
+export async function resolveDraftKey(store, draftKey) {
+    const chain = await store.getDraftLineage(draftKey);
+    if (chain.length === 0)
+        return null;
+    return { currentId: chain[chain.length - 1].id, ids: chain.map((r) => r.id) };
+}
+/**
+ * Mint a new stable draft identity. Uses the Web Crypto global, which both
+ * Node ≥19 and the Workers runtime provide — a `node:crypto` import would not
+ * bundle for the hosted connector.
+ */
+export function newDraftKey() {
+    return `dk_${crypto.randomUUID()}`;
+}