@juspay/neurolink 9.94.0 → 9.94.2

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/rag/document/loaders.d.ts

@@ -61,9 +61,20 @@ export declare class JSONLoader extends TextLoader {
 export declare class CSVLoader extends TextLoader {
     load(source: string, options?: CSVLoaderOptions): Promise<MDocument>;
     canHandle(source: string): boolean;
-    private parseCSVLine;
     private toMarkdownTable;
     private toTextTable;
+    /**
+     * Collapse embedded newlines to a single space so one logical CSV row
+     * renders as exactly one line in the text/markdown table output.
+     *
+     * The shared quote-aware parser (`splitCsvLines` + `splitCSVFields`)
+     * preserves newlines embedded inside a quoted field verbatim — correct
+     * for the `json` output format (where `JSON.stringify` escapes them), but
+     * left as-is here it would split a single record across multiple
+     * physical table rows. Mirrors the same normalization `CSVProcessor`
+     * already applies in its own markdown formatter.
+     */
+    private collapseEmbeddedNewlines;
 }
 /**
  * PDF file loader

package/dist/lib/rag/document/loaders.js

@@ -27,6 +27,8 @@ import { existsSync } from "fs";
 import { readFile } from "fs/promises";
 import { basename, extname } from "path";
 import { logger } from "../../utils/logger.js";
+import { CSVProcessor, stripBom, stripMetadataLine, splitCsvLines, } from "../../utils/csvProcessor.js";
+import { splitCSVFields } from "../../utils/csvUtils.js";
 import { MDocument } from "./MDocument.js";
 /**
  * Text file loader
@@ -115,13 +117,28 @@ export class JSONLoader extends TextLoader {
 export class CSVLoader extends TextLoader {
     async load(source, options) {
         const content = await this.loadContent(source, options?.encoding);
-        const { delimiter = ",", hasHeader = true, columns, outputFormat = "text", } = options || {};
-        const lines = content.split("\n").filter((line) => line.trim());
+        const { delimiter, hasHeader = true, columns, outputFormat = "text", } = options || {};
+        // #361: an explicit delimiter always wins; otherwise detect it from the
+        // content + extension so a .tsv fed through RAG isn't collapsed into one
+        // comma-column (CSVLoader.canHandle already accepts .tsv).
+        const effectiveDelimiter = delimiter ?? CSVProcessor.detectDelimiter(content, extname(source));
+        // Route header/row parsing through the same shared, quote-aware path
+        // detectDelimiter() above already uses internally: a quote-aware logical
+        // row split (splitCsvLines — a newline inside a quoted field stays part
+        // of that field instead of breaking the row) with a leading Excel `sep=`
+        // preamble line stripped (stripMetadataLine), so it can't be parsed as
+        // the header. Field-level splitting also goes through the shared
+        // RFC-4180-aware splitCSVFields() instead of the loader's own naive
+        // backslash-escape parser, which didn't handle doubled-quote (`""`)
+        // escaping or quoted delimiters in the headerless-columns branch.
+        const { dataLines: strippedLines } = stripMetadataLine(splitCsvLines(stripBom(content)));
+        const lines = strippedLines.filter((line) => line.trim());
         const headers = hasHeader
-            ? this.parseCSVLine(lines[0], delimiter)
-            : columns || lines[0]?.split(delimiter).map((_, i) => `col${i + 1}`);
+            ? splitCSVFields(lines[0] ?? "", effectiveDelimiter).map((h) => h.trim())
+            : columns ||
+                splitCSVFields(lines[0] ?? "", effectiveDelimiter).map((_, i) => `col${i + 1}`);
         const dataLines = hasHeader ? lines.slice(1) : lines;
-        const rows = dataLines.map((line) => this.parseCSVLine(line, delimiter));
+        const rows = dataLines.map((line) => splitCSVFields(line, effectiveDelimiter).map((field) => field.trim()));
         let formattedContent;
         switch (outputFormat) {
             case "json":
@@ -145,42 +162,39 @@ export class CSVLoader extends TextLoader {
         const ext = extname(source).toLowerCase();
         return ext === ".csv" || ext === ".tsv";
     }
-    parseCSVLine(line, delimiter) {
-        const result = [];
-        let current = "";
-        let inQuotes = false;
-        for (let i = 0; i < line.length; i++) {
-            const char = line[i];
-            if (char === '"' && (i === 0 || line[i - 1] !== "\\")) {
-                inQuotes = !inQuotes;
-            }
-            else if (char === delimiter && !inQuotes) {
-                result.push(current.trim());
-                current = "";
-            }
-            else {
-                current += char;
-            }
-        }
-        result.push(current.trim());
-        return result;
-    }
     toMarkdownTable(headers, rows) {
-        const headerRow = `| ${headers.join(" | ")} |`;
-        const separator = `| ${headers.map(() => "---").join(" | ")} |`;
-        const dataRows = rows.map((row) => `| ${row.join(" | ")} |`);
+        const safeHeaders = headers.map((h) => this.collapseEmbeddedNewlines(h));
+        const headerRow = `| ${safeHeaders.join(" | ")} |`;
+        const separator = `| ${safeHeaders.map(() => "---").join(" | ")} |`;
+        const dataRows = rows.map((row) => `| ${row.map((cell) => this.collapseEmbeddedNewlines(cell)).join(" | ")} |`);
         return [headerRow, separator, ...dataRows].join("\n");
     }
     toTextTable(headers, rows) {
-        const allRows = [headers, ...rows];
-        const colWidths = headers.map((_, i) => Math.max(...allRows.map((row) => (row[i] || "").length)));
+        const safeHeaders = headers.map((h) => this.collapseEmbeddedNewlines(h));
+        const safeRows = rows.map((row) => row.map((cell) => this.collapseEmbeddedNewlines(cell)));
+        const allRows = [safeHeaders, ...safeRows];
+        const colWidths = safeHeaders.map((_, i) => Math.max(...allRows.map((row) => (row[i] || "").length)));
         const formatRow = (row) => row.map((cell, i) => (cell || "").padEnd(colWidths[i])).join(" | ");
         return [
-            formatRow(headers),
+            formatRow(safeHeaders),
             colWidths.map((w) => "-".repeat(w)).join("-+-"),
-            ...rows.map(formatRow),
+            ...safeRows.map(formatRow),
         ].join("\n");
     }
+    /**
+     * Collapse embedded newlines to a single space so one logical CSV row
+     * renders as exactly one line in the text/markdown table output.
+     *
+     * The shared quote-aware parser (`splitCsvLines` + `splitCSVFields`)
+     * preserves newlines embedded inside a quoted field verbatim — correct
+     * for the `json` output format (where `JSON.stringify` escapes them), but
+     * left as-is here it would split a single record across multiple
+     * physical table rows. Mirrors the same normalization `CSVProcessor`
+     * already applies in its own markdown formatter.
+     */
+    collapseEmbeddedNewlines(cell) {
+        return cell.replace(/\r\n|\n|\r/g, " ");
+    }
 }
 /**
  * PDF file loader

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[];
+};