moontide-mcp 2.0.2 → 2.2.0

package/dist/protocol.js

@@ -36,6 +36,12 @@ export const MAX_RIG_DRUM_NAME = 40;
  */
 export const MIN_PHRASE_CYCLES = 2;
 export const MAX_PHRASE_CYCLES = 64;
+/**
+ * The shortest and longest tempo ramp, in whole bars (one bar is one cycle), that set_code and edit_code accept with
+ * glideBars. page/tempo-glide.js mirrors both by hand (test/protocol.test.js checks both sides).
+ */
+export const MIN_GLIDE_BARS = 1;
+export const MAX_GLIDE_BARS = 64;
 /** The largest tempo the page may report in BPM; a bigger number is not music and the schema refuses it. */
 export const MAX_REPORTED_BPM = 100000;
 /** The two scripts the page loads from unpkg.com; a load-failed report names the ones that did not load. */
@@ -58,6 +64,9 @@ export const MAX_ASK_CONTEXT_LENGTH = 200;
 // The most notes one moment carries; the rest are counted in `more`. page/timeline.js mirrors it by
 // hand (test/ask.test.js checks both sides).
 export const MAX_MOMENT_NOTES = 32;
+// The most cycles one range may cover: the cycles of one Timeline page. page/timeline.js mirrors it by hand
+// (test/ask.test.js checks both sides).
+export const MAX_RANGE_CYCLES = 32;
 // The most bytes (UTF-8) one request line may have, the whole line Claude's Monitor reads: the prefix and the
 // JSON with the text, the context, the chip and the moment. Text of 2000 characters in a script that takes 3
 // bytes per character still fits with the rest of the line, but not every text of MAX_ASK_TEXT_LENGTH characters
@@ -70,6 +79,9 @@ export const MAX_REQUEST_LINE_BYTES = 8192;
 export const MOMENT_BEATS = 4;
 // The most characters in a request id (the page makes the id up so answers can be matched).
 export const MAX_ASK_ID_LENGTH = 64;
+// The longest sentence Claude can close a page request with. The page shows it with an ellipsis in a
+// row and whole in the detail.
+export const MAX_ANSWER_TEXT_LENGTH = 200;
 // The kinds of thing a right-click can point at. The Jam view is
 // the source of 'note' (a pitch class with its role in the scale) and 'warning' (a chord that leaves it).
 export const ASK_CONTEXT_KINDS = [
@@ -89,7 +101,15 @@ export const ASK_CONTEXT_KINDS = [
     'warning',
     'instrument',
     'error',
+    'cell',
+    'group',
+    'range',
 ];
+// The kinds of gesture a request can carry: what the user did to a note of the Timeline that the page could not
+// apply itself. page/ask.js mirrors the list by hand (test/ask.test.js checks both sides).
+export const GESTURE_KINDS = ['pitch', 'rest', 'velocity', 'range'];
+// The most semitones one gesture may carry, up or down: the span of the note range.
+export const MAX_GESTURE_SEMITONES = 127;
 const audioStateSchema = z.enum(['playing', 'waiting-for-click', 'stopped']);
 const midiName = z.string().max(MAX_MIDI_NAME_LENGTH);
 const midiChannel = z.number().int().min(1).max(16);
@@ -114,6 +134,10 @@ export const askMomentNoteShape = {
     state: z.enum(['sounding', 'starts']),
 };
 const askMomentNote = z.object(askMomentNoteShape);
+// A note of a range is a moment note without its state; derived from the moment note, so the two cannot drift apart.
+// test/ask.test.js pins the keys equal to the ones page/ask.js's RANGE_NOTE_FIELDS may copy.
+const askRangeNote = askMomentNote.omit({ state: true });
+export const askRangeNoteShape = askRangeNote.shape;
 // More notes, a longer string or a number out of range is rejected, never trimmed.
 const askMomentSchema = z.object({
     cycle: z.number().int().nonnegative(),
@@ -123,6 +147,27 @@ const askMomentSchema = z.object({
     notes: z.array(askMomentNote).max(MAX_MOMENT_NOTES),
     more: z.number().int().nonnegative(),
 });
+// A closed union: a kind the page does not know, a direction or an amount out of bounds is rejected, never
+// trimmed. z.object drops a key it does not name, so every key of every kind is named here.
+export const askGestureSchema = z.discriminatedUnion('kind', [
+    z.object({
+        kind: z.literal('pitch'),
+        semitones: z
+            .number()
+            .int()
+            .min(-MAX_GESTURE_SEMITONES)
+            .max(MAX_GESTURE_SEMITONES)
+            .refine((semitones) => semitones !== 0, { message: 'a pitch gesture moves the note' }),
+    }),
+    z.object({ kind: z.literal('rest') }),
+    z.object({ kind: z.literal('velocity'), direction: z.enum(['softer', 'louder']) }),
+    z.object({
+        kind: z.literal('range'),
+        version: z.number().int().positive().nullable(),
+        notes: z.array(askRangeNote).max(MAX_MOMENT_NOTES),
+        more: z.number().int().nonnegative(),
+    }),
+]);
 const askContextSchema = z.discriminatedUnion('kind', [
     z.object({ kind: z.literal('session') }),
     z.object({ kind: z.literal('version'), id: z.number().int().positive(), label: askName.optional() }),
@@ -151,6 +196,23 @@ const askContextSchema = z.discriminatedUnion('kind', [
     }),
     z.object({ kind: z.literal('part'), name: askName, owner: askName.optional() }),
     z.object({ kind: z.literal('lane'), track: askName, cycle: z.number().int().nonnegative().optional() }),
+    // Whole cycles of one lane, `to` at least `from` and less than MAX_RANGE_CYCLES cycles after it; a name or a number out of
+    // bounds is rejected, never trimmed.
+    z
+        .object({
+        kind: z.literal('range'),
+        track: askName,
+        from: z.number().int().nonnegative(),
+        to: z.number().int().nonnegative(),
+        sections: z.array(askName).min(1).max(MAX_RANGE_CYCLES).optional(),
+        moreSections: z.number().int().min(1).max(MAX_RANGE_CYCLES - 1).optional(),
+    })
+        .refine((range) => range.to >= range.from && range.to - range.from < MAX_RANGE_CYCLES, {
+        message: `a range covers 1 to ${MAX_RANGE_CYCLES} whole cycles, to not before from`,
+    })
+        .refine((range) => range.moreSections === undefined || range.sections !== undefined, {
+        message: 'moreSections comes only with sections',
+    }),
     // `note` is a pitch class name, never an octave, string or fret; `role` and `scale` are both present or
     // both absent (the page enforces that), absent while the scale is not clear.
     z.object({ kind: z.literal('note'), note: askName, role: askNoteRole.optional(), scale: askName.optional() }),
@@ -164,13 +226,56 @@ const askContextSchema = z.discriminatedUnion('kind', [
         seconds: z.number().int().nonnegative(),
         scale: askName,
     }),
+    // A cell holds a variation or is a rest, never both and never neither; a rest has no fit; the notes outside the scale
+    // come only with a fit of does-not-fit. The page sends nothing else, and the server rejects the rest, never trims it.
+    z
+        .object({
+        kind: z.literal('cell'),
+        section: askName,
+        track: askName,
+        variation: askName.optional(),
+        rest: z.literal(true).optional(),
+        fit: z.enum(['fits', 'does-not-fit', 'cannot-check']).optional(),
+        outside: askName.optional(),
+    })
+        .refine((cell) => (cell.variation === undefined) !== (cell.rest === undefined), {
+        message: 'a cell has a variation or is a rest, not both and not neither',
+    })
+        .refine((cell) => !(cell.rest !== undefined && cell.fit !== undefined), { message: 'a rest cell has no fit' })
+        .refine((cell) => cell.outside === undefined || cell.fit === 'does-not-fit', {
+        message: 'outside notes come only with a fit of does-not-fit',
+    }),
+    z.object({ kind: z.literal('group'), name: askName, parent: askName.optional() }),
 ]);
+/** A structure note holds at most this many lines, each at most this many characters. */
+export const MAX_STRUCTURE_NOTE_LINES = 3;
+export const MAX_STRUCTURE_NOTE_LINE = 600;
 /** The longest wait the server accepts in a pending reply: a day. */
 export const MAX_PENDING_SECONDS = 86400;
 const pendingChangeSchema = z.object({
     cycle: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
     seconds: z.number().finite().nonnegative().max(MAX_PENDING_SECONDS),
 });
+const glideBpmSchema = z.number().finite().positive().max(MAX_REPORTED_BPM);
+// A discriminated union on `state` so a later state is one more member.
+const glideReportSchema = z.discriminatedUnion('state', [
+    z.object({
+        state: z.literal('started'),
+        fromBpm: glideBpmSchema,
+        toBpm: glideBpmSchema,
+        bars: z.number().int().min(MIN_GLIDE_BARS).max(MAX_GLIDE_BARS),
+    }),
+    z.object({
+        state: z.literal('at-line'),
+        toBpm: glideBpmSchema,
+        bars: z.number().int().min(MIN_GLIDE_BARS).max(MAX_GLIDE_BARS),
+    }),
+    z.object({
+        state: z.literal('running'),
+        nowBpm: glideBpmSchema,
+        toBpm: glideBpmSchema,
+    }),
+]);
 // A plain z.union (not discriminatedUnion): 'runtime-error' has no 'ok' field, so the
 // single-key discriminant used for the two 'evaluated' variants can't cover it.
 const pageMessageSchema = z.union([
@@ -182,10 +287,12 @@ const pageMessageSchema = z.union([
         audio: audioStateSchema,
         pending: pendingChangeSchema.optional(),
         bpm: z.number().finite().positive().max(MAX_REPORTED_BPM).optional(),
+        glide: glideReportSchema.optional(),
     }),
     z.object({
         type: z.literal('takeover'),
         id: z.string().min(1).max(64),
+        glideRuns: z.literal(true).optional(),
     }),
     z.object({
         type: z.literal('takeover-canceled'),
@@ -199,12 +306,23 @@ const pageMessageSchema = z.union([
         code: z.string(),
         error: z.string(),
         line: z.number().int().positive().optional(),
+        glideRefused: z.literal(true).optional(),
+    }),
+    z.object({
+        type: z.literal('glide-ended'),
+        reason: z.enum(['finished', 'other-tempo', 'no-tempo', 'error']),
+        bpm: glideBpmSchema.optional(),
     }),
     z.object({
         type: z.literal('runtime-error'),
         message: z.string(),
         evaluateId: z.string().min(1).max(64).optional(),
     }),
+    z.object({
+        type: z.literal('structure-note'),
+        lines: z.array(z.string().max(MAX_STRUCTURE_NOTE_LINE)).max(MAX_STRUCTURE_NOTE_LINES),
+        evaluateId: z.string().min(1).max(64).optional(),
+    }),
     z.object({
         type: z.literal('stop-result'),
         id: z.string(),
@@ -240,6 +358,7 @@ const pageMessageSchema = z.union([
         label: z.string().min(1).max(MAX_MIXER_LABEL_LENGTH),
     }),
     z.object({ type: z.literal('history-request') }),
+    z.object({ type: z.literal('ask-board-request') }),
     z.object({ type: z.literal('data-folder-request') }),
     z.object({ type: z.literal('take-over') }),
     z.object({ type: z.literal('history-restore'), id: z.number().int().positive() }),
@@ -263,9 +382,18 @@ const pageMessageSchema = z.union([
         context: askContextSchema,
         chip: z.string().min(1).max(MAX_ASK_CONTEXT_LENGTH),
         current: z.number().int().positive().nullable(),
-        // z.object drops a key it does not name, so the moment must be named here to reach Claude.
+        // z.object drops a key it does not name, so the moment and the gesture must be named here to reach Claude.
         moment: askMomentSchema.optional(),
-    }),
+        gesture: askGestureSchema.optional(),
+    })
+        // A gesture about one note of a lane rides only on a lane context that carries a moment; the range gesture and the range
+        // context come together and carry no moment (the notes of the range are in the gesture).
+        .refine((ask) => {
+        const isRange = ask.gesture?.kind === 'range';
+        if (isRange || ask.context.kind === 'range')
+            return isRange && ask.context.kind === 'range' && ask.moment === undefined;
+        return ask.gesture === undefined || (ask.context.kind === 'lane' && ask.moment !== undefined);
+    }, { message: 'a gesture needs a lane context and a moment, and a range gesture goes only with a range context' }),
     z.object({
         type: z.literal('midi-state'),
         access: z.enum(['idle', 'pending', 'enabled', 'denied', 'unsupported', 'failed']),

package/dist/reference.js

@@ -53,6 +53,12 @@ export const REFERENCE_TOPICS = [
         title: 'Transitions',
         summary: 'how one change can unfold over several cycles and keep running across later changes with .timeline(id): sweeps, fades, parts that enter later, sections and crossfades',
     },
+    {
+        id: 'structure',
+        file: 'structure.md',
+        title: 'Song structure',
+        summary: 'the song declaration at the top of a piece: sections and lengths, a variation or a rest per track and section, nested groups, harmony per piece and per section, and the play() helper',
+    },
     {
         id: 'midi',
         file: 'midi.md',
@@ -100,3 +106,19 @@ export function referenceToolDescription() {
         `facts about what exists and how to write it, not what to choose. Topics: ${ids}. Call it without a topic for ` +
         'the index. Strudel is JavaScript, not TidalCycles: read tidal-differences before writing Strudel from Tidal habits.');
 }
+const FIRST_JS_BLOCK_RE = /```js\n([\s\S]*?)\n```/;
+/**
+ * The template get_code shows when nothing plays yet: the body of the first js block of the structure topic, a
+ * complete song structure to start a new piece from. The block is read at call time, so the topic and the template
+ * cannot drift apart. A missing block, or a block that declares no song, throws: an empty reply would hide the
+ * mistake from Claude.
+ */
+export function structureTemplateText(dir = referenceDir()) {
+    const topic = readReferenceTopic('structure', dir);
+    const match = FIRST_JS_BLOCK_RE.exec(topic);
+    const body = match?.[1];
+    if (body === undefined || !/^const song\b/m.test(body)) {
+        throw new Error('Moontide: the structure topic has no template block (its first js block must hold const song).');
+    }
+    return body;
+}

package/dist/request-status.js

@@ -0,0 +1,221 @@
+// The request status board: what became of each request a page sent to Claude.
+//
+// The board holds one row per request the page sent, keyed by the id the page made up: the page that
+// sent it, its state and the start of the text and the chip, kept in memory only so a reloaded page can
+// show what it asked. Nothing is ever written to disk and the board holds at most MAX_BOARD_REQUESTS
+// rows (the oldest finished row goes first, an open one only when every row is open). A state only
+// moves forward: a repeat, a step back and any change after a final state are ignored, so the page is
+// never told the same thing twice and never told something that undoes what it was told. A state
+// reaches only the page that sent the request; once that page has gone the row keeps its state and
+// nothing is sent.
+//
+// The page already learns "sent", "waiting" and "received" from the ask-result and ask-received
+// messages. The board adds the states that come later and sends them as ask-status.
+import { MAX_ASK_CONTEXT_LENGTH } from './protocol.js';
+/** How many requests the board keeps; the oldest finished row is dropped first. */
+export const MAX_BOARD_REQUESTS = 50;
+// In the order a request moves through them. page/request-status.js mirrors this list by hand.
+export const REQUEST_STATES = [
+    'sent',
+    'waiting',
+    'received',
+    'started',
+    'line',
+    'applied',
+    'failed',
+    'replaced',
+    'canceled',
+    'answered',
+    'declined',
+];
+/** A request in one of these is finished: nothing follows it. */
+export const FINAL_REQUEST_STATES = [
+    'applied',
+    'failed',
+    'replaced',
+    'canceled',
+    'answered',
+    'declined',
+];
+/** Said when a request is closed by its id and the id is not an open request. */
+export const NOT_OPEN_REQUEST_MESSAGE = 'No open page request has this id: it is unknown or already closed. Nothing changed in the page.';
+// Whitespace, C0 and C1 control characters, the line and paragraph separators and the bidirectional
+// override and isolate characters: none of them belongs in a sentence the page shows to the user.
+const ANSWER_NOISE = /[\s\u0000-\u001F\u007F-\u009F\u2028\u2029\u202A-\u202E\u2066-\u2069]+/gu;
+/** The sentence Claude closes a request with, as the page shows it: each run of noise becomes one space. */
+export function cleanAnswerText(text) {
+    return text.replace(ANSWER_NOISE, ' ').trim();
+}
+/** Where a state stands in the order: 0 to 4 for sent to line, 5 for every final state. */
+export function requestRank(state) {
+    if (FINAL_REQUEST_STATES.includes(state)) {
+        return 5;
+    }
+    return REQUEST_STATES.indexOf(state);
+}
+/** The start of a request text: at most MAX_ASK_CONTEXT_LENGTH code points, an ellipsis when it was cut. */
+function textStart(text) {
+    const points = Array.from(text);
+    return points.length <= MAX_ASK_CONTEXT_LENGTH ? text : `${points.slice(0, MAX_ASK_CONTEXT_LENGTH).join('')}\u2026`;
+}
+export class RequestStatusBoard {
+    send;
+    max;
+    now;
+    // Insertion order is arrival order, so the first key is the oldest request.
+    rows = new Map();
+    constructor(options) {
+        this.send = options.send;
+        this.max = options.max ?? MAX_BOARD_REQUESTS;
+        this.now = options.now ?? Date.now;
+    }
+    /** A request was accepted: it is sent to a listener, or queued until a tool reply. */
+    opened(id, origin, options) {
+        // The channel refuses an id the board holds before it gets here, so a row is never silently reset.
+        if (this.rows.has(id)) {
+            throw new Error(`The request id ${JSON.stringify(id)} is already on the request board`);
+        }
+        const at = this.now();
+        this.rows.set(id, {
+            origin,
+            state: options.queued ? 'waiting' : 'sent',
+            text: textStart(options.text),
+            chip: options.chip,
+            openedAt: at,
+            newsAt: at,
+            last: undefined,
+        });
+        // The bound caps memory, not live work: the oldest finished row goes first. Only when every row is
+        // still open does the oldest open row go.
+        while (this.rows.size > this.max) {
+            let victim;
+            for (const [rowId, row] of this.rows) {
+                if (FINAL_REQUEST_STATES.includes(row.state)) {
+                    victim = rowId;
+                    break;
+                }
+            }
+            victim ??= this.rows.keys().next().value;
+            if (victim === undefined)
+                break;
+            this.rows.delete(victim);
+        }
+    }
+    /** A request that was sent to a listener went back to the queue. */
+    waiting(id) {
+        this.advance(id, 'waiting');
+    }
+    /** Requests were handed to Claude, by a listener or in a tool reply. */
+    delivered(ids) {
+        for (const id of ids) {
+            this.advance(id, 'received');
+        }
+    }
+    /**
+     * A Moontide tool call began. Every request already handed to Claude is now being worked on: Claude
+     * made a call after the request arrived. A request handed over by this very call is still waiting to
+     * be marked, because the mark comes before the reply hands it over.
+     */
+    noteToolCall() {
+        for (const [id, row] of this.rows) {
+            if (row.state === 'received') {
+                this.advance(id, 'started', { type: 'ask-status', id, state: 'started' });
+            }
+        }
+    }
+    /** On the board, open or finished. */
+    has(id) {
+        return this.rows.has(id);
+    }
+    /** On the board and not finished. */
+    isOpen(id) {
+        const row = this.rows.get(id);
+        return row !== undefined && !FINAL_REQUEST_STATES.includes(row.state);
+    }
+    /** The change that answers this request is playing, as the history version it was recorded as. */
+    applied(id, version) {
+        this.advance(id, 'applied', { type: 'ask-status', id, state: 'applied', version });
+    }
+    /** A change that answers this request waits for its bar or phrase line. */
+    line(id, at) {
+        this.advance(id, 'line', { type: 'ask-status', id, state: 'line', at });
+    }
+    /** The change that answers this request could not be evaluated; the reason is already cleaned. */
+    failed(id, reason) {
+        this.advance(id, 'failed', { type: 'ask-status', id, state: 'failed', reason });
+    }
+    /** A newer change took the place of the waiting one that answered this request. */
+    replaced(id) {
+        this.advance(id, 'replaced', { type: 'ask-status', id, state: 'replaced' });
+    }
+    /** Stop, or the page leaving, ended the wait of the change that answered this request. */
+    canceled(id) {
+        this.advance(id, 'canceled', { type: 'ask-status', id, state: 'canceled' });
+    }
+    /**
+     * Claude closed this request in words, without a change to the music. Returns false when the id is not
+     * an open request, so the caller can refuse it loudly.
+     */
+    closed(id, outcome, answer) {
+        if (!this.isOpen(id)) {
+            return false;
+        }
+        this.advance(id, outcome, { type: 'ask-status', id, state: outcome, answer });
+        return true;
+    }
+    /**
+     * What a page that asks for the board is told: the requests whose page has gone and the ones it sent
+     * itself, oldest first. The gone ones now belong to it, so their next states reach it. A request of
+     * another page that is still connected is never listed.
+     */
+    snapshotFor(conn) {
+        const at = this.now();
+        const entries = [];
+        for (const [id, row] of this.rows) {
+            if (row.origin !== null && row.origin !== conn) {
+                continue;
+            }
+            row.origin = conn;
+            const entry = {
+                id,
+                text: row.text,
+                chip: row.chip,
+                state: row.state,
+                openedAgoMs: at - row.openedAt,
+                newsAgoMs: at - row.newsAt,
+            };
+            const last = row.last;
+            if (last?.state === 'applied')
+                entry.version = last.version;
+            if (last?.state === 'line')
+                entry.at = last.at;
+            if (last?.state === 'failed')
+                entry.reason = last.reason;
+            if (last?.state === 'answered' || last?.state === 'declined')
+                entry.answer = last.answer;
+            entries.push(entry);
+        }
+        return entries;
+    }
+    /** The page that sent these requests has gone: the rows keep their state and nothing more is sent. */
+    pageGone(conn) {
+        for (const row of this.rows.values()) {
+            if (row.origin === conn) {
+                row.origin = null;
+            }
+        }
+    }
+    // The one place a state changes. It does nothing for an unknown id or a state that is not higher.
+    advance(id, state, message) {
+        const row = this.rows.get(id);
+        if (row === undefined || requestRank(state) <= requestRank(row.state)) {
+            return;
+        }
+        row.state = state;
+        row.newsAt = this.now();
+        row.last = message;
+        if (message !== undefined && row.origin !== null) {
+            this.send(row.origin, message, 'the request status');
+        }
+    }
+}