[JS & Python] Add cancellation and structured error handling to live audio streaming

samples/js/live-audio-transcription/app.js

@@ -5,7 +5,7 @@
 //
 // Usage: node app.js
 
-import { FoundryLocalManager } from 'foundry-local-sdk';
+import { FoundryLocalManager, CoreError } from 'foundry-local-sdk';
 
 console.log('╔══════════════════════════════════════════════════════════╗');
 console.log('║   Foundry Local — Live Audio Transcription (JS SDK)      ║');
@@ -39,9 +39,16 @@ console.log('Loading model...');
 await model.load();
 console.log('✓ Model loaded');
 
+// Graceful-shutdown coordinator. Set ONCE on the session via
+// createLiveTranscriptionSession(signal) — every subsequent
+// start() / append() / getTranscriptionStream() / stop() call picks it
+// up automatically, so we don't have to thread the signal through every
+// callsite.
+const shutdown = new AbortController();
+
 // Create live transcription session (same pattern as C# sample).
 const audioClient = model.createAudioClient();
-const session = audioClient.createLiveTranscriptionSession();
+const session = audioClient.createLiveTranscriptionSession(shutdown.signal);
 
 session.settings.sampleRate = 16000;  // Default is 16000; shown here for clarity
 session.settings.channels = 1;
@@ -67,9 +74,22 @@ const readPromise = (async () => {
             }
         }
     } catch (err) {
-        if (err.name !== 'AbortError') {
-            console.error('Stream error:', err.message);
+        // AbortError is expected on Ctrl+C; ignore quietly.
+        if (err.name === 'AbortError') return;
+
+        // CoreError surfaces native-core failure metadata (code + isTransient).
+        // Use it to retry quietly on transient blips instead of dying on the
+        // first hiccup. Without CoreError the only signal would be err.message.
+        if (err instanceof CoreError) {
+            if (err.isTransient) {
+                console.warn(`\n⚠ Transient ASR error (${err.code}): ${err.message}. Continuing...`);
+                return;
+            }
+            console.error(`\n✗ Stream error [${err.code}]: ${err.message}`);
+            return;
         }
+
+        console.error('\n✗ Stream error:', err.message);
     }
 })();
 
@@ -108,14 +128,18 @@ try {
         try {
             while (appendQueue.length > 0) {
                 const pcm = appendQueue.shift();
+                // Session-level signal (set in createLiveTranscriptionSession)
+                // applies automatically — no need to pass it here.
                 await session.append(pcm);
             }
         } catch (err) {
+            // Aborted via Ctrl+C — exit quietly.
+            if (err.name === 'AbortError') return;
             console.error('append error:', err.message);
         } finally {
             pumping = false;
             // Handle race where new data arrived after loop exit.
-            if (appendQueue.length > 0) {
+            if (appendQueue.length > 0 && !shutdown.signal.aborted) {
                 void pumpAudio();
             }
         }
@@ -182,9 +206,14 @@ try {
     process.exit(0);
 }
 
-// Handle graceful shutdown
+// Handle graceful shutdown.
+//
+// The AbortController fires the shared `shutdown` signal so any in-flight
+// session.append() / getTranscriptionStream() resolves promptly with an
+// AbortError instead of waiting for stop() to finish draining the queue.
 process.on('SIGINT', async () => {
     console.log('\n\nStopping...');
+    shutdown.abort();
     if (audioInput) {
         audioInput.quit();
     }

sdk/js/src/index.ts

@@ -11,6 +11,7 @@ export { AudioClient, AudioClientSettings } from './openai/audioClient.js';
 export { EmbeddingClient } from './openai/embeddingClient.js';
 export { LiveAudioTranscriptionSession, LiveAudioTranscriptionOptions } from './openai/liveAudioTranscriptionClient.js';
 export type { LiveAudioTranscriptionResponse, TranscriptionContentPart } from './openai/liveAudioTranscriptionTypes.js';
+export { CoreError } from './openai/liveAudioTranscriptionTypes.js';
 export { ResponsesClient, ResponsesClientSettings, getOutputText } from './openai/responsesClient.js';
 export { ModelLoadManager } from './detail/modelLoadManager.js';
 /** @internal */

sdk/js/src/openai/audioClient.ts

@@ -59,10 +59,26 @@ export class AudioClient {
 
     /**
      * Creates a LiveAudioTranscriptionSession for real-time audio streaming ASR.
+     *
+     * @param signal - Optional AbortSignal applied to **all** subsequent
+     *                 ``start`` / ``append`` / ``stop`` /
+     *                 ``getTranscriptionStream`` calls on the returned session.
+     *                 Behaves like C#'s ``CancellationToken`` parameter.
      * @returns A LiveAudioTranscriptionSession instance.
+     *
+     * @example
+     * ```ts
+     * const shutdown = new AbortController();
+     * const session = audioClient.createLiveTranscriptionSession(shutdown.signal);
+     * await session.start();
+     * await session.append(pcm);
+     * for await (const r of session.getTranscriptionStream()) { ... }
+     *
+     * process.on('SIGINT', () => shutdown.abort());
+     * ```
      */
-    public createLiveTranscriptionSession(): LiveAudioTranscriptionSession {
-        return new LiveAudioTranscriptionSession(this.modelId, this.coreInterop);
+    public createLiveTranscriptionSession(signal?: AbortSignal): LiveAudioTranscriptionSession {
+        return new LiveAudioTranscriptionSession(this.modelId, this.coreInterop, signal);
     }
 
     /**