moontide-mcp 2.0.2 → 2.2.0

package/dist/session.js

@@ -1,5 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { AskChannel, listenerScriptPath } from './ask.js';
+import { NOT_OPEN_REQUEST_MESSAGE, RequestStatusBoard, cleanAnswerText } from './request-status.js';
 import { MIDI_PERMISSION_WAIT_MESSAGE, MidiChannel } from './midi-state.js';
 import { applyEdits } from './edit-code.js';
 import { CatalogSaveError, MAX_CATALOG_DRAFTS, MAX_CATALOG_KITS, MAX_CATALOG_SOUNDS, MAX_PART_SOUNDS, catalogFileExists, countText, flattenCatalogPart, parseCatalog, problemsText, saveCatalog, summarizeCatalog, } from './catalog.js';
@@ -71,6 +72,14 @@ export function cleanErrorDetail(detail) {
     }
     return codePoints.slice(0, MAX_DETAIL_CODE_POINTS).join('') + '…';
 }
+/** The page's refusal text of a tempo ramp it could not make, trimmed and cut like any error detail but kept as a sentence. */
+function cleanRefusal(text) {
+    const trimmed = text.trim();
+    if (trimmed === '')
+        return UNKNOWN_ERROR_DETAIL;
+    const codePoints = Array.from(trimmed);
+    return codePoints.length <= MAX_DETAIL_CODE_POINTS ? trimmed : codePoints.slice(0, MAX_DETAIL_CODE_POINTS).join('') + '…';
+}
 /**
  * Builds the tool-response text for a failed evaluation: Strudel's message, the line when
  * known, and a truthful note about what is (or isn't) still playing.
@@ -145,6 +154,24 @@ export function earlierRuntimeErrorLine(message, count, versionId = null) {
         ? `Runtime error from an earlier version (#${versionId}, not the code playing now, repeated ${count} times): ${message}.`
         : `Runtime error from an earlier version (#${versionId}, not the code playing now): ${message}.`;
 }
+/** Every structure-note line in a reply starts with this, so no line of the page can start a reply line itself. */
+export const STRUCTURE_NOTE_LEAD = 'Song structure';
+/**
+ * Cleans one structure-note line from the page: every run of whitespace, control, format, line and paragraph
+ * separator characters becomes one space, then the text is cleaned like an error detail (trailing periods off, cut at
+ * MAX_DETAIL_CODE_POINTS code points). Returns null for a line with nothing left, which is dropped.
+ */
+export function cleanStructureLine(text) {
+    const collapsed = text.replace(/[\s\p{Cc}\p{Cf}\p{Zl}\p{Zp}]+/gu, ' ').trim();
+    if (collapsed === '') {
+        return null;
+    }
+    return cleanErrorDetail(collapsed);
+}
+/** One structure-note line as it appears in a reply: the fixed lead, the version when it is known, the cleaned sentence. */
+export function structureNoteLine(line, versionId = null) {
+    return versionId === null ? `${STRUCTURE_NOTE_LEAD}: ${line}.` : `${STRUCTURE_NOTE_LEAD} in #${versionId}: ${line}.`;
+}
 /**
  * The note Claude gets, once per distinct report, when a page could not load a script from unpkg.com. The fix is on
  * the user's side, so the note says so: Claude cannot repair a blocked network.
@@ -171,6 +198,26 @@ export function takeoverCanceledLine(cycle, reason) {
     }
     return `${head} the page was closed, reloaded or replaced by another tab before then. get_code returns the code from before it.`;
 }
+/**
+ * The note Claude gets, once, when a tempo ramp ended without Claude asking for it: a program stated another tempo, a
+ * program stated no tempo, a step failed, or the page that ran it was closed, reloaded or replaced by another tab.
+ * Stop, a finished ramp and a replaced ramp say nothing. Only the cause (a fixed word) and a number come in: no
+ * page text. `bpm` is the tempo that plays after the end; the wording leaves it out when the page gave none.
+ */
+export function glideEndedLine(reason, bpm) {
+    const shown = bpm === undefined ? undefined : Number.isInteger(bpm) ? String(bpm) : bpm.toFixed(1);
+    const head = 'Note: the tempo ramp ended early:';
+    if (reason === 'other-tempo') {
+        return `${head} a program stated another tempo${shown === undefined ? '' : `, and ${shown} BPM plays now`}.`;
+    }
+    if (reason === 'no-tempo') {
+        return `${head} a program stated no tempo${shown === undefined ? '' : `, so the tempo stays at ${shown} BPM, where the ramp had got to`}.`;
+    }
+    if (reason === 'error') {
+        return `${head} a step failed in the page${shown === undefined ? '' : `, so the tempo stays at ${shown} BPM`}.`;
+    }
+    return `${head} the page was closed, reloaded or replaced by another tab, so the tempo of the code plays.`;
+}
 /**
  * The note when a change that waited for its line took over and replaced code that had been edited by hand
  * in the page. Said at the takeover, never at the request: until the line the hand edit is still what plays, and a
@@ -218,6 +265,9 @@ export class Session {
     // already-counted overflow message, so it's just tallied — this only slightly over-counts
     // the rare tail past MAX_RUNTIME_ERRORS + MAX_DROPPED_RUNTIME_ERRORS distinct messages.
     droppedRuntimeErrorOverflowCount = 0;
+    // The latest structure note of the active page (see handleStructureNote): one slot, replaced by every note and
+    // emptied by the drain. The lines are already cleaned; the version id is looked up at drain time.
+    structureNote = null;
     // True once a stop is confirmed by the page; cleared by the next
     // successful evaluate() reply from the active page.
     stopped = false;
@@ -240,6 +290,11 @@ export class Session {
     pendingChange = null;
     // The notes of waiting changes that did not take over, queued once and drained once, like historyNotes.
     takeoverNotes = [];
+    // The tempo ramp the page runs, as far as the server knows: set when a reply says a ramp started (or the takeover of a
+    // change whose ramp starts at its line), cleared by Stop, a page end and a page loss. Null when none runs.
+    glide = null;
+    // The notes of a ramp that ended early, queued once and drained once, like takeoverNotes.
+    glideNotes = [];
     // The notes of load failure reports a page sent, one per distinct text (at most three), drained once.
     loadFailureNotes = new Set();
     // BPM: the tempo (rounded to one decimal) the last set_code or restore_version reply stated; null before any.
@@ -259,6 +314,8 @@ export class Session {
     supersededPages = new Set();
     /** The page-to-Claude channel (tokens, trust, limits, queue, listener). */
     ask;
+    /** What became of each page request: started, waiting for its line, applied and the other states. */
+    requests;
     /** The MIDI facts of the active page, worded once per change into notice lines. */
     midi;
     // The setup file's store (null without one), the JSON of the last midi-rig each page was
@@ -290,12 +347,36 @@ export class Session {
         this.rig = options?.rig ?? null;
         this.build = options?.build ?? null;
         this.recordIntentTtlMs = options?.recordIntentTtlMs ?? RECORD_INTENT_TTL_MS;
+        const send = (conn, msg, what) => this.sendToPage(conn, msg, what);
+        this.requests = new RequestStatusBoard({ send });
         this.ask = new AskChannel({
-            send: (conn, msg, what) => this.sendToPage(conn, msg, what),
+            send,
+            board: this.requests,
             ackTimeoutMs: options?.askAckTimeoutMs,
         });
         this.midi = new MidiChannel();
     }
+    /** A Moontide tool call began: the requests already handed to Claude are being worked on. */
+    noteToolCall() {
+        this.requests.noteToolCall();
+    }
+    /**
+     * Claude closes an open page request in words. The sentence is cleaned first; one that is empty after
+     * cleaning, and an id that is not an open request, are refused with a plain error and change nothing.
+     */
+    answerRequest(id, outcome, text) {
+        const sentence = cleanAnswerText(text);
+        if (sentence === '') {
+            throw new Error('The sentence is empty after removing spaces and control characters; give one sentence of words.');
+        }
+        if (!this.requests.closed(id, outcome, sentence)) {
+            throw new Error(NOT_OPEN_REQUEST_MESSAGE);
+        }
+    }
+    /** Whether a page request with this id is on the board and not finished. */
+    requestIsOpen(id) {
+        return this.requests.isOpen(id);
+    }
     setPageUrl(url) {
         this.pageUrl = url;
     }
@@ -341,6 +422,42 @@ export class Session {
             return;
         this.pendingChange = null;
         this.takeoverNotes.push(takeoverCanceledLine(waiting.cycle, reason));
+        const answering = waiting.intent?.answering;
+        if (answering === undefined)
+            return;
+        if (reason !== 'replaced') {
+            this.requests.canceled(answering);
+        }
+        else if (!this.answeringStillCarried(answering, waiting.id)) {
+            this.requests.replaced(answering);
+        }
+    }
+    /**
+     * The ramp ended. Clears the record and queues its one note for the next tool reply, except for a finished ramp and
+     * for Stop, which are not told. A no-op when no ramp is recorded, so a second cause (a cancel, then a closing page)
+     * never adds a second line.
+     */
+    dropGlide(reason, bpm) {
+        if (this.glide === null)
+            return;
+        this.glide = null;
+        if (reason === 'finished' || reason === 'stop')
+            return;
+        this.glideNotes.push(glideEndedLine(reason, bpm));
+    }
+    /**
+     * Whether a change other than this one still in flight answers the same request. A newer change that
+     * names the request carries its answer on, so the request must not end as replaced while that answer is
+     * still coming: the newer change settles it (applied, failed or replaced in its turn).
+     */
+    answeringStillCarried(answering, exceptEvaluateId) {
+        for (const [evaluateId, entry] of this.pending) {
+            if (entry.kind === 'evaluate' && evaluateId !== exceptEvaluateId) {
+                if (this.recordIntents.get(evaluateId)?.answering === answering)
+                    return true;
+            }
+        }
+        return false;
     }
     /**
      * Keeps the change the page accepted for its line. One at most (last wins): a change that is
@@ -348,16 +465,32 @@ export class Session {
      * itself (takeover-canceled 'replaced').
      */
     keepWaitingChange(change) {
-        if (this.pendingChange !== null && this.pendingChange.id !== change.id) {
-            console.error(`[moontide] A waiting change (${this.pendingChange.id}) was replaced by request ${change.id} without a cancel message`);
+        const replaced = this.pendingChange;
+        if (replaced !== null && replaced.id !== change.id) {
+            console.error(`[moontide] A waiting change (${replaced.id}) was replaced by request ${change.id} without a cancel message`);
+            // The same rule as a cancel message: the request ends as replaced unless the new change answers it too.
+            const answering = replaced.intent?.answering;
+            if (answering !== undefined && answering !== change.intent?.answering) {
+                this.requests.replaced(answering);
+            }
         }
         this.pendingChange = change;
+        if (change.intent?.answering !== undefined) {
+            this.requests.line(change.intent.answering, change.at === 'phrase' ? 'phrase' : 'bar');
+        }
     }
     /**
      * BPM: rounds the tempo of a reply to one decimal and says whether it differs from the last tempo a reply
      * stated. A reply without a tempo leaves the last told tempo alone.
      */
-    noteTempo(bpm) {
+    noteTempo(bpm, glide) {
+        // A reply that states a ramp says the ramp, not a tempo change: the ramp's target is the tempo told from here on, so the
+        // next reply never announces it as a change when the ramp gets there.
+        if (glide !== undefined) {
+            const target = Math.round(glide.toBpm * 10) / 10;
+            this.lastToldBpm = target;
+            return { bpm: bpm === undefined ? null : Math.round(bpm * 10) / 10, tempoChanged: false };
+        }
         if (bpm === undefined)
             return { bpm: null, tempoChanged: false };
         const rounded = Math.round(bpm * 10) / 10;
@@ -383,6 +516,7 @@ export class Session {
         // A change that waits does not survive a page taking the role: the page that held its gate is
         // gone or replays its code, so Claude is told once (the line is queued once however many causes meet).
         this.dropWaitingChange('page');
+        this.dropGlide('page');
         this.supersededPages.delete(conn);
         if (previous !== null && previous !== conn) {
             this.supersededPages.add(previous);
@@ -437,6 +571,7 @@ export class Session {
         if (this.activePage === conn) {
             this.activePage = null;
             this.dropWaitingChange('page');
+            this.dropGlide('page');
             this.midi.clear();
             this.lastMidiFacts = null;
             // A superseded tab says "playing in another tab": tell it that no tab plays any more, or it
@@ -545,6 +680,10 @@ export class Session {
             this.handleRuntimeError(conn, msg);
             return;
         }
+        if (msg.type === 'structure-note') {
+            this.handleStructureNote(conn, msg);
+            return;
+        }
         if (msg.type === 'stop-result') {
             this.handleStopResult(conn, msg);
             return;
@@ -557,6 +696,10 @@ export class Session {
             this.handleTakeoverCanceled(conn, msg);
             return;
         }
+        if (msg.type === 'glide-ended') {
+            this.handleGlideEnded(conn, msg);
+            return;
+        }
         if (msg.type === 'user-stopped') {
             this.handleUserStopped(conn);
             return;
@@ -598,6 +741,13 @@ export class Session {
             this.ask.handleAsk(conn, msg);
             return;
         }
+        if (msg.type === 'ask-board-request') {
+            const requests = this.requests.snapshotFor(conn);
+            // The board told the page where each request stands; the hand-over messages that follow reach it too.
+            this.ask.adoptOrigin(conn, requests.map((row) => row.id));
+            this.sendToPage(conn, { type: 'ask-board', requests }, 'the request board');
+            return;
+        }
         if (msg.type === 'history-request') {
             this.handleHistoryRequest(conn);
             return;
@@ -1140,6 +1290,8 @@ export class Session {
             return;
         }
         this.stopped = true;
+        // Stop ends a ramp too; it is the user's own act, so Claude is not told.
+        this.dropGlide('stop');
         // A stop the page reports ends a wait too; the page's takeover-canceled for the same id (sent
         // just before) already queued the line, and a second cause adds nothing.
         this.dropWaitingChange('stop');
@@ -1161,6 +1313,7 @@ export class Session {
                     cycle: msg.pending.cycle,
                     at: lateIntent?.at ?? 'bar',
                     intent: lateIntent,
+                    ...(msg.glide?.state === 'at-line' ? { glide: msg.glide } : {}),
                 });
                 console.error(`[moontide] Late pending confirmation kept for request ${msg.id}`);
             }
@@ -1183,6 +1336,15 @@ export class Session {
                 this.handFailureLine = null;
                 const lateVersionId = this.recordConfirmed(conn, msg.code, lateOrigin, lateIntent);
                 this.rememberVersion(msg.id, lateVersionId);
+                // A reply whose audio is stopped records no ramp: Stop ends every ramp, so none runs.
+                // An at-line report on a reply with no pending line is a waiting change that already took over: its ramp started at its line.
+                if ((msg.glide?.state === 'started' || msg.glide?.state === 'at-line') && msg.audio !== 'stopped') {
+                    this.glide = { toBpm: msg.glide.toBpm };
+                }
+                // This branch does not pass through confirmSuccess, so it tells the page itself.
+                if (lateIntent?.answering !== undefined) {
+                    this.requests.applied(lateIntent.answering, lateVersionId);
+                }
                 console.error(`[moontide] Late confirmation stored for request ${msg.id}`);
             }
             else if (msg.ok) {
@@ -1216,6 +1378,7 @@ export class Session {
                         cycle: msg.pending.cycle,
                         at: intent?.at ?? 'bar',
                         intent,
+                        ...(msg.glide?.state === 'at-line' ? { glide: msg.glide } : {}),
                     });
                     entry.resolve({
                         code: msg.code,
@@ -1224,17 +1387,25 @@ export class Session {
                         replacedHandEdit: false,
                         versionId: null,
                         pending: msg.pending,
-                        ...this.noteTempo(msg.bpm),
+                        ...this.noteTempo(msg.bpm, msg.glide),
+                        ...(msg.glide !== undefined ? { glide: msg.glide } : {}),
                     });
                 }
                 else {
                     const { replacedHandEdit, versionId } = this.confirmSuccess(conn, msg.id, msg.code, msg.audio, intent);
+                    // A reply whose audio is stopped states and records no ramp: Stop ends every ramp, so none runs.
+                    const glide = msg.audio === 'stopped' ? undefined : msg.glide;
+                    // A ramp this change started is the one the server tells about when it ends early; a running report leaves the record.
+                    // An at-line report here is a waiting change that already took over when it was answered: its ramp started at its line.
+                    if (glide?.state === 'started' || glide?.state === 'at-line')
+                        this.glide = { toBpm: glide.toBpm };
                     entry.resolve({
                         code: msg.code,
                         audio: msg.audio,
                         replacedHandEdit,
                         versionId,
-                        ...this.noteTempo(msg.bpm),
+                        ...this.noteTempo(msg.bpm, glide),
+                        ...(glide !== undefined ? { glide } : {}),
                     });
                 }
             }
@@ -1249,7 +1420,24 @@ export class Session {
             }
         }
         else {
+            const failedIntent = this.recordIntents.get(msg.id);
             this.recordIntents.delete(msg.id);
+            const failedFor = failedIntent?.answering;
+            // The same rule as a replaced change: an earlier change for the same request that still waits for
+            // its line, or is still on its way, carries the answer on and settles the request in its turn.
+            // A ramp the page refused was refused whole and nothing changed, so the request stays open for the change Claude sends
+            // next (without glideBars), which can still answer it.
+            if (msg.glideRefused !== true &&
+                failedFor !== undefined &&
+                this.pendingChange?.intent?.answering !== failedFor &&
+                !this.answeringStillCarried(failedFor, msg.id)) {
+                this.requests.failed(failedFor, cleanErrorDetail(msg.error));
+            }
+            if (msg.glideRefused === true) {
+                // The page's own refusal text, whole: it already says that nothing was changed, so no evaluation-failure tail is added.
+                entry.reject(new Error(cleanRefusal(msg.error)));
+                return;
+            }
             const tail = this.code === '' ? NOTHING_PLAYING_TAIL : this.stopped ? STILL_STOPPED_TAIL : STILL_PLAYING_TAIL;
             entry.reject(new Error(evalFailedMessage(msg.error, msg.line, tail)));
         }
@@ -1274,12 +1462,17 @@ export class Session {
         this.handFailureLine = null;
         const versionId = this.recordConfirmed(conn, code, origin, intent);
         this.rememberVersion(id, versionId);
+        if (intent?.answering !== undefined) {
+            this.requests.applied(intent.answering, versionId);
+        }
         return { replacedHandEdit, versionId };
     }
     /**
      * The page says the waiting change is audible now. Accepted only from the active page and only for
      * the id of the change that waits; anything else is one stderr line and changes nothing. The message carries
-     * only the id, so the recorded code is the one stored from the pending reply.
+     * the id and, when the ramp the waiting change started at its line still runs, `glideRuns: true`; the recorded code
+     * is the one stored from the pending reply, and the ramp record is set from `glideRuns` (or cleared without it) for a
+     * change that asked for a ramp.
      */
     handleTakeover(conn, msg) {
         if (conn !== this.activePage) {
@@ -1293,6 +1486,11 @@ export class Session {
         }
         this.pendingChange = null;
         const { replacedHandEdit } = this.confirmSuccess(conn, waiting.id, waiting.code, 'playing', waiting.intent);
+        // A change that asked for a ramp at its line ended any older ramp there. Its own ramp is the recorded ramp from here on only
+        // when the page says it still runs; otherwise none runs (nothing to ramp between, or it already ended) and the record is
+        // cleared with no line. A change replaced or canceled before its line never gets here.
+        if (waiting.glide !== undefined)
+            this.glide = msg.glideRuns === true ? { toBpm: waiting.glide.toBpm } : null;
         // An edit that carried a hand edit replaced nothing of it: the Mixer and Parts refuse while a change
         // waits and a hand evaluation cancels the wait, so the code playing at this takeover is still the hand-edited
         // text the edit was built on, and the note would be false.
@@ -1317,6 +1515,17 @@ export class Session {
         }
         this.dropWaitingChange(msg.reason);
     }
+    /**
+     * The page says its tempo ramp ended on its own. Only the active page is trusted; the numbers are bounded by the
+     * protocol schema and the wording is the server's.
+     */
+    handleGlideEnded(conn, msg) {
+        if (conn !== this.activePage) {
+            console.error('[moontide] Ignoring glide-ended from a non-active page');
+            return;
+        }
+        this.dropGlide(msg.reason, msg.bpm === undefined ? undefined : Math.round(msg.bpm * 10) / 10);
+    }
     /**
      * The editedByHand flag after a confirmed evaluation: Claude's code makes the stored code
      * Claude's again (false). A change made from the page (origin 'page') is the user's:
@@ -1484,6 +1693,7 @@ export class Session {
             if (conn === this.activePage) {
                 // A late stop confirmation still reflects reality — the page did stop.
                 this.stopped = true;
+                this.dropGlide('stop');
                 this.dropWaitingChange('stop');
                 console.error(`[moontide] Late stop confirmation stored for request ${msg.id}`);
             }
@@ -1501,6 +1711,7 @@ export class Session {
         this.pending.delete(msg.id);
         if (conn === this.activePage) {
             this.stopped = true;
+            this.dropGlide('stop');
             this.dropWaitingChange('stop');
             entry.resolve(undefined);
         }
@@ -1549,6 +1760,26 @@ export class Session {
             this.droppedRuntimeErrorOverflowCount++;
         }
     }
+    /**
+     * What the page read from the song structure of the code that plays. Accepted only from the active page, like a
+     * runtime error. The latest note replaces the earlier one (an empty list clears it); every line is cleaned here and
+     * the drain puts a fixed lead and the version in front of it. A note is a fact about the structure, never a runtime
+     * error, so it never changes the status of a reply.
+     */
+    handleStructureNote(conn, msg) {
+        if (conn !== this.activePage) {
+            console.error('[moontide] Ignoring a structure note from a non-active page');
+            return;
+        }
+        const lines = [];
+        for (const raw of msg.lines) {
+            const cleaned = cleanStructureLine(raw);
+            if (cleaned !== null) {
+                lines.push(cleaned);
+            }
+        }
+        this.structureNote = { tag: msg.evaluateId ?? null, lines };
+    }
     /**
      * The MIDI facts of the page. Used only from the active page, like a runtime error:
      * a stale page's facts do not describe what is playing.
@@ -1811,6 +2042,14 @@ export class Session {
                 ? 'Note: 1 more distinct runtime error was not shown.'
                 : `Note: ${n} more distinct runtime errors were not shown.`);
         }
+        if (this.structureNote !== null) {
+            const { tag, lines: noteLines } = this.structureNote;
+            const versionId = tag !== null ? this.versionByEvaluateId.get(tag) ?? null : null;
+            for (const line of noteLines) {
+                lines.push(structureNoteLine(line, versionId));
+            }
+            this.structureNote = null;
+        }
         this.runtimeErrors.clear();
         this.droppedRuntimeErrors.clear();
         this.droppedRuntimeErrorOverflowCount = 0;
@@ -1827,6 +2066,9 @@ export class Session {
         // A change that waited for a line and did not take over, told once.
         lines.push(...this.takeoverNotes);
         this.takeoverNotes.length = 0;
+        // A tempo ramp that ended early, told once.
+        lines.push(...this.glideNotes);
+        this.glideNotes.length = 0;
         // The build line comes before the setup file lines, then the MIDI lines, then the ask
         // lines (the arming line stays last). Runtime error lines and the history notes come earlier.
         lines.push(...this.buildNotes);
@@ -1896,6 +2138,8 @@ export class Session {
             force: false,
             at: options?.at,
             phraseCycles: options?.phraseCycles,
+            glideBars: options?.glideBars,
+            answering: options?.answering,
         });
     }
     /**
@@ -1954,6 +2198,8 @@ export class Session {
             force: false,
             at: options?.at,
             phraseCycles: options?.phraseCycles,
+            glideBars: options?.glideBars,
+            answering: options?.answering,
             carriesHandEdit,
         }).then((outcome) => ({ outcome, code: result.code, ranges: result.ranges, base, carriesHandEdit }));
     }
@@ -2001,6 +2247,7 @@ export class Session {
             label: restoredLabel(id),
             restoredFrom: id,
             origin: options?.origin,
+            answering: options?.answering,
             force: true,
         });
     }
@@ -2020,6 +2267,8 @@ export class Session {
                 message.at = intent.at;
             if (intent.phraseCycles !== undefined)
                 message.phraseCycles = intent.phraseCycles;
+            if (intent.glideBars !== undefined)
+                message.glideBars = intent.glideBars;
             return message;
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moontide-mcp",
-  "version": "2.0.2",
+  "version": "2.2.0",
   "mcpName": "io.github.konni-arcadia/moontide",
   "description": "Claude steers live music by writing Strudel code played in a browser page",
   "keywords": [