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

package/dist/services/GeminiService.js

@@ -1,8 +1,18 @@
 import { Logger } from '../utils/Logger.js';
+import { AiAuthError, AiRateLimitError } from './ai/AiTransport.js';
+import { TransientError } from '../utils/CategorisedError.js';
 import { GoogleAuth } from 'google-auth-library';
+import { cliTransports, hasCliTransport } from './ai/CliTransport.js';
+/**
+ * Cheapest possible request that still proves a transport can answer.
+ * Being on PATH says nothing about being logged in (#252 review).
+ */
+const TRANSPORT_PROBE_PROMPT = 'Reply with exactly: OK';
+import { buildMeasurementPrompt } from './ai/AudioMeasurements.js';
 import * as os from 'os';
 import * as path from 'path';
 import * as fs from 'fs/promises';
+import { ValidationError } from '../utils/CategorisedError.js';
 /**
  * GeminiService provides AI-powered music analysis and suggestions
  * using Google's Gemini API.
@@ -25,6 +35,12 @@ export class GeminiService {
     cacheTtlMs;
     timeoutMs;
     maxPatternLength;
+    /** Whether shelling out to a local CLI is permitted. */
+    enableCliTransport;
+    /** Resolved transport; undefined = not yet resolved, null = none available. */
+    transport = undefined;
+    /** In-flight transport resolution, so concurrent callers share one probe. */
+    transportPromise = null;
     adcAvailable = null; // null = not checked yet
     adcCheckPromise = null;
     cliCredentialsChecked = false;
@@ -47,20 +63,40 @@ export class GeminiService {
         this.cacheTtlMs = (config?.cacheTtlSeconds || 300) * 1000;
         this.timeoutMs = (config?.timeoutSeconds || 30) * 1000;
         this.maxPatternLength = config?.maxPatternLength || 5000;
+        this.enableCliTransport =
+            config?.enableCliTransport ?? process.env.STRUDEL_DISABLE_CLI_AI !== '1';
     }
     /**
-     * Checks if Gemini service is available (API key or ADC configured)
-     * Note: This is synchronous and may return false before ADC check completes.
-     * Use isAvailableAsync() for accurate ADC detection.
+     * Whether AI features can currently be served.
+     *
+     * Synchronous, so it can only report what is already known: an API key,
+     * a completed ADC probe, or a transport resolved by an earlier call.
+     * It deliberately does NOT scan for CLIs — that is I/O.
+     *
+     * Gates call this, so it has to be complete without being async. It
+     * covers an API key, a finished ADC probe, an already-resolved
+     * transport, and an installed CLI. What it CANNOT see synchronously is
+     * whether that CLI is logged in — `resolveTransport()` probes for that
+     * and falls through to the next candidate, so a gate saying "available"
+     * may still be followed by a transport error naming the reason.
      */
     isAvailable() {
-        return !!this.apiKey || this.adcAvailable === true;
+        return (!!this.apiKey ||
+            this.adcAvailable === true ||
+            this.transport != null ||
+            // A locally authenticated CLI serves requests perfectly well without
+            // any key of ours (#252). Detecting one is a PATH scan, not I/O
+            // against a service, so this stays synchronous.
+            (this.enableCliTransport && hasCliTransport()));
     }
     /**
      * Async check for Gemini service availability.
      * Checks in order: API key, env var, Gemini CLI config, ADC.
      * @returns Promise<boolean> indicating if service can make API calls
      */
+    async canServe() {
+        return (await this.resolveTransport()) !== null;
+    }
     async isAvailableAsync() {
         // 1. Explicit API key or env var already set
         if (this.apiKey)
@@ -225,10 +261,10 @@ export class GeminiService {
      * Get authentication error message
      */
     getAuthErrorMessage() {
-        return 'Gemini API key not configured. Options:\n' +
+        return ('No AI transport available. Options:\n' +
             '1. Set GEMINI_API_KEY environment variable\n' +
-            '2. Install Gemini CLI and run "gemini auth login"\n' +
-            '3. Run "gcloud auth application-default login" for ADC';
+            '2. Run "gcloud auth application-default login" for ADC\n' +
+            '3. Install and authenticate one of: claude, agy, codex');
     }
     /**
      * Ensure authentication is available (API key, Gemini CLI, or ADC)
@@ -236,18 +272,52 @@ export class GeminiService {
      * @throws {Error} When no authentication method is available
      */
     async ensureAuthentication() {
-        // 1. Already have API key (explicit or from env var)
-        if (this.apiKey)
+        // A resolved transport IS authentication. An authenticated CLI needs
+        // no API key of ours — it holds its own credentials, which is the
+        // entire point of #252. Checking the key ladder first would reject a
+        // machine where AI works perfectly well.
+        if ((await this.resolveTransport()) !== null)
             return;
-        // 2. Check Gemini CLI config file
-        const cliKey = await this.loadGeminiCliCredentials();
-        if (cliKey)
-            return;
-        // 3. Fall back to ADC
-        const adcAvailable = await this.checkADC();
-        if (!adcAvailable) {
-            throw new Error(this.getAuthErrorMessage());
+        // Typed, not phrased. The message lists GEMINI_API_KEY and gcloud
+        // commands, and used to be categorised `permission` only because
+        // `gemini` was in the matcher's auth list — which also made every
+        // unrelated Gemini failure a credentials problem (#382).
+        throw new AiAuthError(this.getAuthErrorMessage());
+    }
+    /**
+     * Analyses audio from locally computed measurements.
+     *
+     * Preferred over {@link analyzeAudio}. No installed CLI can decode
+     * audio — asked directly, they say so — and `agy` will sometimes
+     * confabulate detailed analysis of audio it never examined, which is
+     * worse than refusing. Measuring locally and sending numbers is
+     * deterministic and works with every provider rather than one.
+     *
+     * @param measurements - Peak, RMS, tempo, key and spectrum measured locally
+     * @param pattern - The Strudel source that produced the audio
+     * @param context - What the user was aiming for
+     * @returns Structured feedback in the same shape as analyzeAudio
+     *
+     * @example
+     * await service.analyzeAudioMeasurements(
+     *   { durationMs: 5000, peak: 1.12, rms: 0.36 },
+     *   'stack(s("bd*4"), s("~ cp"))',
+     * );
+     */
+    async analyzeAudioMeasurements(measurements, pattern, context) {
+        await this.ensureAuthentication();
+        this.checkRateLimit();
+        const cacheKey = `measure-${await this.getTransportId() ?? 'none'}-${JSON.stringify(measurements)}-${(pattern ?? '').slice(0, 200)}`;
+        const cached = this.getFromCache(this.audioCache, cacheKey);
+        if (cached) {
+            this.logger.debug('Returning cached measurement analysis');
+            return cached;
         }
+        const prompt = buildMeasurementPrompt(measurements, pattern, context);
+        const response = await this.callGeminiAPIWithTimeout(prompt);
+        const feedback = this.parseAudioResponse(response);
+        this.audioCache.set(cacheKey, { result: feedback, timestamp: Date.now() });
+        return feedback;
     }
     /**
      * Analyzes audio data and provides qualitative feedback
@@ -276,15 +346,31 @@ export class GeminiService {
             const prompt = this.buildAudioPrompt(context);
             // Use timeout for audio analysis (may take longer due to media processing)
             const audioTimeoutMs = this.timeoutMs * 2; // Double timeout for audio
+            let audioTimer;
             const timeoutPromise = new Promise((_, reject) => {
-                setTimeout(() => {
+                audioTimer = setTimeout(() => {
                     reject(new Error(`Audio analysis timed out after ${audioTimeoutMs / 1000} seconds`));
                 }, audioTimeoutMs);
             });
-            const response = await Promise.race([
-                this.callGeminiAPI(prompt, audioBase64, 'audio/webm'),
-                timeoutPromise
-            ]);
+            let response;
+            try {
+                response = await Promise.race([
+                    // Derive from the blob rather than hardcoding: the feedback path
+                    // now sends WAV (decoded PCM), and telling Gemini it is WebM makes
+                    // it decode the wrong container.
+                    this.callGeminiAPI(prompt, audioBase64, audioData.type || 'audio/webm'),
+                    timeoutPromise
+                ]);
+            }
+            finally {
+                // The race settling does not disarm the loser. Without this the
+                // handle and its closure live for the full 60s even when the API
+                // answered at once — eight of them outlived one test file, and in
+                // a long-lived server they accumulate (#404). The sibling call
+                // site at `callWithTimeout` already did this; this one did not.
+                if (audioTimer !== undefined)
+                    clearTimeout(audioTimer);
+            }
             const feedback = this.parseAudioResponse(response);
             this.audioCache.set(cacheKey, { result: feedback, timestamp: Date.now() });
             return feedback;
@@ -295,7 +381,7 @@ export class GeminiService {
             if (error.message?.includes('timed out')) {
                 throw new Error('Audio analysis timed out. The audio sample may be too long. Try a shorter recording.');
             }
-            if (error.message?.includes('rate limit') || error.message?.includes('Rate limit')) {
+            if (error instanceof AiRateLimitError) {
                 throw error; // Re-throw rate limit errors as-is
             }
             throw new Error(`Audio analysis failed: ${error.message}`);
@@ -324,7 +410,7 @@ export class GeminiService {
             if (error.message?.includes('timed out')) {
                 throw new Error('Variation suggestion timed out. The pattern may be too complex. Try a simpler pattern.');
             }
-            if (error.message?.includes('rate limit') || error.message?.includes('Rate limit')) {
+            if (error instanceof AiRateLimitError) {
                 throw error; // Re-throw rate limit errors as-is
             }
             throw new Error(`Variation suggestion failed: ${error.message}`);
@@ -361,7 +447,7 @@ export class GeminiService {
             if (error.message?.includes('timed out')) {
                 throw new Error('Creative feedback timed out. The pattern may be too complex. Try a simpler pattern.');
             }
-            if (error.message?.includes('rate limit') || error.message?.includes('Rate limit')) {
+            if (error instanceof AiRateLimitError) {
                 throw error; // Re-throw rate limit errors as-is
             }
             throw new Error(`Creative feedback failed: ${error.message}`);
@@ -370,6 +456,16 @@ export class GeminiService {
     /**
      * Clears all cached analysis results
      */
+    /**
+     * Forget the resolved transport so the next call re-probes.
+     *
+     * A long-lived server that started with no credentials could otherwise
+     * never recover: `resolveTransport()` caches `null` and logging into a
+     * CLI afterwards would require a restart.
+     */
+    resetTransport() {
+        this.transport = undefined;
+    }
     clearCache() {
         this.audioCache.clear();
         this.patternCache.clear();
@@ -392,7 +488,12 @@ export class GeminiService {
             const waitTimeMs = this.rateLimit.lastResetTime + this.rateLimitWindowMs - now;
             const waitTimeSec = Math.ceil(waitTimeMs / 1000);
             this.rateLimit.nextAvailableTime = now + waitTimeMs;
-            throw new Error(`Rate limit exceeded (${this.maxRequestsPerMinute} requests/minute). ` +
+            // A typed error, not a phrase. Three call sites and
+            // `categorizeError` all used to recognise this by matching "rate
+            // limit" in the message, so rewording it would have silently
+            // recategorised a rate limit as an internal failure that is not
+            // worth retrying — which is the opposite of the truth (#380).
+            throw new AiRateLimitError(`Rate limit exceeded (${this.maxRequestsPerMinute} requests/minute). ` +
                 `Wait ${waitTimeSec} seconds before retrying.`);
         }
         this.rateLimit.requestCount++;
@@ -445,7 +546,7 @@ export class GeminiService {
         }
         // Check for excessive length
         if (trimmed.length > this.maxPatternLength) {
-            throw new Error(`${methodName}: Pattern exceeds maximum length of ${this.maxPatternLength} characters ` +
+            throw new ValidationError(`${methodName}: Pattern exceeds maximum length of ${this.maxPatternLength} characters ` +
                 `(current: ${trimmed.length}). Truncate or simplify the pattern.`);
         }
         return trimmed;
@@ -456,16 +557,100 @@ export class GeminiService {
      * @returns API response text
      * @throws {Error} When request times out or API fails
      */
+    /**
+     * Resolves the transport that will actually serve requests.
+     *
+     * The Gemini HTTP API when credentials exist, otherwise the first
+     * locally authenticated CLI. Cached after the first resolution so a
+     * PATH scan and auth probe do not run per request.
+     *
+     * @returns The active transport, or null when nothing can serve
+     */
+    async resolveTransport() {
+        if (this.transport !== undefined)
+            return this.transport;
+        // Single-flight, matching checkADC() above. Without it two concurrent
+        // ai_assist calls each ran the full PATH scan and each SPAWNED A
+        // PROBE SUBPROCESS per candidate CLI — real quota, burned twice —
+        // before the last writer won the assignment anyway (#265).
+        this.transportPromise ??= this.doResolveTransport()
+            .finally(() => { this.transportPromise = null; });
+        return this.transportPromise;
+    }
+    async doResolveTransport() {
+        if (this.transport !== undefined)
+            return this.transport;
+        if (await this.isAvailableAsync()) {
+            this.transport = {
+                id: `gemini-api:${this.model}`,
+                label: 'Gemini API',
+                isAvailable: () => Promise.resolve(true),
+                send: (prompt) => this.callGeminiAPI(prompt),
+            };
+            return this.transport;
+        }
+        // No API credentials. A locally authenticated CLI still works, which
+        // is the whole of #252: `agy` holds valid Gemini auth that this
+        // service's credential ladder cannot see.
+        //
+        // Being on PATH is not the same as being usable. An installed but
+        // unauthenticated `claude` would otherwise win — it is first in the
+        // preference order — and every request would fail without `agy` ever
+        // being tried, on exactly the machine this feature exists to serve.
+        // So probe each candidate and fall through when it cannot answer.
+        for (const candidate of this.enableCliTransport ? cliTransports() : []) {
+            if (!(await candidate.isAvailable()))
+                continue;
+            try {
+                await candidate.send(TRANSPORT_PROBE_PROMPT);
+            }
+            catch (error) {
+                this.logger.debug(`Transport ${candidate.label} unusable: ${error instanceof Error ? error.message : String(error)}`);
+                continue;
+            }
+            this.logger.debug(`Using AI transport: ${candidate.label}`);
+            this.transport = candidate;
+            return this.transport;
+        }
+        this.transport = null;
+        return null;
+    }
+    /** Identifier of the transport in use, for diagnostics. */
+    async getTransportId() {
+        return (await this.resolveTransport())?.id ?? null;
+    }
     async callGeminiAPIWithTimeout(prompt) {
+        const transport = await this.resolveTransport();
+        if (transport === null) {
+            // Typed, not phrased. The message lists GEMINI_API_KEY and gcloud
+            // commands, and used to be categorised `permission` only because
+            // `gemini` was in the matcher's auth list — which also made every
+            // unrelated Gemini failure a credentials problem (#382).
+            throw new AiAuthError(this.getAuthErrorMessage());
+        }
+        // A CLI transport enforces its own timeout and can kill the process
+        // tree; racing it against a shorter one here would leave the loser
+        // running. The caller would see "timed out" while an agentic CLI kept
+        // working for another 90 seconds, burning quota, and repeated
+        // timeouts would stack live subprocesses.
+        if (transport.id.startsWith('cli:')) {
+            return transport.send(prompt);
+        }
+        let timer;
         const timeoutPromise = new Promise((_, reject) => {
-            setTimeout(() => {
+            timer = setTimeout(() => {
                 reject(new Error(`Request timed out after ${this.timeoutMs / 1000} seconds`));
             }, this.timeoutMs);
         });
-        return Promise.race([
-            this.callGeminiAPI(prompt),
-            timeoutPromise
-        ]);
+        try {
+            return await Promise.race([transport.send(prompt), timeoutPromise]);
+        }
+        finally {
+            // Otherwise the handle and its closure are held until the deadline
+            // even when the request succeeded immediately.
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
     }
     async callGeminiAPI(prompt, mediaData, mimeType) {
         // Dynamic import for ES module compatibility
@@ -600,7 +785,7 @@ Consider:
         try {
             const jsonMatch = response.match(/\{[\s\S]*\}/);
             if (!jsonMatch)
-                throw new Error('No JSON found in response');
+                throw new TransientError('No JSON found in response');
             const parsed = JSON.parse(jsonMatch[0]);
             return {
                 mood: parsed.mood || 'unknown',
@@ -625,7 +810,7 @@ Consider:
         try {
             const jsonMatch = response.match(/\[[\s\S]*\]/);
             if (!jsonMatch)
-                throw new Error('No JSON array found in response');
+                throw new TransientError('No JSON array found in response');
             const parsed = JSON.parse(jsonMatch[0]);
             return parsed.map((item) => ({
                 description: item.description || '',
@@ -642,7 +827,7 @@ Consider:
         try {
             const jsonMatch = response.match(/\{[\s\S]*\}/);
             if (!jsonMatch)
-                throw new Error('No JSON found in response');
+                throw new TransientError('No JSON found in response');
             const parsed = JSON.parse(jsonMatch[0]);
             return {
                 complexity: parsed.complexity || 'moderate',
@@ -705,7 +890,7 @@ Consider:
             if (error.message?.includes('timed out')) {
                 throw new Error('Pattern modification timed out. The pattern may be too complex. Try a simpler pattern.');
             }
-            if (error.message?.includes('rate limit') || error.message?.includes('Rate limit')) {
+            if (error instanceof AiRateLimitError) {
                 throw error; // Re-throw rate limit errors as-is
             }
             throw new Error(`Pattern modification failed: ${error.message}`);