@juspay/neurolink 9.94.0 → 9.94.1

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [9.94.1](https://github.com/juspay/neurolink/compare/v9.94.0...v9.94.1) (2026-07-19)
+
+### Bug Fixes
+
+- **(cli):** play mp3 TTS on Linux via real decoders, not paplay ([#1138](https://github.com/juspay/neurolink/issues/1138)) ([a5a9a16](https://github.com/juspay/neurolink/commit/a5a9a16ef5fc71a084962faa031a74bb322155e2))
+- **(skills):** fail closed on scoped skills without a scopeId ([#1139](https://github.com/juspay/neurolink/issues/1139)) ([5ae7b9f](https://github.com/juspay/neurolink/commit/5ae7b9f77168262fdff54c6df03bb3103d34d1cc)), closes [#1135](https://github.com/juspay/neurolink/issues/1135)
+
 ## [9.94.0](https://github.com/juspay/neurolink/compare/v9.93.2...v9.94.0) (2026-07-19)
 
 ### Features

package/dist/browser/neurolink.min.js

@@ -1594,8 +1594,8 @@ Original size: ${ED(n)} | Externalized \u2014 use retrieve_context with artifact
 \u2022 Search through conversation history
 Supports filtering by role, pagination for large content, and regex search.
 To fetch an externalized artifact, provide \`artifactId\` (omit sessionId).`,inputSchema:m.object({sessionId:m.string().optional().describe("Session ID for conversation history retrieval. Required unless artifactId is provided."),artifactId:m.string().optional().describe("Artifact ID from an externalized MCP tool output (visible in the tool output as neurolinkArtifactId=<id>). When provided, returns the full stored payload directly."),messageId:m.string().optional().describe("Specific message ID to retrieve"),role:m.enum(["user","assistant","system","tool_call","tool_result"]).optional().describe("Filter messages by role"),lastN:m.number().int().positive().optional().describe("Retrieve the last N messages matching the filter"),offset:m.number().int().nonnegative().optional().describe("Character offset for paginated reading of large content (default: 0)"),limit:m.number().int().positive().optional().describe("Max characters to return per message (default: 50000)"),search:m.string().optional().describe("Regex pattern to search within message content. Returns matching lines with line numbers.")}),execute:async t=>Ke({name:"neurolink.memory.retrieve_context",tracer:_e.memory,attributes:{"memory.operation":t.artifactId?"artifact.fetch":"session.retrieve","memory.has_artifact_id":!!t.artifactId,"memory.has_session_id":!!t.sessionId,"memory.role":t.role??"any","memory.search":!!t.search}},async n=>u0r(t,r,e,n))}}}async function u0r(r,e,t,n){if(r.artifactId){if(!t)return g.warn("[MemoryRetrievalTools] retrieve_context called with artifactId but no ArtifactStore is configured"),n.setStatus({code:Me.ERROR,message:"Artifact store not configured"}),{error:"Artifact store not configured \u2014 mcp.outputLimits.strategy must be set to 'externalize' to use artifactId retrieval",artifactId:r.artifactId};let a=await Ge(t.retrieve(r.artifactId),1e4,new Error(`ArtifactStore.retrieve() timed out for artifact "${r.artifactId}"`));if(a===null)return n.setStatus({code:Me.ERROR,message:"Artifact not found or has expired"}),{error:"Artifact not found or has expired",artifactId:r.artifactId};let c=Math.min(r.limit??WHe,KHe),l=r.offset??0,u=a.slice(l,l+c);return n.setAttribute("memory.artifact_size",a.length),n.setAttribute("memory.returned_bytes",u.length),{artifactId:r.artifactId,content:u,totalSize:a.length,hasMore:l+c<a.length,offset:l,limit:c}}if(!r.sessionId)return n.setStatus({code:Me.ERROR,message:"sessionId is required when artifactId is not provided"}),{error:"sessionId is required when artifactId is not provided"};if(!e)return n.setStatus({code:Me.ERROR,message:"Memory manager not configured"}),{error:"Session history retrieval requires Redis conversation memory \u2014 enable mcp.conversationMemory with a Redis backend, or use artifactId to retrieve an externalized MCP tool output."};let o=xe.createSpan("memory","memory.retrieve",{"memory.operation":"retrieve","memory.store":"redis","memory.query":r.search||r.messageId||`lastN:${r.lastN??"all"}`}),s=Date.now(),i=String(r.sessionId);try{let a=await Ge(e.getSessionRaw(i),1e4,new Error(`getSessionRaw() timed out for session "${i}"`));if(!a){let p=xe.endSpan(o,2,`Session not found: ${i}`);return Ze().recordSpan(p),{error:"Session not found",sessionId:i}}let c=a.messages;if(r.messageId){let p=c.find(f=>f.id===r.messageId);if(!p){let f=xe.endSpan(o,2,`Message not found: ${r.messageId}`);return Ze().recordSpan(f),{error:"Message not found",messageId:r.messageId}}c=[p]}r.role&&(c=c.filter(p=>p.role===r.role)),r.lastN&&(c=c.slice(-r.lastN));let l=Math.min(r.limit??WHe,KHe),u=c.map(p=>{let f=p.content??"";if(r.search)try{let v=r.search;if(v.length>200)return{id:p.id,error:"Search pattern too long (max 200 chars)"};let T=v.replace(/[.*+?^${}()|[\]\\]/g,"\\$&"),S=new RegExp(T,"i"),C=f.split(`
-`).map((R,P)=>({line:P+1,text:R})).filter(R=>S.test(R.text)).slice(0,l0r);return{id:p.id,role:p.role,tool:p.tool,matchCount:C.length,matches:C,totalSize:f.length}}catch{return{id:p.id,error:"Invalid regex pattern"}}let h=r.offset??0,y=h+l,x=f.slice(h,y);return{id:p.id,role:p.role,tool:p.tool,content:x,totalSize:f.length,hasMore:y<f.length}});o.durationMs=Date.now()-s;let d=xe.endSpan(o,1);return Ze().recordSpan(d),n.setAttribute("memory.message_count",u.length),{messages:u,totalMessages:u.length}}catch(a){o.durationMs=Date.now()-s;let c=xe.endSpan(o,2);return c.statusMessage=a instanceof Error?a.message:String(a),Ze().recordSpan(c),g.error("[MemoryRetrievalTools] Error retrieving context",{error:a instanceof Error?a.message:String(a)}),n.setStatus({code:Me.ERROR,message:a instanceof Error?a.message:String(a)}),n.recordException(a instanceof Error?a:new Error(String(a))),{error:"Failed to retrieve context"}}}var WHe,KHe,l0r,JHe=k(()=>{"use strict";Dr();Jn();q();It();xo();Cn();Vr();WHe=5e4,KHe=2e5,l0r=50});function Px(r){let{instructions:e,...t}=r;return t}function XHe(r){return[...r].sort((e,t)=>e.name<t.name?-1:e.name>t.name?1:0)}function Rde(r,e){let t=e.query?.toLowerCase(),n=e.tag?.toLowerCase(),o=r.filter(s=>!((s.status??"active")!=="active"||e.scopeId&&s.scope==="scoped"&&!(s.scopeIds??[]).includes(e.scopeId)||t&&!(s.name.toLowerCase().includes(t)||(s.displayName??"").toLowerCase().includes(t)||s.description.toLowerCase().includes(t))||n&&!(s.tags??[]).some(a=>a.toLowerCase().includes(n))));return e.limit!==void 0?o.slice(0,e.limit):o}function A3(r){let e=r.replace(/\\/g,"/");return e.length>0&&!e.startsWith("/")&&!e.split("/").some(t=>t===".."||t==="")}function kD(r,e){return!e||r.scope!=="scoped"?!0:(r.scopeIds??[]).includes(e)}function YHe(r){let e=r.match(/^[^.!?]*[.!?]/);return e?e[0].trim():r}function ZHe(r,e){if(r.length===0)return null;let t=i=>["<available_skills>",...r.map(c=>{let l=c.tags&&c.tags.length>0?` [tags: ${c.tags.join(", ")}]`:"";return`- ${c.name}: ${i(c)}${l}`}),"</available_skills>"].join(`
-`),n=t(i=>i.description);if(n.length<=e)return n;let o=t(i=>YHe(i.description));if(o.length<=e)return o;let s=80;return t(i=>{let a=YHe(i.description);return a.length>s?`${a.slice(0,s-1)}\u2026`:a})}function QHe(r,e){if(r.length===0)return null;let t=r.slice(0,e),n=t.map(s=>{let i=s.displayName?`${s.name} (${s.displayName})`:s.name,a=s.tags&&s.tags.length>0?` [tags: ${s.tags.join(", ")}]`:"";return`- ${i}: ${s.description}${a}`}),o=r.length>t.length?`
+`).map((R,P)=>({line:P+1,text:R})).filter(R=>S.test(R.text)).slice(0,l0r);return{id:p.id,role:p.role,tool:p.tool,matchCount:C.length,matches:C,totalSize:f.length}}catch{return{id:p.id,error:"Invalid regex pattern"}}let h=r.offset??0,y=h+l,x=f.slice(h,y);return{id:p.id,role:p.role,tool:p.tool,content:x,totalSize:f.length,hasMore:y<f.length}});o.durationMs=Date.now()-s;let d=xe.endSpan(o,1);return Ze().recordSpan(d),n.setAttribute("memory.message_count",u.length),{messages:u,totalMessages:u.length}}catch(a){o.durationMs=Date.now()-s;let c=xe.endSpan(o,2);return c.statusMessage=a instanceof Error?a.message:String(a),Ze().recordSpan(c),g.error("[MemoryRetrievalTools] Error retrieving context",{error:a instanceof Error?a.message:String(a)}),n.setStatus({code:Me.ERROR,message:a instanceof Error?a.message:String(a)}),n.recordException(a instanceof Error?a:new Error(String(a))),{error:"Failed to retrieve context"}}}var WHe,KHe,l0r,JHe=k(()=>{"use strict";Dr();Jn();q();It();xo();Cn();Vr();WHe=5e4,KHe=2e5,l0r=50});function Px(r){let{instructions:e,...t}=r;return t}function XHe(r){return[...r].sort((e,t)=>e.name<t.name?-1:e.name>t.name?1:0)}function Rde(r,e){let t=e.query?.toLowerCase(),n=e.tag?.toLowerCase(),o=r.filter(s=>!((s.status??"active")!=="active"||s.scope==="scoped"&&(!e.scopeId||!(s.scopeIds??[]).includes(e.scopeId))||t&&!(s.name.toLowerCase().includes(t)||(s.displayName??"").toLowerCase().includes(t)||s.description.toLowerCase().includes(t))||n&&!(s.tags??[]).some(a=>a.toLowerCase().includes(n))));return e.limit!==void 0?o.slice(0,e.limit):o}function A3(r){let e=r.replace(/\\/g,"/");return e.length>0&&!e.startsWith("/")&&!e.split("/").some(t=>t===".."||t==="")}function kD(r,e){return r.scope!=="scoped"?!0:e?(r.scopeIds??[]).includes(e):!1}function YHe(r){let e=r.match(/^[^.!?]*[.!?]/);return e?e[0].trim():r}function ZHe(r,e){if(r.length===0)return null;let t=i=>["<available_skills>",...r.map(c=>{let l=c.tags&&c.tags.length>0?` [tags: ${c.tags.join(", ")}]`:"";return`- ${c.name}: ${i(c)}${l}`}),"</available_skills>"].join(`
+`),n=t(i=>i.description);if(n.length<=e)return n;let o=t(i=>YHe(i.description));if(o.length<=e)return o;let s=80;return t(i=>{let a=YHe(i.description);return a.length>s?`${a.slice(0,s-1)}\u2026`:a})}function QHe(r,e){if(r.length===0||e<=0)return null;let t=r.slice(0,e),n=t.map(s=>{let i=s.displayName?`${s.name} (${s.displayName})`:s.name,a=s.tags&&s.tags.length>0?` [tags: ${s.tags.join(", ")}]`:"";return`- ${i}: ${s.description}${a}`}),o=r.length>t.length?`
 (${r.length-t.length} more skills exist \u2014 use list_skills to discover them.)`:"";return["## Available Skills","The following team-defined skills (SOPs, playbooks, workflows) are available.","Before answering from general knowledge, check whether one applies to the user's request.","To use a skill, call the use_skill tool with its name to load the full instructions, then follow them exactly.","",...n].join(`
 `)+o}var JT=k(()=>{"use strict"});function Ide(r){let e=r.version??1;return{id:`skill-${bs()}`,role:"user",content:`[Skill loaded: ${r.name} v${e}]
 

package/dist/cli/utils/audioPlayer.d.ts

@@ -6,32 +6,67 @@
  *
  * @module cli/utils/audioPlayer
  */
-import type { AudioFormat } from "../../lib/types/index.js";
+import type { TTSAudioFormat, CliAudioPlayerCommand } from "../../lib/types/index.js";
 /**
  * Get the file extension for an audio format
  *
  * @param format - Audio format
  * @returns File extension string (e.g., "mp3", "wav")
  */
-export declare function getAudioExtension(format: AudioFormat): string;
+export declare function getAudioExtension(format: TTSAudioFormat): string;
+/**
+ * Escape a value for interpolation inside a single-quoted PowerShell string.
+ * PowerShell's single-quoted strings only treat `''` as a literal `'` — unlike
+ * shell/execFile argv, this string is parsed by powershell.exe itself, so an
+ * unescaped quote (e.g. a Windows username like `O'Brien` under `%TEMP%`)
+ * would break out of the string and let the remainder run as PS code.
+ */
+export declare function escapePowerShellSingleQuoted(value: string): string;
+/**
+ * Build the ordered list of player commands to try for a file.
+ *
+ * The list is tried in order until one succeeds; a missing binary (ENOENT) or a
+ * decode failure simply advances to the next candidate.
+ *
+ * The Linux ordering is the crux of the mp3-playback fix (#1138): `paplay`
+ * (PulseAudio) and `aplay` (ALSA) only decode libsndfile/PCM formats and
+ * **cannot** decode mp3/AAC. Since `--tts-format` defaults to mp3, compressed
+ * formats must lead with real decoders (ffplay/mpv/mpg123/cvlc); paplay/aplay
+ * remain only as last-resort fallbacks (and still work for wav/ogg).
+ *
+ * @param filePath - Path to the audio file
+ * @param format - Audio format
+ * @param platform - Platform id (defaults to `process.platform`; injectable for tests)
+ * @returns Ordered player commands; empty for unsupported platforms
+ */
+export declare function getPlayerCandidates(filePath: string, format: TTSAudioFormat, platform?: NodeJS.Platform): CliAudioPlayerCommand[];
+/**
+ * Build a helpful, format-aware error message when no player could decode the file.
+ *
+ * Exported for testing: the message a user sees when Linux mp3 playback finds no
+ * decoder must name the real fix (ffmpeg/mpv/mpg123/VLC or `--tts-format wav`),
+ * not the misleading "install PulseAudio" that paplay-only routing produced (#1138).
+ */
+export declare function buildPlaybackErrorMessage(platform: NodeJS.Platform, format: TTSAudioFormat, attempts: string[]): string;
 /**
  * Play audio from a buffer using platform-specific CLI tools
  *
- * Writes the buffer to a temporary file, plays it using the appropriate
- * system audio player, and cleans up the temp file afterward.
+ * Writes the buffer to a temporary file, plays it using the first available
+ * system audio player that can decode the format, and cleans up the temp file.
  *
  * Supported platforms:
- * - macOS: uses `afplay` (built-in, supports mp3/wav/aac/flac)
- * - Linux: uses `paplay` for non-wav, `aplay` for wav
- * - Windows: uses PowerShell SoundPlayer (wav) or WMPlayer.OCX (mp3)
+ * - macOS: `afplay` (built-in; decodes mp3/wav/aac/flac)
+ * - Linux: real decoders (ffplay/mpv/mpg123/cvlc) for compressed formats,
+ *   aplay/paplay for wav — falling through the list until one works
+ * - Windows: PowerShell SoundPlayer (wav) or WMPlayer.OCX (compressed)
  *
  * @param buffer - Audio data buffer
  * @param format - Audio format (mp3, wav, ogg, opus)
- * @throws Error if playback fails or platform is unsupported
+ * @throws Error if no available player can play the audio, or platform is unsupported
  *
  * @example
  * ```typescript
  * await playAudio(audioBuffer, "mp3");
  * ```
  */
-export declare function playAudio(buffer: Buffer, format: AudioFormat): Promise<void>;
+export declare function playAudio(buffer: Buffer, format: TTSAudioFormat): Promise<void>;

package/dist/cli/utils/audioPlayer.js

@@ -7,11 +7,25 @@
  * @module cli/utils/audioPlayer
  */
 import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
+/** Wall-clock cap on a single player invocation; a hung decoder must not block the CLI forever. */
+const PLAYER_TIMEOUT_MS = 30_000;
+/**
+ * Single source of truth for format -> temp-file-extension. Formats outside this
+ * playback-supported set (m4a, flac, webm, mp4, mpeg, mpga, pcm16) fall back to
+ * "mp3" — `playAudio` only ever receives the four formats below in practice.
+ */
+const AUDIO_EXTENSIONS = {
+    mp3: "mp3",
+    wav: "wav",
+    ogg: "ogg",
+    opus: "opus",
+};
 /**
  * Get the file extension for an audio format
  *
@@ -19,73 +33,145 @@ const execFileAsync = promisify(execFile);
  * @returns File extension string (e.g., "mp3", "wav")
  */
 export function getAudioExtension(format) {
-    switch (format) {
-        case "mp3":
-            return "mp3";
-        case "wav":
-            return "wav";
-        case "ogg":
-            return "ogg";
-        case "opus":
-            return "opus";
-        default:
-            return "mp3";
-    }
+    return AUDIO_EXTENSIONS[format] ?? "mp3";
+}
+/** ffmpeg's ffplay decodes every format we emit; quiet + auto-exit for CLI use. */
+function ffplayCommand(filePath) {
+    return {
+        command: "ffplay",
+        args: ["-nodisp", "-autoexit", "-loglevel", "quiet", filePath],
+    };
 }
 /**
- * Get the platform-specific audio player command and arguments
+ * Escape a value for interpolation inside a single-quoted PowerShell string.
+ * PowerShell's single-quoted strings only treat `''` as a literal `'` — unlike
+ * shell/execFile argv, this string is parsed by powershell.exe itself, so an
+ * unescaped quote (e.g. a Windows username like `O'Brien` under `%TEMP%`)
+ * would break out of the string and let the remainder run as PS code.
+ */
+export function escapePowerShellSingleQuoted(value) {
+    return value.replace(/'/g, "''");
+}
+/**
+ * Build the ordered list of player commands to try for a file.
+ *
+ * The list is tried in order until one succeeds; a missing binary (ENOENT) or a
+ * decode failure simply advances to the next candidate.
+ *
+ * The Linux ordering is the crux of the mp3-playback fix (#1138): `paplay`
+ * (PulseAudio) and `aplay` (ALSA) only decode libsndfile/PCM formats and
+ * **cannot** decode mp3/AAC. Since `--tts-format` defaults to mp3, compressed
+ * formats must lead with real decoders (ffplay/mpv/mpg123/cvlc); paplay/aplay
+ * remain only as last-resort fallbacks (and still work for wav/ogg).
  *
  * @param filePath - Path to the audio file
  * @param format - Audio format
- * @returns Object with command and args for execFile
+ * @param platform - Platform id (defaults to `process.platform`; injectable for tests)
+ * @returns Ordered player commands; empty for unsupported platforms
  */
-function getPlayerCommand(filePath, format) {
-    const platform = process.platform;
+export function getPlayerCandidates(filePath, format, platform = process.platform) {
+    const isWav = format === "wav";
     switch (platform) {
         case "darwin":
-            return { command: "afplay", args: [filePath] };
+            // afplay decodes mp3/wav/aac/flac natively.
+            return [{ command: "afplay", args: [filePath] }];
         case "linux":
-            if (format === "wav") {
-                return { command: "aplay", args: [filePath] };
+            if (isWav) {
+                // WAV/PCM: ALSA and PulseAudio both decode it; ffplay as a backstop.
+                return [
+                    { command: "aplay", args: [filePath] },
+                    { command: "paplay", args: [filePath] },
+                    ffplayCommand(filePath),
+                ];
+            }
+            // Compressed formats (mp3/ogg/opus): lead with decoders that actually
+            // handle them, then fall back to paplay/aplay (which work for some
+            // formats but never mp3).
+            return [
+                ffplayCommand(filePath),
+                {
+                    command: "mpv",
+                    args: ["--no-video", "--really-quiet", filePath],
+                },
+                ...(format === "mp3"
+                    ? [{ command: "mpg123", args: ["-q", filePath] }]
+                    : []),
+                {
+                    command: "cvlc",
+                    args: ["--play-and-exit", "--no-loop", "--intf", "dummy", filePath],
+                },
+                { command: "paplay", args: [filePath] },
+                { command: "aplay", args: [filePath] },
+            ];
+        case "win32": {
+            // filePath is embedded inside a single-quoted PS string below, so it must
+            // be escaped — a Windows username with an apostrophe (e.g. `O'Brien`,
+            // present in `%TEMP%`) would otherwise break out of the string.
+            const psPath = escapePowerShellSingleQuoted(filePath);
+            if (isWav) {
+                return [
+                    {
+                        command: "powershell",
+                        args: [
+                            "-NoProfile",
+                            "-Command",
+                            `(New-Object System.Media.SoundPlayer '${psPath}').PlaySync()`,
+                        ],
+                    },
+                ];
             }
-            return { command: "paplay", args: [filePath] };
-        case "win32":
-            if (format === "wav") {
-                return {
+            return [
+                {
                     command: "powershell",
                     args: [
                         "-NoProfile",
                         "-Command",
-                        `(New-Object System.Media.SoundPlayer '${filePath}').PlaySync()`,
+                        `$player = New-Object -ComObject WMPlayer.OCX; $player.URL = '${psPath}'; $player.controls.play(); Start-Sleep -Seconds 1; while ($player.playState -eq 3) { Start-Sleep -Milliseconds 100 }; $player.close()`,
                     ],
-                };
-            }
-            return {
-                command: "powershell",
-                args: [
-                    "-NoProfile",
-                    "-Command",
-                    `$player = New-Object -ComObject WMPlayer.OCX; $player.URL = '${filePath}'; $player.controls.play(); Start-Sleep -Seconds 1; while ($player.playState -eq 3) { Start-Sleep -Milliseconds 100 }; $player.close()`,
-                ],
-            };
+                },
+            ];
+        }
         default:
-            throw new Error(`Unsupported platform: ${platform}. Audio playback is supported on macOS, Linux, and Windows.`);
+            return [];
     }
 }
+/**
+ * Build a helpful, format-aware error message when no player could decode the file.
+ *
+ * Exported for testing: the message a user sees when Linux mp3 playback finds no
+ * decoder must name the real fix (ffmpeg/mpv/mpg123/VLC or `--tts-format wav`),
+ * not the misleading "install PulseAudio" that paplay-only routing produced (#1138).
+ */
+export function buildPlaybackErrorMessage(platform, format, attempts) {
+    const tried = attempts.length ? ` (tried: ${attempts.join("; ")})` : "";
+    if (platform === "linux") {
+        if (format === "wav") {
+            return `Could not play wav audio${tried}. Install ALSA (aplay) or PulseAudio (paplay).`;
+        }
+        // mpg123 only decodes mp3 (see getPlayerCandidates) — recommending it for
+        // ogg/opus failures would send users chasing a decoder that can't help.
+        if (format === "mp3") {
+            return `Could not play mp3 audio${tried}. paplay/aplay cannot decode mp3; install one of: ffmpeg (ffplay), mpv, mpg123, or VLC (cvlc) — or use --tts-format wav.`;
+        }
+        return `Could not play ${format} audio${tried}. Install ffmpeg (ffplay), mpv, or VLC (cvlc) — or use --tts-format wav.`;
+    }
+    return `Could not play ${format} audio${tried}. Ensure a system audio player is installed and available in PATH.`;
+}
 /**
  * Play audio from a buffer using platform-specific CLI tools
  *
- * Writes the buffer to a temporary file, plays it using the appropriate
- * system audio player, and cleans up the temp file afterward.
+ * Writes the buffer to a temporary file, plays it using the first available
+ * system audio player that can decode the format, and cleans up the temp file.
  *
  * Supported platforms:
- * - macOS: uses `afplay` (built-in, supports mp3/wav/aac/flac)
- * - Linux: uses `paplay` for non-wav, `aplay` for wav
- * - Windows: uses PowerShell SoundPlayer (wav) or WMPlayer.OCX (mp3)
+ * - macOS: `afplay` (built-in; decodes mp3/wav/aac/flac)
+ * - Linux: real decoders (ffplay/mpv/mpg123/cvlc) for compressed formats,
+ *   aplay/paplay for wav — falling through the list until one works
+ * - Windows: PowerShell SoundPlayer (wav) or WMPlayer.OCX (compressed)
  *
  * @param buffer - Audio data buffer
  * @param format - Audio format (mp3, wav, ogg, opus)
- * @throws Error if playback fails or platform is unsupported
+ * @throws Error if no available player can play the audio, or platform is unsupported
  *
  * @example
  * ```typescript
@@ -94,36 +180,47 @@ function getPlayerCommand(filePath, format) {
  */
 export async function playAudio(buffer, format) {
     const ext = getAudioExtension(format);
-    const tempFile = path.join(os.tmpdir(), `nl-tts-${Date.now()}.${ext}`);
+    // randomUUID (not just Date.now()) avoids two concurrent calls in the same
+    // millisecond racing on the same temp path.
+    const tempFile = path.join(os.tmpdir(), `nl-tts-${randomUUID()}.${ext}`);
     try {
         // Write audio buffer to temp file
         await fs.promises.writeFile(tempFile, buffer);
-        const { command, args } = getPlayerCommand(tempFile, format);
-        try {
-            await execFileAsync(command, args);
+        const candidates = getPlayerCandidates(tempFile, format);
+        if (candidates.length === 0) {
+            throw new Error(`Unsupported platform: ${process.platform}. Audio playback is supported on macOS, Linux, and Windows.`);
         }
-        catch (execError) {
-            const err = execError;
-            // Handle binary not found
-            if (err.code === "ENOENT") {
-                if (process.platform === "linux" && command === "paplay") {
-                    // Fallback to aplay on Linux
-                    try {
-                        await execFileAsync("aplay", [tempFile]);
-                        return;
-                    }
-                    catch (fallbackError) {
-                        const fbErr = fallbackError;
-                        if (fbErr.code === "ENOENT") {
-                            throw new Error("Neither paplay nor aplay found. Install PulseAudio (paplay) or ALSA (aplay) for audio playback.", { cause: fallbackError });
-                        }
-                        throw fallbackError;
-                    }
-                }
-                throw new Error(`Audio player '${command}' not found. Ensure it is installed and available in PATH.`, { cause: execError });
+        const attempts = [];
+        for (const { command, args } of candidates) {
+            try {
+                // `timeout` guards against a hung decoder (e.g. blocked on the audio
+                // device) so playback can't stall the CLI forever; SIGTERM lets the
+                // player shut down cleanly before Node force-kills it.
+                await execFileAsync(command, args, {
+                    timeout: PLAYER_TIMEOUT_MS,
+                    killSignal: "SIGTERM",
+                });
+                return; // Played successfully.
+            }
+            catch (execError) {
+                const err = execError;
+                // Every failure (missing binary, decode error, or timeout) is
+                // recorded and surfaced in the final error below — none are lost.
+                // We still advance to the next candidate rather than aborting on the
+                // first non-ENOENT failure: `command` existing but failing on this
+                // particular file (e.g. a corrupt stream, or one decoder lacking
+                // codec support) doesn't mean the *next* candidate will fail too,
+                // and failing fast here would defeat the multi-decoder fallback
+                // that #1138 exists to provide.
+                const detail = err.killed
+                    ? `timed out after ${PLAYER_TIMEOUT_MS}ms`
+                    : err.code === "ENOENT"
+                        ? "not installed"
+                        : (err.message ?? "failed");
+                attempts.push(`${command}: ${detail}`);
             }
-            throw execError;
         }
+        throw new Error(buildPlaybackErrorMessage(process.platform, format, attempts));
     }
     finally {
         // Always clean up temp file

package/dist/lib/skills/skillMatcher.d.ts

@@ -26,7 +26,13 @@ export declare function filterSkillIndex(items: SkillIndexItem[], query: SkillSe
  * keys are built by concatenation (S3, Redis) or path joining.
  */
 export declare function isSafeSkillResourcePath(resourcePath: string): boolean;
-/** Whether a skill is visible from the calling scope. */
+/**
+ * Whether a skill is visible from the calling scope. Fails closed, matching
+ * `filterSkillIndex`: a scoped skill is hidden unless the caller supplies a
+ * `scopeId` that the skill explicitly lists. Omitting `scopeId` therefore
+ * yields global skills only — it must never expose a scoped skill by name
+ * through `use_skill` / `read_skill_resource` (#1139).
+ */
 export declare function isSkillVisibleInScope(skill: Pick<SkillDefinition, "scope" | "scopeIds">, scopeId?: string): boolean;
 /**
  * Render the `<available_skills>` block embedded in the use_skill tool

package/dist/lib/skills/skillMatcher.js

@@ -29,11 +29,14 @@ export function filterSkillIndex(items, query) {
         if ((item.status ?? "active") !== "active") {
             return false;
         }
-        // Scope filter: global skills always pass; scoped skills require a
-        // matching scopeId. When the caller provides no scopeId, scoped skills
-        // still pass (curator semantics — unscoped callers see everything).
-        if (query.scopeId && item.scope === "scoped") {
-            if (!(item.scopeIds ?? []).includes(query.scopeId)) {
+        // Scope filter: global skills always pass. Scoped skills require a
+        // scopeId that matches; when the caller supplies no scopeId we fail
+        // closed and exclude them, so a shared multi-tenant instance that forgets
+        // to pass a per-call scopeId never leaks one tenant's scoped skills to
+        // everyone (#1139). Callers that legitimately want a tenant's scoped
+        // skills must pass that tenant's scopeId.
+        if (item.scope === "scoped") {
+            if (!query.scopeId || !(item.scopeIds ?? []).includes(query.scopeId)) {
                 return false;
             }
         }
@@ -67,11 +70,20 @@ export function isSafeSkillResourcePath(resourcePath) {
         !normalized.startsWith("/") &&
         !normalized.split("/").some((segment) => segment === ".." || segment === ""));
 }
-/** Whether a skill is visible from the calling scope. */
+/**
+ * Whether a skill is visible from the calling scope. Fails closed, matching
+ * `filterSkillIndex`: a scoped skill is hidden unless the caller supplies a
+ * `scopeId` that the skill explicitly lists. Omitting `scopeId` therefore
+ * yields global skills only — it must never expose a scoped skill by name
+ * through `use_skill` / `read_skill_resource` (#1139).
+ */
 export function isSkillVisibleInScope(skill, scopeId) {
-    if (!scopeId || skill.scope !== "scoped") {
+    if (skill.scope !== "scoped") {
         return true;
     }
+    if (!scopeId) {
+        return false;
+    }
     return (skill.scopeIds ?? []).includes(scopeId);
 }
 /** Trim a description to its first sentence (or the whole text when unsplittable). */
@@ -127,7 +139,10 @@ export function renderSkillListing(items, budgetChars) {
  * Returns null when nothing is visible so callers can skip injection.
  */
 export function formatSkillsPromptIndex(items, maxItems) {
-    if (items.length === 0) {
+    // Nothing visible, or the index is explicitly disabled (maxItems <= 0):
+    // skip injection entirely rather than emit a header + "N more skills exist"
+    // note with zero skill lines (#1139).
+    if (items.length === 0 || maxItems <= 0) {
         return null;
     }
     const visible = items.slice(0, maxItems);

package/dist/lib/types/cli.d.ts

@@ -1675,3 +1675,12 @@ export type CliNetworkCommandArgs = BaseCommandArgs & {
     /** Show detailed information */
     detailed?: boolean;
 };
+/**
+ * A single audio-player invocation for CLI TTS playback: a binary plus its
+ * arguments for `execFile`. The player list is tried in order until one
+ * succeeds (see `src/cli/utils/audioPlayer.ts`).
+ */
+export type CliAudioPlayerCommand = {
+    command: string;
+    args: string[];
+};

package/dist/skills/skillMatcher.d.ts

@@ -26,7 +26,13 @@ export declare function filterSkillIndex(items: SkillIndexItem[], query: SkillSe
  * keys are built by concatenation (S3, Redis) or path joining.
  */
 export declare function isSafeSkillResourcePath(resourcePath: string): boolean;
-/** Whether a skill is visible from the calling scope. */
+/**
+ * Whether a skill is visible from the calling scope. Fails closed, matching
+ * `filterSkillIndex`: a scoped skill is hidden unless the caller supplies a
+ * `scopeId` that the skill explicitly lists. Omitting `scopeId` therefore
+ * yields global skills only — it must never expose a scoped skill by name
+ * through `use_skill` / `read_skill_resource` (#1139).
+ */
 export declare function isSkillVisibleInScope(skill: Pick<SkillDefinition, "scope" | "scopeIds">, scopeId?: string): boolean;
 /**
  * Render the `<available_skills>` block embedded in the use_skill tool

package/dist/skills/skillMatcher.js

@@ -29,11 +29,14 @@ export function filterSkillIndex(items, query) {
         if ((item.status ?? "active") !== "active") {
             return false;
         }
-        // Scope filter: global skills always pass; scoped skills require a
-        // matching scopeId. When the caller provides no scopeId, scoped skills
-        // still pass (curator semantics — unscoped callers see everything).
-        if (query.scopeId && item.scope === "scoped") {
-            if (!(item.scopeIds ?? []).includes(query.scopeId)) {
+        // Scope filter: global skills always pass. Scoped skills require a
+        // scopeId that matches; when the caller supplies no scopeId we fail
+        // closed and exclude them, so a shared multi-tenant instance that forgets
+        // to pass a per-call scopeId never leaks one tenant's scoped skills to
+        // everyone (#1139). Callers that legitimately want a tenant's scoped
+        // skills must pass that tenant's scopeId.
+        if (item.scope === "scoped") {
+            if (!query.scopeId || !(item.scopeIds ?? []).includes(query.scopeId)) {
                 return false;
             }
         }
@@ -67,11 +70,20 @@ export function isSafeSkillResourcePath(resourcePath) {
         !normalized.startsWith("/") &&
         !normalized.split("/").some((segment) => segment === ".." || segment === ""));
 }
-/** Whether a skill is visible from the calling scope. */
+/**
+ * Whether a skill is visible from the calling scope. Fails closed, matching
+ * `filterSkillIndex`: a scoped skill is hidden unless the caller supplies a
+ * `scopeId` that the skill explicitly lists. Omitting `scopeId` therefore
+ * yields global skills only — it must never expose a scoped skill by name
+ * through `use_skill` / `read_skill_resource` (#1139).
+ */
 export function isSkillVisibleInScope(skill, scopeId) {
-    if (!scopeId || skill.scope !== "scoped") {
+    if (skill.scope !== "scoped") {
         return true;
     }
+    if (!scopeId) {
+        return false;
+    }
     return (skill.scopeIds ?? []).includes(scopeId);
 }
 /** Trim a description to its first sentence (or the whole text when unsplittable). */
@@ -127,7 +139,10 @@ export function renderSkillListing(items, budgetChars) {
  * Returns null when nothing is visible so callers can skip injection.
  */
 export function formatSkillsPromptIndex(items, maxItems) {
-    if (items.length === 0) {
+    // Nothing visible, or the index is explicitly disabled (maxItems <= 0):
+    // skip injection entirely rather than emit a header + "N more skills exist"
+    // note with zero skill lines (#1139).
+    if (items.length === 0 || maxItems <= 0) {
         return null;
     }
     const visible = items.slice(0, maxItems);

package/dist/types/cli.d.ts

@@ -1675,3 +1675,12 @@ export type CliNetworkCommandArgs = BaseCommandArgs & {
     /** Show detailed information */
     detailed?: boolean;
 };
+/**
+ * A single audio-player invocation for CLI TTS playback: a binary plus its
+ * arguments for `execFile`. The player list is tried in order until one
+ * succeeds (see `src/cli/utils/audioPlayer.ts`).
+ */
+export type CliAudioPlayerCommand = {
+    command: string;
+    args: string[];
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "9.94.0",
+  "version": "9.94.1",
   "packageManager": "pnpm@10.15.1",
   "description": "TypeScript AI SDK with 24+ LLM providers behind one consistent API. MCP-native (connect any MCP server), voice TTS/STT/realtime, RAG, agents, memory, context compaction. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · DeepSeek · NVIDIA NIM and more.",
   "author": {