Changelog: 1599 fragment

changelog.d/1599-keyless-voice-key-hint.md

@@ -0,0 +1,4 @@
+- Without `OPENAI_API_KEY`, the mic now says the key is missing and to add it in
+  Provider Settings, instead of showing the raw server error with a hint to
+  check microphone permissions. `/api/realtime/token` returns
+  `code: "API_KEY_MISSING"` with its 503 (asturksever, #1599).

changelog.d/1600-load-chip-key-required.md

@@ -1,4 +0,0 @@
-- A layer that is only waiting for a key now ends the load chip on an amber
-  `KEY REQUIRED` instead of a red `LOAD FAILED`, so a keyless Environmental
-  first run no longer reports a failure while earthquakes load. A real error
-  still wins over a missing key (asturksever, #1600).

server/providers/openai/realtime.js

@@ -224,7 +224,12 @@ function createRealtimeTokenHandler({
       if (!bearer) {
         res.statusCode = 503;
         res.setHeader('Content-Type', 'application/json');
-        res.end(JSON.stringify({ error: 'OPENAI_API_KEY is not set' }));
+        res.end(
+          JSON.stringify({
+            error: 'OPENAI_API_KEY is not set',
+            code: 'API_KEY_MISSING',
+          }),
+        );
         return;
       }
     }

src/firstRunExperience.js

@@ -98,9 +98,15 @@ export const FIRST_RUN_MISSIONS = Object.freeze({
     // for the FULLY CONFIGURED experience (owner ruling, 2026-08-23): the tile
     // promises both, so it turns on both, and the subcopy in index.html says so.
     //
-    // Keyless, FIRMS's own row reads "KEY REQUIRED", and the quakes half of
-    // the tile still delivers in full; the global status chip ends on KEY
-    // REQUIRED too (src/loadingFeedback.js) rather than LOAD FAILED.
+    // Keyless, FIRMS is honest where it counts — its own layer row reads
+    // "UNAVAILABLE · NASA FIRMS · LIVE · KEY REQUIRED", and the quakes half of
+    // the tile still delivers in full. What is NOT honest is the GLOBAL status
+    // chip, which has no key-required terminal state and folds that row into
+    // "LOAD FAILED". That aggregation is the defect, not this preset: fixing it
+    // means a KEY REQUIRED terminal state in src/loadingFeedback.js, a state
+    // machine shared by every layer and not a thing to refactor the night
+    // before a launch. LEDGERED post-launch. Until it lands, keyless visitors
+    // are judged on the layer row, which tells them the truth.
     layerIds: Object.freeze(['earthquakes', 'local-firms']),
     busyKey: msg('Scanning active events…'),
   }),

src/firstRunExperience.test.mjs

@@ -606,10 +606,11 @@ test('the tile is the FULLY CONFIGURED experience: quakes and fires together', (
   const environmental = FIRST_RUN_MISSIONS.environmental;
   assert.deepEqual(environmental.layerIds, ['earthquakes', 'local-firms']);
 
-  // Keyless, the LAYER ROW reads "KEY REQUIRED", and the global chip now ends
-  // on KEY REQUIRED as well instead of LOAD FAILED (src/loadingFeedback.js,
-  // covered in loadingFeedback.test.mjs). The note says so where the next
-  // editor will read it.
+  // Keyless, the honest surface is the LAYER ROW ("KEY REQUIRED"), which the
+  // FIRMS layer already reports. The misleading part is the GLOBAL chip folding
+  // that row into LOAD FAILED — a defect in the shared state machine, ledgered
+  // post-launch, and the note must stay where the next editor will read it
+  // rather than being re-discovered as a launcher bug.
   const module = fs.readFileSync(
     new URL('./firstRunExperience.js', import.meta.url),
     'utf8',
@@ -620,7 +621,7 @@ test('the tile is the FULLY CONFIGURED experience: quakes and fires together', (
   );
   assert.match(table, /KEY REQUIRED/);
   assert.match(table, /src\/loadingFeedback\.js/);
-  assert.match(table, /rather than LOAD FAILED/);
+  assert.match(table, /LEDGERED post-launch/);
 });
 
 test('every visitor gets the same tile — there is no degraded keyless variant', async () => {

src/hudSummaryResponse.test.mjs

@@ -150,7 +150,10 @@ test('the installed keyless HUD route stays successful after the voice quota is
     const firstToken = await invokeRoute(token);
     const secondToken = await invokeRoute(token);
     assert.equal(firstToken.statusCode, 503);
-    assert.deepEqual(firstToken.body, { error: 'OPENAI_API_KEY is not set' });
+    assert.deepEqual(firstToken.body, {
+      error: 'OPENAI_API_KEY is not set',
+      code: 'API_KEY_MISSING',
+    });
     assert.equal(secondToken.statusCode, 429);
 
     for (let attempt = 0; attempt < 2; attempt += 1) {

src/loadingFeedback.js

@@ -85,18 +85,13 @@ export function normalizeLayerLoading(layer = {}) {
 function terminalFromParticipantStats(summary, participantIds) {
   if (!participantIds?.length) return null;
   const participants = new Set(participantIds);
-  const records = summary.records.filter((record) =>
-    participants.has(record.id),
-  );
-  // A layer waiting for a key did not fail: its row names the key. Only an
-  // actual error makes the whole batch read LOAD FAILED.
-  if (
-    records.some(
-      (record) => !record.keyRequired && (record.error || record.unavailable),
-    )
+  return summary.records.some(
+    (record) =>
+      participants.has(record.id) &&
+      (record.error || record.unavailable || record.keyRequired),
   )
-    return 'error';
-  return records.some((record) => record.keyRequired) ? 'key' : null;
+    ? 'error'
+    : null;
 }
 
 /** Aggregate all manager layers without changing their lifecycle authority. */
@@ -287,7 +282,7 @@ function terminalFromEvent(event) {
 }
 
 function mergeTerminalOutcome(current, next) {
-  const severity = { complete: 1, key: 2, cancelled: 3, error: 4 };
+  const severity = { complete: 1, cancelled: 2, error: 3 };
   if (!next) return current || null;
   if (!current || severity[next] > severity[current]) return next;
   return current;
@@ -429,7 +424,6 @@ export function presentLoadingFeedback(state, summary, nowMs) {
     const labels = {
       complete: 'LOAD COMPLETE',
       cancelled: 'LOAD CANCELLED',
-      key: 'KEY REQUIRED',
       error: 'LOAD FAILED',
     };
     const label =

src/loadingFeedback.test.mjs

@@ -247,11 +247,11 @@ test('terminal loading feedback centers its label without an empty detail slot',
   const css = readStylesheet(new URL('../style.css', import.meta.url));
   assert.match(
     css,
-    /#global-loading-status:is\(\s*\[data-state='complete'\],\s*\[data-state='cancelled'\],\s*\[data-state='key'\],\s*\[data-state='error'\]\s*\)\s*\{[\s\S]*?justify-content:\s*center;[\s\S]*?text-align:\s*center;/,
+    /#global-loading-status:is\(\s*\[data-state='complete'\],\s*\[data-state='cancelled'\],\s*\[data-state='error'\]\s*\)\s*\{[\s\S]*?justify-content:\s*center;[\s\S]*?text-align:\s*center;/,
   );
   assert.match(
     css,
-    /#global-loading-status:is\(\s*\[data-state='complete'\],\s*\[data-state='cancelled'\],\s*\[data-state='key'\],\s*\[data-state='error'\]\s*\)\s*#global-loading-detail\s*\{\s*display:\s*none;/,
+    /#global-loading-status:is\(\s*\[data-state='complete'\],\s*\[data-state='cancelled'\],\s*\[data-state='error'\]\s*\)\s*#global-loading-detail\s*\{\s*display:\s*none;/,
   );
 });
 
@@ -346,7 +346,7 @@ test('participant stats failure outranks a simultaneous visibility completion',
     name: 'AIS Vessels',
     enabled: true,
     lifecycleState: 'enabled',
-    stats: { loading: false, error: 'Upstream closed' },
+    stats: { loading: false, keyRequired: true },
   }]);
   state = reduceLoadingFeedback(state, missingKey, 250, {
     type: 'visibility', layerId: 'ais-live-vessels', enabled: true,
@@ -355,36 +355,6 @@ test('participant stats failure outranks a simultaneous visibility completion',
   assert.equal(state.terminal, 'error');
 });
 
-test('a layer waiting for a key ends the batch as KEY REQUIRED, not LOAD FAILED', () => {
-  const quakes = (stats) => ({ id: 'earthquakes', name: 'Earthquakes', ...stats });
-  const fires = (stats) => ({ id: 'local-firms', name: 'Active Fires', ...stats });
-  const enabling = aggregateLayerLoading([
-    quakes({ lifecycleState: 'enabling', stats: { loading: true } }),
-    fires({ lifecycleState: 'enabling', stats: { loading: true } }),
-  ]);
-  let state = reduceLoadingFeedback(createLoadingFeedbackState(), enabling, 0);
-  state = reduceLoadingFeedback(state, enabling, 200);
-  const settled = aggregateLayerLoading([
-    quakes({ enabled: true, stats: { count: 27, lastUpdate: 1 } }),
-    fires({ enabled: true, stats: { status: 'unavailable', keyRequired: true, error: 'KEY REQUIRED' } }),
-  ]);
-  state = reduceLoadingFeedback(state, settled, 250);
-  assert.equal(state.terminal, 'key');
-  assert.deepEqual(state.failedEventIds, []);
-  const view = presentLoadingFeedback(state, settled, 260);
-  assert.equal(view.state, 'key');
-  assert.equal(view.label, 'KEY REQUIRED');
-
-  // A real failure beside it still reads as one.
-  const broken = aggregateLayerLoading([
-    quakes({ enabled: true, stats: { error: 'USGS 503' } }),
-    fires({ enabled: true, stats: { status: 'unavailable', keyRequired: true } }),
-  ]);
-  let failing = reduceLoadingFeedback(createLoadingFeedbackState(), enabling, 0);
-  failing = reduceLoadingFeedback(failing, enabling, 200);
-  assert.equal(reduceLoadingFeedback(failing, broken, 250).terminal, 'error');
-});
-
 test('retains the worst terminal outcome until every concurrent load drains', () => {
   const both = aggregateLayerLoading([
     { id: 'a', name: 'A', lifecycleState: 'enabling' },

src/ui/shellFeedback.js

@@ -23,7 +23,6 @@ const STATUS_LABEL_KEYS = Object.freeze({
   'LOAD COMPLETE': msg('LOAD COMPLETE'),
   'LOAD CANCELLED': msg('LOAD CANCELLED'),
   'LOAD FAILED': msg('LOAD FAILED'),
-  'KEY REQUIRED': msg('KEY REQUIRED'),
   'LIVE DATA OFF': msg('LIVE DATA OFF'),
   'MAPPED SITES LOADED': msg('MAPPED SITES LOADED'),
   'RETRYING MAPPED SITES': msg('RETRYING MAPPED SITES'),

src/ui/styles/status.css

@@ -131,7 +131,6 @@ html:not([lang='en']) #global-loading-detail {
 #global-loading-status:is(
   [data-state='complete'],
   [data-state='cancelled'],
-  [data-state='key'],
   [data-state='error']
 ) {
   justify-content: center;
@@ -140,7 +139,6 @@ html:not([lang='en']) #global-loading-detail {
 #global-loading-status:is(
     [data-state='complete'],
     [data-state='cancelled'],
-    [data-state='key'],
     [data-state='error']
   )
   #global-loading-detail {
@@ -157,13 +155,11 @@ html:not([lang='en']) #global-loading-detail {
 #global-loading-status[data-state='cancelled'] {
   color: #ffd488;
 }
-#global-loading-status:is([data-state='retry'], [data-state='key']) {
+#global-loading-status[data-state='retry'] {
   border-color: rgba(255, 212, 136, 0.55);
 }
-#global-loading-status:is([data-state='retry'], [data-state='key'])
-  #global-loading-label,
-#global-loading-status:is([data-state='retry'], [data-state='key'])
-  #global-loading-detail {
+#global-loading-status[data-state='retry'] #global-loading-label,
+#global-loading-status[data-state='retry'] #global-loading-detail {
   color: #ffd488;
 }
 #global-loading-status[data-state='cancelled'] #global-loading-label,

src/ui/views/panels/VoiceControl.vue

@@ -166,7 +166,7 @@ const frameStyle = (panel) => ({
           <button class="gev-voice-error-dismiss" type="button" @click="controls?.dismissError()">{{ t('DISMISS') }}</button>
         </div>
         <div id="gev-voice-error-detail">{{ view.error.text }}</div>
-        <div class="gev-voice-error-hint" :hidden="view.error.typed">{{ t('Check microphone permission and network access, then try again.') }}</div>
+        <div class="gev-voice-error-hint" :hidden="view.error.typed || view.error.hint === false">{{ t('Check microphone permission and network access, then try again.') }}</div>
       </div>
   </div>
 </template>

src/voice/control.js

@@ -107,7 +107,7 @@ function initialState(panel) {
         t('Hold Space to speak · tap Space to activate focused controls'),
     },
     // A typed chat error reads as chat's, without the microphone hint.
-    error: { text: '', typed: false },
+    error: { text: '', typed: false, hint: true },
     // Connection and turn state beside the selected mode's indicator.
     phase: { text: '' },
     voicePanel: {

src/voice/realtimeBackend.js

@@ -39,8 +39,9 @@ export function createRealtimeBackend({
       if (!response.ok) {
         const reason =
           typeof data?.error === 'string' ? data.error : data?.error?.message;
-        throw new Error(
-          reason || `Realtime token failed: HTTP ${response.status}`,
+        throw Object.assign(
+          new Error(reason || `Realtime token failed: HTTP ${response.status}`),
+          typeof data?.code === 'string' ? { code: data.code } : {},
         );
       }
       const token =

src/voice/realtimeBackend.test.mjs

@@ -143,3 +143,17 @@ test('controller lifetime stops pending transport and releases resources through
   assert.equal(controller.stream, null);
   assert.equal(controller.isActive(), false);
 });
+
+test('a missing server key keeps its code, so the UI can point to Provider Settings', async () => {
+  const backend = createRealtimeBackend({
+    tokenTransport: async () =>
+      Response.json(
+        { error: 'OPENAI_API_KEY is not set', code: 'API_KEY_MISSING' },
+        { status: 503 },
+      ),
+  });
+  await assert.rejects(backend.requestToken(), {
+    message: 'OPENAI_API_KEY is not set',
+    code: 'API_KEY_MISSING',
+  });
+});

src/voice/realtimeController.js

@@ -18,7 +18,7 @@ import {
 } from './pointerContext.js';
 
 import { shouldPauseRadioForVoice } from './realtimeProtocol.js';
-import { postDebugLog } from './realtimeDiagnostics.js';
+import { missingVoiceKeyText, postDebugLog } from './realtimeDiagnostics.js';
 
 export {
   readStoredVoiceTier,
@@ -436,6 +436,9 @@ export class GevRealtimeController extends RealtimeFacade {
         status === 'error'
           ? resolvedDetail() || t('Voice session could not be started.')
           : '',
+      // "Check microphone permission" is wrong advice for a missing key.
+      hint: () =>
+        !(status === 'error' && resolvedDetail() === missingVoiceKeyText()),
     });
     if (status === 'idle' || status === 'connecting' || status === 'error') {
       this.setVoiceSpeaker('idle');

src/voice/realtimeDiagnostics.js

@@ -1,3 +1,11 @@
+import { t } from '../i18n/index.js';
+
+/** The voice error when the server has no OpenAI key: where to add it. */
+export const missingVoiceKeyText = () =>
+  t('Needs {envVars} — add it in Provider Settings', {
+    envVars: 'OPENAI_API_KEY',
+  });
+
 const ERROR_LOG_LIMIT = 30;
 
 const ERROR_STORAGE_KEY = 'gev-realtime-errors';
@@ -83,6 +91,7 @@ function createErrorRecord(source, error, extra = {}) {
       String(error?.message || '').trim() ||
       'No browser error message supplied',
     errorDetail: rtcError?.errorDetail || null,
+    code: typeof rtcError?.code === 'string' ? rtcError.code : null,
     sctpCauseCode: rtcError?.sctpCauseCode ?? null,
     receivedAlert: rtcError?.receivedAlert ?? null,
     sentAlert: rtcError?.sentAlert ?? null,
@@ -91,6 +100,8 @@ function createErrorRecord(source, error, extra = {}) {
 }
 
 function formatErrorForDisplay(record) {
+  // A missing key is a setup step, not a connection fault: say where to add it.
+  if (record.code === 'API_KEY_MISSING') return missingVoiceKeyText();
   const primary = [record.source, record.message].filter(Boolean).join(': ');
   const state = [
     record.errorDetail && `detail=${record.errorDetail}`,