@manudota/artist-mcp 2.2.2-staging.103 → 2.3.0

package/dist/agents.js

@@ -117,7 +117,26 @@ const resolveRegistry = async () => {
     ]));
     const localRoot = localAgentRoot();
     if (localRoot) {
-        for (const entry of (await readLocalRegistry(localRoot)).entries) {
+        const local = (await readLocalRegistry(localRoot)).entries;
+        // Replacing rather than layering, where the deployment says so.
+        //
+        // Layering is right for a musician who has copied out a few playbooks and
+        // edited them: the ones they did not copy should keep working. Hosted is
+        // the other case — one pack, written for one notebook, and a bundled
+        // playbook surviving because the custom pack happens not to name its id is
+        // a generic rule in force that nobody chose. Cleared before the local
+        // entries go in, so what is served is exactly what is in that directory.
+        //
+        // Only ever narrows: a mode this does not recognise layers, which is what
+        // every install that has never heard of it already does.
+        // No emptiness check here, deliberately. `readLocalRegistry` already throws
+        // for a directory with no `artist/` and for one holding no Markdown, so by
+        // this line `local` cannot be empty and a guard would be unreachable code
+        // claiming to protect something. The strictness this mode needs is the
+        // strictness the local layer already has.
+        if (process.env.ARTIST_MCP_PACK_MODE === 'replace')
+            byId.clear();
+        for (const entry of local) {
             byId.set(entry.id, { ...entry, source: 'local', origin: localRoot });
         }
     }

package/dist/api.d.ts

@@ -9,6 +9,29 @@
 export declare const GRAPH = "https://graph.microsoft.com/v1.0";
 export declare const GMAIL = "https://gmail.googleapis.com/gmail/v1";
 export declare const CALENDAR = "https://www.googleapis.com/calendar/v3";
+/**
+ * How many provider requests one tool call may have in flight at once.
+ *
+ * Jitter above spreads the *retries* of a herd; nothing spread the herd's
+ * first arrival, and that is the burst the logs actually show — forty
+ * `attempt=1 waited=0s` refusals landing in the same millisecond, because a
+ * survey of a forty-page notebook opened forty Graph requests simultaneously.
+ * Every one of them then had to win its own retry ladder against a provider
+ * that was only busy because of them.
+ *
+ * Four is chosen to be boring rather than optimal: it is slow enough that
+ * OneNote answers instead of refusing, and parallel enough that a survey is
+ * still meaningfully faster than a loop. The number that matters is "not N".
+ */
+export declare const FANOUT_LIMIT = 4;
+/**
+ * `Promise.all(items.map(fn))` with a ceiling on how many run at once.
+ *
+ * Results stay in the order of `items`, and a rejection rejects the whole
+ * call, so this is a drop-in for the `Promise.all` it replaces: callers that
+ * already catch per item keep behaving exactly as they did.
+ */
+export declare const mapWithConcurrency: <T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>) => Promise<R[]>;
 /**
  * What a call needs from the grant, for the one failure that is not a fault.
  *

package/dist/api.js

@@ -47,6 +47,42 @@ const THROTTLE_BUDGET_MS = 8_000;
  * arrivals scattered across the window.
  */
 const jittered = (ms) => Math.round(ms / 2 + Math.random() * (ms / 2));
+/**
+ * How many provider requests one tool call may have in flight at once.
+ *
+ * Jitter above spreads the *retries* of a herd; nothing spread the herd's
+ * first arrival, and that is the burst the logs actually show — forty
+ * `attempt=1 waited=0s` refusals landing in the same millisecond, because a
+ * survey of a forty-page notebook opened forty Graph requests simultaneously.
+ * Every one of them then had to win its own retry ladder against a provider
+ * that was only busy because of them.
+ *
+ * Four is chosen to be boring rather than optimal: it is slow enough that
+ * OneNote answers instead of refusing, and parallel enough that a survey is
+ * still meaningfully faster than a loop. The number that matters is "not N".
+ */
+export const FANOUT_LIMIT = 4;
+/**
+ * `Promise.all(items.map(fn))` with a ceiling on how many run at once.
+ *
+ * Results stay in the order of `items`, and a rejection rejects the whole
+ * call, so this is a drop-in for the `Promise.all` it replaces: callers that
+ * already catch per item keep behaving exactly as they did.
+ */
+export const mapWithConcurrency = async (items, limit, fn) => {
+    const results = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        for (;;) {
+            const index = next++;
+            if (index >= items.length)
+                return;
+            results[index] = await fn(items[index], index);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return results;
+};
 /**
  * What the provider actually asked for, when it says.
  *

package/dist/dispatch.d.ts

@@ -30,6 +30,10 @@ import { type ProviderName } from './tokens.js';
  * fails on any edit to this table so that the change has to be deliberate.
  */
 export declare const OPERATIONS: {
+    readonly list_notebooks: {
+        readonly provider: "microsoft";
+        readonly effect: "read";
+    };
     readonly list_notes: {
         readonly provider: "microsoft";
         readonly effect: "read";

package/dist/dispatch.js

@@ -16,7 +16,7 @@ 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';
+import { listNotebooks, listNotes, mapNotes, readNote } from './notes.js';
 import { applyEdit, previewEdit } from './onenote-patch.js';
 import { createPage, previewPage } from './onenote-write.js';
 import { accessTokenFor } from './oauth.js';
@@ -39,6 +39,7 @@ import { loadTokens } from './tokens.js';
  * fails on any edit to this table so that the change has to be deliberate.
  */
 export const OPERATIONS = {
+    list_notebooks: { provider: 'microsoft', effect: 'read' },
     list_notes: { provider: 'microsoft', effect: 'read' },
     map_notes: { provider: 'microsoft', effect: 'read' },
     read_note: { provider: 'microsoft', effect: 'read' },
@@ -111,6 +112,8 @@ export const connectedProviders = async () => {
 export const dispatchWith = (resolve, record = recordWrite) => async (op, params = {}) => {
     const token = await resolve(PROVIDER_FOR[op]);
     switch (op) {
+        case 'list_notebooks':
+            return (await listNotebooks(token));
         case 'list_notes':
             return (await listNotes(token));
         case 'map_notes':

package/dist/mail.js

@@ -5,7 +5,7 @@
  * thing being worked on. Ported from the edge function with behaviour intact.
  */
 import { GraphError } from './client.js';
-import { gmailGet } from './api.js';
+import { FANOUT_LIMIT, gmailGet, mapWithConcurrency } from './api.js';
 import { htmlToText } from './notes.js';
 /** Gmail ids are opaque hex-ish strings; anything else never reaches a URL. */
 export const GMAIL_ID = /^[A-Za-z0-9_-]{1,128}$/;
@@ -119,7 +119,7 @@ export const listEmails = async (token, rawQuery) => {
     const ids = ((await listRes.json()).messages ?? [])
         .map((m) => m.id)
         .filter((id) => typeof id === 'string' && GMAIL_ID.test(id));
-    const emails = await Promise.all(ids.map(async (id) => {
+    const emails = await mapWithConcurrency(ids, FANOUT_LIMIT, async (id) => {
         const res = await gmailGet(`/users/me/messages/${encodeURIComponent(id)}` +
             '?format=metadata&metadataHeaders=Subject&metadataHeaders=From' +
             '&metadataHeaders=To&metadataHeaders=Date', token);
@@ -133,7 +133,7 @@ export const listEmails = async (token, rawQuery) => {
             date: header(msg.payload?.headers, 'Date'),
             snippet: msg.snippet ?? null,
         };
-    }));
+    });
     return { emails };
 };
 export const readEmail = async (token, emailId) => {

package/dist/notes.d.ts

@@ -8,6 +8,25 @@
  */
 import { type PageResource } from './page-attachments.js';
 import { type EditablePart } from './onenote-patch.js';
+/**
+ * A short value proving a caller has actually seen this account's notebook list.
+ *
+ * The gate it serves used to be a module-level boolean — "has anything listed
+ * the notebooks yet" — which is a fair approximation of one CLI session and
+ * nonsense on hosted, where every request may land on a different instance and
+ * the flag is shared by every user on the one it lands on. It refused real
+ * selections on a cold instance and admitted unseen ones on a warm one.
+ *
+ * Derived from the notebook names rather than stored, so it needs no session
+ * and no shared storage: the same account yields the same key on any instance,
+ * a client that never saw the list cannot produce it, and a key from an account
+ * with different notebooks does not match. It is not a secret and does not need
+ * to be — it proves the list was seen, nothing more.
+ *
+ * Order and case are normalised so the key does not change when Graph returns
+ * the same notebooks in a different order.
+ */
+export declare const notebookKeyFor: (names: readonly string[]) => string;
 export type NoteSummary = {
     id: string;
     title: string;
@@ -65,6 +84,31 @@ export declare const pageDatesAreCreationDates: (sections: readonly {
  * both are marked.
  */
 export declare const htmlToText: (html: string) => string;
+/**
+ * Which notebooks this account has, and nothing else.
+ *
+ * One Graph request. `listNotes` answers the same question as a side effect of
+ * fetching every page of every section — a hundred requests on an organised
+ * account — and the notebook question is asked far more often than the page
+ * one: every call that has to ask "which notebook?" paid for the pages of all
+ * of them to print a list of names.
+ *
+ * That is what was throttling the account. Graph refused with 20166, "the app
+ * has issued too many requests on behalf of this user", against a listing whose
+ * answer was already contained in the single request that starts it, since
+ * `parentNotebook` expands inline on the sections call.
+ *
+ * Counted in sections rather than pages, because a page count is exactly the
+ * thing that cannot be known without the hundred requests. A number that costs
+ * a hundred requests to be slightly more familiar is not worth it, and the
+ * count is only there to help the user recognise which notebook is which.
+ */
+export declare const listNotebooks: (token: string) => Promise<{
+    notebooks: {
+        name: string;
+        sections: number;
+    }[];
+}>;
 /**
  * `/me/onenote/pages` looks like the obvious call and works right up until the
  * account has too many sections, at which point Graph fails the whole request
@@ -140,6 +184,31 @@ export type NoteSketch = NoteSummary & {
     chars_total: number | null;
     error: string | null;
 };
+/**
+ * How long a survey may spend before it returns what it has.
+ *
+ * The hosted route dies at sixty seconds (`maxDuration` in the MCP route), and
+ * dying there is the worst available outcome: the caller waits the full minute
+ * and receives nothing, not even the pages that were already sketched. Three
+ * of those in a row is what a chat client's retries look like from the logs.
+ *
+ * Forty-five leaves room for the answer to be assembled and sent after the
+ * last sketch lands. The number is a floor on usefulness rather than a tuning
+ * knob: whatever the notebook looks like, the survey now returns.
+ */
+export declare const MAP_DEADLINE_MS = 45000;
+type MapNotesOptions = {
+    deadlineMs?: number;
+    /** Injectable so a test can reach the deadline without spending the time. */
+    now?: () => number;
+};
+export type MapNotesResult = {
+    sketches: NoteSketch[];
+    read_in_full: number;
+    /** Pages the deadline cut off. Unsurveyed, and reported as such. */
+    not_reached: number;
+    elapsed_ms: number;
+};
 /**
  * Sketch every page in a chosen notebook, cheaply, so a notebook can be triaged
  * without reading all of it.
@@ -156,10 +225,7 @@ export type NoteSketch = NoteSummary & {
  *
  * Scoped to one notebook, as intake requires. Nothing maps across scopes.
  */
-export declare const mapNotes: (token: string, pages: NoteSummary[]) => Promise<{
-    sketches: NoteSketch[];
-    read_in_full: number;
-}>;
+export declare const mapNotes: (token: string, pages: NoteSummary[], { deadlineMs, now }?: MapNotesOptions) => Promise<MapNotesResult>;
 /** A page attachment as `read_note` reports it: named, never read. */
 export type PageAttachment = Omit<PageResource, 'position'>;
 export type NoteContent = {
@@ -207,3 +273,4 @@ export type NoteContent = {
 export declare const readNote: (token: string, noteId: unknown, fromPart?: unknown, { withEditIds }?: {
     withEditIds?: boolean;
 }) => Promise<NoteContent>;
+export {};

package/dist/notes.js

@@ -6,11 +6,34 @@
  * enumeration below, which exists for a reason that is not obvious from the
  * code alone.
  */
+import { createHash } from 'node:crypto';
 import { MAX_TEXT_CHARS } from './attachments.js';
 import { GraphError } from './client.js';
-import { graphGet } from './api.js';
+import { FANOUT_LIMIT, graphGet, mapWithConcurrency } from './api.js';
 import { pageResources } from './page-attachments.js';
 import { editablePartsFrom } from './onenote-patch.js';
+/**
+ * A short value proving a caller has actually seen this account's notebook list.
+ *
+ * The gate it serves used to be a module-level boolean — "has anything listed
+ * the notebooks yet" — which is a fair approximation of one CLI session and
+ * nonsense on hosted, where every request may land on a different instance and
+ * the flag is shared by every user on the one it lands on. It refused real
+ * selections on a cold instance and admitted unseen ones on a warm one.
+ *
+ * Derived from the notebook names rather than stored, so it needs no session
+ * and no shared storage: the same account yields the same key on any instance,
+ * a client that never saw the list cannot produce it, and a key from an account
+ * with different notebooks does not match. It is not a secret and does not need
+ * to be — it proves the list was seen, nothing more.
+ *
+ * Order and case are normalised so the key does not change when Graph returns
+ * the same notebooks in a different order.
+ */
+export const notebookKeyFor = (names) => createHash('sha256')
+    .update([...names].map((n) => n.trim().toLowerCase()).sort().join('\n'))
+    .digest('hex')
+    .slice(0, 8);
 /** Graph ids are opaque, but they are concatenated into URLs, so they are checked like any other value. */
 const ONENOTE_ID = /^[A-Za-z0-9!._~-]{1,300}$/;
 /**
@@ -89,6 +112,40 @@ export const htmlToText = (html) => html
     .join('\n')
     .replace(/\n{3,}/g, '\n\n')
     .trim();
+/**
+ * Which notebooks this account has, and nothing else.
+ *
+ * One Graph request. `listNotes` answers the same question as a side effect of
+ * fetching every page of every section — a hundred requests on an organised
+ * account — and the notebook question is asked far more often than the page
+ * one: every call that has to ask "which notebook?" paid for the pages of all
+ * of them to print a list of names.
+ *
+ * That is what was throttling the account. Graph refused with 20166, "the app
+ * has issued too many requests on behalf of this user", against a listing whose
+ * answer was already contained in the single request that starts it, since
+ * `parentNotebook` expands inline on the sections call.
+ *
+ * Counted in sections rather than pages, because a page count is exactly the
+ * thing that cannot be known without the hundred requests. A number that costs
+ * a hundred requests to be slightly more familiar is not worth it, and the
+ * count is only there to help the user recognise which notebook is which.
+ */
+export const listNotebooks = async (token) => {
+    const res = await graphGet('/me/onenote/sections?$select=id,displayName' +
+        '&$expand=parentNotebook($select=displayName)&$top=100', token);
+    const sections = (await res.json()).value ?? [];
+    const counts = new Map();
+    for (const section of sections) {
+        if (typeof section.id !== 'string' || !ONENOTE_ID.test(section.id))
+            continue;
+        const name = section.parentNotebook?.displayName ?? '(unnamed notebook)';
+        counts.set(name, (counts.get(name) ?? 0) + 1);
+    }
+    return {
+        notebooks: [...counts].map(([name, sectionCount]) => ({ name, sections: sectionCount })),
+    };
+};
 /**
  * `/me/onenote/pages` looks like the obvious call and works right up until the
  * account has too many sections, at which point Graph fails the whole request
@@ -99,46 +156,68 @@ export const htmlToText = (html) => html
  * Do not "simplify" this back to the single call.
  */
 export const listNotes = async (token) => {
-    const sectionsRes = await graphGet(
-    // lastModifiedDateTime is what the detector reads, and it is the field
-    // that actually tracks change — unlike the one on a page. Selected here
-    // rather than fetched separately: the request is made either way.
-    '/me/onenote/sections?$select=id,displayName,lastModifiedDateTime' +
-        '&$expand=parentNotebook($select=displayName)&$top=100', token);
-    const sections = (await sectionsRes.json()).value ?? [];
-    const usable = sections.filter((s) => typeof s.id === 'string' && ONENOTE_ID.test(s.id));
-    const perSection = await Promise.all(usable.map(async (section) => {
-        const res = await graphGet(`/me/onenote/sections/${section.id}/pages` +
-            // createdDateTime is selected only so the two can be compared. It
-            // costs nothing — the request is made either way.
-            '?$select=id,title,createdDateTime,lastModifiedDateTime&$top=100', token);
-        const pages = (await res.json()).value ?? [];
-        return pages.map((p) => ({
-            id: p.id,
-            title: p.title ?? '(untitled)',
-            section: section.displayName ?? null,
+    const startedAt = Date.now();
+    let sectionCount = 0;
+    let failure = null;
+    try {
+        const sectionsRes = await graphGet(
+        // lastModifiedDateTime is what the detector reads, and it is the field
+        // that actually tracks change — unlike the one on a page. Selected here
+        // rather than fetched separately: the request is made either way.
+        '/me/onenote/sections?$select=id,displayName,lastModifiedDateTime' +
+            '&$expand=parentNotebook($select=displayName)&$top=100', token);
+        const sections = (await sectionsRes.json()).value ?? [];
+        const usable = sections.filter((s) => typeof s.id === 'string' && ONENOTE_ID.test(s.id));
+        sectionCount = usable.length;
+        const perSection = await mapWithConcurrency(usable, FANOUT_LIMIT, async (section) => {
+            const res = await graphGet(`/me/onenote/sections/${section.id}/pages` +
+                // createdDateTime is selected only so the two can be compared. It
+                // costs nothing — the request is made either way.
+                '?$select=id,title,createdDateTime,lastModifiedDateTime&$top=100', token);
+            const pages = (await res.json()).value ?? [];
+            return pages.map((p) => ({
+                id: p.id,
+                title: p.title ?? '(untitled)',
+                section: section.displayName ?? null,
+                notebook: section.parentNotebook?.displayName ?? null,
+                last_modified: p.lastModifiedDateTime ?? null,
+            }));
+        });
+        const sectionSummaries = usable.map((section, i) => ({
+            id: section.id,
+            name: section.displayName ?? '(unnamed section)',
             notebook: section.parentNotebook?.displayName ?? null,
-            last_modified: p.lastModifiedDateTime ?? null,
+            last_modified: section.lastModifiedDateTime ?? null,
+            pages: (perSection[i] ?? []).length,
         }));
-    }));
-    const sectionSummaries = usable.map((section, i) => ({
-        id: section.id,
-        name: section.displayName ?? '(unnamed section)',
-        notebook: section.parentNotebook?.displayName ?? null,
-        last_modified: section.lastModifiedDateTime ?? null,
-        pages: (perSection[i] ?? []).length,
-    }));
-    const creationDates = pageDatesAreCreationDates(sectionSummaries, perSection);
-    // Newest first, matching the order the single-call version happened to
-    // return; pages with no timestamp sort last rather than jumping to the top.
-    const notes = perSection
-        .flat()
-        .map((n) => ({ ...n, date_is_creation: creationDates }))
-        .sort((a, b) => (b.last_modified ?? '').localeCompare(a.last_modified ?? ''));
-    // Sections newest first for the same reason, and because when page dates are
-    // useless this is the ordering the caller actually reads.
-    const sectionList = sectionSummaries.sort((a, b) => (b.last_modified ?? '').localeCompare(a.last_modified ?? ''));
-    return { notes, sections: sectionList, page_dates_are_creation_dates: creationDates };
+        const creationDates = pageDatesAreCreationDates(sectionSummaries, perSection);
+        // Newest first, matching the order the single-call version happened to
+        // return; pages with no timestamp sort last rather than jumping to the top.
+        const notes = perSection
+            .flat()
+            .map((n) => ({ ...n, date_is_creation: creationDates }))
+            .sort((a, b) => (b.last_modified ?? '').localeCompare(a.last_modified ?? ''));
+        // Sections newest first for the same reason, and because when page dates are
+        // useless this is the ordering the caller actually reads.
+        const sectionList = sectionSummaries.sort((a, b) => (b.last_modified ?? '').localeCompare(a.last_modified ?? ''));
+        return { notes, sections: sectionList, page_dates_are_creation_dates: creationDates };
+    }
+    catch (err) {
+        failure = err instanceof Error ? err.message : String(err);
+        throw err;
+    }
+    finally {
+        // Logged in a `finally`, and that is the whole point of it.
+        //
+        // The survey's own line sat after its await, so a run that threw logged
+        // nothing — and a throttled listing throws HERE, before the survey is ever
+        // reached, which is why a failed map produced nineteen 429s and no
+        // evidence. A measurement that exists only when nothing went wrong
+        // measures the wrong runs.
+        console.warn(`[artist-mcp] list_notes sections=${sectionCount} ` +
+            `elapsed=${Date.now() - startedAt}ms` +
+            (failure === null ? '' : ` failed=${failure}`));
+    }
 };
 /**
  * The sections that changed within a window.
@@ -251,6 +330,25 @@ const previewOf = async (token, id) => {
     const { previewText } = (await res.json());
     return (previewText ?? '').trim();
 };
+/**
+ * How long a survey may spend before it returns what it has.
+ *
+ * The hosted route dies at sixty seconds (`maxDuration` in the MCP route), and
+ * dying there is the worst available outcome: the caller waits the full minute
+ * and receives nothing, not even the pages that were already sketched. Three
+ * of those in a row is what a chat client's retries look like from the logs.
+ *
+ * Forty-five leaves room for the answer to be assembled and sent after the
+ * last sketch lands. The number is a floor on usefulness rather than a tuning
+ * knob: whatever the notebook looks like, the survey now returns.
+ */
+export const MAP_DEADLINE_MS = 45_000;
+/**
+ * A page the deadline was reached before. Not an error and not an empty page —
+ * distinguishing it from both is the whole point, because a page that was never
+ * looked at must never read as a page with nothing on it.
+ */
+const NOT_REACHED = Symbol('not reached');
 /**
  * Sketch every page in a chosen notebook, cheaply, so a notebook can be triaged
  * without reading all of it.
@@ -267,61 +365,102 @@ const previewOf = async (token, id) => {
  *
  * Scoped to one notebook, as intake requires. Nothing maps across scopes.
  */
-export const mapNotes = async (token, pages) => {
-    const sketches = await Promise.all(pages.map(async (page) => {
-        const base = { ...page, chars_total: null, error: null };
-        let preview = '';
-        let reason = null;
-        try {
-            preview = await previewOf(token, page.id);
-            // A preview this thin cannot separate a working unit from a stray
-            // note, which is the one thing the map exists to do.
-            if (preview === '')
-                reason = 'the page has no preview text';
-            else if (preview.length < PREVIEW_FLOOR)
-                reason = `the preview was only ${preview.length} characters`;
-        }
-        catch (err) {
-            reason = `the preview call failed (${err instanceof Error ? err.message : String(err)})`;
-        }
-        if (reason === null) {
-            return {
-                ...base,
-                sketch: preview,
-                source: 'preview',
-                fell_back: null,
-                // Graph gives no page length and does not say it truncated, so a
-                // preview at full length is the only sign there is more. Inferred,
-                // and reported as an inference rather than as a fact.
-                more: preview.length >= PREVIEW_LIKELY_CAP,
-            };
-        }
-        // Case by case, and only for the pages that need it.
-        try {
-            const { text, chars_total } = await readNote(token, page.id);
-            return {
-                ...base,
-                sketch: text.slice(0, DERIVED_SKETCH_CHARS),
-                source: 'page',
-                fell_back: reason,
-                more: chars_total > DERIVED_SKETCH_CHARS,
-                chars_total,
-            };
-        }
-        catch (err) {
-            // Both routes failed. Reported as a gap, never dropped from the map:
-            // a page missing from a survey reads as a page that is not there.
-            return {
-                ...base,
-                sketch: null,
-                source: 'none',
-                fell_back: reason,
-                more: false,
-                error: err instanceof Error ? err.message : String(err),
-            };
-        }
-    }));
-    return { sketches, read_in_full: sketches.filter((s) => s.source === 'page').length };
+export const mapNotes = async (token, pages, { deadlineMs = MAP_DEADLINE_MS, now = Date.now } = {}) => {
+    const mapStartedAt = now();
+    const stopAt = mapStartedAt + deadlineMs;
+    // Held outside the try so the `finally` can report them whatever happens.
+    let sketched = 0;
+    let readInFull = 0;
+    let notReached = 0;
+    let mapFailure = null;
+    try {
+        const outcomes = await mapWithConcurrency(pages, FANOUT_LIMIT, async (page) => {
+            // Checked before the work, not during it: a page that has started is
+            // allowed to finish, because abandoning a request mid-flight costs the
+            // same quota as completing it and returns nothing for the spend.
+            if (now() >= stopAt) {
+                notReached += 1;
+                return NOT_REACHED;
+            }
+            const base = { ...page, chars_total: null, error: null };
+            let preview = '';
+            let reason = null;
+            try {
+                preview = await previewOf(token, page.id);
+                // A preview this thin cannot separate a working unit from a stray
+                // note, which is the one thing the map exists to do.
+                if (preview === '')
+                    reason = 'the page has no preview text';
+                else if (preview.length < PREVIEW_FLOOR)
+                    reason = `the preview was only ${preview.length} characters`;
+            }
+            catch (err) {
+                reason = `the preview call failed (${err instanceof Error ? err.message : String(err)})`;
+            }
+            if (reason === null) {
+                return {
+                    ...base,
+                    sketch: preview,
+                    source: 'preview',
+                    fell_back: null,
+                    // Graph gives no page length and does not say it truncated, so a
+                    // preview at full length is the only sign there is more. Inferred,
+                    // and reported as an inference rather than as a fact.
+                    more: preview.length >= PREVIEW_LIKELY_CAP,
+                };
+            }
+            // Case by case, and only for the pages that need it.
+            try {
+                const { text, chars_total } = await readNote(token, page.id);
+                return {
+                    ...base,
+                    sketch: text.slice(0, DERIVED_SKETCH_CHARS),
+                    source: 'page',
+                    fell_back: reason,
+                    more: chars_total > DERIVED_SKETCH_CHARS,
+                    chars_total,
+                };
+            }
+            catch (err) {
+                // Both routes failed. Reported as a gap, never dropped from the map:
+                // a page missing from a survey reads as a page that is not there.
+                return {
+                    ...base,
+                    sketch: null,
+                    source: 'none',
+                    fell_back: reason,
+                    more: false,
+                    error: err instanceof Error ? err.message : String(err),
+                };
+            }
+        });
+        const sketches = outcomes.filter((o) => o !== NOT_REACHED);
+        sketched = sketches.length;
+        readInFull = sketches.filter((s) => s.source === 'page').length;
+        return {
+            sketches,
+            read_in_full: readInFull,
+            not_reached: notReached,
+            elapsed_ms: now() - mapStartedAt,
+        };
+    }
+    catch (err) {
+        mapFailure = err instanceof Error ? err.message : String(err);
+        throw err;
+    }
+    finally {
+        // The line that says where the time went — on every run, the failed ones
+        // included, because those are the runs actually worth measuring.
+        //
+        // Fallbacks are the suspect: a preview costs one request, a fallback costs
+        // two plus the page's whole HTML, and arithmetic says forty previews at
+        // four concurrent should take about five seconds rather than sixty. This
+        // settles it with evidence instead.
+        console.warn(`[artist-mcp] map_notes pages=${pages.length} sketched=${sketched} ` +
+            `read_in_full=${readInFull} not_reached=${notReached} ` +
+            `elapsed=${now() - mapStartedAt}ms` +
+            (mapFailure === null ? '' : ` failed=${mapFailure}`));
+    }
 };
 /**
  * Read one page, in parts only when it is too long for a single answer.

package/dist/onenote-patch.js

@@ -236,7 +236,27 @@ const ATTRS_BY_TAG = {
     td: new Set(['colspan', 'rowspan', 'align', 'valign', 'width']),
     th: new Set(['colspan', 'rowspan', 'align', 'valign', 'width']),
     a: new Set(['href']),
+    // A checkbox is a `data-tag` on the paragraph, so without this a task can be
+    // read and never written: `htmlToText` has rendered these as `[ ]` and `[x]`
+    // since before anything could write, and a patch carrying one was refused.
+    // Per-tag rather than global, because a tag on a table cell or a heading is
+    // not a task and OneNote renders it somewhere nobody asked for a checkbox.
+    p: new Set(['data-tag']),
+    li: new Set(['data-tag']),
 };
+/**
+ * The only `data-tag` values this tool will write.
+ *
+ * OneNote defines dozens — `important`, `question`, `remember-for-later` and
+ * the rest — and every one of them is a claim about the line it marks. These
+ * two are the only ones with an agreed meaning here: a task, and a task that is
+ * done. Anything else is a model deciding that something is important, which is
+ * exactly the kind of judgement that must not arrive as page markup.
+ *
+ * Narrow on purpose, and cheap to widen if a use turns up that is really asked
+ * for rather than merely available.
+ */
+const TASK_TAGS = new Set(['to-do', 'to-do:completed']);
 /**
  * What may appear in a `style`, which OneNote's own tables lean on heavily for
  * borders and widths — so forbidding it outright would mean every replaced
@@ -274,6 +294,13 @@ const checkAttributes = (tag, raw) => {
                 'OneNote. Nothing was written. Keep the markup to tables, rows, cells, ' +
                 'paragraphs, lists and simple emphasis.');
         }
+        if (name === 'data-tag' && !TASK_TAGS.has(value)) {
+            throw failure(`<${tag}> carries data-tag="${value}", which this tool will not send to ` +
+                'OneNote. Nothing was written. Only "to-do" and "to-do:completed" are ' +
+                'written: an open task and a done one. Every other OneNote tag states ' +
+                'something about the line — that it is important, or a question — and ' +
+                'that is the musician\'s to say, not this tool\'s.');
+        }
         if (name === 'style' && !SAFE_STYLE.test(value)) {
             throw failure(`The style on <${tag}> contains something this tool will not send: ` +
                 `"${value}". Nothing was written. Plain declarations such as ` +

package/dist/server.js

@@ -6,7 +6,7 @@ import { WRITE_CAPABILITIES, isGranted } from "./grants.js";
 import { listAgentWorkflows, loadAgentWorkflow } from "./agents.js";
 import { GraphError } from "./client.js";
 import { call as localCall } from "./dispatch.js";
-import { narrowNotes, narrowSections } from "./notes.js";
+import { narrowNotes, narrowSections, notebookKeyFor } from "./notes.js";
 /** One call per page, so a notebook nobody put a number on does not become hundreds of requests. */
 const DEFAULT_MAP_PAGES = 40;
 /** Times are stated with their zone; the calendar's zone need not be the reader's. */
@@ -26,20 +26,6 @@ const describeSize = (bytes) => {
         return `${Math.round(bytes / 1024)} KB`;
     return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 };
-/**
- * Whether this server has ever handed back the list of notebooks.
- *
- * The one thing the server can actually know about where a notebook name came
- * from. It cannot see who typed it — but a name arriving before the list was
- * ever served cannot have come from the tool, so it came from somewhere outside
- * the conversation. That is the case worth catching: a session inferred a
- * notebook from saved context and answered about the wrong one, correctly and
- * without saying which.
- *
- * Only ever set to true, and only by serving the list. It says nothing after a
- * session has seen the notebooks once, which is the honest limit of it.
- */
-let notebooksHaveBeenListed = false;
 /**
  * Settle which notebook is being worked in, before anything reads a page.
  *
@@ -48,46 +34,63 @@ let notebooksHaveBeenListed = false;
  * intake depends on, and two copies of it would eventually disagree. The caller
  * names itself so the instruction says which tool to call again.
  */
-const selectNotebook = async (call, notebook, tool) => {
-    const { notes, sections = [], page_dates_are_creation_dates = false, } = await call("list_notes");
-    if (notes.length === 0)
+const selectNotebook = async (call, notebook, notebookKey, tool) => {
+    // The notebook question first, and on its own, because it is the cheap one.
+    //
+    // `list_notes` answers it as a side effect of fetching every page of every
+    // section — a hundred Graph requests on an organised account — and most calls
+    // that reach here only need the names: to ask which notebook, or to check
+    // that a supplied one exists. Paying for every page of every notebook to
+    // print a list of names is what had Graph refusing with 20166.
+    const { notebooks } = await call("list_notebooks");
+    if (notebooks.length === 0)
         return { message: "No notes found." };
-    const names = [...new Set(notes.map((n) => n.notebook ?? "(unnamed notebook)"))];
+    const names = notebooks.map((n) => n.name);
     // Handing back every page across every notebook invites work on the wrong
     // one. With a choice to be made and nothing chosen, the pages are withheld
     // until the user has actually made it.
     // A name that arrives before this session has ever seen the list did not come
     // from the tool, so it is either the user's or a guess — and the two are
     // indistinguishable from here. Ask, the same way an omitted name asks.
-    const unseenName = notebook !== undefined && !notebooksHaveBeenListed;
-    if ((!notebook || unseenName) && names.length > 1) {
-        notebooksHaveBeenListed = true;
-        const counts = names.map((name) => {
-            const total = notes.filter((n) => (n.notebook ?? "(unnamed notebook)") === name).length;
-            return `- ${name} — ${total} page${total === 1 ? "" : "s"}`;
-        });
+    // Proven against the account's own notebooks rather than against a flag this
+    // process happens to hold. Required only where the choice is real: one
+    // notebook is not a choice, and demanding proof of a list with a single entry
+    // would be ceremony.
+    const expected = notebookKeyFor(names);
+    const proven = notebookKey !== undefined && notebookKey.trim().toLowerCase() === expected;
+    const unproven = notebook !== undefined && !proven;
+    if ((!notebook || unproven) && names.length > 1) {
+        // Sections rather than pages: a page count is precisely the thing that
+        // cannot be known without the hundred requests this path exists to avoid,
+        // and the number is only here to help the user tell one notebook from
+        // another.
+        const counts = notebooks.map(({ name, sections: n }) => `- ${name} — ${n} section${n === 1 ? "" : "s"}`);
         return {
             message: `This account has ${names.length} notebooks:\n${counts.join("\n")}\n\n` +
-                (unseenName
-                    ? `You asked for "${notebook}", but nothing in this conversation has ` +
-                        "named a notebook yet. Ask the user which one they mean — including " +
-                        "whether it is that one — and call " +
-                        `${tool} again once they have said. A notebook you know of from ` +
-                        "elsewhere is a guess, and a guess here produces an answer that is " +
-                        "correct about the wrong pages."
+                `notebook_key: ${expected}\n\n` +
+                (unproven
+                    ? `You asked for "${notebook}" without the notebook_key from this ` +
+                        "list, so nothing in this conversation had seen the notebooks yet. " +
+                        "Ask the user which one they mean — including whether it is that " +
+                        `one — and call ${tool} again with that name AND the notebook_key ` +
+                        "above. A notebook you know of from elsewhere is a guess, and a " +
+                        "guess here produces an answer that is correct about the wrong pages."
                     : `Ask the user which notebook to work in, then call ${tool} again ` +
-                        "with that name. Do not guess, and do not work across notebooks " +
-                        "unless the user asks for it."),
+                        "with that name and the notebook_key above. Do not guess, and do " +
+                        "not work across notebooks unless the user asks for it."),
         };
     }
-    notebooksHaveBeenListed = true;
     const wanted = notebook?.trim().toLowerCase();
+    // Checked before the expensive call, not after it: a misspelled notebook
+    // should cost one request to refuse, not a hundred.
+    if (wanted !== undefined && !names.some((name) => name.trim().toLowerCase() === wanted)) {
+        return { message: `No notebook named "${notebook}". Available: ${names.join(", ")}.` };
+    }
+    // Settled. Only now are the pages worth what they cost.
+    const { notes, sections = [], page_dates_are_creation_dates = false, } = await call("list_notes");
     const pages = wanted
         ? notes.filter((n) => (n.notebook ?? "").trim().toLowerCase() === wanted)
         : notes;
-    if (wanted && pages.length === 0) {
-        return { message: `No notebook named "${notebook}". Available: ${names.join(", ")}.` };
-    }
     // A name that was supplied walks straight past the question above, so a
     // guessed one is indistinguishable from a chosen one. Found in use: asked
     // about "this notebook" in a fresh chat, a session inferred one from saved
@@ -173,7 +176,7 @@ const renderChangedSections = (chosen, notebook, since) => {
  * the only way OneNote allows a cell to change.
  */
 const INDEX_ENTRIES = 12;
-const serverVersion = '2.2.2-staging.103'; // x-release-please-version
+const serverVersion = '2.3.0'; // x-release-please-version
 const errorResult = (err) => {
     const message = err instanceof GraphError ? err.message : `Unexpected error: ${err}`;
     return { content: [{ type: "text", text: message }], isError: true };
@@ -715,6 +718,14 @@ const createServer = async (call, grants = []) => {
             "notebook you happen to know the user has: a plausible guess here " +
             "is indistinguishable from their choice and produces a confident " +
             "answer about the wrong notebook."),
+        notebook_key: z
+            .string()
+            .optional()
+            .describe("The notebook_key printed with the notebook list, passed back exactly " +
+            "as it was given. Required alongside `notebook` on an account with " +
+            "more than one notebook: it is how this tool knows the name came " +
+            "from the list rather than from somewhere outside the conversation. " +
+            "Never invent one, and never reuse one from an earlier session."),
         since: z
             .string()
             .optional()
@@ -734,9 +745,9 @@ const createServer = async (call, grants = []) => {
             .describe("Cap the number of pages returned, newest first. The reply says how " +
             "many matched, so a capped list is never mistaken for the whole " +
             "notebook."),
-    }, async ({ notebook, since, limit }) => {
+    }, async ({ notebook, notebook_key, since, limit }) => {
         try {
-            const chosen = await selectNotebook(call, notebook, "list_notes");
+            const chosen = await selectNotebook(call, notebook, notebook_key, "list_notes");
             if ("message" in chosen) {
                 return { content: [{ type: "text", text: chosen.message }] };
             }
@@ -832,6 +843,14 @@ const createServer = async (call, grants = []) => {
             "this conversation, or named by the user in it. Omit when they have " +
             "not chosen one. Never fill it in from saved context or an earlier " +
             "session."),
+        notebook_key: z
+            .string()
+            .optional()
+            .describe("The notebook_key printed with the notebook list, passed back exactly " +
+            "as it was given. Required alongside `notebook` on an account with " +
+            "more than one notebook: it is how this tool knows the name came " +
+            "from the list rather than from somewhere outside the conversation. " +
+            "Never invent one, and never reuse one from an earlier session."),
         since: z
             .string()
             .optional()
@@ -844,9 +863,9 @@ const createServer = async (call, grants = []) => {
             .min(1)
             .optional()
             .describe(`Cap how many pages are sketched, newest first. Defaults to ${DEFAULT_MAP_PAGES}.`),
-    }, async ({ notebook, since, limit }) => {
+    }, async ({ notebook, notebook_key, since, limit }) => {
         try {
-            const chosen = await selectNotebook(call, notebook, "map_notes");
+            const chosen = await selectNotebook(call, notebook, notebook_key, "map_notes");
             if ("message" in chosen) {
                 return { content: [{ type: "text", text: chosen.message }] };
             }
@@ -898,7 +917,7 @@ const createServer = async (call, grants = []) => {
                     ],
                 };
             }
-            const { sketches, read_in_full } = await call("map_notes", { pages });
+            const { sketches, read_in_full, not_reached } = await call("map_notes", { pages });
             const blocks = sketches.map((s) => {
                 const location = [s.notebook, s.section].filter(Boolean).join(" / ");
                 const head = `## ${s.title}${location ? ` (${location})` : ""} — dated ${s.last_modified ?? "unknown"}` +
@@ -930,6 +949,16 @@ const createServer = async (call, grants = []) => {
                     "usable preview and were read in full instead, so those sketches " +
                     "cover more of the page than the rest.");
             }
+            if (not_reached > 0) {
+                // Said before the other truncations, because it is the one the
+                // caller did not ask for: `limit` is their own cap and this is the
+                // clock running out. A partial survey that does not say so is a
+                // survey the caller will read as complete.
+                caveats.push(`Stopped after ${sketches.length} of ${sketches.length + not_reached} pages: the ` +
+                    "survey ran out of time before the rest were reached. Those pages are " +
+                    "UNSURVEYED, not empty — call map_notes again with a smaller `limit` to " +
+                    "cover them, or read_note the ones you already know you need.");
+            }
             if (pages.length < matched) {
                 caveats.push(`Sketched the ${pages.length} newest by date of ${matched} pages. ` +
                     "Raise `limit` or narrow with `since` for the rest.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manudota/artist-mcp",
-  "version": "2.2.2-staging.103",
+  "version": "2.3.0",
   "description": "MCP server that reads your OneNote notes in Claude Desktop or Codex, with optional Gmail and Calendar as supporting evidence. Signs in on your own machine; writes are opt-in per install.",
   "keywords": [
     "mcp",