@williamzujkowski/live-coding-music-mcp 3.0.0 → 4.1.0

package/dist/services/Transferable.js

@@ -0,0 +1,114 @@
+/**
+ * Copies a value into something Node's IPC can carry (#307).
+ *
+ * Its own module because it has to be testable: `engineChild.ts` imports
+ * `@strudel/*`, which is ESM and will not load under this project's
+ * CommonJS Jest, so nothing in that file can be reached by a unit test.
+ * This has no dependencies at all.
+ */
+import { ValidationError } from '../utils/CategorisedError.js';
+/** Bounds on what may cross the IPC boundary. Both are far above any real result. */
+const MAX_TRANSFER_DEPTH = 32;
+const MAX_TRANSFER_NODES = 2_000_000;
+/**
+ * A result that cannot cross the IPC boundary: too many values, or
+ * nested too deep.
+ *
+ * Extends `ValidationError` because that is what it is — the caller
+ * asked for more than can be returned, and the fix is a narrower query.
+ * It reaches the parent as a reconstructed error, so the category also
+ * travels as an explicit field; see `engineChild`.
+ */
+export class TransferError extends ValidationError {
+}
+/**
+ * Copies a result into something Node's IPC can carry.
+ *
+ * The obvious implementation is `JSON.parse(JSON.stringify(value))`, and
+ * it was, until cross-model review (codex) pointed out what that hands to
+ * a pattern author: **`JSON.stringify` calls `toJSON` on any value that
+ * defines one**. A hap value is pattern-controlled, so
+ * `pure({toJSON: () => { while (true); }})` runs an infinite loop here —
+ * outside the vm's timeout, which has already returned. The parent's
+ * deadline still fires and still kills the child, so the server survives;
+ * what does not survive is the child if the PARENT is killed first, since
+ * a blocked event loop can never process `disconnect`. That is an orphan
+ * process with no owner.
+ *
+ * So: walk it by hand. Never invoke `toJSON`, never invoke a getter on a
+ * prototype, drop what cannot cross, and bound both depth and node count
+ * so a pathological structure fails loudly instead of silently eating the
+ * heap the cap is there to protect.
+ */
+export function toTransferable(value, depth = 0, budget = { nodes: 0 }) {
+    if (++budget.nodes > MAX_TRANSFER_NODES) {
+        throw new TransferError(`Result exceeds the ${String(MAX_TRANSFER_NODES)}-value transfer limit. ` +
+            'Narrow the query or simplify the pattern.');
+    }
+    if (depth > MAX_TRANSFER_DEPTH) {
+        throw new TransferError(`Result nests deeper than ${String(MAX_TRANSFER_DEPTH)} levels and cannot be returned.`);
+    }
+    if (value === null || value === undefined)
+        return null;
+    switch (typeof value) {
+        case 'string':
+        case 'boolean':
+            return value;
+        case 'number':
+            // NaN and Infinity are not JSON; null is what JSON.stringify
+            // produced for them too, so this keeps the wire shape unchanged.
+            return Number.isFinite(value) ? value : null;
+        case 'bigint':
+            return value.toString();
+        // Functions and symbols have no representation on the other side, and
+        // a pattern that produced one was not going to be read anyway.
+        case 'function':
+        case 'symbol':
+            return null;
+        default:
+            break;
+    }
+    if (Array.isArray(value)) {
+        // Index loop, not `.map`. `map` is looked up on the value, and an
+        // array's own `map` property is writable: `const a = []; a.map = ...`
+        // is an ordinary assignment, so calling it would run pattern-supplied
+        // code in the child — the same class of hole as `toJSON`, one method
+        // over. Descriptors for the same reason as below.
+        const out = [];
+        for (let i = 0; i < value.length; i++) {
+            // Charged before the descriptor is even looked at. A hole and a
+            // getter both used to `continue` without recursing, and the node
+            // budget is only charged inside `toTransferable` — so a sparse
+            // array cost nothing against it. `const a = []; a.length = 5e7`
+            // is cheap to build and walked all 50 million holes, pushing a
+            // null for each, past a 2-million-node bound whose whole purpose
+            // is to refuse exactly that (#408).
+            if (++budget.nodes > MAX_TRANSFER_NODES) {
+                throw new TransferError(`Result exceeds the ${String(MAX_TRANSFER_NODES)}-value transfer limit. ` +
+                    'Narrow the query or simplify the pattern.');
+            }
+            const descriptor = Object.getOwnPropertyDescriptor(value, i);
+            if (descriptor === undefined) {
+                out.push(null);
+                continue;
+            }
+            if (descriptor.get !== undefined) {
+                out.push(null);
+                continue;
+            }
+            out.push(toTransferable(descriptor.value, depth + 1, budget));
+        }
+        return out;
+    }
+    // Own enumerable properties only. Inherited accessors are pattern-
+    // controlled code too, and nothing legitimate arrives on a prototype.
+    const out = {};
+    for (const key of Object.keys(value)) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        // A getter is a function call. Skip it rather than run it.
+        if (descriptor === undefined || descriptor.get !== undefined)
+            continue;
+        out[key] = toTransferable(descriptor.value, depth + 1, budget);
+    }
+    return out;
+}

package/dist/services/ai/AiTransport.js

@@ -0,0 +1,56 @@
+/**
+ * AiTransport — the one thing that varies between AI providers.
+ *
+ * `GeminiService` grew ~950 lines around a single provider, but almost
+ * none of it is provider-specific: prompt building, JSON parsing, caching,
+ * rate limiting and the response contracts are all provider-agnostic. The
+ * genuinely variable part is one operation — get a prompt to a model and
+ * get text back.
+ *
+ * So that is the whole seam:
+ *
+ *     type AiTransport = (prompt: string) => Promise<string>
+ *
+ * Two implementations satisfy it: an HTTP call to the Gemini API, and a
+ * subprocess call to a locally authenticated CLI (`agy`, `claude`,
+ * `codex`). Everything above the seam stays exactly where it is, which is
+ * also why the ~80 existing tests keep working.
+ *
+ * ## Why there is no audio attachment parameter
+ *
+ * There was going to be one. It turned out none of the installed CLIs can
+ * actually hear audio — verified by asking each directly:
+ *
+ *   agy    -> "I CANNOT PERCEIVE AUDIO DIRECTLY"
+ *   codex  -> "CANNOT DECODE AUDIO"
+ *   claude -> "CANNOT DECODE AUDIO"
+ *
+ * `agy` is the dangerous one: as an agentic CLI it will sometimes write
+ * and run DSP code, producing exactly correct numbers, and sometimes just
+ * describe plausible-sounding music it never analysed. A differential
+ * probe caught it reporting a clipped file as clean and a clean file as
+ * clipped. Right often enough to trust, wrong unpredictably, is the worst
+ * property an automated feedback loop can have.
+ *
+ * The answer is to not ask a model to hear. We already measure the audio
+ * locally (`AudioAnalyzer` for FFT/tempo/key, `AudioExportService` for
+ * peak/RMS) and send the *numbers* as text. That is deterministic, and it
+ * works with every provider rather than one — so the transport only ever
+ * needs to carry text.
+ *
+ * @module services/ai/AiTransport
+ */
+/** Raised when a transport cannot authenticate. */
+export class AiAuthError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AiAuthError';
+    }
+}
+/** Raised when a transport is rate limited. */
+export class AiRateLimitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AiRateLimitError';
+    }
+}

package/dist/services/ai/AudioMeasurements.js

@@ -0,0 +1,155 @@
+/**
+ * AudioMeasurements — describing audio to a model that cannot hear it.
+ *
+ * The obvious design was to hand a WAV to a multimodal model. That does
+ * not work here: none of the installed CLIs can decode audio. Asked
+ * directly, they say so —
+ *
+ *   agy    -> "I CANNOT PERCEIVE AUDIO DIRECTLY"
+ *   codex  -> "CANNOT DECODE AUDIO"
+ *   claude -> "CANNOT DECODE AUDIO"
+ *
+ * `agy` is the dangerous one. Being agentic, it sometimes writes and runs
+ * DSP code and returns exactly correct figures, and sometimes just
+ * describes plausible music it never analysed. A differential probe
+ * caught it calling a clipped file clean and a clean file clipped. Right
+ * often enough to trust, wrong unpredictably, is the worst possible
+ * property for an automated feedback loop.
+ *
+ * So we do not ask a model to listen. We measure the audio ourselves —
+ * `AudioExportService` already computes peak and RMS while decoding, and
+ * `AudioAnalyzer` computes FFT bands, spectral centroid, tempo and key —
+ * and send the numbers as text.
+ *
+ * That inverts the constraint into an advantage. Measurement is
+ * deterministic and reproducible, the model does the part it is actually
+ * good at (interpretation and musical judgement), and it works with every
+ * provider rather than one.
+ *
+ * @module services/ai/AudioMeasurements
+ */
+/** Converts a linear amplitude to dBFS, the unit mixing engineers use. */
+/**
+ * Amplitude at or below which a capture is treated as silent.
+ *
+ * Not exactly zero: dithering, a DC offset, or a single stray sample
+ * can leave a capture technically non-zero while containing no audio.
+ */
+export const SILENCE_THRESHOLD = 1e-4;
+export function toDbfs(amplitude) {
+    if (amplitude <= 0)
+        return -Infinity;
+    return 20 * Math.log10(amplitude);
+}
+/**
+ * Renders measurements as text a model can reason about.
+ *
+ * Deliberately states units and interpretation rather than dumping raw
+ * numbers: "peak 1.12 (CLIPPING)" gets a useful answer where "peak: 1.12"
+ * invites the model to guess what scale that is on.
+ *
+ * @param m - Locally computed measurements
+ * @returns Human- and model-readable measurement block
+ */
+export function describeMeasurements(m) {
+    const lines = [];
+    lines.push(`- Duration: ${String(Math.round(m.durationMs))} ms`);
+    if (m.sampleRate !== undefined) {
+        lines.push(`- Format: ${String(m.sampleRate)} Hz, ${String(m.channels ?? 2)} channel(s)`);
+    }
+    // Silence first, and loudly.
+    //
+    // A silent capture was described as "Infinity dB of headroom", which
+    // is arithmetically true and useless: toDbfs(0) is -Infinity, and the
+    // verdict ladder had a branch for clipping and one for low headroom
+    // but none for nothing-at-all. buildMeasurementPrompt then wraps this
+    // in "these measurements are accurate — treat them as ground truth"
+    // and asks the model for mood, style and energy. Silence is THE
+    // documented failure mode of this project's headless capture, and the
+    // model was given no signal it had happened (#343).
+    const isSilent = m.peak !== undefined && m.peak <= SILENCE_THRESHOLD
+        && (m.rms === undefined || m.rms <= SILENCE_THRESHOLD);
+    if (isSilent) {
+        lines.push('- SILENT: nothing was recorded. Peak and RMS are both at or below ' +
+            `${String(SILENCE_THRESHOLD)}. Do not infer mood, style or energy from this — ` +
+            'there is no audio to describe. The capture failed, or the pattern was not playing.');
+    }
+    if (m.peak !== undefined) {
+        const db = toDbfs(m.peak);
+        const verdict = m.peak > 1
+            ? 'CLIPPING — above full scale, so the mix is distorting'
+            : m.peak > 0.95
+                ? 'very close to full scale, little headroom'
+                : m.peak <= SILENCE_THRESHOLD
+                    ? 'silence — no signal at all'
+                    : `${(-db).toFixed(1)} dB of headroom`;
+        lines.push(`- Peak: ${m.peak.toFixed(4)} (${db.toFixed(2)} dBFS) — ${verdict}`);
+    }
+    if (m.rms !== undefined) {
+        lines.push(`- RMS: ${m.rms.toFixed(4)} (${toDbfs(m.rms).toFixed(2)} dBFS) — perceived loudness`);
+    }
+    if (m.peak !== undefined && m.rms !== undefined && m.rms > 0) {
+        const crest = toDbfs(m.peak / m.rms);
+        lines.push(`- Crest factor: ${crest.toFixed(1)} dB — ` +
+            (crest < 6 ? 'heavily compressed / dense' : crest > 15 ? 'very dynamic / sparse' : 'moderate dynamics'));
+    }
+    if (m.tempo !== undefined) {
+        lines.push(`- Detected tempo: ${String(Math.round(m.tempo.bpm))} BPM ` +
+            `(confidence ${m.tempo.confidence.toFixed(2)})`);
+    }
+    if (m.key !== undefined) {
+        lines.push(`- Detected key: ${m.key.key} ${m.key.scale} ` +
+            `(confidence ${m.key.confidence.toFixed(2)})`);
+    }
+    if (m.spectrum !== undefined) {
+        const s = m.spectrum;
+        lines.push(`- Spectrum (0-255): bass ${String(Math.round(s.bass))}, ` +
+            `low-mid ${String(Math.round(s.lowMid))}, mid ${String(Math.round(s.mid))}, ` +
+            `high-mid ${String(Math.round(s.highMid))}, treble ${String(Math.round(s.treble))}`);
+        lines.push(`- Spectral centroid: ${String(Math.round(s.centroid))} Hz (${s.brightness})`);
+    }
+    if (m.rhythm !== undefined) {
+        lines.push(`- Rhythm: complexity ${m.rhythm.complexity.toFixed(2)}, ` +
+            `density ${m.rhythm.density.toFixed(2)}, syncopation ${m.rhythm.syncopation.toFixed(2)}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Builds the audio-feedback prompt from measurements plus the pattern.
+ *
+ * The pattern source matters as much as the numbers: it lets the model
+ * connect a measurement to the line that caused it, which is the
+ * difference between "the mix is clipping" and "these three layers sum
+ * above 1.0, lower them".
+ *
+ * @param m - Locally computed measurements
+ * @param pattern - The Strudel source that produced the audio
+ * @param context - Optional intent (style/bpm/key the user was aiming for)
+ * @returns Prompt text for any model
+ */
+export function buildMeasurementPrompt(m, pattern, context) {
+    const parts = [
+        'You are analysing a short recording of a live-coded music performance made with Strudel.',
+        '',
+        'These measurements were computed directly from the audio signal. They are',
+        'accurate — treat them as ground truth rather than re-estimating them.',
+        '',
+        describeMeasurements(m),
+    ];
+    if (pattern !== undefined && pattern.trim().length > 0) {
+        parts.push('', 'The Strudel pattern that produced it:', '```javascript', pattern.trim(), '```');
+    }
+    if (context !== undefined) {
+        const intent = [];
+        if (context.style !== undefined)
+            intent.push(`intended style: ${context.style}`);
+        if (context.bpm !== undefined)
+            intent.push(`intended BPM: ${String(context.bpm)}`);
+        if (context.key !== undefined)
+            intent.push(`intended key: ${context.key}`);
+        if (intent.length > 0)
+            parts.push('', `Intent — ${intent.join(', ')}.`);
+    }
+    parts.push('', 'Respond with ONLY this JSON object and no other text:', '{', '  "mood": "<one word, e.g. energetic, hypnotic, melancholic>",', '  "style": "<musical genre you infer>",', '  "energy": "<low|medium|high>",', '  "suggestions": ["<specific, actionable change>", "<another>", "<another>"],', '  "confidence": <0.0-1.0>', '}', '', 'Ground every suggestion in a measurement or a line of the pattern. If the', 'audio is clipping, say so first and name the layers responsible. Do not', 'claim to have heard timbral detail the measurements do not support.');
+    return parts.join('\n');
+}

package/dist/services/ai/CliTransport.js

@@ -0,0 +1,256 @@
+/**
+ * CliTransport — reaches a model through a locally authenticated CLI.
+ *
+ * Fixes the case where a machine has working AI credentials that
+ * `GeminiService` cannot see (#252). Its auth ladder only understands
+ * `GEMINI_API_KEY`, `~/.gemini/settings.json`, and gcloud ADC — but the
+ * Antigravity CLI (`agy`) keeps credentials elsewhere entirely, so
+ * `ai_assist` reported "Gemini API not configured" while Gemini worked
+ * fine two directories away.
+ *
+ * Each CLI is invoked in print/non-interactive mode. The flags are not
+ * guessable and were established by probing the installed binaries:
+ *
+ *   agy    --print='PROMPT'          (must be the `=` form; a bare
+ *                                     positional gets eaten by --add-dir)
+ *   claude -p 'PROMPT'               (fastest, ~3s)
+ *   codex  exec --sandbox read-only --skip-git-repo-check 'PROMPT'
+ *                                    (reads stdin when given no prompt
+ *                                     argument, so stdin must be closed
+ *                                     or it hangs forever)
+ *
+ * @module services/ai/CliTransport
+ * @nist si-10 "Information input validation"
+ */
+import { spawn } from 'node:child_process';
+import { accessSync, constants, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { AiAuthError } from './AiTransport.js';
+/** Default budget for a CLI call. They are slower than an HTTP request. */
+export const CLI_TIMEOUT_MS = 120_000;
+/** Cap on captured output, so a runaway CLI cannot exhaust memory. */
+export const CLI_MAX_BUFFER = 8 * 1024 * 1024;
+/** Time allowed for buffered output to drain after the child exits. */
+export const DRAIN_GRACE_MS = 50;
+/**
+ * Environment handed to the CLI.
+ *
+ * These are agentic CLIs with filesystem and tool access, and the prompt
+ * carries pattern text that may have come from a stored file or an
+ * imported MIDI. Passing the full parent environment would hand any
+ * provider credential in it to a different vendor's agent, so the child
+ * gets only what it needs to find its own config.
+ */
+function childEnv() {
+    const keep = ['PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'LANG', 'LC_ALL', 'TERM', 'TMPDIR', 'XDG_CONFIG_HOME', 'XDG_CACHE_HOME'];
+    const env = {};
+    for (const key of keep) {
+        const value = process.env[key];
+        if (value !== undefined)
+            env[key] = value;
+    }
+    return env;
+}
+/**
+ * The CLIs this server knows how to drive, in preference order.
+ *
+ * Order is by measured latency and output cleanliness: claude ~3s with
+ * the tidiest output, codex ~5s, agy ~2.4s bare but slower with files.
+ * `gemini` is deliberately absent — its free tier was retired and it
+ * fails with `IneligibleTierError` before reaching a model, so listing it
+ * would only produce confusing failures.
+ */
+export const KNOWN_CLIS = [
+    {
+        bin: 'claude',
+        label: 'Claude CLI',
+        // The prompt must precede any variadic flag: --disallowedTools and
+        // friends will swallow a trailing positional and tokenize it into
+        // bogus deny rules.
+        args: prompt => ['-p', prompt],
+    },
+    {
+        bin: 'agy',
+        label: 'Antigravity CLI',
+        // `--print=` rather than `--print `: the space form lets a following
+        // flag be taken as the prompt.
+        args: prompt => [`--print=${prompt}`],
+    },
+    {
+        bin: 'codex',
+        label: 'Codex CLI',
+        args: prompt => ['exec', '--sandbox', 'read-only', '--skip-git-repo-check', prompt],
+        needsClosedStdin: true,
+    },
+];
+/** Resolves a binary on PATH by scanning it — no shell, no subprocess. */
+function isOnPath(bin) {
+    for (const dir of (process.env.PATH ?? '').split(':')) {
+        if (dir === '')
+            continue;
+        try {
+            const candidate = join(dir, bin);
+            accessSync(candidate, constants.X_OK);
+            // Directories are mode 755, so X_OK alone passes for them. Without
+            // this check a directory named `claude` on PATH makes the gate
+            // promise AI is configured, and spawn then fails.
+            if (statSync(candidate).isFile())
+                return true;
+        }
+        catch {
+            // not here; keep looking
+        }
+    }
+    return false;
+}
+/**
+ * Runs a CLI with stdin closed and its output captured.
+ *
+ * `spawn` rather than `execFile` because execFile ignores the `stdio`
+ * option: codex reads stdin when it gets no prompt argument, so without
+ * an explicitly closed stdin it blocks until the timeout kills it —
+ * measured, it hung for the full 90s budget.
+ */
+function runCli(bin, args, timeoutMs) {
+    return new Promise(resolve => {
+        // 'ignore' on stdin is the whole point; never a shell, so prompt text
+        // cannot be reinterpreted as shell syntax.
+        // detached: the CLI is agentic and spawns its own tool subprocesses.
+        // Killing only the direct child orphans those, and an orphan holding
+        // the inherited stdout fd keeps 'close' from ever firing — measured,
+        // a child SIGKILLed at 500ms did not emit 'close' until 30,002ms.
+        // Its own process group lets us kill the whole tree.
+        const child = spawn(bin, args, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            shell: false,
+            detached: true,
+            env: childEnv(),
+        });
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        let bytes = 0;
+        let settled = false;
+        // Decode as a stream: a multi-byte character split across a chunk
+        // boundary becomes U+FFFD if each chunk is toString()'d alone, and
+        // model output is full of curly quotes and accents.
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        const killTree = (signal) => {
+            try {
+                if (child.pid !== undefined)
+                    process.kill(-child.pid, signal);
+            }
+            catch {
+                // group already gone
+            }
+            try {
+                child.kill(signal);
+            }
+            catch { /* already dead */ }
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killTree('SIGKILL');
+        }, timeoutMs);
+        let overflowed = false;
+        const capture = (chunk, onto) => {
+            bytes += chunk.length;
+            if (bytes > CLI_MAX_BUFFER) {
+                // Say why, rather than surfacing a bare `exited null` with empty
+                // stderr that reads like an external kill.
+                overflowed = true;
+                killTree('SIGKILL');
+                return;
+            }
+            if (onto === 'out')
+                stdout += chunk;
+            else
+                stderr += chunk;
+        };
+        const settle = (code, errMessage) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            // Release the pipes.
+            //
+            // Settling on 'exit' rather than 'close' is deliberate (see below),
+            // but it means the child's stdout and stderr can still be open when
+            // this resolves — and an open pipe is an open handle. Under Jest
+            // that surfaces as "a worker process has failed to exit gracefully"
+            // on any parallel run large enough to reuse a worker: measured, 18
+            // suites plus this one warns where 18 plus any other suite does not
+            // (#362). Nothing needs the streams after this point; everything
+            // they carried is already in `stdout`/`stderr`.
+            child.stdout.destroy();
+            child.stderr.destroy();
+            resolve({
+                stdout,
+                stderr: overflowed
+                    ? `output exceeded ${String(CLI_MAX_BUFFER)} bytes and was terminated`
+                    : errMessage ?? stderr,
+                code,
+                timedOut,
+            });
+        };
+        child.stdout.on('data', (c) => { capture(c, 'out'); });
+        child.stderr.on('data', (c) => { capture(c, 'err'); });
+        child.on('error', (err) => { settle(null, err.message); });
+        // Settle on 'exit', not 'close'. 'close' waits for every inherited
+        // stdio pipe to close, which an orphaned grandchild can hold open
+        // indefinitely — that is the hang above. A short grace lets buffered
+        // output drain first, so nothing is truncated in the normal case.
+        child.on('exit', (code) => {
+            setTimeout(() => { settle(code); }, DRAIN_GRACE_MS);
+        });
+    });
+}
+/**
+ * Builds a transport entry for one CLI.
+ *
+ * The prompt is passed as an argument-vector element, never interpolated
+ * into a shell string, so prompt content cannot become shell syntax.
+ *
+ * @param spec - How to drive the CLI
+ * @param timeoutMs - Budget for a single invocation
+ * @returns A transport entry usable by the AI service
+ * @nist si-10 "Information input validation"
+ */
+export function createCliTransport(spec, timeoutMs = CLI_TIMEOUT_MS) {
+    return {
+        id: `cli:${spec.bin}`,
+        label: spec.label,
+        isAvailable: () => Promise.resolve(isOnPath(spec.bin)),
+        send: async (prompt) => {
+            const { stdout, stderr, code, timedOut } = await runCli(spec.bin, spec.args(prompt), timeoutMs);
+            if (timedOut) {
+                throw new Error(`${spec.label} timed out after ${String(timeoutMs)}ms.`);
+            }
+            const detail = stderr.trim().slice(0, 400);
+            if (code !== 0) {
+                if (/ENOENT|not found/i.test(detail)) {
+                    throw new AiAuthError(`${spec.label} (${spec.bin}) is not installed.`);
+                }
+                if (/auth|login|credential|unauthor|tier|eligib/i.test(detail)) {
+                    throw new AiAuthError(`${spec.label} is not authenticated: ${detail}`);
+                }
+                throw new Error(`${spec.label} exited ${String(code)}: ${detail}`);
+            }
+            return stdout.trim();
+        },
+    };
+}
+/**
+ * Whether any known CLI is installed — synchronously.
+ *
+ * A PATH scan, not a subprocess, so availability gates stay synchronous
+ * and callers (and their ~80 existing mocks) do not have to become async.
+ */
+export function hasCliTransport() {
+    return KNOWN_CLIS.some(spec => isOnPath(spec.bin));
+}
+/** Transport entries for every CLI this server knows how to drive. */
+export function cliTransports(timeoutMs = CLI_TIMEOUT_MS) {
+    return KNOWN_CLIS.map(spec => createCliTransport(spec, timeoutMs));
+}

package/dist/services/engineChild.js

@@ -0,0 +1,83 @@
+/**
+ * Child entrypoint for the isolated local pattern engine (#307).
+ *
+ * Forked by `IsolatedEngineRunner` with `--max-old-space-size`. Owns one
+ * `StrudelEngine`, answers RPC over IPC, and is expected to die from time
+ * to time — that is the design, not a fault. Nothing here should try to
+ * survive a bad pattern; the parent handles death and respawns.
+ *
+ * This file is deliberately the only place that imports `StrudelEngine`
+ * into the isolated process, so the parent never loads `@strudel/*` at all.
+ */
+import { StrudelEngine } from './StrudelEngine.js';
+import { ISOLATED_METHODS } from './LocalPatternEngine.js';
+import { toTransferable } from './Transferable.js';
+import { BusinessError, TransientError, ValidationError } from '../utils/CategorisedError.js';
+const engine = new StrudelEngine();
+/**
+ * Object-literal method shorthand, and `Object.hasOwn` on the way in.
+ * A plain `HANDLERS[method]` would happily resolve `constructor` or
+ * `toString` off the prototype chain and call it with attacker-chosen
+ * arguments — the same class of bug this repo has now found nine times.
+ */
+const HANDLERS = {
+    transpile(code) {
+        return engine.transpile(code);
+    },
+    validate(code) {
+        return engine.validate(code);
+    },
+    analyzePattern(code) {
+        return engine.analyzePattern(code);
+    },
+    queryEvents(code, start, end) {
+        return engine.queryEvents(code, start, end);
+    },
+};
+/** The category an error carries, when it is one of ours. */
+function categoryOf(error) {
+    if (error instanceof ValidationError)
+        return 'validation';
+    if (error instanceof BusinessError)
+        return 'business';
+    if (error instanceof TransientError)
+        return 'transient';
+    return undefined;
+}
+process.on('message', (raw) => {
+    const request = raw;
+    if (!request || typeof request.id !== 'number')
+        return;
+    const send = (payload) => {
+        process.send?.({ id: request.id, ...payload });
+    };
+    if (!ISOLATED_METHODS.includes(request.method) || !Object.hasOwn(HANDLERS, request.method)) {
+        send({ ok: false, error: { name: 'TypeError', message: `Unknown engine method: ${String(request.method)}` } });
+        return;
+    }
+    try {
+        const handler = HANDLERS[request.method];
+        const result = handler(...(request.args ?? []));
+        send({ ok: true, result: toTransferable(result) });
+    }
+    catch (error) {
+        send({
+            ok: false,
+            error: {
+                name: error instanceof Error ? error.name : 'Error',
+                message: error instanceof Error ? error.message : String(error),
+                // The class cannot cross IPC — the parent rebuilds a plain Error
+                // from this payload — so the verdict travels as a field. Without
+                // it, "Result exceeds the 2000000-value transfer limit. Narrow
+                // the query" arrived uncategorised and was reported as an
+                // internal failure not worth retrying (#382).
+                category: categoryOf(error),
+            },
+        });
+    }
+});
+// If the parent goes away, so do we. A forked engine outliving its server
+// is a leaked process, not a feature.
+process.on('disconnect', () => {
+    process.exit(0);
+});