ofw-mcp 2.7.0 → 2.8.0

package/dist/extract/zip.js

@@ -0,0 +1,110 @@
+// A minimal, dependency-free ZIP reader.
+//
+// OOXML attachments (.xlsx/.docx/.pptx) are ZIP containers of XML parts, so
+// reading one is the first step of every office-document extractor. This is
+// deliberately not a general ZIP library: it reads the central directory,
+// slices an entry's bytes, and inflates DEFLATE members via the WHATWG
+// `DecompressionStream` — which exists in BOTH Node ≥18 and workerd, so the
+// same code runs on the stdio server and the hosted connector. Using
+// `node:zlib` here would break the Worker build; adding a userland inflate
+// dependency would bloat it. Neither is necessary.
+import { inflateBounded, MAX_DECOMPRESSED_BYTES } from './inflate.js';
+const EOCD_SIG = 0x06054b50;
+const CENTRAL_SIG = 0x02014b50;
+const LOCAL_SIG = 0x04034b50;
+const ZIP64_SENTINEL = 0xffffffff;
+/**
+ * Hard ceiling on a single decompressed member (32 MiB). An attachment is a
+ * co-parent-supplied file, so a zip bomb is a real (if unlikely) input, and the
+ * Worker's memory budget is what is being protected.
+ *
+ * The cap is enforced on the bytes as they arrive ({@link inflateBounded}), NOT
+ * on the size the archive declares for itself. The declared size is checked too
+ * — it rejects an HONEST oversized member without inflating anything — but it
+ * is an optimization, not the guarantee: a central directory is free to claim
+ * 1 KB in front of a member that expands to a gigabyte.
+ */
+export const ZIP_MAX_UNCOMPRESSED_BYTES = MAX_DECOMPRESSED_BYTES;
+/** Locate the end-of-central-directory record, scanning back past any comment. */
+function findEocd(bytes) {
+    // The comment field is a uint16, so the record starts at most 22+65535 bytes
+    // from the end. Scan backwards for the signature.
+    const earliest = Math.max(0, bytes.length - (22 + 0xffff));
+    for (let i = bytes.length - 22; i >= earliest; i--) {
+        if (bytes.readUInt32LE(i) === EOCD_SIG)
+            return i;
+    }
+    throw new Error('not a ZIP archive (no end-of-central-directory record)');
+}
+export async function readZip(bytes, opts = {}) {
+    const limit = opts.maxUncompressedBytes ?? ZIP_MAX_UNCOMPRESSED_BYTES;
+    const eocd = findEocd(bytes);
+    const count = bytes.readUInt16LE(eocd + 10);
+    const cdOffset = bytes.readUInt32LE(eocd + 16);
+    if (cdOffset === ZIP64_SENTINEL || count === 0xffff) {
+        throw new Error('ZIP64 archives are not supported');
+    }
+    const entries = new Map();
+    let p = cdOffset;
+    for (let i = 0; i < count; i++) {
+        if (bytes.readUInt32LE(p) !== CENTRAL_SIG) {
+            throw new Error(`corrupt ZIP central directory at offset ${p}`);
+        }
+        const nameLen = bytes.readUInt16LE(p + 28);
+        const extraLen = bytes.readUInt16LE(p + 30);
+        const commentLen = bytes.readUInt16LE(p + 32);
+        const name = bytes.toString('utf8', p + 46, p + 46 + nameLen);
+        entries.set(name, {
+            name,
+            method: bytes.readUInt16LE(p + 10),
+            compressedSize: bytes.readUInt32LE(p + 20),
+            uncompressedSize: bytes.readUInt32LE(p + 24),
+            localOffset: bytes.readUInt32LE(p + 42),
+        });
+        p += 46 + nameLen + extraLen + commentLen;
+    }
+    const cache = new Map();
+    async function read(name) {
+        const cached = cache.get(name);
+        if (cached)
+            return cached;
+        const entry = entries.get(name);
+        if (!entry)
+            return null;
+        // Cheap pre-check for an honest oversized member. A lying header falls
+        // through to the streaming cap below, which is the real guarantee.
+        if (entry.uncompressedSize > limit) {
+            throw new Error(`ZIP member ${name} is too large to extract (${entry.uncompressedSize} bytes)`);
+        }
+        // The central directory records the local header's offset, but the local
+        // header carries its OWN name/extra lengths (they can differ from the
+        // central copy), so the data offset must be computed from it.
+        const lo = entry.localOffset;
+        if (bytes.readUInt32LE(lo) !== LOCAL_SIG) {
+            throw new Error(`corrupt ZIP local header for ${name}`);
+        }
+        const start = lo + 30 + bytes.readUInt16LE(lo + 26) + bytes.readUInt16LE(lo + 28);
+        const raw = bytes.subarray(start, start + entry.compressedSize);
+        let out;
+        if (entry.method === 0)
+            out = Buffer.from(raw);
+        else if (entry.method === 8)
+            out = await inflateBounded(raw, 'deflate-raw', limit, `ZIP member ${name}`);
+        else
+            throw new Error(`unsupported ZIP compression method ${entry.method} for ${name}`);
+        cache.set(name, out);
+        return out;
+    }
+    return {
+        names: () => [...entries.keys()],
+        has: (name) => entries.has(name),
+        read,
+        async readText(name) {
+            const buf = await read(name);
+            if (!buf)
+                return null;
+            const text = buf.toString('utf8');
+            return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+        },
+    };
+}

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

package/dist/sync.js

@@ -222,8 +222,13 @@ async function walkPages(client, folder, folderId, opts, store) {
                 await fetchAttachmentMetaBudgeted(client, item.id, detailFileIds, store, budget);
             }
         }
-        // Flush the page's rows in one transaction/RPC. Empty array is a no-op.
-        await store.upsertMessages(toUpsert);
+        // Flush the page's rows in one transaction/RPC. Skipped entirely when the
+        // page held nothing new: on the Worker this call is a Durable-Object RPC,
+        // and a DO RPC counts against the same subrequest budget as an OFW fetch.
+        // A deep re-walk crosses page after page of already-cached messages, so an
+        // unconditional "no-op" write spends the caller's budget to store nothing.
+        if (toUpsert.length > 0)
+            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.

package/dist/tools/delivery.js

@@ -0,0 +1,99 @@
+// The attachment delivery ladder.
+//
+// A successful fetch must always produce retrievable content. "The host cannot
+// render this type" is a DISPLAY limit, and letting it become a DATA limit is
+// the bug this module exists to close: `ofw_download_attachment` used to fetch
+// a 10 KB custody-schedule spreadsheet, hand back an EmbeddedResource, and have
+// the host reject it with "Resources of type '…spreadsheetml.sheet' are not
+// currently supported" — leaving the caller holding nothing at all.
+//
+// Every inline delivery now walks the same rungs and returns the first that
+// works:
+//
+//   1. host-renderable image  → ImageContent (the model sees the picture)
+//   2. extractable document   → the FILE'S TEXT, as text (see src/extract)
+//   3. raw bytes              → base64 EmbeddedResource, as before
+//
+// Rung 3 never disappears, so nothing regresses; rung 2 is what makes a
+// spreadsheet, PDF, Word or PowerPoint attachment readable at all. When a rung
+// is skipped or fails, the response says so by name in `deliveryAttempts` —
+// a caller must never be left guessing why it got bytes instead of content.
+import { extractAttachment } from '../extract/index.js';
+import { isHostRenderableImage } from './attachments.js';
+/**
+ * Attempt extraction, converting every failure into a REASON rather than an
+ * exception: a format we cannot read must still be delivered as bytes, and the
+ * caller is owed the explanation either way.
+ */
+export async function tryExtract(bytes, mimeType, fileName, opts) {
+    try {
+        const extracted = await extractAttachment(bytes, mimeType, fileName, {
+            maxChars: opts.maxChars,
+            parts: opts.parts,
+        });
+        if (!extracted) {
+            return { reason: `no text extractor for ${mimeType} (${fileName})` };
+        }
+        return { extracted, truncated: extracted.truncated ?? false };
+    }
+    catch (err) {
+        // A malformed .xlsx is still an .xlsx: report why it could not be read and
+        // fall through to the bytes, rather than failing the whole call.
+        return { reason: `extraction failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+/**
+ * Build the content blocks for an inline download by walking the ladder.
+ * The first block is always a JSON meta block naming `deliveredVia`, so the
+ * caller can tell how the content arrived without inspecting block types.
+ */
+export async function buildInlineDelivery(input) {
+    const { fileId, fileName, mimeType, bytes, forcedInline, options } = input;
+    const meta = {
+        fileId, fileName, mimeType, sizeBytes: bytes.length, mode: 'inline',
+    };
+    if (forcedInline)
+        meta.forcedInline = true;
+    const block = () => ({ type: 'text', text: JSON.stringify(meta, null, 2) });
+    // Rung 1 — the host renders these itself, and a picture beats a description.
+    if (isHostRenderableImage(mimeType)) {
+        meta.deliveredVia = 'image';
+        return { content: [block(), { type: 'image', data: bytes.toString('base64'), mimeType }] };
+    }
+    // Rung 2 — extraction. Skipped only when the caller explicitly opts out.
+    const attempts = [];
+    if (options.extract === false) {
+        attempts.push('extraction skipped (extract:false)');
+    }
+    else {
+        const outcome = await tryExtract(bytes, mimeType, fileName, options);
+        if (outcome.extracted) {
+            meta.deliveredVia = 'extracted';
+            meta.extracted = outcome.extracted;
+            meta.truncated = outcome.truncated;
+            // The bytes are deliberately NOT also attached: the extracted text is the
+            // readable form, and a duplicate base64 blob would be the very payload
+            // the host rejects — plus double the response size.
+            meta.note = 'Content extracted from the file. Pass extract:false to get the raw bytes instead.';
+            return { content: [block()] };
+        }
+        /* v8 ignore next -- tryExtract always sets `reason` when it returns no extraction */
+        attempts.push(outcome.reason ?? 'extraction produced no content');
+    }
+    // Rung 3 — the bytes themselves. Always available, so a fetch that succeeded
+    // never ends with the caller holding nothing.
+    meta.deliveredVia = 'blob';
+    meta.deliveryAttempts = attempts;
+    meta.note = 'Returned as raw bytes. Some hosts cannot render an embedded resource of this type; '
+        + 'if it came back unreadable, the file has no text extractor here (see deliveryAttempts).';
+    return {
+        content: [block(), {
+                type: 'resource',
+                resource: {
+                    uri: `ofw://attachment/${fileId}/${encodeURIComponent(fileName)}`,
+                    mimeType,
+                    blob: bytes.toString('base64'),
+                },
+            }],
+    };
+}

package/dist/tools/draft-freshness.js

@@ -47,8 +47,13 @@ function isNotFound(e) {
  * 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.
+ * 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.
+ *
+ * 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).
  */
 export async function fetchServerDraft(client, id) {
     let raw;
@@ -77,6 +82,22 @@ export async function fetchServerDraft(client, id) {
         recipients: mapRecipients(detail.recipients),
     };
 }
+/**
+ * The fields whose divergence constitutes a REAL conflict — the actual message
+ * content a caller would lose if we overwrote a copy edited elsewhere. Anything
+ * NOT listed here (currently only `replyToId`) is connector/server-authored
+ * metadata: OFW normalizes `replyToId` after a draft is saved (dropping it, or
+ * re-targeting it to the thread tip), which is the connector's own mutation
+ * surfacing later — not third-party interference. A divergence in metadata
+ * alone must never refuse the write, or the guard manufactures a false STALE
+ * for a change the caller did not make. See issue thread on save/edit round
+ * trips.
+ */
+const SUBSTANTIVE_FIELDS = ['subject', 'body', 'recipients'];
+/** The substantive subset of a changed-field list (drops metadata like replyToId). */
+function substantiveChanges(changed) {
+    return changed.filter((f) => SUBSTANTIVE_FIELDS.includes(f));
+}
 function diffFields(a, b) {
     const changed = [];
     if (a.subject !== b.subject)
@@ -102,8 +123,17 @@ function diffFields(a, b) {
  *  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.
+ * In BOTH modes the conflict decision turns on the SUBSTANTIVE fields
+ * (subject/body/recipients), not on any revision delta. When the only thing
+ * that moved is connector/server-authored metadata — `replyToId` normalized
+ * after the save — the content is intact, so it is FRESH (with `metadataOnly`
+ * set) rather than STALE. That is the connector's own mutation resurfacing, not
+ * a third party editing the draft; refusing it would be a false positive that
+ * trains callers to distrust the guard. The fail-safe direction is untouched:
+ * the moment subject, body or recipients differ, it still refuses.
+ *
+ * Everything else — server ahead of cache on real content, no cached base to
+ * compare, draft gone from the server — refuses.
  */
 export function checkDraftFreshness(input) {
     const { server, cached, expectedRevision } = input;
@@ -119,6 +149,20 @@ export function checkDraftFreshness(input) {
         if (expectedRevision === actual) {
             return { verdict: 'FRESH', reason: 'expectedRevision matches the live server draft.', changedFields: [] };
         }
+        // Token mismatch. When the caller's token is the one WE cached, we can name
+        // exactly what drifted — and if that is metadata alone, it is our own
+        // post-save normalization, not a conflict.
+        if (cached !== null && draftRevision(cached) === expectedRevision) {
+            const changedFields = diffFields(server, cached);
+            if (substantiveChanges(changedFields).length === 0) {
+                return {
+                    verdict: 'FRESH',
+                    reason: `Only connector-authored metadata (${changedFields.join(', ')}) changed since you read the draft; its subject, body and recipients are unchanged, so this is not a conflict.`,
+                    changedFields,
+                    metadataOnly: true,
+                };
+            }
+        }
         return {
             verdict: 'STALE',
             reason: `expectedRevision ${expectedRevision} does not match the live server draft (${actual}) — it changed after you read it.`,
@@ -136,6 +180,14 @@ export function checkDraftFreshness(input) {
     if (changedFields.length === 0) {
         return { verdict: 'FRESH', reason: 'The cached draft matches the live server draft.', changedFields: [] };
     }
+    if (substantiveChanges(changedFields).length === 0) {
+        return {
+            verdict: 'FRESH',
+            reason: `Only connector-authored metadata (${changedFields.join(', ')}) differs from the cached copy; subject, body and recipients match, so this is not a conflict.`,
+            changedFields,
+            metadataOnly: true,
+        };
+    }
     return {
         verdict: 'STALE',
         reason: `The draft on OurFamilyWizard differs from the cached copy (${changedFields.join(', ')}) — it was edited outside this tool.`,