moontide-mcp 2.1.0 → 2.4.0

package/dist/mcp.js

@@ -7,7 +7,7 @@ import { z } from 'zod';
 import { EDIT_NOTHING_PLAYING_MESSAGE, NOT_STARTED_MESSAGE } from './session.js';
 import { PAGE_WAIT_MS, START_INSTRUCTION, START_PROMPT, START_PROMPT_DESCRIPTION, START_PROMPT_TITLE, START_TOOL, START_TOOL_DESCRIPTION, notStartedForRequestsText, notStartedForRequestsToolText, pageLine, startMoontide, } from './start.js';
 import { MAX_EDITS, changedExcerpt } from './edit-code.js';
-import { MAX_PHRASE_CYCLES, MIN_PHRASE_CYCLES } from './protocol.js';
+import { MAX_ANSWER_TEXT_LENGTH, MAX_ASK_ID_LENGTH, MAX_GLIDE_BARS, MAX_PHRASE_CYCLES, MIN_GLIDE_BARS, MIN_PHRASE_CYCLES, } from './protocol.js';
 import { MAX_LABEL_LENGTH, MAX_FAVORITE_NAME_LENGTH } from './history.js';
 import { PAGE_REQUESTS_ALREADY_OFF, PAGE_REQUESTS_ALREADY_ON, PAGE_REQUESTS_OFF_DESCRIPTION, PAGE_REQUESTS_OFF_PROMPT, PAGE_REQUESTS_OFF_TEXT, PAGE_REQUESTS_OFF_TITLE, PAGE_REQUESTS_ON_DESCRIPTION, PAGE_REQUESTS_ON_PROMPT, PAGE_REQUESTS_ON_TITLE, PAGE_REQUESTS_INSTRUCTION, PAGE_REQUESTS_STATE_DESCRIPTION, PAGE_REQUESTS_TOOL, PAGE_REQUESTS_TOOL_DESCRIPTION, REQUEST_LINE_FRAMING, listenerScriptPath, noPageForRequestsText, noPageForRequestsToolText, pageRequestsOnText, } from './ask.js';
 import { REFERENCE_TOPICS, REFERENCE_TOPIC_IDS, REFERENCE_URI_PREFIX, readReferenceTopic, referenceIndexText, referenceToolDescription, structureTemplateText, } from './reference.js';
@@ -77,10 +77,12 @@ export function whenFlagLines(code) {
 // text: it holds no code and no page text. The music plays as written; nothing is refused, blocked or rewritten.
 export const NO_STRUCTURE_NOTE = 'Note: this new piece declares no song structure; every new piece declares one once at the top (see the structure topic of get_strudel_reference). It plays as written.';
 // A text match only, like GETTIME_CALL_RE: the code is never parsed, evaluated or changed on the server, and a match
-// inside a comment or a string counts too, by design. Anchored at a line start with [ \t]* (never \s*, so a run of blank
-// lines cannot make the scan quadratic) and ended on a word boundary, so `const songs`, `const song2`, `let song` and a
-// commented-out line are not a structure. The m flag only: no global flag, so test() keeps no lastIndex.
-const SONG_CONST_RE = /^[ \t]*const[ \t]+song\b/m;
+// inside a comment or a string counts too, by design. A song declared with let or var gets its own line from the page,
+// which reads only const, so the server says nothing more for it and the two lines never disagree. Anchored at a line
+// start with [ \t]* (never \s*, so a run of blank lines cannot make the scan quadratic) and ended on a word boundary, so
+// `const songs`, `const song2` and a commented-out line are not a song. The m flag only: no global flag, so test() keeps
+// no lastIndex.
+const SONG_DECLARATION_RE = /^[ \t]*(?:const|let|var)[ \t]+song\b/m;
 /** The shortest line, in characters after trimming, that counts when telling a new piece from a changed one. */
 const NEW_PIECE_MIN_LINE = 8;
 /**
@@ -105,7 +107,7 @@ function isNewPiece(previous, code) {
 }
 /** The note when `code` replaces `previousCode` as a new piece and declares no song structure, empty otherwise. */
 export function newPieceWithoutStructureLines(previousCode, code) {
-    if (SONG_CONST_RE.test(code))
+    if (SONG_DECLARATION_RE.test(code))
         return [];
     return isNewPiece(previousCode, code) ? [NO_STRUCTURE_NOTE] : [];
 }
@@ -154,6 +156,24 @@ export function tempoLine(bpm, pendingCycle) {
     const shown = Number.isInteger(bpm) ? String(bpm) : bpm.toFixed(1);
     return pendingCycle === undefined ? `Tempo: ${shown} BPM.` : `Tempo from cycle ${pendingCycle}: ${shown} BPM.`;
 }
+/**
+ * The one-line tempo ramp of a reply, said in place of the tempo line. Three states: a ramp that started with this change,
+ * a ramp that starts at the line of a waiting change (`pendingCycle` is the line), and a ramp that goes on because this
+ * change restated its target. The numbers come from the page, bounded by the protocol schema; only numbers are
+ * formatted here, so no page text enters the reply.
+ */
+export function glideLine(glide, pendingCycle) {
+    const shown = (bpm) => (Number.isInteger(bpm) ? String(bpm) : bpm.toFixed(1));
+    if (glide.state === 'running') {
+        return `Tempo ramp goes on: to ${shown(glide.toBpm)} BPM, now ${shown(glide.nowBpm)} BPM.`;
+    }
+    const length = glide.bars === 1 ? 'over 1 bar' : `over ${glide.bars} bars`;
+    if (glide.state === 'at-line') {
+        const line = pendingCycle === undefined ? 'at its line' : `from cycle ${pendingCycle}`;
+        return `Tempo ramp ${line}: from the tempo playing then to ${shown(glide.toBpm)} BPM ${length}.`;
+    }
+    return `Tempo ramp: from ${shown(glide.fromBpm)} to ${shown(glide.toBpm)} BPM ${length}.`;
+}
 /**
  * The first note of get_code while a change waits to take over: the code the reply shows is the code
  * that plays until the line.
@@ -189,16 +209,47 @@ function changeStatus(outcome, at, hadRuntimeErrors, pageUrl) {
  * the at-once note when a requested line was skipped because nothing played.
  */
 function changeNoteLines(outcome, at) {
-    const tempo = outcome.tempoChanged && outcome.bpm !== null ? [tempoLine(outcome.bpm, outcome.pending?.cycle)] : [];
+    // A change that started a ramp says the ramp in place of the tempo line: the tempo that plays has not changed yet.
+    const tempo = outcome.glide !== undefined
+        ? [glideLine(outcome.glide, outcome.pending?.cycle)]
+        : outcome.tempoChanged && outcome.bpm !== null
+            ? [tempoLine(outcome.bpm, outcome.pending?.cycle)]
+            : [];
     const atOnce = (at === 'bar' || at === 'phrase') && outcome.pending === undefined && outcome.audio !== 'stopped'
         ? [AT_ONCE_NOTE]
         : [];
     return [...tempo, ...atOnce];
 }
 const LABEL_FIELD_DESCRIPTION = 'A few words saying what this change is, for example "added a bass"; shown by list_history';
+// One description for the three tools that change the music, so Claude meets the same fact wherever it reads it.
+export const ANSWERING_FIELD_DESCRIPTION = 'The id of the page request this change answers, from its request line; the page shows that request as applied only when the change names it here';
+// Said in a reply when `answering` names no open page request. No user text, no id: the note is the same every time.
+// The music change itself is never refused or held back for it.
+export const UNKNOWN_ANSWERING_NOTE = 'Note: answering names no open page request (it is unknown or already closed), so it changed no request status; the music change is not affected by it.';
+/** The note when `answering` was given and names no open request, empty otherwise. */
+export function unknownAnsweringLines(answering, open) {
+    return answering !== undefined && !open ? [UNKNOWN_ANSWERING_NOTE] : [];
+}
+export const ANSWER_REQUEST_TOOL = 'answer_request';
+export const ANSWER_REQUEST_DESCRIPTION = 'Closes a request typed in the Moontide page without changing the music. Use outcome answered when the request was answered in words, declined when it will not or cannot be done. ' +
+    `Give one sentence of at most ${MAX_ANSWER_TEXT_LENGTH} characters; the page shows it under the request. ` +
+    'A change that answers a request names it with answering on set_code, edit_code or restore_version instead. ' +
+    'An id that is not an open request is refused and nothing changes.';
+export const ANSWER_REQUEST_ID_DESCRIPTION = 'The id of the page request to close, from its request line';
+export const ANSWER_REQUEST_OUTCOME_DESCRIPTION = 'answered when the request was answered in words, declined when it will not or cannot be done';
+export const ANSWER_REQUEST_TEXT_DESCRIPTION = `One sentence for the user, at most ${MAX_ANSWER_TEXT_LENGTH} characters; the page shows it under the request`;
+/** The reply when a request was closed, one fixed line per outcome. */
+export function answerRequestReply(outcome) {
+    return outcome === 'answered' ? 'The page request was closed as answered.' : 'The page request was closed as declined.';
+}
 const AT_FIELD_DESCRIPTION = "When the change takes over: 'now' (the default) within a fraction of a second, 'bar' on the next bar line, 'phrase' on the next phrase line (4 cycles, counted from Play). " +
     'The code is checked at once; the reply says the cycle and about how many seconds away it is.';
 const PHRASE_CYCLES_FIELD_DESCRIPTION = "How many cycles one phrase lasts, for at: 'phrase' (2 to 64, default 4)";
+// Facts only: the bounds are the only digits. It is one description for both tools that change the music's code.
+export const GLIDE_BARS_FIELD_DESCRIPTION = 'Whole bars, 1 to 64, to move the tempo smoothly from the tempo that plays to the one this code sets with setcps or setcpm; with at, it starts at the line. Refused when nothing plays, no tempo is set or it already plays. Stop, or code with another tempo or none, cancels it';
+// Said when set_code or edit_code asks for a ramp while nothing plays. The page holds the same text for the case the server
+// cannot know about (a page that has not played yet); a test checks both. Nothing was started, opened or sent.
+export const GLIDE_NOTHING_PLAYS_MESSAGE = 'Nothing plays, so there is no tempo to ramp from. Nothing was changed. Send the change again without glideBars.';
 /**
  * The tool description of edit_code. The when-to-use rule comes first; Claude Code keeps at most 2048
  * characters of a tool description.
@@ -349,6 +400,8 @@ export function createMcpServer(options) {
             'Call it before every change.',
         annotations: { readOnlyHint: true },
     }, async () => {
+        // Marks the page requests Claude already holds as started; first, so a request this reply hands over is not.
+        session.noteToolCall();
         // Before the start there is no page and no code: say how to start and start nothing. No drain, so queued
         // notices wait for the next reply.
         const server = starter.current();
@@ -382,6 +435,7 @@ export function createMcpServer(options) {
             topic: z.enum(REFERENCE_TOPIC_IDS).optional().describe('One topic to return; omit it to get the index of topics'),
         },
     }, async ({ topic }) => {
+        session.noteToolCall();
         try {
             const text = topic ? readReferenceTopic(topic) : referenceIndexText();
             return { content: [{ type: 'text', text }] };
@@ -422,19 +476,34 @@ export function createMcpServer(options) {
                 .max(MAX_PHRASE_CYCLES)
                 .optional()
                 .describe(PHRASE_CYCLES_FIELD_DESCRIPTION),
+            glideBars: z.number().int().min(MIN_GLIDE_BARS).max(MAX_GLIDE_BARS).optional().describe(GLIDE_BARS_FIELD_DESCRIPTION),
+            answering: z.string().min(1).max(MAX_ASK_ID_LENGTH).optional().describe(ANSWERING_FIELD_DESCRIPTION),
         },
-    }, async ({ code, label, at, phraseCycles }) => {
+    }, async ({ code, label, at, phraseCycles, glideBars, answering }) => {
+        session.noteToolCall();
+        // An id that is not open never reaches the change: it is told once and the music change goes ahead.
+        const answeringOpen = answering === undefined ? true : session.requestIsOpen(answering);
         try {
             // A phrase length means nothing for another timing; refused before anything reaches the page.
             if (phraseCycles !== undefined && at !== 'phrase') {
                 throw new Error("phraseCycles applies only with at: 'phrase'.");
             }
+            // A ramp needs music to leave: refused before Moontide starts, a tab opens or anything reaches the page.
+            if (glideBars !== undefined && (!session.hasActivePage() || session.isStopped())) {
+                throw new Error(GLIDE_NOTHING_PLAYS_MESSAGE);
+            }
             // The first change of the music starts Moontide and waits for the page of the tab it opens.
             await starter.ensureStarted();
             await starter.waitForPage();
             // What played before this call, read before the page changes it: the new-piece note compares the two.
             const previousCode = session.getCode();
-            const outcome = await session.evaluate(code, { label, at, phraseCycles });
+            const outcome = await session.evaluate(code, {
+                label,
+                at,
+                phraseCycles,
+                glideBars,
+                answering: answeringOpen ? answering : undefined,
+            });
             const { lines, hadRuntimeErrors } = session.drainNotices();
             // Claude must never be told "ok, playing" when something went wrong —
             // including when the user pressed Stop while this code was still starting.
@@ -454,6 +523,7 @@ export function createMcpServer(options) {
                 ...lines,
                 ...whenFlagLines(outcome.code),
                 ...newPieceWithoutStructureLines(previousCode, outcome.code),
+                ...unknownAnsweringLines(answering, answeringOpen),
                 ...getTimeAnchorLines(outcome.code),
             ]);
             return { content: [{ type: 'text', text }] };
@@ -464,7 +534,7 @@ export function createMcpServer(options) {
             // A failed set_code doesn't clear a pending hand edit, so keep surfacing it.
             const notices = session.wasEditedByHand() ? [HAND_EDIT_NOTE] : [];
             const message = err instanceof Error ? err.message : String(err);
-            throw new Error(withNoticeLines(message, [...notices, ...lines]));
+            throw new Error(withNoticeLines(message, [...notices, ...lines, ...unknownAnsweringLines(answering, answeringOpen)]));
         }
     });
     // Changes part of the code that will play by exact replacements, through the same Session path as
@@ -502,20 +572,35 @@ export function createMcpServer(options) {
                 .max(MAX_PHRASE_CYCLES)
                 .optional()
                 .describe(PHRASE_CYCLES_FIELD_DESCRIPTION),
+            glideBars: z.number().int().min(MIN_GLIDE_BARS).max(MAX_GLIDE_BARS).optional().describe(GLIDE_BARS_FIELD_DESCRIPTION),
+            answering: z.string().min(1).max(MAX_ASK_ID_LENGTH).optional().describe(ANSWERING_FIELD_DESCRIPTION),
         },
-    }, async ({ edits, base, label, at, phraseCycles }) => {
+    }, async ({ edits, base, label, at, phraseCycles, glideBars, answering }) => {
+        session.noteToolCall();
+        const answeringOpen = answering === undefined ? true : session.requestIsOpen(answering);
         try {
             // The same rule and text as set_code, before anything reaches the page.
             if (phraseCycles !== undefined && at !== 'phrase') {
                 throw new Error("phraseCycles applies only with at: 'phrase'.");
             }
+            // The same rule and text as set_code.
+            if (glideBars !== undefined && (!session.hasActivePage() || session.isStopped())) {
+                throw new Error(GLIDE_NOTHING_PLAYS_MESSAGE);
+            }
             // Nothing plays before a start, so there is nothing to edit: refuse before a tab opens for a request that cannot work.
             if (starter.current() === null) {
                 throw new Error(EDIT_NOTHING_PLAYING_MESSAGE);
             }
             await starter.ensureStarted();
             await starter.waitForPage();
-            const edit = await session.editCode(edits, { base, label, at, phraseCycles });
+            const edit = await session.editCode(edits, {
+                base,
+                label,
+                at,
+                phraseCycles,
+                glideBars,
+                answering: answeringOpen ? answering : undefined,
+            });
             const { outcome } = edit;
             const { lines, hadRuntimeErrors } = session.drainNotices();
             const status = changeStatus(outcome, at, hadRuntimeErrors, session.getPageUrl());
@@ -535,6 +620,7 @@ export function createMcpServer(options) {
                 ...otherText,
                 ...lines,
                 ...whenFlagLines(outcome.code),
+                ...unknownAnsweringLines(answering, answeringOpen),
                 ...getTimeAnchorLines(outcome.code),
             ]);
             return { content: [{ type: 'text', text }] };
@@ -543,7 +629,7 @@ export function createMcpServer(options) {
             const { lines } = session.drainNotices();
             const notices = session.wasEditedByHand() ? [HAND_EDIT_NOTE] : [];
             const message = err instanceof Error ? err.message : String(err);
-            throw new Error(withNoticeLines(message, [...notices, ...lines]));
+            throw new Error(withNoticeLines(message, [...notices, ...lines, ...unknownAnsweringLines(answering, answeringOpen)]));
         }
     });
     server.registerTool('list_history', {
@@ -558,6 +644,7 @@ export function createMcpServer(options) {
             favorites: z.boolean().optional().describe('true to list only favorites'),
         },
     }, async ({ limit, filter, favorites }) => {
+        session.noteToolCall();
         try {
             const text = session.listHistory({ limit, filter, favoritesOnly: favorites });
             const { lines } = session.drainNotices();
@@ -580,6 +667,7 @@ export function createMcpServer(options) {
                 .describe("Name to keep it under, in the user's words"),
         },
     }, async ({ id, name }) => {
+        session.noteToolCall();
         try {
             const text = session.favoriteVersion(id, name);
             const { lines } = session.drainNotices();
@@ -595,14 +683,17 @@ export function createMcpServer(options) {
         description: 'Plays a past version again, by its id from list_history, in one call: it takes over within a fraction of a second without stopping the music, with the same checks as set_code. The restore is added to the history as a new version ("restored from #id"); nothing is rewritten. Returns the code as confirmed by the page. A restore always takes over at once and replaces a change that waits for a bar or phrase line. The old version replaces the music at once; when the user asked for gradual changes this session, bring it in with set_code and a transition instead. Like set_code, it starts Moontide first when it is not started yet, but only for an id that exists in the history.',
         inputSchema: {
             id: z.number().int().positive().describe('Version id from list_history, for example 41 for #41'),
+            answering: z.string().min(1).max(MAX_ASK_ID_LENGTH).optional().describe(ANSWERING_FIELD_DESCRIPTION),
         },
-    }, async ({ id }) => {
+    }, async ({ id, answering }) => {
+        session.noteToolCall();
+        const answeringOpen = answering === undefined ? true : session.requestIsOpen(answering);
         try {
             // The history needs no page: an id that cannot be restored fails before Moontide starts or a tab opens.
             session.assertVersionExists(id);
             await starter.ensureStarted();
             await starter.waitForPage();
-            const outcome = await session.restoreVersion(id);
+            const outcome = await session.restoreVersion(id, { answering: answeringOpen ? answering : undefined });
             const { lines, hadRuntimeErrors } = session.drainNotices();
             // versionId is null only on a history-write failure — the write-failure
             // note (queued by the same recordConfirmed path set_code uses) explains why below.
@@ -612,7 +703,12 @@ export function createMcpServer(options) {
             const status = outcome.audio === 'playing' && !hadRuntimeErrors
                 ? `${head} — now playing.`
                 : `${head}. ${playStatus(outcome.audio, hadRuntimeErrors, session.getPageUrl())}`;
-            const tempo = outcome.tempoChanged && outcome.bpm !== null ? [tempoLine(outcome.bpm)] : [];
+            // A restored version that restates the target of a running ramp lets it go on, and says so in place of the tempo line.
+            const tempo = outcome.glide !== undefined
+                ? [glideLine(outcome.glide)]
+                : outcome.tempoChanged && outcome.bpm !== null
+                    ? [tempoLine(outcome.bpm)]
+                    : [];
             const notices = outcome.replacedHandEdit ? [HAND_EDIT_REPLACED_NOTE] : [];
             // The same t/f flag note and getTime() warn note as set_code, the getTime() note last.
             const text = withNoticeLines(`${status}\n\n${outcome.code}`, [
@@ -620,6 +716,7 @@ export function createMcpServer(options) {
                 ...notices,
                 ...lines,
                 ...whenFlagLines(outcome.code),
+                ...unknownAnsweringLines(answering, answeringOpen),
                 ...getTimeAnchorLines(outcome.code),
             ]);
             return { content: [{ type: 'text', text }] };
@@ -631,13 +728,36 @@ export function createMcpServer(options) {
             const { lines } = session.drainNotices();
             const notices = session.wasEditedByHand() ? [HAND_EDIT_NOTE] : [];
             const message = err instanceof Error ? err.message : String(err);
-            throw new Error(withNoticeLines(message, [...notices, ...lines]));
+            throw new Error(withNoticeLines(message, [...notices, ...lines, ...unknownAnsweringLines(answering, answeringOpen)]));
+        }
+    });
+    // Needs no started Moontide: a request id is only open while a server runs. It changes no music.
+    server.registerTool(ANSWER_REQUEST_TOOL, {
+        description: ANSWER_REQUEST_DESCRIPTION,
+        annotations: { destructiveHint: false },
+        inputSchema: {
+            id: z.string().min(1).max(MAX_ASK_ID_LENGTH).describe(ANSWER_REQUEST_ID_DESCRIPTION),
+            outcome: z.enum(['answered', 'declined']).describe(ANSWER_REQUEST_OUTCOME_DESCRIPTION),
+            text: z.string().max(MAX_ANSWER_TEXT_LENGTH).describe(ANSWER_REQUEST_TEXT_DESCRIPTION),
+        },
+    }, async ({ id, outcome, text }) => {
+        session.noteToolCall();
+        try {
+            session.answerRequest(id, outcome, text);
+            const { lines } = session.drainNotices();
+            return { content: [{ type: 'text', text: withNoticeLines(answerRequestReply(outcome), lines) }] };
+        }
+        catch (err) {
+            const { lines } = session.drainNotices();
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(withNoticeLines(message, lines));
         }
     });
     server.registerTool('stop', {
         description: 'Stops all sound in the Moontide page right away, even when the current code is broken. The code stays in the editor; get_code still returns it, and the next set_code starts playing again. Before Moontide is started it says so and starts nothing.',
         annotations: { destructiveHint: false, idempotentHint: true },
     }, async () => {
+        session.noteToolCall();
         if (starter.current() === null) {
             throw new Error(NOT_STARTED_MESSAGE);
         }
@@ -659,12 +779,13 @@ export function createMcpServer(options) {
         }
     });
     server.registerTool('get_midi_instruments', {
-        description: "When the user has described their instruments, call this before writing MIDI code. Lists the MIDI instruments the user described in instruments.json, as facts: for each one its id, model, exact port name, whether it is connected right now, its channels and their roles, how many sounds it has, its bank select, its reset, whether it follows MIDI clock and its controls. Pass instrument (an id from that list) to get that instrument's full sound list, with the program number sent for each sound and its bank when it has one. A sound is chosen in the code with the sound option of .midi(). An instrument with a sound catalog shows how many sounds the catalog holds and its categories; search_midi_sounds finds them. For an instrument with a rhythm channel it says how a kit goes out and which drum map applies; with instrument set it lists each drum map as note numbers and drum names, a kit's own map only when it differs from the model's, and says when a kit has no known map. Drum notes are written as note numbers in the code. It also says which instruments the user switched off in the page: their notes are silent, and .midi() code newly aimed at them is refused until the user switches them on.",
+        description: "When the user has described their instruments, call this before writing MIDI code. Lists the MIDI instruments the user described in instruments.json, as facts: for each one its id, model, exact port name, whether it is connected right now, its channels and their roles, how many sounds it has, its bank select, its reset, whether it follows MIDI clock and its controls. Pass instrument (an id from that list) to get that instrument's full sound list, with the program number sent for each sound and its bank when it has one. A sound is chosen in the code with the sound option of .midi(). An instrument with a sound catalog shows how many sounds the catalog holds and its categories; search_midi_sounds finds them. For an instrument whose model describes settings it lists the tone, part and scene setting names with their ranges, the tone ones per engine, and the settings topic of get_strudel_reference has their rules; with instrument set it gives the engine of each sound the catalog places in one. For an instrument with a rhythm channel it says how a kit goes out and which drum map applies; with instrument set it lists each drum map as note numbers and drum names, a kit's own map only when it differs from the model's, and says when a kit has no known map. Drum notes are written as note numbers in the code. It also says which instruments the user switched off in the page: their notes are silent, and .midi() code newly aimed at them is refused until the user switches them on.",
         annotations: { readOnlyHint: true },
         inputSchema: {
             instrument: z.string().min(1).max(32).optional().describe('An instrument id from instruments.json, to list its sounds'),
         },
     }, async ({ instrument }) => {
+        session.noteToolCall();
         try {
             const text = session.instrumentsReply(instrument);
             const { lines } = session.drainNotices();
@@ -677,7 +798,7 @@ export function createMcpServer(options) {
         }
     });
     server.registerTool('search_midi_sounds', {
-        description: "Searches the sound catalog of one instrument: a list of the model's sounds kept in the user's data folder, built from a patch-name file or a sound list the user owns. It finds sounds by words in the name or the category, in any order, with case and spaces ignored. It returns at most 25 matches: the exact name first, then names that start with the words, then names that contain them, then matches in the category only. Each match gives the name as the sound option of .midi() takes it, the program as sent (0-127), the bank when there is one and the category. It says how many more matched. A drum kit is marked (drum kit) and gives its drum map, or says the map is unknown.",
+        description: "Searches the sound catalog of one instrument: a list of the model's sounds kept in the user's data folder, built from a patch-name file or a sound list the user owns. It finds sounds by words in the name or the category, in any order, with case and spaces ignored. It returns at most 25 matches: the exact name first, then names that start with the words, then names that contain them, then matches in the category only. Each match gives the name as the sound option of .midi() takes it, the program as sent (0-127), the bank when there is one, the category and, for an instrument whose model declares engines, the engine of the sound or that it is in no engine. It says how many more matched. A drum kit is marked (drum kit) and gives its drum map, or says the map is unknown.",
         annotations: { readOnlyHint: true },
         inputSchema: {
             instrument: z.string().min(1).max(32).describe('An instrument id from instruments.json whose model has a sound catalog'),
@@ -685,6 +806,7 @@ export function createMcpServer(options) {
             category: z.string().max(60).optional().describe('Only sounds of this category; case and spaces do not matter'),
         },
     }, async ({ instrument, query, category }) => {
+        session.noteToolCall();
         try {
             const text = session.searchMidiSounds({ instrument, query, category });
             const { lines } = session.drainNotices();
@@ -697,13 +819,14 @@ export function createMcpServer(options) {
         }
     });
     server.registerTool('save_midi_model', {
-        description: "Saves an instrument model that you drafted from a page of the instrument's manual the user pasted, into the user's Moontide data folder (models/<id>.json), never into Moontide itself. First call it with confirmed: false: it checks the model and returns a summary (channels, sounds with their program numbers as sent and as numbered in a manual from 1, controls, reset bytes, notes) and saves nothing. Show that summary to the user, and call it again with the same model and confirmed: true only after they say yes. It refuses an id of a model Moontide ships, and an existing model unless overwrite is true. Fields: id (lowercase letters, digits, dashes or underscores, at most 32), name, channels { melodic, rhythm } (lists of channels 1-16), bankSelect (none, msb or msb-lsb), rhythmBank (optional: true when the instrument chooses drum kits by bank select and program change; every rhythm sound then needs a bank), drumMaps (optional, at most 8: [{ id, name, notes: [{ note 0-127, name }] }] typed from the instrument's manual), drumMap (optional: the id of the map of kits without their own; general-midi is built in), a rhythm sound's noteMap (optional: a map id, or null when no map is known for that kit), defaultVolume (0-127), clock (optional: true when the instrument follows MIDI clock, so Moontide sends it the clock, Start and Stop), reset (optional: sysex with at most 4 messages, each { kind: roland-dt1, model, address, data } as hex bytes or { kind: raw, bytes } from F0 to F7 and at most 32 bytes, and waitMs), controls ([{ id, name, cc, min, max, default }]), sounds { melodic, rhythm } ([{ name, program 0-127 as sent, bank { msb, lsb } when the instrument needs one }]) and notes (facts about the instrument, at most 10).",
+        description: "Saves an instrument model that you drafted from a page of the instrument's manual the user pasted, into the user's Moontide data folder (models/<id>.json), never into Moontide itself. First call it with confirmed: false: it checks the model and returns a summary (channels, sounds with their program numbers as sent and as numbered in a manual from 1, controls, reset bytes, notes) and saves nothing. Show that summary to the user, and call it again with the same model and confirmed: true only after they say yes. It refuses an id of a model Moontide ships, and an existing model unless overwrite is true. Fields: id (lowercase letters, digits, dashes or underscores, at most 32), name, channels { melodic, rhythm } (lists of channels 1-16), bankSelect (none, msb or msb-lsb), rhythmBank (optional: true when the instrument chooses drum kits by bank select and program change; every rhythm sound then needs a bank), drumMaps (optional, at most 8: [{ id, name, notes: [{ note 0-127, name }] }] typed from the instrument's manual), drumMap (optional: the id of the map of kits without their own; general-midi is built in), a rhythm sound's noteMap (optional: a map id, or null when no map is known for that kit), defaultVolume (0-127), clock (optional: true when the instrument follows MIDI clock, so Moontide sends it the clock, Start and Stop), monophonic (optional: true when the instrument plays one note at a time), reset (optional: sysex with at most 4 messages, each { kind: roland-dt1, model, address, data } as hex bytes or { kind: raw, bytes } from F0 to F7 and at most 32 bytes, and waitMs), controls ([{ id, name, cc, min, max, default }]), sounds { melodic, rhythm } ([{ name, program 0-127 as sent, bank { msb, lsb } when the instrument needs one }]) and notes (facts about the instrument, at most 10).",
         inputSchema: {
             model: z.record(z.string(), z.unknown()).describe('The drafted model, as a JSON object'),
             confirmed: z.boolean().describe('false to check and summarize without saving; true only after the user said yes to the summary'),
             overwrite: z.boolean().optional().describe('true to replace an existing user model with the same id'),
         },
     }, async ({ model, confirmed, overwrite }) => {
+        session.noteToolCall();
         try {
             const text = session.saveMidiModel({ model, confirmed, overwrite });
             const { lines } = session.drainNotices();
@@ -752,6 +875,7 @@ export function createMcpServer(options) {
                 .describe('The sounds of this part, grouped by bank and category; at most 500 sounds in the call'),
         },
     }, async ({ model, confirmed, append, more, source, programNumbering, overwrite, banks }) => {
+        session.noteToolCall();
         try {
             const text = session.saveMidiCatalog({ model, confirmed, append, more, source, programNumbering, overwrite, banks });
             const { lines } = session.drainNotices();
@@ -800,6 +924,7 @@ export function createMcpServer(options) {
             state: z.enum(['on', 'off']).describe(PAGE_REQUESTS_STATE_DESCRIPTION),
         },
     }, async ({ state }) => {
+        session.noteToolCall();
         const result = switchPageRequests({ session, state });
         if ('noPage' in result) {
             throw new Error(starter.current() === null ? notStartedForRequestsToolText() : noPageForRequestsToolText(session.getPageUrl()));
@@ -826,6 +951,7 @@ export function createMcpServer(options) {
         description: START_TOOL_DESCRIPTION,
         annotations: { destructiveHint: false, idempotentHint: true },
     }, async () => {
+        session.noteToolCall();
         const text = await startMoontide(starter);
         return { content: [{ type: 'text', text }] };
     });

package/dist/midi-state.js

@@ -104,6 +104,21 @@ export function midiFailedLine(failure) {
     const reason = failure === null ? '' : ` (${quoteMidiName(failure)})`;
     return `MIDI: Web MIDI could not start${reason}, so tracks using .midi() are silent. Other tracks keep playing.`;
 }
+/** Setting names joined by ', ': the schema holds each to a letter and then letters and digits, and cleaning keeps it so. */
+function settingNameList(names) {
+    return names.map(cleanMidiName).join(', ');
+}
+/** The words of each reason the memory guard gives (src/protocol.ts lists them). */
+const GUARD_REASON_WORDS = {
+    'not-bytes': 'it is not a list of numbers, so it cannot be checked',
+    'too-long': 'it is too long to be checked',
+    incomplete: 'it is not a complete system exclusive message',
+    'not-data-set': 'it is not a Roland data set (command 12) for the model of the instrument',
+    'unknown-areas': 'Moontide does not know which addresses of this instrument are temporary',
+    outside: 'it would write outside the temporary scene and tones',
+    checksum: 'its checksum does not match',
+    nrpn: 'it is not one of the NRPN part offsets Moontide knows for this instrument',
+};
 /**
  * The line of one event the page sent: a reset of an instrument, a sound change that may
  * cut a note, a sound kept after a failed evaluation, a send that failed, and clock or transport the
@@ -129,9 +144,36 @@ export function midiEventLine(event) {
         }
         case 'send-failed': {
             const id = quoteMidiName(event.instrument);
-            const what = event.what === 'reset' ? 'the reset' : 'the sound setup';
+            const what = event.what === 'reset' ? 'the reset' : event.what === 'settings' ? 'the settings' : 'the sound setup';
             return `MIDI: ${what} could not be sent to instrument ${id} (${quoteMidiName(event.failure)}).`;
         }
+        case 'settings-scene': {
+            const id = quoteMidiName(event.instrument);
+            return `MIDI: the scene settings ${settingNameList(event.names)} of ${id} reach every part of the instrument, not only the channel of their .midi() call.`;
+        }
+        case 'settings-left': {
+            const id = quoteMidiName(event.instrument);
+            const names = settingNameList(event.names);
+            const nothing = 'are no longer in the code that plays. Nothing is sent for them, so the instrument keeps the last value';
+            if (event.level === 'scene')
+                return `MIDI: the scene settings ${names} of ${id} ${nothing} until the instrument itself changes it.`;
+            if (event.level === 'part')
+                return `MIDI: the part settings ${names} of ${id} channel ${event.channel} ${nothing} until the instrument itself changes it.`;
+            return `MIDI: the tone settings ${names} of ${id} channel ${event.channel} ${nothing} until it loads the tone again.`;
+        }
+        case 'sysex-refused': {
+            const id = quoteMidiName(event.instrument);
+            const unread = event.reason === 'not-bytes' || event.reason === 'too-long';
+            const what = event.source === 'reset'
+                ? `the reset of ${id} was`
+                : event.source === 'settings'
+                    ? `the settings for ${id} were`
+                    : `a ${unread ? 'MIDI' : 'system exclusive'} message from the code to ${id} was`;
+            const only = event.reason === 'nrpn'
+                ? 'only Roland data sets into its temporary scene and tones, and the NRPN part offsets it knows.'
+                : 'only Roland data sets into its temporary scene and tones.';
+            return `MIDI: ${what} not sent: ${GUARD_REASON_WORDS[event.reason]}. Moontide sends nothing to an instrument that could write to its memory, ${only}`;
+        }
         case 'clock-dropped':
             return MIDI_CLOCK_DROPPED_LINE;
     }