@juspay/neurolink 13.8.16 → 13.8.18

package/dist/voice/livekit/voiceAgent.js

@@ -16,6 +16,7 @@
  */
 import { ReadableStream } from "node:stream/web";
 import { logger } from "../../utils/logger.js";
+import { markAgentDefinition } from "./agentDefinition.js";
 import { createVoiceBrain } from "./brain.js";
 import { resolveBrainDefaults, resolveEouTurnDetection } from "./config.js";
 import { attachEventBridge } from "./eventBridge.js";
@@ -458,5 +459,5 @@ export function defineVoiceAgent(config) {
             });
         }
     }
-    return { entry };
+    return markAgentDefinition({ entry });
 }

package/dist/voice/livekit/xaiSessionWatch.d.ts

@@ -18,9 +18,4 @@
  * third.
  */
 import type { XaiObservedSession } from "../../types/index.js";
-/**
- * Log the usage of every response, warn when the service runs another model
- * than the one asked for, and report a refused upgrade as a session error.
- * `requestedModel` is the id the session was configured with.
- */
 export declare function observeXaiSession(session: XaiObservedSession, requestedModel: string): void;

package/dist/voice/livekit/xaiSessionWatch.js

@@ -129,8 +129,38 @@ function watchForRefusedUpgrade(session) {
  * than the one asked for, and report a refused upgrade as a session error.
  * `requestedModel` is the id the session was configured with.
  */
+/** The plugin's own wording for a refused upgrade (agents-plugin-xai >= 1.9). */
+const PLUGIN_REFUSAL = /refused the connection: (\d{3})/;
 export function observeXaiSession(session, requestedModel) {
     const stopWatching = watchForRefusedUpgrade(session);
+    // Since @livekit/agents-plugin-xai 1.9 a refused upgrade no longer escapes
+    // as an uncaught exception: the plugin reports it as its own `error` event,
+    // worded for OpenAI and naming no key. This listener is registered before
+    // the agent's, so it can end the crash watch and relabel the event in place
+    // with the xAI-specific diagnosis (HTTP status + XAI_API_KEY hint).
+    session.on("error", (event) => {
+        if (!isRecord(event)) {
+            return;
+        }
+        const inner = event.error;
+        const text = inner instanceof Error
+            ? inner.message
+            : typeof event.message === "string"
+                ? event.message
+                : "";
+        const status = Number(PLUGIN_REFUSAL.exec(text)?.[1]);
+        if (Number.isNaN(status)) {
+            return;
+        }
+        stopWatching();
+        const message = describeRefusal(status);
+        logger.error("realtime.xai.connectRefused", { status, error: message });
+        event.error = new Error(message);
+        event.recoverable = false;
+        if (typeof event.label !== "string" || event.label.length === 0) {
+            event.label = "xai.RealtimeModel";
+        }
+    });
     session.on("openai_server_event_received", (event) => {
         if (isRecord(event) && event.type === "session.created") {
             stopWatching();

package/dist/voice/providers/GeminiLive.js

@@ -6,8 +6,21 @@
  * @module voice/providers/GeminiLive
  */
 import { logger } from "../../utils/logger.js";
+import { redactUrlsInText } from "../../utils/logSanitize.js";
 import { RealtimeError } from "../errors.js";
 import { BaseRealtimeHandler } from "../RealtimeVoiceAPI.js";
+/**
+ * A copy of `err` whose message has every URL — and so the `?key=` the Live
+ * endpoint requires — reduced to origin + path. The original is left alone
+ * for anything still holding it; `cause` is not carried, since it would hold
+ * the unscrubbed text.
+ */
+function scrubUrlFromError(err) {
+    const scrubbed = new Error(redactUrlsInText(err.message));
+    scrubbed.name = err.name;
+    scrubbed.stack = err.stack ? redactUrlsInText(err.stack) : undefined;
+    return scrubbed;
+}
 /**
  * Google Gemini Live Voice API Handler
  *
@@ -52,7 +65,9 @@ export class GeminiLive extends BaseRealtimeHandler {
             const { default: WebSocket } = await import("ws");
             // Determine model
             const model = config.model ?? "gemini-2.5-flash-native-audio-preview-09-2025";
-            // Connect to Gemini Live API
+            // Connect to Gemini Live API. The Live endpoint authenticates with the
+            // key as a query parameter; every error below is scrubbed with
+            // `redactUrlsInText` so that URL never reaches a log or a caller.
             const wsUrl = `wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1alpha.GenerativeService.BidiGenerateContent?key=${this.apiKey}`;
             this.ws = new WebSocket(wsUrl);
             // Issue 9: capture a local reference so the closure below doesn't need
@@ -70,7 +85,7 @@ export class GeminiLive extends BaseRealtimeHandler {
                 const errorHandler = (err) => {
                     clearTimeout(timeout);
                     ws.off("open", openHandler);
-                    reject(err);
+                    reject(scrubUrlFromError(err));
                 };
                 const timeout = setTimeout(() => {
                     // C1: close the half-opened socket and detach temp listeners so we
@@ -92,7 +107,7 @@ export class GeminiLive extends BaseRealtimeHandler {
                 this.session = null;
             });
             this.ws.on("error", (err) => {
-                this.emitError(err);
+                this.emitError(scrubUrlFromError(err));
             });
             // Send setup message
             await this.sendSetup(config, model);
@@ -114,8 +129,8 @@ export class GeminiLive extends BaseRealtimeHandler {
         }
         catch (err) {
             this.emitStateChange("error");
-            const errorMessage = err instanceof Error ? err.message : String(err || "Unknown error");
-            throw RealtimeError.connectionFailed(errorMessage, "gemini-live", err instanceof Error ? err : undefined);
+            const errorMessage = redactUrlsInText(err instanceof Error ? err.message : String(err || "Unknown error"));
+            throw RealtimeError.connectionFailed(errorMessage, "gemini-live", err instanceof Error ? scrubUrlFromError(err) : undefined);
         }
     }
     async disconnect() {
@@ -133,7 +148,7 @@ export class GeminiLive extends BaseRealtimeHandler {
             logger.info("[GeminiLiveHandler] Disconnected");
         }
         catch (err) {
-            const errorMessage = err instanceof Error ? err.message : String(err || "Unknown error");
+            const errorMessage = redactUrlsInText(err instanceof Error ? err.message : String(err || "Unknown error"));
             throw RealtimeError.protocolError(`Disconnect failed: ${errorMessage}`, "gemini-live", err instanceof Error ? err : undefined);
         }
     }

package/dist/voice/providers/GoogleSTT.js

@@ -6,6 +6,7 @@
  * @module voice/providers/GoogleSTT
  */
 import { logger } from "../../utils/logger.js";
+import { redactUrlsInText } from "../../utils/logSanitize.js";
 import { STTError } from "../errors.js";
 /**
  * Google Cloud Speech-to-Text Handler
@@ -213,10 +214,9 @@ export class GoogleSTT {
                     content: audioBuffer.toString("base64"),
                 },
             };
-            // Build URL with API key
-            const url = this.apiKey
-                ? `${this.baseUrl}/speech:recognize?key=${this.apiKey}`
-                : `${this.baseUrl}/speech:recognize`;
+            // The key travels in the `x-goog-api-key` header, never in the URL:
+            // a URL is what proxies, access logs and `fetch failed` causes record.
+            const url = `${this.baseUrl}/speech:recognize`;
             const controller = new AbortController();
             const timeoutId = setTimeout(() => controller.abort(), 30000);
             let response;
@@ -225,6 +225,7 @@ export class GoogleSTT {
                     method: "POST",
                     headers: {
                         "Content-Type": "application/json",
+                        ...(this.apiKey ? { "x-goog-api-key": this.apiKey } : {}),
                         ...(this.credentialsPath && !this.apiKey
                             ? { Authorization: `Bearer ${await this.getAccessToken()}` }
                             : {}),
@@ -237,7 +238,9 @@ export class GoogleSTT {
                 if (fetchErr instanceof Error && fetchErr.name === "AbortError") {
                     throw STTError.transcriptionFailed("Google STT request timed out after 30 seconds", "google-stt", fetchErr);
                 }
-                throw fetchErr;
+                // A transport error embeds the request URL; scrub any URL (and its
+                // query) before the message reaches a log or a caller.
+                throw STTError.transcriptionFailed(redactUrlsInText(fetchErr instanceof Error ? fetchErr.message : String(fetchErr)), "google-stt", fetchErr instanceof Error ? fetchErr : undefined);
             }
             finally {
                 clearTimeout(timeoutId);

package/dist/voice/transcribe.d.ts

@@ -12,7 +12,7 @@
  *
  * @module voice/transcribe
  */
-import type { STTOptions, STTStreamingOptions, TranscribeAudioInput, TranscribeDeps, TranscribeOptions, TranscribeResult, TTSAudioFormat } from "../types/index.js";
+import type { AttachmentPolicy, STTOptions, STTStreamingOptions, TranscribeAudioInput, TranscribeDeps, TranscribeOptions, TranscribeResult, TTSAudioFormat } from "../types/index.js";
 /**
  * The first `seconds` of a PCM WAV as a smaller WAV, so a language probe
  * uploads kilobytes instead of the whole recording. Anything that is not a
@@ -33,7 +33,7 @@ export declare function audioFormatFromBytes(buffer: Buffer): TTSAudioFormat | u
  *
  * @throws STTError when the input is a frame stream, or cannot be read
  */
-export declare function loadTranscribeAudio(input: TranscribeAudioInput, timeoutMs?: number): Promise<{
+export declare function loadTranscribeAudio(input: TranscribeAudioInput, timeoutMs?: number, attachmentPolicy?: AttachmentPolicy): Promise<{
     buffer: Buffer;
     formatHint?: TTSAudioFormat;
 }>;

package/dist/voice/transcribe.js

@@ -12,9 +12,9 @@
  *
  * @module voice/transcribe
  */
-import { promises as fs } from "fs";
 import { extname } from "path";
 import { fileURLToPath } from "url";
+import { downloadAttachment, readAttachmentFile, } from "../utils/attachmentPolicy.js";
 import { guardEngineResult, promptTermsOf, runTranscribeStream, } from "./transcribeStream.js";
 import { ENGINE_SAMPLE_RATE } from "./streaming/endpointer.js";
 import { alignWordsToText } from "./correction/align.js";
@@ -74,6 +74,12 @@ function correctionLinesDisabled() {
 }
 /** Default timeout for fetching an `http(s)://` audio input. */
 const URL_FETCH_TIMEOUT_MS = 60_000;
+/**
+ * Ceiling for a recording named by path or URL: 512 MiB, the same budget the
+ * transcription WebSocket allows a file-mode upload. `attachments.maxBytes`
+ * lowers it.
+ */
+const TRANSCRIBE_AUDIO_MAX_BYTES = 512 * 1024 * 1024;
 /** Container names an extension or magic number can map to. */
 const KNOWN_FORMATS = [
     "mp3",
@@ -140,7 +146,7 @@ export function audioFormatFromBytes(buffer) {
  *
  * @throws STTError when the input is a frame stream, or cannot be read
  */
-export async function loadTranscribeAudio(input, timeoutMs) {
+export async function loadTranscribeAudio(input, timeoutMs, attachmentPolicy) {
     if (Buffer.isBuffer(input)) {
         return { buffer: input };
     }
@@ -160,17 +166,20 @@ export async function loadTranscribeAudio(input, timeoutMs) {
     }
     const source = input.trim();
     if (/^https?:\/\//i.test(source)) {
-        const controller = new AbortController();
         const limit = timeoutMs ?? URL_FETCH_TIMEOUT_MS;
-        const timer = setTimeout(() => controller.abort(), limit);
         try {
-            const response = await fetch(source, { signal: controller.signal });
-            if (!response.ok) {
-                throw STTError.audioLoadFailed(`fetching the audio URL returned HTTP ${response.status}`);
-            }
-            const buffer = Buffer.from(await response.arrayBuffer());
+            // The instance's attachment policy: HTTPS to a public host unless it
+            // says otherwise, the connection pinned to the vetted addresses,
+            // redirects re-validated per hop, and the body bounded while it
+            // streams rather than read whole with `arrayBuffer()`.
+            const downloaded = await downloadAttachment(source, {
+                policy: attachmentPolicy,
+                maxBytes: TRANSCRIBE_AUDIO_MAX_BYTES,
+                label: "audio URL",
+                timeoutMs: limit,
+            });
             return {
-                buffer,
+                buffer: downloaded.buffer,
                 formatHint: audioFormatFromName(new URL(source).pathname),
             };
         }
@@ -183,9 +192,6 @@ export async function loadTranscribeAudio(input, timeoutMs) {
                 ? `fetching the audio URL timed out after ${limit}ms`
                 : `fetching the audio URL failed: ${error instanceof Error ? error.message : String(error)}`, error instanceof Error ? error : undefined);
         }
-        finally {
-            clearTimeout(timer);
-        }
     }
     let path;
     try {
@@ -195,16 +201,26 @@ export async function loadTranscribeAudio(input, timeoutMs) {
         throw STTError.audioLoadFailed("the file: URL is not a valid local path", error instanceof Error ? error : undefined);
     }
     try {
+        // Roots containment when configured, O_NOFOLLOW open of the real path,
+        // regular files only, bounded read.
+        const read = await readAttachmentFile(path, {
+            policy: attachmentPolicy,
+            maxBytes: TRANSCRIBE_AUDIO_MAX_BYTES,
+            label: "audio file",
+        });
         return {
-            buffer: await fs.readFile(path),
+            buffer: read.buffer,
             formatHint: audioFormatFromName(path),
         };
     }
     catch (error) {
         const code = error?.code;
-        throw STTError.audioLoadFailed(code === "ENOENT"
-            ? "no file at the given path"
-            : `reading the file failed${code ? ` (${code})` : ""}`, error instanceof Error ? error : undefined);
+        const detail = typeof code === "string" && code.startsWith("ATTACHMENT_")
+            ? error instanceof Error
+                ? error.message
+                : String(error)
+            : `reading the file failed${code ? ` (${String(code)})` : ""}`;
+        throw STTError.audioLoadFailed(code === "ENOENT" ? "no file at the given path" : detail, error instanceof Error ? error : undefined);
     }
 }
 // ============================================================================
@@ -575,7 +591,7 @@ function sumTimings(corrections, key) {
 async function transcribeLayers(options, deps, startedAt) {
     const steps = [];
     // 1. Audio, and its container when the caller did not name one.
-    const { buffer, formatHint } = await loadTranscribeAudio(options.audio, options.timeoutMs);
+    const { buffer, formatHint } = await loadTranscribeAudio(options.audio, options.timeoutMs, deps.attachmentPolicy);
     if (buffer.length === 0) {
         throw STTError.audioEmpty(options.provider);
     }

package/dist/voice/whistle/audio.js

@@ -12,8 +12,7 @@
  * @module voice/whistle/audio
  */
 import { spawn } from "node:child_process";
-import { randomUUID } from "node:crypto";
-import { rm, writeFile } from "node:fs/promises";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { STT_ERROR_CODES } from "../../types/index.js";
@@ -209,8 +208,11 @@ function ffmpegUnavailable(format, cause) {
 async function decodeWithFfmpeg(audio, format) {
     const binary = await resolveFfmpeg();
     // A file, not a pipe: MP4/M4A often keep their index at the end, which a pipe cannot seek to.
-    const input = join(tmpdir(), `neurolink-whistle-${randomUUID()}.${format ?? "bin"}`);
-    await writeFile(input, audio);
+    // Its own mkdtemp directory (0o700) and an owner-only file: the recording is
+    // the caller's, and the OS temp directory is shared.
+    const dir = await mkdtemp(join(tmpdir(), "neurolink-whistle-"));
+    const input = join(dir, `input.${format ?? "bin"}`);
+    await writeFile(input, audio, { mode: 0o600, flag: "wx" });
     try {
         const raw = await new Promise((resolvePromise, reject) => {
             const proc = spawn(binary, [
@@ -218,6 +220,10 @@ async function decodeWithFfmpeg(audio, format) {
                 "-hide_banner",
                 "-loglevel",
                 "error",
+                // Pin the demuxer to local files: a container that references
+                // another URL or file cannot make ffmpeg open it.
+                "-protocol_whitelist",
+                "file,crypto,data",
                 "-i",
                 input,
                 "-f",
@@ -262,6 +268,6 @@ async function decodeWithFfmpeg(audio, format) {
         throw STTError.invalidFormat(`${format ?? "unknown"} (ffmpeg could not decode it: ${error instanceof Error ? error.message : String(error)})`, [...WHISTLE_NATIVE_FORMATS, ...WHISTLE_FFMPEG_FORMATS], "whistle");
     }
     finally {
-        await rm(input, { force: true }).catch(() => undefined);
+        await rm(dir, { recursive: true, force: true }).catch(() => undefined);
     }
 }