@manudota/artist-mcp 1.8.3-staging.90 → 2.0.0

package/README.md

@@ -74,8 +74,8 @@ Google is supporting evidence, and needs the separate Google connection:
 | --- | --- |
 | `list_emails` | Gmail search results — subject, sender, date, snippet |
 | `read_email` | Message body, plus what is attached by name, type, and size |
-| `map_attachment` | What is on each page of a PDF, without reading it |
-| `read_attachment` | Images as pictures; PDFs and `.docx` as text, in page ranges |
+| `map_gmail_attachment` | What is on each page of a PDF, without reading it |
+| `read_gmail_attachment` | Images as pictures; PDFs and `.docx` as text, in page ranges |
 | `list_events` | Calendar events in a window, recurrences expanded and flagged |
 | `read_event` | Description and attendees for one event |
 

package/dist/attachments.d.ts

@@ -11,6 +11,19 @@
  *   - `npm:unpdf@1` became a normal dependency import.
  *   - Response shapes are declared, because json() is typed loosely under Deno.
  */
+/**
+ * Two ceilings, and neither is decoration.
+ *
+ * Extraction decodes a PDF into memory, and the cost tracks pages and text
+ * volume rather than file size: a 195 KB, 176-page file measured 185 MB of
+ * heap when every page was read at once, against a 256 MB function. So the
+ * character cap is enforced *during* the page loop with an early stop, which
+ * held the same file to 19 MB. A byte cap alone does not protect this.
+ *
+ * The byte cap is the cruder guard, on what is fetched at all. Contracts and
+ * riders sit far below it — a real 7-page rider was 0.6 MB.
+ */
+export declare const MAX_ATTACHMENT_BYTES: number;
 /**
  * Exported because `read_note` holds itself to the same number. One policy on
  * how much text may arrive in a single answer, in one place, rather than two
@@ -131,6 +144,42 @@ export declare function imageResult(meta: {
     text: string;
 };
 export declare function unsupportedNote(mimeType: string, filename: string): string;
+/**
+ * How bytes arrive. Everything below this line works on the result and has no
+ * idea where it came from, which is what lets one PDF/image/.docx path serve
+ * both a mail message and a OneNote page. See issue #70.
+ */
+export type AttachmentLoader = () => Promise<{
+    oversized: true;
+    meta: AttachmentMeta;
+} | {
+    oversized: false;
+    meta: AttachmentMeta;
+    bytes: Uint8Array;
+}>;
+/**
+ * The Gmail loader: the only part of this file that knows about messages.
+ *
+ * The ids are validated here, when the loader is built, rather than inside the
+ * closure. A malformed id is a caller mistake and should be reported before any
+ * other argument is looked at, which is where it was reported before the loader
+ * became a parameter.
+ */
+export declare function gmailLoader(token: string, emailId: unknown, attachmentId: unknown): AttachmentLoader;
+/**
+ * What is known about a file before it is read, whatever it came from.
+ *
+ * Written out rather than derived from the Gmail entry it used to be, because a
+ * page resource has no Gmail id and `size` is genuinely unknown until the bytes
+ * arrive: OneNote offers no size ahead of the fetch at all. Gmail's own entries
+ * satisfy this structurally and carry their extra field along untouched.
+ */
+export type AttachmentMeta = {
+    id: string;
+    filename: string;
+    mime_type: string;
+    size: number | null;
+};
 /**
  * Map an attachment: what is on each page, without reading any of it.
  *
@@ -138,10 +187,16 @@ export declare function unsupportedNote(mimeType: string, filename: string): str
  * page one. This costs one text pass and returns a few hundred bytes, so a
  * caller can name the pages worth reading and then read only those.
  */
-export declare function mapAttachment(token: string, emailId: unknown, attachmentId: unknown): Promise<{
+export declare function mapAttachment(load: AttachmentLoader, 
+/**
+ * The read tool to point at. Passed in rather than hardcoded: the map is
+ * source-neutral, and naming the mail tool while mapping a page attachment
+ * sends the model to a tool that cannot open it. See issue #70.
+ */
+readTool: string): Promise<{
     filename: string;
     mime_type: string;
-    size: number;
+    size: number | null;
     kind: "too_large";
     text: string;
     note: string;
@@ -173,7 +228,7 @@ export declare function mapAttachment(token: string, emailId: unknown, attachmen
     mime_type: string;
     size: number;
 }>;
-export declare function readAttachment(token: string, emailId: unknown, attachmentId: unknown, fromPage: unknown, pageCount: unknown): Promise<{
+export declare function readAttachment(load: AttachmentLoader, fromPage: unknown, pageCount: unknown): Promise<{
     kind: "unsupported";
     images: never[];
     note: string;
@@ -197,7 +252,7 @@ export declare function readAttachment(token: string, emailId: unknown, attachme
 } | {
     filename: string;
     mime_type: string;
-    size: number;
+    size: number | null;
     kind: "too_large";
     text: string;
     note: string;

package/dist/attachments.js

@@ -32,7 +32,7 @@ const failure = (message) => new GraphError(message, false);
  * The byte cap is the cruder guard, on what is fetched at all. Contracts and
  * riders sit far below it — a real 7-page rider was 0.6 MB.
  */
-const MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+export const MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
 /**
  * Exported because `read_note` holds itself to the same number. One policy on
  * how much text may arrive in a single answer, in one place, rather than two
@@ -844,7 +844,15 @@ export function unsupportedNote(mimeType, filename) {
     return `Reading ${mimeType} attachments is not built yet, so the contents of ` +
         `${filename} have not been read.`;
 }
-async function loadAttachment(token, emailId, attachmentId) {
+/**
+ * The Gmail loader: the only part of this file that knows about messages.
+ *
+ * The ids are validated here, when the loader is built, rather than inside the
+ * closure. A malformed id is a caller mistake and should be reported before any
+ * other argument is looked at, which is where it was reported before the loader
+ * became a parameter.
+ */
+export function gmailLoader(token, emailId, attachmentId) {
     if (typeof emailId !== "string" || !GMAIL_ID.test(emailId)) {
         throw failure("email_id is missing or malformed.");
     }
@@ -852,42 +860,52 @@ async function loadAttachment(token, emailId, attachmentId) {
         throw failure("attachment_id is missing or malformed.");
     }
     const id = encodeURIComponent(emailId);
-    const msgRes = await gmailGet(`/users/me/messages/${id}?format=full`, token);
-    const msg = (await msgRes.json());
-    const attachments = extractAttachments(msg.payload);
-    const meta = attachments.find((a) => a.id === attachmentId);
-    if (!meta) {
-        // Name what is there. A bare "not found" invites the caller to retry with
-        // the same id, and this is the one error a caller can actually act on.
-        const available = attachments.length
-            ? attachments.map((a) => `${a.id} (${a.filename})`).join(", ")
-            : "none";
-        throw failure(`That message has no attachment ${attachmentId}. Available: ${available}.`);
-    }
-    if (meta.size !== null && meta.size > MAX_ATTACHMENT_BYTES) {
-        return { oversized: true, meta };
-    }
-    const attRes = await gmailGet(`/users/me/messages/${id}/attachments/${encodeURIComponent(meta.gmail_id)}`, token);
-    const payload = (await attRes.json());
-    if (typeof payload.data !== "string") {
-        throw failure("Gmail returned no data for that attachment.");
-    }
-    return { oversized: false, meta, bytes: decodeBytes(payload.data) };
+    return async () => {
+        const msgRes = await gmailGet(`/users/me/messages/${id}?format=full`, token);
+        const msg = (await msgRes.json());
+        const attachments = extractAttachments(msg.payload);
+        const meta = attachments.find((a) => a.id === attachmentId);
+        if (!meta) {
+            // Name what is there. A bare "not found" invites the caller to retry with
+            // the same id, and this is the one error a caller can actually act on.
+            const available = attachments.length
+                ? attachments.map((a) => `${a.id} (${a.filename})`).join(", ")
+                : "none";
+            throw failure(`That message has no attachment ${attachmentId}. Available: ${available}.`);
+        }
+        if (meta.size !== null && meta.size > MAX_ATTACHMENT_BYTES) {
+            return { oversized: true, meta };
+        }
+        const attRes = await gmailGet(`/users/me/messages/${id}/attachments/${encodeURIComponent(meta.gmail_id)}`, token);
+        const payload = (await attRes.json());
+        if (typeof payload.data !== "string") {
+            throw failure("Gmail returned no data for that attachment.");
+        }
+        return { oversized: false, meta, bytes: decodeBytes(payload.data) };
+    };
 }
 /** The refusal, worded once so reading and mapping cannot drift apart. */
 function tooLargeResult(meta) {
     return {
         filename: meta.filename,
         mime_type: meta.mime_type,
-        size: meta.size ?? 0,
+        // Null, not 0. A size nobody measured must not arrive as a number: the
+        // renderer shows no size line at all rather than "0 B" beside a note
+        // saying the file is at least the limit. See issue #70.
+        size: meta.size,
         kind: "too_large",
         text: "",
-        note: 
-        // One decimal: rounding 13.8 to "14" overstates a file sitting near
-        // the limit, and near the limit is exactly when the number is read.
-        `This file is ${((meta.size ?? 0) / (1024 * 1024)).toFixed(1)} MB, above the ` +
-            `${MAX_ATTACHMENT_BYTES / (1024 * 1024)} MB limit for reading in chat. ` +
-            `It was not fetched.`,
+        note: meta.size === null
+            // No size was ever available -- a OneNote resource reports none, and the
+            // fetch was stopped at the limit rather than run to the end. "At least"
+            // is all that can be said, so it is all that is said.
+            ? `This file is at least the ${MAX_ATTACHMENT_BYTES / (1024 * 1024)} MB ` +
+                `limit for reading in chat, so it was not read to the end.`
+            // One decimal: rounding 13.8 to "14" overstates a file sitting near
+            // the limit, and near the limit is exactly when the number is read.
+            : `This file is ${(meta.size / (1024 * 1024)).toFixed(1)} MB, above the ` +
+                `${MAX_ATTACHMENT_BYTES / (1024 * 1024)} MB limit for reading in chat. ` +
+                `It was not fetched.`,
     };
 }
 /**
@@ -897,8 +915,14 @@ function tooLargeResult(meta) {
  * page one. This costs one text pass and returns a few hundred bytes, so a
  * caller can name the pages worth reading and then read only those.
  */
-export async function mapAttachment(token, emailId, attachmentId) {
-    const loaded = await loadAttachment(token, emailId, attachmentId);
+export async function mapAttachment(load, 
+/**
+ * The read tool to point at. Passed in rather than hardcoded: the map is
+ * source-neutral, and naming the mail tool while mapping a page attachment
+ * sends the model to a tool that cannot open it. See issue #70.
+ */
+readTool) {
+    const loaded = await load();
     if (loaded.oversized)
         return tooLargeResult(loaded.meta);
     const { meta, bytes } = loaded;
@@ -918,7 +942,7 @@ export async function mapAttachment(token, emailId, attachmentId) {
                     (doc.parts_total > 1 ? ` in ${doc.parts_total} parts` : "") +
                     `. There is no page map to give: a .docx records no pages, and its ` +
                     `heading styles are not dependable enough to divide it honestly. ` +
-                    `Read it with read_attachment.`
+                    `Read it with ${readTool}.`
                 : `${meta.filename} could not be opened as a Word document.`,
         };
     }
@@ -956,18 +980,12 @@ export async function mapAttachment(token, emailId, attachmentId) {
                 : `Every page of this ${map.pages_total}-page file is a picture, so ` +
                     `there is nothing to map. `) +
                 `A scan cannot be searched without reading the pages themselves — ask ` +
-                `read_attachment for them.`
-            : `${map.pages_total} pages. Use read_attachment with from_page and ` +
+                `${readTool} for them.`
+            : `${map.pages_total} pages. Use ${readTool} with from_page and ` +
                 `page_count to read the ones that matter, rather than reading it all.`,
     };
 }
-export async function readAttachment(token, emailId, attachmentId, fromPage, pageCount) {
-    if (typeof emailId !== "string" || !GMAIL_ID.test(emailId)) {
-        throw failure("email_id is missing or malformed.");
-    }
-    if (typeof attachmentId !== "string" || !ATTACHMENT_ID.test(attachmentId)) {
-        throw failure("attachment_id is missing or malformed.");
-    }
+export async function readAttachment(load, fromPage, pageCount) {
     if (fromPage !== undefined && fromPage !== null &&
         (typeof fromPage !== "number" || !Number.isFinite(fromPage) || fromPage < 1)) {
         throw failure("from_page must be a page number, 1 or greater.");
@@ -976,7 +994,7 @@ export async function readAttachment(token, emailId, attachmentId, fromPage, pag
         (typeof pageCount !== "number" || !Number.isFinite(pageCount) || pageCount < 1)) {
         throw failure("page_count must be a number of pages, 1 or greater.");
     }
-    const loaded = await loadAttachment(token, emailId, attachmentId);
+    const loaded = await load();
     if (loaded.oversized)
         return tooLargeResult(loaded.meta);
     const { meta, bytes } = loaded;

package/dist/connect.d.ts

@@ -11,6 +11,16 @@
  * opt-in — the same asymmetry the product has everywhere else.
  */
 export declare const runConnect: (input?: string) => Promise<void>;
+/**
+ * Reconnect whatever has lapsed, without the user having to work out which.
+ *
+ * The reconnect was always one command; knowing that it was needed, and for
+ * which provider, was the part that cost people a session. This closes that
+ * gap — and refuses to do anything when nothing has lapsed, so it can be run on
+ * a hunch without silently sending someone through a consent screen they did
+ * not need.
+ */
+export declare const runReconnect: () => Promise<void>;
 /**
  * Removing the stored token stops this machine using the connection, but it
  * does not revoke the grant at the provider — only the user's account page can

package/dist/connect.js

@@ -16,6 +16,7 @@ import { ENTRY_NAME, configPath, readConfig } from './config.js';
 import { parseGrants } from './grants.js';
 import { WRITE_SCOPES, connect } from './oauth.js';
 import { PROVIDERS } from './oauth.js';
+import { expiryAtConnect, expiryNotice, expiryState } from './expiry.js';
 import { clearProvider, loadTokens, readProvider } from './tokens.js';
 const PROVIDER_NAMES = Object.keys(PROVIDERS);
 const parseProvider = (input) => {
@@ -40,7 +41,7 @@ export const runConnect = async (input) => {
     // provider, so passing all of them asks each provider for only its own.
     const grants = await installedGrants();
     const relevant = grants.filter((name) => WRITE_SCOPES[name]?.provider === provider);
-    await connect(provider, grants);
+    const expiresAt = await connect(provider, grants);
     console.log(`\n${PROVIDERS[provider].label} connected — ${PURPOSE[provider]}.`);
     if (relevant.length === 0) {
         console.log('Read-only. Nothing is ever written back to your account.');
@@ -56,10 +57,42 @@ export const runConnect = async (input) => {
                 : 'Nothing else is ever written back: not mail, and no event is ' +
                     'changed except by the reschedule you granted.'));
     }
+    // Said at the one moment the user is certainly reading, which is the whole
+    // point: #94 describes a connection that dies weekly, an error that correctly
+    // advises a reconnect, and a cause nobody could see from either.
+    const lapses = expiryAtConnect(provider, expiresAt);
+    if (lapses !== undefined)
+        console.log(`\n${lapses}`);
     if (provider === 'microsoft' && (await readProvider('google')) === undefined) {
         console.log('\nTo add Gmail and Calendar as evidence: artist-mcp connect google');
     }
 };
+/**
+ * Reconnect whatever has lapsed, without the user having to work out which.
+ *
+ * The reconnect was always one command; knowing that it was needed, and for
+ * which provider, was the part that cost people a session. This closes that
+ * gap — and refuses to do anything when nothing has lapsed, so it can be run on
+ * a hunch without silently sending someone through a consent screen they did
+ * not need.
+ */
+export const runReconnect = async () => {
+    const { providers } = await loadTokens();
+    const lapsed = PROVIDER_NAMES.filter((name) => {
+        const entry = providers[name];
+        return entry !== undefined && expiryState(entry).kind === 'lapsed';
+    });
+    if (lapsed.length === 0) {
+        console.log('Nothing has lapsed. Run `artist-mcp status` to see what is connected.');
+        // Not an error: "nothing to do" is the answer, and exiting non-zero would
+        // make a scheduled check look like a failure every time it worked.
+        return;
+    }
+    for (const provider of lapsed) {
+        console.log(`\n${PROVIDERS[provider].label} lapsed — reconnecting.`);
+        await runConnect(provider);
+    }
+};
 /**
  * Removing the stored token stops this machine using the connection, but it
  * does not revoke the grant at the provider — only the user's account page can
@@ -244,11 +277,26 @@ export const runStatus = async () => {
         console.log('Nothing connected on this machine. Start with: artist-mcp connect');
         return;
     }
+    let anyLapsed = false;
     for (const name of PROVIDER_NAMES) {
         const entry = providers[name];
         const label = PROVIDERS[name].label.padEnd(10);
-        console.log(entry === undefined
-            ? `${label} not connected`
-            : `${label} connected ${entry.connectedAt.slice(0, 10)} — ${entry.scope}`);
+        if (entry === undefined) {
+            console.log(`${label} not connected`);
+            continue;
+        }
+        console.log(`${label} connected ${entry.connectedAt.slice(0, 10)} — ${entry.scope}`);
+        // On its own line and only when there is something to say. A connection
+        // with a week left says nothing, so the day it does say something the line
+        // is new rather than furniture.
+        const notice = expiryNotice(name, entry);
+        if (notice !== undefined) {
+            console.log(`${' '.repeat(11)}${notice}`);
+            if (expiryState(entry).kind === 'lapsed')
+                anyLapsed = true;
+        }
+    }
+    if (anyLapsed) {
+        console.log('\nOr reconnect everything that lapsed at once: artist-mcp reconnect');
     }
 };

package/dist/dispatch.d.ts

@@ -50,14 +50,22 @@ export declare const OPERATIONS: {
         readonly provider: "google";
         readonly effect: "read";
     };
-    readonly read_attachment: {
+    readonly read_gmail_attachment: {
         readonly provider: "google";
         readonly effect: "read";
     };
-    readonly map_attachment: {
+    readonly map_gmail_attachment: {
         readonly provider: "google";
         readonly effect: "read";
     };
+    readonly read_page_attachment: {
+        readonly provider: "microsoft";
+        readonly effect: "read";
+    };
+    readonly map_page_attachment: {
+        readonly provider: "microsoft";
+        readonly effect: "read";
+    };
     readonly list_events: {
         readonly provider: "google";
         readonly effect: "read";

package/dist/dispatch.js

@@ -12,7 +12,8 @@
  */
 import { GraphError } from './client.js';
 import { recordWrite } from './audit.js';
-import { mapAttachment, readAttachment } from './attachments.js';
+import { gmailLoader, mapAttachment, readAttachment } from './attachments.js';
+import { oneNoteLoader } from './page-attachments.js';
 import { createEvent, deleteEvent, listCalendars, listEvents, previewDeleteEvent, previewEvent, previewRescheduleEvent, readEvent, rescheduleEvent, } from './calendar.js';
 import { listEmails, readEmail } from './mail.js';
 import { listNotes, mapNotes, readNote } from './notes.js';
@@ -42,8 +43,14 @@ export const OPERATIONS = {
     read_note: { provider: 'microsoft', effect: 'read' },
     list_emails: { provider: 'google', effect: 'read' },
     read_email: { provider: 'google', effect: 'read' },
-    read_attachment: { provider: 'google', effect: 'read' },
-    map_attachment: { provider: 'google', effect: 'read' },
+    read_gmail_attachment: { provider: 'google', effect: 'read' },
+    map_gmail_attachment: { provider: 'google', effect: 'read' },
+    // Separate rows rather than a source parameter on the two above. The token is
+    // resolved from this table before the call is made, so one operation cannot
+    // span two providers without breaking the rule that a Gmail call never spends
+    // a Microsoft token. The model still sees two tools; see issue #70.
+    read_page_attachment: { provider: 'microsoft', effect: 'read' },
+    map_page_attachment: { provider: 'microsoft', effect: 'read' },
     list_events: { provider: 'google', effect: 'read' },
     read_event: { provider: 'google', effect: 'read' },
     list_calendars: { provider: 'google', effect: 'read' },
@@ -105,10 +112,14 @@ export const dispatchWith = (resolve, record = recordWrite) => async (op, params
             return (await listEmails(token, params.query));
         case 'read_email':
             return (await readEmail(token, params.email_id));
-        case 'map_attachment':
-            return (await mapAttachment(token, params.email_id, params.attachment_id));
-        case 'read_attachment':
-            return (await readAttachment(token, params.email_id, params.attachment_id, params.from_page, params.page_count));
+        case 'map_gmail_attachment':
+            return (await mapAttachment(gmailLoader(token, params.email_id, params.attachment_id), 'read_gmail_attachment'));
+        case 'read_gmail_attachment':
+            return (await readAttachment(gmailLoader(token, params.email_id, params.attachment_id), params.from_page, params.page_count));
+        case 'map_page_attachment':
+            return (await mapAttachment(oneNoteLoader(token, params.note_id, params.attachment_id), 'read_page_attachment'));
+        case 'read_page_attachment':
+            return (await readAttachment(oneNoteLoader(token, params.note_id, params.attachment_id), params.from_page, params.page_count));
         case 'list_events':
             return (await listEvents(token, params.calendar_id, params.query, params.time_min, params.time_max));
         case 'read_event':

package/dist/expiry.d.ts

@@ -0,0 +1,62 @@
+/**
+ * What a connection's age means, and what to say about it.
+ *
+ * Split out and pure because it is a decision rather than an integration: the
+ * refresh failure in oauth.ts and the report in connect.ts must not describe
+ * the same connection differently, and the only way to be sure of that is for
+ * both to call this. It also makes the arithmetic testable against a fixed
+ * clock, which is the half that is easy to get wrong and hard to notice.
+ *
+ * The fact being reasoned about is #94: Google expires refresh tokens issued
+ * by an app in Testing publishing status after seven days. Nothing here knows
+ * that number — it arrives with the connection, from the deployment (see
+ * `statedExpiry`), so this file stays true when the app is verified.
+ */
+import type { ProviderName, StoredTokens } from './tokens.js';
+/** The one command that fixes any of this, per provider. */
+export declare const reconnectCommand: (provider: ProviderName) => string;
+export type ExpiryState = 
+/** The provider stated no limit, so there is nothing to say. */
+{
+    kind: 'unlimited';
+}
+/** Stated a limit, still inside it. */
+ | {
+    kind: 'valid';
+    daysLeft: number;
+    expiresAt: string;
+}
+/** Stated a limit, and it has passed. */
+ | {
+    kind: 'lapsed';
+    daysAgo: number;
+    expiresAt: string;
+};
+export declare const expiryState: (tokens: StoredTokens, now?: Date) => ExpiryState;
+/**
+ * The line `status` prints, or nothing when there is nothing to say.
+ *
+ * Silent while the limit is comfortably far off. A warning shown every single
+ * day is read as decoration by the third day, and the whole point of this is to
+ * be believed on the day it matters.
+ */
+export declare const expiryNotice: (provider: ProviderName, tokens: StoredTokens, now?: Date) => string | undefined;
+/**
+ * What to say at the end of a successful connect.
+ *
+ * Said here rather than discovered later, which is the entire complaint in #94:
+ * the connection simply stopped, the error advised a reconnect, the advice was
+ * right, and the cause stayed invisible for as long as anyone cared to look.
+ */
+export declare const expiryAtConnect: (provider: ProviderName, expiresAt: string | undefined, now?: Date) => string | undefined;
+/**
+ * Why a refresh was rejected, inferred from the connection's own age.
+ *
+ * The provider cannot tell us: Google answers `invalid_grant` with "Token has
+ * been expired or revoked" whether it lapsed on schedule or someone withdrew
+ * the app in their account settings. Those are opposite situations — one is
+ * expected and one is worth investigating — so the distinction is drawn here,
+ * from the expiry the connection recorded, and worded as the inference it is.
+ * Nothing below claims the provider said any of it.
+ */
+export declare const explainRefreshFailure: (provider: ProviderName, tokens: StoredTokens, now?: Date) => string;

package/dist/expiry.js

@@ -0,0 +1,112 @@
+/**
+ * What a connection's age means, and what to say about it.
+ *
+ * Split out and pure because it is a decision rather than an integration: the
+ * refresh failure in oauth.ts and the report in connect.ts must not describe
+ * the same connection differently, and the only way to be sure of that is for
+ * both to call this. It also makes the arithmetic testable against a fixed
+ * clock, which is the half that is easy to get wrong and hard to notice.
+ *
+ * The fact being reasoned about is #94: Google expires refresh tokens issued
+ * by an app in Testing publishing status after seven days. Nothing here knows
+ * that number — it arrives with the connection, from the deployment (see
+ * `statedExpiry`), so this file stays true when the app is verified.
+ */
+/** Where a provider's own page for withdrawing an app's access lives. */
+const CONNECTED_APPS = {
+    google: 'https://myaccount.google.com/connections',
+    microsoft: 'https://account.live.com/consent/Manage',
+};
+/** The one command that fixes any of this, per provider. */
+export const reconnectCommand = (provider) => `artist-mcp connect ${provider}`;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * The two directions round opposite ways, because the honest answer differs.
+ *
+ * Time remaining rounds **up**: a connection with eleven hours left reads as
+ * "1 day", never "0 days", since reporting zero days left on something that
+ * still works teaches someone to ignore the line.
+ *
+ * Time elapsed rounds **down**: something that lapsed two days and three hours
+ * ago is "2 days ago", not "3". Overstating how long a connection has been
+ * dead is a small lie in the one place the user is checking the facts.
+ */
+const daysLeftFrom = (from, to) => Math.max(1, Math.ceil((to - from) / DAY_MS));
+const daysSince = (from, to) => Math.floor((to - from) / DAY_MS);
+export const expiryState = (tokens, now = new Date()) => {
+    const { expiresAt } = tokens;
+    if (expiresAt === undefined)
+        return { kind: 'unlimited' };
+    const at = Date.parse(expiresAt);
+    // A stored date that will not parse is treated as no limit rather than as
+    // an expiry. A connection wrongly declared dead is worse than one whose
+    // warning is missing: the second still works.
+    if (Number.isNaN(at))
+        return { kind: 'unlimited' };
+    const ms = now.getTime();
+    return ms >= at
+        ? { kind: 'lapsed', daysAgo: daysSince(at, ms), expiresAt }
+        : { kind: 'valid', daysLeft: daysLeftFrom(ms, at), expiresAt };
+};
+/**
+ * The line `status` prints, or nothing when there is nothing to say.
+ *
+ * Silent while the limit is comfortably far off. A warning shown every single
+ * day is read as decoration by the third day, and the whole point of this is to
+ * be believed on the day it matters.
+ */
+export const expiryNotice = (provider, tokens, now = new Date()) => {
+    const state = expiryState(tokens, now);
+    if (state.kind === 'lapsed') {
+        // Under a day is "today" rather than "0 days ago", which reads as a bug.
+        const when = state.daysAgo === 0 ? 'today' : `${state.daysAgo} day${state.daysAgo === 1 ? '' : 's'} ago`;
+        return `LAPSED ${when}. Reconnect: ${reconnectCommand(provider)}`;
+    }
+    if (state.kind === 'valid' && state.daysLeft <= 2) {
+        return (`expires in ${state.daysLeft} day${state.daysLeft === 1 ? '' : 's'}. ` +
+            `Reconnect any time: ${reconnectCommand(provider)}`);
+    }
+    return undefined;
+};
+/**
+ * What to say at the end of a successful connect.
+ *
+ * Said here rather than discovered later, which is the entire complaint in #94:
+ * the connection simply stopped, the error advised a reconnect, the advice was
+ * right, and the cause stayed invisible for as long as anyone cared to look.
+ */
+export const expiryAtConnect = (provider, expiresAt, now = new Date()) => {
+    if (expiresAt === undefined)
+        return undefined;
+    const state = expiryState({ refreshToken: '', scope: '', connectedAt: '', expiresAt }, now);
+    if (state.kind !== 'valid')
+        return undefined;
+    return (`This connection lapses in ${state.daysLeft} days, on ${state.expiresAt.slice(0, 10)}. ` +
+        `That is a limit ${provider === 'google' ? 'Google' : 'the provider'} applies to this ` +
+        `app, not a fault, and reconnecting takes one command: ${reconnectCommand(provider)}`);
+};
+/**
+ * Why a refresh was rejected, inferred from the connection's own age.
+ *
+ * The provider cannot tell us: Google answers `invalid_grant` with "Token has
+ * been expired or revoked" whether it lapsed on schedule or someone withdrew
+ * the app in their account settings. Those are opposite situations — one is
+ * expected and one is worth investigating — so the distinction is drawn here,
+ * from the expiry the connection recorded, and worded as the inference it is.
+ * Nothing below claims the provider said any of it.
+ */
+export const explainRefreshFailure = (provider, tokens, now = new Date()) => {
+    const state = expiryState(tokens, now);
+    const fix = `Reconnect with: ${reconnectCommand(provider)}`;
+    if (state.kind === 'lapsed') {
+        return (`This connection reached the ${state.expiresAt.slice(0, 10)} limit this app is ` +
+            `subject to, so it most likely expired on schedule rather than anything ` +
+            `going wrong. ${fix}`);
+    }
+    if (state.kind === 'valid') {
+        return (`This is earlier than the ${state.expiresAt.slice(0, 10)} limit this connection ` +
+            `was given, so something withdrew it rather than it lapsing — check whether ` +
+            `the app was removed at ${CONNECTED_APPS[provider]}. ${fix}`);
+    }
+    return fix;
+};