moontide-mcp 2.0.2 → 2.2.0

package/dist/mcp.js

@@ -7,10 +7,10 @@ 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, } from './reference.js';
+import { REFERENCE_TOPICS, REFERENCE_TOPIC_IDS, REFERENCE_URI_PREFIX, readReferenceTopic, referenceIndexText, referenceToolDescription, structureTemplateText, } from './reference.js';
 export const NOTHING_PLAYING_MESSAGE = 'Nothing is playing yet.';
 export const PLAYING_WITH_ERRORS_MESSAGE = 'Playing, but with runtime errors (see below).';
 export const STOPPED_MESSAGE = 'ok, stopped. The code stays in the page; call set_code to start playing again.';
@@ -22,6 +22,12 @@ export const HAND_EDIT_REPLACED_NOTE = 'Note: the code you replaced had been edi
 export const HAND_EDIT_KEPT_NOTE = 'Note: the code you edited had been edited by hand in the page since your last change; your edit was applied on top of it.';
 // The page's text is authoritative, as for set_code; when it differs from the composed program the reply says so.
 export const EDIT_OTHER_TEXT_NOTE = 'Note: the page confirmed a text that differs from the edited code, so the lines above may not match what plays; get_code returns what plays.';
+// The line above the song structure template get_code shows when nothing plays yet.
+export const STRUCTURE_TEMPLATE_INTRO = 'A song structure to start a new piece from (the structure topic of get_strudel_reference explains it):';
+/** The intro line and the template in a js fence, read from the structure topic at call time (a missing block throws). */
+function structureTemplateBlock() {
+    return `${STRUCTURE_TEMPLATE_INTRO}\n\`\`\`js\n${structureTemplateText()}\n\`\`\``;
+}
 export const GETTIME_ANCHOR_NOTE = 'Note: this code reads getTime(); an anchor taken from it restarts every time a later change re-sends this code, ' +
     'while a transition anchored with .timeline(id) keeps running across changes (see the transitions topic).';
 // A warning only, as a text match: the code is never parsed, evaluated or changed on the server;
@@ -67,6 +73,44 @@ export function whenFlagLines(code) {
     }
     return [];
 }
+// The reply line a set_code of a new piece carries when the piece declares no song structure. One plain line, fixed
+// 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. 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;
+/**
+ * True when `code` is a new piece compared with `previous`: the previous code is empty, holds no line of
+ * NEW_PIECE_MIN_LINE or more characters, or `code` keeps fewer than half of those lines (kept * 2 < total, so keeping
+ * exactly half is not new). Lines are compared trimmed, through a Set, so the cost is linear in the two texts.
+ */
+function isNewPiece(previous, code) {
+    const longLines = previous
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length >= NEW_PIECE_MIN_LINE);
+    if (longLines.length === 0)
+        return true;
+    const kept = new Set(code.split('\n').map((line) => line.trim()));
+    let keptCount = 0;
+    for (const line of longLines) {
+        if (kept.has(line))
+            keptCount += 1;
+    }
+    return keptCount * 2 < longLines.length;
+}
+/** The note when `code` replaces `previousCode` as a new piece and declares no song structure, empty otherwise. */
+export function newPieceWithoutStructureLines(previousCode, code) {
+    if (SONG_DECLARATION_RE.test(code))
+        return [];
+    return isNewPiece(previousCode, code) ? [NO_STRUCTURE_NOTE] : [];
+}
 export function waitingForClickMessage(pageUrl) {
     return `Waiting for the user's click: the code is loaded and will start playing after one click on the page at ${pageUrl}.`;
 }
@@ -112,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.
@@ -147,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.
@@ -243,15 +336,12 @@ export const SERVER_INSTRUCTIONS = [
     // underscore and never lets it solo. The solo-label claim of scripts/check-reference.mjs reads
     // this string from the source, so it stays one single-quoted line.
     'A label longer than one character that starts with a capital S plays alone, unless it also ends with an underscore, which silences it instead: while a label that plays alone exists, every other label is silent.',
+    // The standing rule for song structure, kept to one short sentence: the full form is the structure topic and the
+    // template get_code shows when nothing plays yet, so only the duty and the place to look are said here. No example
+    // and no section names: any example would suggest a style.
+    'Every new piece declares its song structure once at the top; the structure topic of get_strudel_reference has the form.',
     // Read before editing.
     "Before changing the music, call get_code: it includes the user's hand edits.",
-    // Act on a vague request. How to explain a change and when to ask before a rewrite
-    // are in the set_code description. No example line: any example would suggest a style.
-    'When a request is vague, act on your own reading of it instead of asking first.',
-    // Guidance, not structure. The reply that reports a failed sound says which sound
-    // and that it plays nothing. Moontide never blocks, rewrites or refuses code because a sound failed;
-    // naming a replacement would steer the palette.
-    'If you replace a sound that failed to load, tell the user which one and what replaced it, never silently.',
     // A session frame applies to every change, surprises included, until lifted, and a
     // gradual frame means each change, surprises and small edits included, arrives through a transition,
     // not only as a smaller step. No variety rule; nothing says how a surprise should sound.
@@ -305,19 +395,22 @@ export function createMcpServer(options) {
     const server = new McpServer({ name: 'moontide', version: readPackageVersion() }, { instructions: SERVER_INSTRUCTIONS });
     server.registerTool('get_code', {
         description: "Reads the Strudel code currently playing in the Moontide page, i.e. the last code the page confirmed, " +
-            "including edits the user evaluated by hand; returns 'Nothing is playing yet.' before anything played. " +
+            "including edits the user evaluated by hand; returns 'Nothing is playing yet.' before anything played, with a template of a song structure to start from. " +
             'Before Moontide is started it says so and starts nothing; after the start its reply also names the page address, the port and the tab title. ' +
             '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();
         if (server === null) {
-            throw new Error(NOT_STARTED_MESSAGE);
+            // The first get_code of a fresh session comes before the start, and nothing plays yet either way.
+            throw new Error(`${NOT_STARTED_MESSAGE}\n\n${structureTemplateBlock()}`);
         }
         const code = session.getCode();
-        const text = code === '' ? NOTHING_PLAYING_MESSAGE : code;
+        const text = code === '' ? `${NOTHING_PLAYING_MESSAGE}\n\n${structureTemplateBlock()}` : code;
         const { lines } = session.drainNotices();
         // STOPPED_NOTE first when both apply, then HAND_EDIT_NOTE, then the version line, then the page line, then drained lines.
         const notices = [];
@@ -342,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 }] };
@@ -365,7 +459,9 @@ export function createMcpServer(options) {
             'Double-quoted and backtick strings are parsed as mini-notation wherever they appear, helpers included, while single-quoted strings stay plain JavaScript (see the tidal-differences topic). ' +
             `When Moontide is not started yet, set_code starts it first: its page opens in a new browser tab and the call waits up to ${PAGE_WAIT_MS / 1000} seconds for that page to connect. ` +
             'Before changing existing music, call get_code and build on what it returns, including hand edits. Keep what the user said matters; if a small request ' +
-            'needs a full rewrite and the user said what matters, ask first, otherwise rewrite and say so. Returns ' +
+            'needs a full rewrite and the user said what matters, ask first, otherwise rewrite and say so. ' +
+            // Moved here from the server instructions (CLIENT_INSTRUCTIONS_LIMIT): Claude meets it where it writes the code.
+            'When a request is vague, act on your own reading of it instead of asking first. Returns ' +
             'the code as confirmed by the page. Pass a short label saying what changed; every version that plays is ' +
             'kept in the history. Then tell the user in one line what you chose: the musical terms, plus a short ' +
             'image in plain words.',
@@ -380,17 +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();
-            const outcome = await session.evaluate(code, { label, at, phraseCycles });
+            // 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,
+                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.
@@ -401,13 +514,16 @@ export function createMcpServer(options) {
             // BPM: the tempo line first when it changed; the at-once note when a requested line was skipped
             // because nothing played (both from changeNoteLines, shared with edit_code).
             const notices = outcome.replacedHandEdit ? [HAND_EDIT_REPLACED_NOTE] : [];
-            // The t/f flag note comes right before the getTime() note. The getTime() warn note, when
-            // present, is always the last line.
+            // Order of the reply lines: the change notes, the hand-edit note, the drained notices (structure notes included),
+            // the t/f flag note, the new-piece note, then the getTime() warn note, which is always the last line. The new-piece
+            // note is for set_code only: edit_code changes part of a piece and restore_version brings an older one back.
             const text = withNoticeLines(`${status}\n\n${outcome.code}`, [
                 ...changeNoteLines(outcome, at),
                 ...notices,
                 ...lines,
                 ...whenFlagLines(outcome.code),
+                ...newPieceWithoutStructureLines(previousCode, outcome.code),
+                ...unknownAnsweringLines(answering, answeringOpen),
                 ...getTimeAnchorLines(outcome.code),
             ]);
             return { content: [{ type: 'text', text }] };
@@ -418,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
@@ -456,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());
@@ -489,6 +620,7 @@ export function createMcpServer(options) {
                 ...otherText,
                 ...lines,
                 ...whenFlagLines(outcome.code),
+                ...unknownAnsweringLines(answering, answeringOpen),
                 ...getTimeAnchorLines(outcome.code),
             ]);
             return { content: [{ type: 'text', text }] };
@@ -497,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', {
@@ -512,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();
@@ -534,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();
@@ -549,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.
@@ -566,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}`, [
@@ -574,6 +716,7 @@ export function createMcpServer(options) {
                 ...notices,
                 ...lines,
                 ...whenFlagLines(outcome.code),
+                ...unknownAnsweringLines(answering, answeringOpen),
                 ...getTimeAnchorLines(outcome.code),
             ]);
             return { content: [{ type: 'text', text }] };
@@ -585,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);
         }
@@ -619,6 +785,7 @@ export function createMcpServer(options) {
             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();
@@ -639,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();
@@ -658,6 +826,7 @@ export function createMcpServer(options) {
             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();
@@ -706,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();
@@ -754,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()));
@@ -780,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 }] };
     });