@juspay/neurolink 10.11.2 → 10.12.0

package/dist/cli/commands/auth.d.ts

@@ -17,7 +17,7 @@
  * Currently supports:
  * - Anthropic (API key + OAuth)
  */
-import type { AuthCommandArgs } from "../../lib/types/index.js";
+import type { AccountQuota, AuthCommandArgs } from "../../lib/types/index.js";
 /**
  * Handle the login subcommand
  * `neurolink auth login <provider>`
@@ -26,6 +26,13 @@ import type { AuthCommandArgs } from "../../lib/types/index.js";
  * (e.g., "anthropic:alice") to support multi-account pools.
  */
 export declare function handleLogin(argv: AuthCommandArgs): Promise<void>;
+/**
+ * Format the dynamic per-plan limit windows (model-scoped weeklies such as
+ * Fable, plus any future kinds) as extra display lines. `session` and
+ * `weekly_all` are omitted — they already render as the SESSION / WEEKLY
+ * columns. Exported for the continuous test suite.
+ */
+export declare function formatQuotaWindowRows(quota: AccountQuota): string[];
 /**
  * Handle the list subcommand
  * `neurolink auth list`

package/dist/cli/commands/auth.js

@@ -27,7 +27,8 @@ import ora from "ora";
 import { logger } from "../../lib/utils/logger.js";
 import { defaultTokenStore } from "../../lib/auth/tokenStore.js";
 import { CLAUDE_CODE_CLIENT_ID, ANTHROPIC_AUTH_URL, ANTHROPIC_TOKEN_URL, ANTHROPIC_REDIRECT_URI, CLAUDE_CLI_USER_AGENT, OAUTH_BETA_HEADERS, } from "../../lib/auth/anthropicOAuth.js";
-import { loadAccountQuotas } from "../../lib/proxy/accountQuota.js";
+import { flushAccountQuotas, loadAccountQuotas, saveAccountQuota, } from "../../lib/proxy/accountQuota.js";
+import { fetchAccountUsage, listAnthropicAccountsForUsage, usageToQuota, } from "../../lib/proxy/accountUsage.js";
 // =============================================================================
 // CONSTANTS
 // =============================================================================
@@ -161,6 +162,137 @@ function formatQuotaColumns(quota) {
             : "",
     };
 }
+/**
+ * Format the dynamic per-plan limit windows (model-scoped weeklies such as
+ * Fable, plus any future kinds) as extra display lines. `session` and
+ * `weekly_all` are omitted — they already render as the SESSION / WEEKLY
+ * columns. Exported for the continuous test suite.
+ */
+export function formatQuotaWindowRows(quota) {
+    if (!quota.windows?.length) {
+        return [];
+    }
+    const colorize = (pct, text) => {
+        if (pct <= 10) {
+            return chalk.red(text);
+        }
+        if (pct <= 30) {
+            return chalk.yellow(text);
+        }
+        return chalk.green(text);
+    };
+    const rows = [];
+    for (const window of quota.windows) {
+        if (window.kind === "session" || window.kind === "weekly_all") {
+            continue;
+        }
+        const remaining = Math.round((1 - window.used) * 100);
+        const label = window.scopeModel
+            ? `${window.group ?? window.kind} (${window.scopeModel})`
+            : window.kind;
+        const reset = window.resetsAt > 0
+            ? chalk.gray(`  resets ${formatTimeUntil(window.resetsAt)}`)
+            : "";
+        rows.push(`${chalk.gray(`${label}:`)} ${colorize(remaining, `${remaining}% left`)}${reset}`);
+    }
+    return rows;
+}
+/**
+ * Fetch fresh limits for `auth list --refresh`.
+ *
+ * Prefers the running proxy's GET /limits endpoint so the proxy's in-memory
+ * routing state is refreshed as a side effect; falls back to fetching the
+ * usage endpoint directly from this process (persisting through the same
+ * quota store) when no proxy is running or the call fails.
+ */
+async function refreshAccountLimitsForList() {
+    const errors = [];
+    const proxyState = detectRunningProxyState();
+    if (proxyState?.port) {
+        const host = proxyState.host && proxyState.host !== "0.0.0.0"
+            ? proxyState.host
+            : "127.0.0.1";
+        try {
+            const response = await fetch(`http://${host}:${proxyState.port}/limits`, {
+                signal: AbortSignal.timeout(45_000),
+            });
+            if (response.ok) {
+                const payload = (await response.json());
+                const quotas = {};
+                for (const result of payload.results) {
+                    if (result.quota) {
+                        quotas[result.account] = result.quota;
+                    }
+                    if (result.status === "error" && result.error) {
+                        errors.push(`${result.account}: ${result.error}`);
+                    }
+                }
+                return { via: "proxy", quotas, errors };
+            }
+            errors.push(`running proxy /limits returned HTTP ${response.status}; fetching directly`);
+        }
+        catch {
+            // Keep the message generic: a raw fetch error can echo the requested
+            // URL, and this string reaches the text and JSON CLI output.
+            errors.push("running proxy /limits unreachable; fetching directly");
+        }
+    }
+    try {
+        const accounts = await listAnthropicAccountsForUsage();
+        const prior = await loadAccountQuotas().catch(() => ({}));
+        const quotas = {};
+        const CONCURRENCY = 3;
+        let nextIndex = 0;
+        const worker = async () => {
+            for (;;) {
+                const index = nextIndex++;
+                if (index >= accounts.length) {
+                    return;
+                }
+                const account = accounts[index];
+                if (account.type !== "oauth") {
+                    continue; // api_key accounts have no subscription windows
+                }
+                // Isolate failures per account: one rejection must not abort the
+                // Promise.all sweep or discard the other accounts' refreshed quotas.
+                try {
+                    const result = await fetchAccountUsage(account);
+                    if (!result.ok) {
+                        errors.push(`${account.label}: ${result.error}`);
+                        continue;
+                    }
+                    const quota = usageToQuota(result.usage, {
+                        now: Date.now(),
+                        prior: prior[account.label] ?? null,
+                    });
+                    if (!quota) {
+                        errors.push(`${account.label}: usage payload had no recognizable limit windows`);
+                        continue;
+                    }
+                    await saveAccountQuota(account.label, quota);
+                    quotas[account.label] = quota;
+                }
+                catch (err) {
+                    errors.push(`${account.label}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        };
+        try {
+            await Promise.all(Array.from({ length: Math.min(CONCURRENCY, accounts.length || 1) }, () => worker()));
+        }
+        finally {
+            // The quota store's debounced flush timer is unref()'d and this process
+            // is short-lived — flush now (even on a partial sweep) or the completed
+            // saves never reach disk.
+            await flushAccountQuotas().catch(() => undefined);
+        }
+        return { via: "direct", quotas, errors };
+    }
+    catch (err) {
+        errors.push(`direct limit fetch failed (${err instanceof Error ? err.message : String(err)})`);
+        return { via: "none", quotas: null, errors };
+    }
+}
 /**
  * Handle the list subcommand
  * `neurolink auth list`
@@ -189,6 +321,7 @@ export async function handleList(argv) {
             let email;
             let tokenStatus = "unknown";
             let expiresAt;
+            let tokenType;
             // Derive email from the compound key label when it looks like an email.
             // The credentials file is a shared singleton that gets overwritten on
             // every login — reading email from it would show the LATEST login's
@@ -220,6 +353,7 @@ export async function handleList(argv) {
                 const tokens = await defaultTokenStore.loadTokens(key);
                 if (tokens) {
                     expiresAt = tokens.expiresAt;
+                    tokenType = tokens.tokenType;
                     const isExpired = defaultTokenStore.isTokenExpired(tokens, 0);
                     tokenStatus = isExpired ? "expired" : "valid";
                     // Extract per-account metadata from scope (e.g. "tier:pro email:user@example.com")
@@ -242,9 +376,24 @@ export async function handleList(argv) {
             catch {
                 // Token load failed — show as unknown
             }
-            return { key, provider, label, email, tier, tokenStatus, expiresAt };
+            return {
+                key,
+                provider,
+                label,
+                email,
+                tier,
+                tokenStatus,
+                expiresAt,
+                tokenType,
+            };
         }));
-        // Load persisted quota data (captured from proxy responses).
+        // Optionally fetch FRESH limits from Anthropic before rendering.
+        let refreshOutcome;
+        if (argv.refresh) {
+            refreshOutcome = await refreshAccountLimitsForList();
+        }
+        // Load persisted quota data (captured from proxy responses), then overlay
+        // anything just refreshed — freshly fetched values win over the snapshot.
         let quotas = {};
         try {
             quotas = await loadAccountQuotas();
@@ -252,6 +401,9 @@ export async function handleList(argv) {
         catch {
             // Non-fatal — quota display is best-effort
         }
+        if (refreshOutcome?.quotas) {
+            quotas = { ...quotas, ...refreshOutcome.quotas };
+        }
         if (argv.format === "json") {
             // Merge quota data into each account object for JSON output
             const withQuota = enrichedAccounts.map((acct) => {
@@ -259,9 +411,29 @@ export async function handleList(argv) {
                 const quota = quotas[quotaKey] ?? null;
                 return { ...acct, quota };
             });
-            logger.always(JSON.stringify(withQuota, null, 2));
+            if (refreshOutcome) {
+                // --refresh envelopes the array so the fetch outcome travels with it.
+                logger.always(JSON.stringify({
+                    refresh: {
+                        via: refreshOutcome.via,
+                        errors: refreshOutcome.errors,
+                    },
+                    accounts: withQuota,
+                }, null, 2));
+            }
+            else {
+                logger.always(JSON.stringify(withQuota, null, 2));
+            }
         }
         else {
+            if (refreshOutcome) {
+                if (refreshOutcome.via !== "none") {
+                    logger.always(chalk.gray(`\nFetched fresh limits from Anthropic (${refreshOutcome.via === "proxy" ? "via running proxy" : "direct"}).`));
+                }
+                for (const refreshError of refreshOutcome.errors) {
+                    logger.always(chalk.yellow(`⚠ ${refreshError}`));
+                }
+            }
             logger.always(chalk.bold("\nAuthenticated Accounts:\n"));
             // Check if any account has quota data to decide column layout
             const hasQuota = enrichedAccounts.some((acct) => {
@@ -296,14 +468,21 @@ export async function handleList(argv) {
                 if (hasQuota && quota) {
                     const qc = formatQuotaColumns(quota);
                     logger.always(`  ${chalk.cyan(displayLabel)} ${displayProvider} ${displayEmail} ${statusText} ${qc.sessionText.padEnd(10)} ${qc.weeklyText.padEnd(10)}`);
+                    const indent = " ".repeat(2 + 20 + 1 + 12 + 1 + 28 + 1 + 14 + 1);
                     // Second line: reset times (indented under session/weekly columns)
                     if (qc.sessionReset || qc.weeklyReset) {
-                        const indent = " ".repeat(2 + 20 + 1 + 12 + 1 + 28 + 1 + 14 + 1);
                         logger.always(`${indent}${(qc.sessionReset || "").padEnd(10)} ${qc.weeklyReset || ""}`);
                     }
+                    // Dynamic per-plan windows (e.g. the Fable-only weekly limit)
+                    for (const windowRow of formatQuotaWindowRows(quota)) {
+                        logger.always(`${indent}${windowRow}`);
+                    }
                 }
                 else {
-                    logger.always(`  ${chalk.cyan(displayLabel)} ${displayProvider} ${displayEmail} ${statusText}${hasQuota ? "  -          -" : ""}`);
+                    const apiKeyNote = refreshOutcome && acct.tokenType && acct.tokenType !== "Bearer"
+                        ? chalk.gray("  (api key — not refreshed)")
+                        : "";
+                    logger.always(`  ${chalk.cyan(displayLabel)} ${displayProvider} ${displayEmail} ${statusText}${hasQuota ? "  -          -" : ""}${apiKeyNote}`);
                 }
             }
             logger.always("");

package/dist/cli/factories/authCommandFactory.js

@@ -214,8 +214,14 @@ export class AuthCommandFactory {
      */
     static buildListOptions(yargs) {
         return yargs
+            .option("refresh", {
+            type: "boolean",
+            default: false,
+            description: "Fetch fresh limits from Anthropic for all OAuth accounts before listing (via the running proxy when available)",
+        })
             .example("$0 auth list", "List all authenticated accounts")
-            .example("$0 auth list --format json", "List accounts in JSON format");
+            .example("$0 auth list --format json", "List accounts in JSON format")
+            .example("$0 auth list --refresh", "Fetch fresh session/weekly/model-scoped limits before listing");
     }
     /**
      * Build options for remove subcommand

package/dist/lib/adapters/audioFormatSupport.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Native audio delivery to providers that can listen.
+ *
+ * ## The gap this closes
+ *
+ * Until this module existed, attaching an audio file produced a message
+ * containing only a metadata block:
+ *
+ *   ## Audio File: "recording.mp3"
+ *   Duration: 19s | Codec: MPEG 2 Layer 3 | Bitrate: 32 kbps |
+ *   Sample Rate: 22050 Hz | Channels: 1 (Mono)
+ *
+ * No audio bytes were ever handed to the provider. Every question about what
+ * the recording *says* — transcribe this, who is speaking, what was agreed —
+ * was answered from a description of the file, and Gemini has accepted inline
+ * audio the whole time.
+ *
+ * The failure was invisible for an instructive reason: that metadata block
+ * answers precisely the questions a test is most tempted to ask. "How long is
+ * this audio?" and "what sample rate is it?" both succeed with no audio
+ * attached, so a suite built on them reports working audio support. It took an
+ * end-to-end test asking for a spoken word to expose it.
+ *
+ * ## Provider scope
+ *
+ * Deliberately a capability map rather than "send audio to everyone". A
+ * provider that cannot accept an audio part responds with an opaque HTTP 400,
+ * which is worse than the metadata summary it would otherwise have received —
+ * so an unlisted provider keeps the existing text-only behaviour and loses
+ * nothing.
+ *
+ * @module adapters/audioFormatSupport
+ */
+import type { AudioConversionResult } from "../types/index.js";
+/** Whether `provider` can be handed raw audio bytes. */
+export declare function supportsNativeAudio(provider: string): boolean;
+/** Whether `mimeType` must be re-encoded before a native provider will read it. */
+export declare function needsAudioTranscode(mimeType: string): boolean;
+/**
+ * Return audio bytes a native provider can read, transcoding when the source
+ * container is one it does not accept.
+ *
+ * Never throws for audio reasons. When conversion is impossible — no ffmpeg, an
+ * unreadable stream — the original bytes and MIME type come back with
+ * `converted: false`, and the caller falls back to the metadata summary. That
+ * keeps this from turning a previously-working (if limited) request into a
+ * failure.
+ *
+ * @param buffer - Raw audio bytes.
+ * @param mimeType - Detected MIME type of `buffer`.
+ * @param extension - Source extension, used so ffmpeg picks the right demuxer.
+ */
+export declare function toProviderCompatibleAudio(buffer: Buffer, mimeType: string, extension: string): Promise<AudioConversionResult>;

package/dist/lib/adapters/audioFormatSupport.js

@@ -0,0 +1,201 @@
+/**
+ * Native audio delivery to providers that can listen.
+ *
+ * ## The gap this closes
+ *
+ * Until this module existed, attaching an audio file produced a message
+ * containing only a metadata block:
+ *
+ *   ## Audio File: "recording.mp3"
+ *   Duration: 19s | Codec: MPEG 2 Layer 3 | Bitrate: 32 kbps |
+ *   Sample Rate: 22050 Hz | Channels: 1 (Mono)
+ *
+ * No audio bytes were ever handed to the provider. Every question about what
+ * the recording *says* — transcribe this, who is speaking, what was agreed —
+ * was answered from a description of the file, and Gemini has accepted inline
+ * audio the whole time.
+ *
+ * The failure was invisible for an instructive reason: that metadata block
+ * answers precisely the questions a test is most tempted to ask. "How long is
+ * this audio?" and "what sample rate is it?" both succeed with no audio
+ * attached, so a suite built on them reports working audio support. It took an
+ * end-to-end test asking for a spoken word to expose it.
+ *
+ * ## Provider scope
+ *
+ * Deliberately a capability map rather than "send audio to everyone". A
+ * provider that cannot accept an audio part responds with an opaque HTTP 400,
+ * which is worse than the metadata summary it would otherwise have received —
+ * so an unlisted provider keeps the existing text-only behaviour and loses
+ * nothing.
+ *
+ * @module adapters/audioFormatSupport
+ */
+import { withTimeout } from "../utils/errorHandling.js";
+import { logger } from "../utils/logger.js";
+import { getFfmpegPath, runFfmpeg } from "./video/ffmpegAdapter.js";
+/**
+ * Ceiling for one audio conversion.
+ *
+ * Longer than the image equivalent because a lossless hour-long WAV is a
+ * legitimate input and re-encoding it is not instant, but still bounded so a
+ * wedged decoder cannot hold a generation request open indefinitely.
+ */
+const AUDIO_TRANSCODE_TIMEOUT_MS = 120_000;
+/**
+ * Providers that accept inline audio parts.
+ *
+ * Google's Gemini models (both Vertex and AI Studio) take audio as `inlineData`
+ * alongside text. Other providers are omitted rather than assumed: OpenAI's
+ * audio models use a different request shape than the chat-completions path
+ * NeuroLink builds here, and sending an audio part to a provider that does not
+ * expect one converts a working (if limited) response into a hard failure.
+ */
+const NATIVE_AUDIO_PROVIDERS = new Set([
+    "vertex",
+    "google-vertex",
+    "googlevertex",
+    "google-ai-studio",
+    "googleaistudio",
+    "google-ai",
+    "googleai",
+    "gemini",
+]);
+/**
+ * Audio MIME types the native providers accept as-is.
+ *
+ * Gemini's documented set. Anything outside it is transcoded rather than
+ * rejected, because the container a user happens to have — a voice memo in
+ * CAF, a Windows recording in WMA — says nothing about whether the audio
+ * inside is useful.
+ */
+const NATIVE_AUDIO_MIME_TYPES = new Set([
+    "audio/wav",
+    "audio/x-wav",
+    "audio/mpeg",
+    "audio/mp3",
+    "audio/aiff",
+    "audio/x-aiff",
+    "audio/aac",
+    "audio/ogg",
+    "audio/flac",
+    "audio/x-flac",
+]);
+/** MIME type every transcode targets. Universally accepted and compact. */
+const TRANSCODE_TARGET_MIME = "audio/mpeg";
+/** Whether `provider` can be handed raw audio bytes. */
+export function supportsNativeAudio(provider) {
+    return NATIVE_AUDIO_PROVIDERS.has(provider.toLowerCase().trim());
+}
+/** Whether `mimeType` must be re-encoded before a native provider will read it. */
+export function needsAudioTranscode(mimeType) {
+    return !NATIVE_AUDIO_MIME_TYPES.has(normalizeAudioMime(mimeType));
+}
+function normalizeAudioMime(mimeType) {
+    return mimeType.split(";")[0].trim().toLowerCase();
+}
+/**
+ * Re-encode audio to MP3 with ffmpeg.
+ *
+ * Temp files rather than stdin: several of the containers that need converting
+ * (CAF, WavPack, AU) carry their metadata in a trailer or require seeking, and
+ * a piped stream leaves ffmpeg unable to find it. The directory is removed in
+ * `finally` whether or not the conversion succeeded.
+ *
+ * Node builtins are imported dynamically because the browser bundle stubs
+ * `node:fs/promises` without `mkdtemp`; nothing in a browser spawns ffmpeg, so
+ * the import belongs at the point of use.
+ */
+async function transcodeToMp3(buffer, extension) {
+    const [{ randomUUID }, { mkdtemp, readFile, rm, writeFile }, { tmpdir }, { join },] = await Promise.all([
+        import("node:crypto"),
+        import("node:fs/promises"),
+        import("node:os"),
+        import("node:path"),
+    ]);
+    const workDir = await mkdtemp(join(tmpdir(), "neurolink-audio-"));
+    const inputPath = join(workDir, `${randomUUID()}${extension}`);
+    const outputPath = join(workDir, `${randomUUID()}.mp3`);
+    try {
+        await writeFile(inputPath, buffer);
+        await runFfmpeg([
+            "-y",
+            "-v",
+            "error",
+            "-i",
+            inputPath,
+            // Downmix and cap the rate: speech is the point, and a 48 kHz stereo
+            // re-encode of a mono voice memo triples the payload for nothing.
+            "-ac",
+            "1",
+            "-ar",
+            "16000",
+            "-c:a",
+            "libmp3lame",
+            "-q:a",
+            "4",
+            outputPath,
+        ], 
+        // Without this the call inherits runFfmpeg's frame-extraction default of
+        // 30s, which is sized for pulling a single video frame — so the 120s
+        // ceiling above, chosen precisely because re-encoding a lossless
+        // hour-long WAV is not instant, could never be reached. ffmpeg killed the
+        // transcode at 30s and the outer race never got to run.
+        { timeoutMs: AUDIO_TRANSCODE_TIMEOUT_MS });
+        return await readFile(outputPath);
+    }
+    finally {
+        await rm(workDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+/**
+ * Return audio bytes a native provider can read, transcoding when the source
+ * container is one it does not accept.
+ *
+ * Never throws for audio reasons. When conversion is impossible — no ffmpeg, an
+ * unreadable stream — the original bytes and MIME type come back with
+ * `converted: false`, and the caller falls back to the metadata summary. That
+ * keeps this from turning a previously-working (if limited) request into a
+ * failure.
+ *
+ * @param buffer - Raw audio bytes.
+ * @param mimeType - Detected MIME type of `buffer`.
+ * @param extension - Source extension, used so ffmpeg picks the right demuxer.
+ */
+export async function toProviderCompatibleAudio(buffer, mimeType, extension) {
+    const normalized = normalizeAudioMime(mimeType);
+    if (!needsAudioTranscode(normalized)) {
+        return { buffer, mimeType: normalized, converted: false };
+    }
+    // Resolving the binary first turns "ffmpeg is not installed" into one clear
+    // warning rather than a spawn error surfacing from inside the conversion.
+    const ffmpegAvailable = await getFfmpegPath()
+        .then(() => true)
+        .catch(() => false);
+    if (!ffmpegAvailable) {
+        logger.warn(`[audioFormatSupport] ${normalized} needs conversion before a provider can ` +
+            `read it, but ffmpeg is unavailable — falling back to a metadata-only ` +
+            `summary. Install ffmpeg (or set FFMPEG_PATH) to enable this format.`);
+        return { buffer, mimeType: normalized, converted: false };
+    }
+    try {
+        const converted = await withTimeout(transcodeToMp3(buffer, extension), AUDIO_TRANSCODE_TIMEOUT_MS, new Error(`audio transcode exceeded ${AUDIO_TRANSCODE_TIMEOUT_MS}ms`));
+        if (converted.length === 0) {
+            throw new Error("produced an empty audio stream");
+        }
+        logger.debug(`[audioFormatSupport] Transcoded ${normalized} → ${TRANSCODE_TARGET_MIME} ` +
+            `(${buffer.length} → ${converted.length} bytes) for native delivery`);
+        return {
+            buffer: converted,
+            mimeType: TRANSCODE_TARGET_MIME,
+            converted: true,
+        };
+    }
+    catch (error) {
+        logger.warn(`[audioFormatSupport] Could not convert ${normalized} for native delivery ` +
+            `— falling back to a metadata-only summary: ` +
+            `${error instanceof Error ? error.message.split("\n")[0] : String(error)}`);
+        return { buffer, mimeType: normalized, converted: false };
+    }
+}
+//# sourceMappingURL=audioFormatSupport.js.map

package/dist/lib/processors/archive/ArchiveProcessor.d.ts

@@ -193,6 +193,43 @@ export declare class ArchiveProcessor extends BaseFileProcessor<ProcessedArchive
      * @param entries - Previously extracted entry metadata
      * @returns Map of entry name to extracted text content
      */
+    /**
+     * Whether an entry name looks like something worth inlining as text.
+     *
+     * Shared by the ZIP and TAR paths so the two cannot drift into disagreeing
+     * about which members are worth reading — they did, because only ZIP had the
+     * rule at all.
+     */
+    private isExtractableEntryName;
+    /**
+     * Decode bytes to text, or null when they are not text.
+     *
+     * A NUL byte in the first 512 bytes, or a high proportion of replacement
+     * characters after decoding, means binary — inlining that would spend the
+     * extraction budget on mojibake.
+     */
+    private decodeEntryText;
+    /**
+     * Decompress a single-stream archive (.bz2, .xz, .zst).
+     *
+     * Node ships zstd from v22.15/23, so that one needs no help. bzip2 and xz
+     * have no Node binding, and adding a native module for them would make an
+     * optional format a build-time dependency for every consumer — so the system
+     * tools are used when present, the same soft-dependency arrangement this
+     * codebase already has with ffmpeg. Absent tooling returns null and the
+     * caller reports the format as unsupported *on this machine* rather than
+     * unsupported in principle.
+     */
+    private decompressSingleStream;
+    /**
+     * Extract a single-stream archive: decompress, then treat the result as a
+     * TAR when it is one and as a lone file otherwise.
+     *
+     * The tar check matters because `.tar.xz` and `.tar.zst` are how these
+     * formats are usually met — reporting one opaque "decompressed-content" blob
+     * for an archive of forty files would be technically true and useless.
+     */
+    private extractSingleStreamEntries;
     private extractEntryContents;
     /**
      * Build a structured text description of the archive for LLM consumption.