youtube-knowledge-mcp 2.1.0 → 3.0.0

package/dist/utils/ytdlp-env.js

@@ -0,0 +1,121 @@
+import { accessSync, constants, statSync } from 'node:fs';
+import { envEnum, envString } from './env.js';
+import { assertInsideHome } from './validate.js';
+/**
+ * The session options yt-dlp is started with, read from the environment.
+ *
+ * Cookies are how yt-dlp reads age-restricted, members-only and sign-in-gated
+ * videos, and how it gets past the "confirm you're not a bot" check YouTube
+ * sometimes applies to an address. They are also the user's own account, so
+ * everything here is careful about two things: the values are validated at
+ * boot and never at request time, and neither the cookie path nor its contents
+ * ever appear in a log line, a tool result or an error message.
+ */
+export const COOKIE_BROWSERS = [
+    'brave',
+    'chrome',
+    'chromium',
+    'edge',
+    'firefox',
+    'opera',
+    'safari',
+    'vivaldi',
+    'whale',
+];
+const PROXY_SCHEMES = new Set(['http:', 'https:', 'socks4:', 'socks4a:', 'socks5:', 'socks5h:']);
+function readCookiesFile(env) {
+    const raw = envString('YOUTUBE_MCP_COOKIES_FILE', env);
+    if (raw === undefined)
+        return undefined;
+    // The message names the variable and never the path: the path is the one
+    // thing about a cookies file that should not travel.
+    const rejected = (reason) => new Error(`YOUTUBE_MCP_COOKIES_FILE ${reason}. Point it at a readable cookies file in your home directory.`);
+    let path;
+    try {
+        path = assertInsideHome(raw, 'cookies file');
+    }
+    catch {
+        throw rejected('must be inside your home directory');
+    }
+    try {
+        if (!statSync(path).isFile())
+            throw rejected('is not a regular file');
+        accessSync(path, constants.R_OK);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('YOUTUBE_MCP_COOKIES_FILE'))
+            throw error;
+        throw rejected('could not be read');
+    }
+    return path;
+}
+function readProxy(env) {
+    const raw = envString('YOUTUBE_MCP_PROXY', env);
+    if (raw === undefined)
+        return undefined;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error('YOUTUBE_MCP_PROXY must be a URL such as socks5h://127.0.0.1:1080.');
+    }
+    if (!PROXY_SCHEMES.has(url.protocol)) {
+        throw new Error(`YOUTUBE_MCP_PROXY must use one of ${[...PROXY_SCHEMES].map((s) => s.slice(0, -1)).join(', ')}.`);
+    }
+    return url.toString();
+}
+function readSleep(env) {
+    const raw = envString('YOUTUBE_MCP_SLEEP_REQUESTS_S', env);
+    if (raw === undefined)
+        return undefined;
+    const seconds = Number(raw);
+    if (!Number.isFinite(seconds) || seconds < 0) {
+        throw new Error('YOUTUBE_MCP_SLEEP_REQUESTS_S must be a non-negative number of seconds.');
+    }
+    return seconds;
+}
+/**
+ * Validate the session settings and turn them into yt-dlp flags.
+ *
+ * Throws a plain `Error` naming the variable: this runs at boot, where a bad
+ * setting should stop the server before a transport starts, not surface as a
+ * puzzling failure on the first tool call.
+ */
+export function readYtDlpEnv(env = process.env) {
+    const cookiesFile = readCookiesFile(env);
+    const browser = envEnum('YOUTUBE_MCP_COOKIES_FROM_BROWSER', COOKIE_BROWSERS, env);
+    const proxy = readProxy(env);
+    const sleep = readSleep(env);
+    if (cookiesFile !== undefined && browser !== undefined) {
+        throw new Error('Set either YOUTUBE_MCP_COOKIES_FILE or YOUTUBE_MCP_COOKIES_FROM_BROWSER, not both.');
+    }
+    const args = [];
+    if (cookiesFile !== undefined)
+        args.push('--cookies', cookiesFile);
+    if (browser !== undefined)
+        args.push('--cookies-from-browser', browser);
+    if (proxy !== undefined)
+        args.push('--proxy', proxy);
+    if (sleep !== undefined)
+        args.push('--sleep-requests', String(sleep));
+    return {
+        args,
+        cookies: cookiesFile !== undefined ? 'file' : browser !== undefined ? 'browser' : 'none',
+        ...(browser === undefined ? {} : { browser }),
+        proxy: proxy !== undefined,
+        ...(sleep === undefined ? {} : { sleepRequestsSeconds: sleep }),
+    };
+}
+/** One line for the boot log: what is configured, never what it is. */
+export function describeYtDlpEnv(settings) {
+    const cookies = settings.cookies === 'browser'
+        ? `browser (${settings.browser ?? 'unknown'})`
+        : settings.cookies;
+    const parts = [`yt-dlp cookies: ${cookies}`, `proxy: ${settings.proxy ? 'configured' : 'none'}`];
+    if (settings.sleepRequestsSeconds !== undefined) {
+        parts.push(`sleep between requests: ${settings.sleepRequestsSeconds}s`);
+    }
+    return parts.join(' · ');
+}
+//# sourceMappingURL=ytdlp-env.js.map

package/dist/utils/ytdlp-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ytdlp-env.js","sourceRoot":"","sources":["../../src/utils/ytdlp-env.ts"],"names":[],"mappings":"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"}

package/dist/utils/ytdlp-limiter.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Takes a concurrency slot, waiting for one when the limiter is full.
+ *
+ * The wait honours the request's abort signal. It used to be a bare promise
+ * with no way out, so a client that gave up stayed queued forever — and since a
+ * media transfer runs without a wall-clock timeout, three stalled downloads
+ * held every slot and every later call queued behind them, uncancellable. The
+ * server was not slow, it was wedged, and no tool could run again.
+ */
+export declare function acquireSlot(signal: AbortSignal | undefined): Promise<void>;
+/**
+ * Hands the slot to the next waiter rather than freeing it and letting them
+ * race for it: decrementing first left `active` below the limit for a tick, so
+ * a fresh caller could take the slot the queue was already promised and the
+ * limiter would run over its own ceiling.
+ */
+export declare function releaseSlot(): void;
+/** Test seam: lets the suite assert the limiter without spawning processes. */
+export declare function concurrencyState(): {
+    active: number;
+    queued: number;
+    /** The level in force now, which throttling can lower. */
+    limit: number;
+    /** The configured maximum the level never exceeds. */
+    ceiling: number;
+};
+//# sourceMappingURL=ytdlp-limiter.d.ts.map

package/dist/utils/ytdlp-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ytdlp-limiter.d.ts","sourceRoot":"","sources":["../../src/utils/ytdlp-limiter.ts"],"names":[],"mappings":"AAiCA;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BhF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAOlC;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,IAAI;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;CACjB,CAOA"}

package/dist/utils/ytdlp-limiter.js

@@ -0,0 +1,85 @@
+import { envInt } from './env.js';
+import { YouTubeError } from './errors.js';
+import { effectiveConcurrency } from './ytdlp-pacer.js';
+/**
+ * The concurrency limiter every yt-dlp spawn passes through.
+ *
+ * A cap so batch operations do not look like a scraper to YouTube, with a queue
+ * that honours cancellation so an abandoned request never holds a place in it.
+ */
+/**
+ * The ceiling this server will never exceed.
+ *
+ * A limit of 0 (or NaN) would queue every call forever, so the floor is 1.
+ * Under throttling the pacer lowers the level below this; the setting is the
+ * maximum, not the level.
+ */
+const MAX_CONCURRENT = envInt('YOUTUBE_MCP_MAX_CONCURRENCY', 3, { min: 1, max: 32 });
+/** The level in force right now: the configured ceiling, or less if throttled. */
+function currentLimit() {
+    return Math.max(1, Math.min(MAX_CONCURRENT, effectiveConcurrency()));
+}
+let active = 0;
+const waiting = [];
+/**
+ * Takes a concurrency slot, waiting for one when the limiter is full.
+ *
+ * The wait honours the request's abort signal. It used to be a bare promise
+ * with no way out, so a client that gave up stayed queued forever — and since a
+ * media transfer runs without a wall-clock timeout, three stalled downloads
+ * held every slot and every later call queued behind them, uncancellable. The
+ * server was not slow, it was wedged, and no tool could run again.
+ */
+export async function acquireSlot(signal) {
+    // No already-aborted check here: `runYtDlp` makes it before every attempt and
+    // nothing awaits in between, so a second one could never fire — an
+    // unreachable guard that reads like a reachable one.
+    if (active < currentLimit()) {
+        active++;
+        return;
+    }
+    await new Promise((resolve, reject) => {
+        const waiter = {
+            grant: () => {
+                signal?.removeEventListener('abort', onAbort);
+                resolve();
+            },
+            cancel: (error) => {
+                signal?.removeEventListener('abort', onAbort);
+                reject(error);
+            },
+        };
+        function onAbort() {
+            const index = waiting.indexOf(waiter);
+            if (index !== -1)
+                waiting.splice(index, 1);
+            waiter.cancel(new YouTubeError('CANCELLED', 'The request was cancelled.'));
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+        waiting.push(waiter);
+    });
+}
+/**
+ * Hands the slot to the next waiter rather than freeing it and letting them
+ * race for it: decrementing first left `active` below the limit for a tick, so
+ * a fresh caller could take the slot the queue was already promised and the
+ * limiter would run over its own ceiling.
+ */
+export function releaseSlot() {
+    const next = waiting.shift();
+    if (next) {
+        next.grant();
+        return;
+    }
+    active--;
+}
+/** Test seam: lets the suite assert the limiter without spawning processes. */
+export function concurrencyState() {
+    return {
+        active,
+        queued: waiting.length,
+        limit: currentLimit(),
+        ceiling: MAX_CONCURRENT,
+    };
+}
+//# sourceMappingURL=ytdlp-limiter.js.map

package/dist/utils/ytdlp-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ytdlp-limiter.js","sourceRoot":"","sources":["../../src/utils/ytdlp-limiter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAExD;;;;;GAKG;AAEH;;;;;;GAMG;AACH,MAAM,cAAc,GAAG,MAAM,CAAC,6BAA6B,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC;AAErF,kFAAkF;AAClF,SAAS,YAAY;IACnB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,oBAAoB,EAAE,CAAC,CAAC,CAAC;AACvE,CAAC;AAOD,IAAI,MAAM,GAAG,CAAC,CAAC;AACf,MAAM,OAAO,GAAa,EAAE,CAAC;AAE7B;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,MAA+B;IAC/D,8EAA8E;IAC9E,mEAAmE;IACnE,qDAAqD;IACrD,IAAI,MAAM,GAAG,YAAY,EAAE,EAAE,CAAC;QAC5B,MAAM,EAAE,CAAC;QACT,OAAO;IACT,CAAC;IAED,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC1C,MAAM,MAAM,GAAW;YACrB,KAAK,EAAE,GAAG,EAAE;gBACV,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBAC9C,OAAO,EAAE,CAAC;YACZ,CAAC;YACD,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;gBAChB,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBAC9C,MAAM,CAAC,KAAK,CAAC,CAAC;YAChB,CAAC;SACF,CAAC;QAEF,SAAS,OAAO;YACd,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACtC,IAAI,KAAK,KAAK,CAAC,CAAC;gBAAE,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YAC3C,MAAM,CAAC,MAAM,CAAC,IAAI,YAAY,CAAC,WAAW,EAAE,4BAA4B,CAAC,CAAC,CAAC;QAC7E,CAAC;QAED,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3D,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW;IACzB,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IAC7B,IAAI,IAAI,EAAE,CAAC;QACT,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,OAAO;IACT,CAAC;IACD,MAAM,EAAE,CAAC;AACX,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,gBAAgB;IAQ9B,OAAO;QACL,MAAM;QACN,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,KAAK,EAAE,YAAY,EAAE;QACrB,OAAO,EAAE,cAAc;KACxB,CAAC;AACJ,CAAC"}

package/dist/utils/ytdlp-pacer.d.ts

@@ -0,0 +1,64 @@
+import type { YouTubeErrorCode } from './errors.js';
+/**
+ * How this server reacts to being throttled.
+ *
+ * The old behaviour was three attempts with at most ~1.5 seconds of jitter and
+ * no memory between calls, which is fine for a blip and useless for an
+ * hour-long harvest: nothing slowed down, nothing waited, and a hard block
+ * produced an hour of identical failures.
+ *
+ * This adds three things that only make sense across calls — a shared
+ * cooldown, an adaptive concurrency ceiling, and a circuit breaker — so the
+ * state is deliberately process-global, the same scope as the limiter it
+ * cooperates with.
+ */
+export declare const RATE_LIMIT_COOLDOWN_BASE_MS = 30000;
+export declare const RATE_LIMIT_COOLDOWN_MAX_MS: number;
+export declare const BOT_CHECK_COOLDOWN_MS: number;
+export declare const MAX_BACKOFF_MS = 120000;
+export declare const BASE_BACKOFF_MS = 750;
+export declare const AIMD_MIN_CONCURRENCY = 1;
+export declare const AIMD_INCREASE_AFTER_SUCCESSES = 20;
+export declare const AIMD_DECREASE_FACTOR = 0.5;
+/** Consecutive throttles before a global cooldown starts. */
+export declare const COOLDOWN_AFTER_STRIKES = 2;
+export declare const CIRCUIT_STRIKES = 5;
+export declare const CIRCUIT_OPEN_MS: number;
+interface RetryPolicy {
+    /** Total spawns, including the first. */
+    attempts: number;
+    backoff: 'none' | 'exponential';
+    cooldown: 'none' | 'rate-limit' | 'bot-check';
+    concurrency: 'none' | 'decrease' | 'floor';
+}
+export declare function policyFor(code: YouTubeErrorCode): RetryPolicy;
+export declare function backoffDelay(attempt: number, style: RetryPolicy['backoff']): number;
+export interface PacerDecision {
+    giveUp: boolean;
+    delayMs: number;
+}
+/** Records a failure and says whether to try again, and after how long. */
+export declare function onFailure(code: YouTubeErrorCode, attempt: number, now?: number): PacerDecision;
+/** Records a clean spawn, easing the ceiling back up one step at a time. */
+export declare function onSuccess(): void;
+/** How long a caller should wait before spawning, in milliseconds. */
+export declare function waitMs(now?: number): number;
+export declare function circuitOpen(now?: number): boolean;
+/**
+ * The ceiling the limiter should honour right now.
+ *
+ * Infinite until something throttles us, so an untroubled server runs at
+ * whatever YOUTUBE_MCP_MAX_CONCURRENCY allows and the limiter stays the only
+ * authority on the normal case.
+ */
+export declare function effectiveConcurrency(now?: number): number;
+export declare function pacerState(now?: number): {
+    cooldownMs: number;
+    circuitOpen: boolean;
+    strikes: number;
+    concurrency: number;
+};
+/** Test seam; the pacer is process-global in normal use. */
+export declare function resetPacer(): void;
+export {};
+//# sourceMappingURL=ytdlp-pacer.d.ts.map

package/dist/utils/ytdlp-pacer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ytdlp-pacer.d.ts","sourceRoot":"","sources":["../../src/utils/ytdlp-pacer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAClD,eAAO,MAAM,0BAA0B,QAAc,CAAC;AACtD,eAAO,MAAM,qBAAqB,QAAc,CAAC;AACjD,eAAO,MAAM,cAAc,SAAU,CAAC;AACtC,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC,eAAO,MAAM,oBAAoB,IAAI,CAAC;AACtC,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAChD,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,6DAA6D;AAC7D,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,eAAO,MAAM,eAAe,QAAa,CAAC;AAE1C,UAAU,WAAW;IACnB,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,aAAa,CAAC;IAChC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,WAAW,CAAC;IAC9C,WAAW,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC;CAC5C;AAkCD,wBAAgB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,WAAW,CAE7D;AA+BD,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,CAAC,SAAS,CAAC,GAAG,MAAM,CAMnF;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,2EAA2E;AAC3E,wBAAgB,SAAS,CACvB,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,GAAG,SAAa,GACf,aAAa,CAuCf;AAED,4EAA4E;AAC5E,wBAAgB,SAAS,IAAI,IAAI,CAQhC;AAED,sEAAsE;AACtE,wBAAgB,MAAM,CAAC,GAAG,SAAa,GAAG,MAAM,CAG/C;AAED,wBAAgB,WAAW,CAAC,GAAG,SAAa,GAAG,OAAO,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,SAAa,GAAG,MAAM,CAG7D;AAED,wBAAgB,UAAU,CAAC,GAAG,SAAa,GAAG;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB,CAOA;AAED,4DAA4D;AAC5D,wBAAgB,UAAU,IAAI,IAAI,CAQjC"}

package/dist/utils/ytdlp-pacer.js

@@ -0,0 +1,165 @@
+/**
+ * How this server reacts to being throttled.
+ *
+ * The old behaviour was three attempts with at most ~1.5 seconds of jitter and
+ * no memory between calls, which is fine for a blip and useless for an
+ * hour-long harvest: nothing slowed down, nothing waited, and a hard block
+ * produced an hour of identical failures.
+ *
+ * This adds three things that only make sense across calls — a shared
+ * cooldown, an adaptive concurrency ceiling, and a circuit breaker — so the
+ * state is deliberately process-global, the same scope as the limiter it
+ * cooperates with.
+ */
+export const RATE_LIMIT_COOLDOWN_BASE_MS = 30_000;
+export const RATE_LIMIT_COOLDOWN_MAX_MS = 15 * 60_000;
+export const BOT_CHECK_COOLDOWN_MS = 10 * 60_000;
+export const MAX_BACKOFF_MS = 120_000;
+export const BASE_BACKOFF_MS = 750;
+export const AIMD_MIN_CONCURRENCY = 1;
+export const AIMD_INCREASE_AFTER_SUCCESSES = 20;
+export const AIMD_DECREASE_FACTOR = 0.5;
+/** Consecutive throttles before a global cooldown starts. */
+export const COOLDOWN_AFTER_STRIKES = 2;
+export const CIRCUIT_STRIKES = 5;
+export const CIRCUIT_OPEN_MS = 5 * 60_000;
+const TERMINAL = {
+    attempts: 1,
+    backoff: 'none',
+    cooldown: 'none',
+    concurrency: 'none',
+};
+/**
+ * What to do about each kind of failure.
+ *
+ * BOT_CHECK does not retry, and that is measured rather than assumed: from a
+ * datacenter address, eight player clients, a fifteen-minute cooldown, a PO
+ * token provider and curl_cffi TLS impersonation all returned the same answer.
+ * Retrying spends requests on a known-dead path; stopping and naming the cause
+ * is the useful response. The cooldown still applies, because whatever else is
+ * in flight should not keep hammering.
+ */
+const POLICIES = {
+    RATE_LIMITED: {
+        attempts: 5,
+        backoff: 'exponential',
+        cooldown: 'rate-limit',
+        concurrency: 'decrease',
+    },
+    BOT_CHECK: { attempts: 1, backoff: 'none', cooldown: 'bot-check', concurrency: 'floor' },
+    TIMEOUT: { attempts: 3, backoff: 'exponential', cooldown: 'none', concurrency: 'decrease' },
+    // Deliberately absent: an unclassified yt-dlp failure carries no evidence
+    // that a second attempt would go differently, and `retryable` is false on it,
+    // so it falls through to TERMINAL. Listing it here with attempts > 1 would
+    // state a policy the retry loop correctly refuses to honour.
+};
+export function policyFor(code) {
+    return POLICIES[code] ?? TERMINAL;
+}
+let state = {
+    cooldownUntil: 0,
+    circuitOpenUntil: 0,
+    strikes: 0,
+    successes: 0,
+    concurrency: Number.POSITIVE_INFINITY,
+};
+/** ±25% so parallel callers do not come back in lockstep. */
+function jitter(ms) {
+    return Math.round(ms * (0.75 + Math.random() * 0.5));
+}
+function cooldownFor(kind, strikes) {
+    if (kind === 'none')
+        return 0;
+    if (kind === 'bot-check')
+        return BOT_CHECK_COOLDOWN_MS;
+    const escalated = RATE_LIMIT_COOLDOWN_BASE_MS * 2 ** Math.max(0, strikes - 1);
+    return jitter(Math.min(escalated, RATE_LIMIT_COOLDOWN_MAX_MS));
+}
+export function backoffDelay(attempt, style) {
+    if (style === 'none')
+        return 0;
+    // Exponential with full jitter, capped so a long run cannot stall for hours.
+    const ceiling = Math.min(BASE_BACKOFF_MS * 2 ** (attempt - 1), MAX_BACKOFF_MS);
+    return Math.round(Math.random() * ceiling);
+}
+/** Records a failure and says whether to try again, and after how long. */
+export function onFailure(code, attempt, now = Date.now()) {
+    const policy = policyFor(code);
+    const throttled = policy.cooldown !== 'none';
+    if (throttled) {
+        state.strikes += 1;
+        state.successes = 0;
+        // A first strike gets the exponential backoff and nothing more: one 429 is
+        // a blip, and making a single interactive call wait out a 30-second global
+        // cooldown would be worse than the problem. The cooldown starts once the
+        // client has been refused twice in a row, which is when it has stopped
+        // being a blip. A bot check skips the grace: it was measured not to clear
+        // on its own, so there is nothing to be gained by trying again sooner.
+        const grace = policy.cooldown === 'bot-check' ? 1 : COOLDOWN_AFTER_STRIKES;
+        if (state.strikes >= grace) {
+            state.cooldownUntil = Math.max(state.cooldownUntil, now + cooldownFor(policy.cooldown, state.strikes));
+        }
+        if (policy.concurrency === 'floor') {
+            state.concurrency = AIMD_MIN_CONCURRENCY;
+        }
+        else if (policy.concurrency === 'decrease') {
+            state.concurrency = Math.max(AIMD_MIN_CONCURRENCY, Math.floor(effectiveConcurrency(now) * AIMD_DECREASE_FACTOR));
+        }
+        if (state.strikes >= CIRCUIT_STRIKES) {
+            state.circuitOpenUntil = now + CIRCUIT_OPEN_MS;
+        }
+    }
+    return attempt >= policy.attempts
+        ? { giveUp: true, delayMs: 0 }
+        : { giveUp: false, delayMs: backoffDelay(attempt, policy.backoff) };
+}
+/** Records a clean spawn, easing the ceiling back up one step at a time. */
+export function onSuccess() {
+    state.strikes = 0;
+    state.successes += 1;
+    if (state.successes >= AIMD_INCREASE_AFTER_SUCCESSES) {
+        state.successes = 0;
+        if (Number.isFinite(state.concurrency))
+            state.concurrency += 1;
+    }
+}
+/** How long a caller should wait before spawning, in milliseconds. */
+export function waitMs(now = Date.now()) {
+    if (state.circuitOpenUntil > now)
+        return state.circuitOpenUntil - now;
+    return Math.max(0, state.cooldownUntil - now);
+}
+export function circuitOpen(now = Date.now()) {
+    return state.circuitOpenUntil > now;
+}
+/**
+ * The ceiling the limiter should honour right now.
+ *
+ * Infinite until something throttles us, so an untroubled server runs at
+ * whatever YOUTUBE_MCP_MAX_CONCURRENCY allows and the limiter stays the only
+ * authority on the normal case.
+ */
+export function effectiveConcurrency(now = Date.now()) {
+    if (circuitOpen(now))
+        return AIMD_MIN_CONCURRENCY;
+    return state.concurrency;
+}
+export function pacerState(now = Date.now()) {
+    return {
+        cooldownMs: waitMs(now),
+        circuitOpen: circuitOpen(now),
+        strikes: state.strikes,
+        concurrency: effectiveConcurrency(now),
+    };
+}
+/** Test seam; the pacer is process-global in normal use. */
+export function resetPacer() {
+    state = {
+        cooldownUntil: 0,
+        circuitOpenUntil: 0,
+        strikes: 0,
+        successes: 0,
+        concurrency: Number.POSITIVE_INFINITY,
+    };
+}
+//# sourceMappingURL=ytdlp-pacer.js.map

package/dist/utils/ytdlp-pacer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ytdlp-pacer.js","sourceRoot":"","sources":["../../src/utils/ytdlp-pacer.ts"],"names":[],"mappings":"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"}

package/dist/utils/ytdlp-parse.d.ts

@@ -0,0 +1,13 @@
+import type { z } from 'zod';
+/**
+ * Parse yt-dlp JSON output against a schema.
+ *
+ * Every JSON.parse in this codebase used to be unguarded, so a truncated or
+ * non-JSON response surfaced as a raw SyntaxError; and the guard that replaced
+ * it only checked for an object, so a field of the wrong type still reached
+ * the code that read it.
+ */
+export declare function parseYtDlpJson<T>(stdout: string, schema: z.ZodType<T, z.ZodTypeDef, unknown>, what: string): T;
+/** Parse newline-delimited JSON, skipping rows that do not parse or do not match. */
+export declare function parseYtDlpJsonLines<T>(stdout: string, schema: z.ZodType<T, z.ZodTypeDef, unknown>): T[];
+//# sourceMappingURL=ytdlp-parse.d.ts.map

package/dist/utils/ytdlp-parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ytdlp-parse.d.ts","sourceRoot":"","sources":["../../src/utils/ytdlp-parse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAa7B;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,UAAU,EAAE,OAAO,CAAC,EAC3C,IAAI,EAAE,MAAM,GACX,CAAC,CAWH;AAED,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,UAAU,EAAE,OAAO,CAAC,GAC1C,CAAC,EAAE,CAcL"}

package/dist/utils/ytdlp-parse.js

@@ -0,0 +1,48 @@
+import { YouTubeError } from './errors.js';
+/** Reading yt-dlp's JSON output without trusting its shape. */
+function outOfDate(what, detail, cause) {
+    return new YouTubeError('MALFORMED_RESPONSE', `yt-dlp returned ${detail} for ${what}.`, {
+        nextStep: 'This usually means yt-dlp is out of date. Run `yt-dlp -U` and try again.',
+        retryable: cause !== undefined,
+        cause,
+    });
+}
+/**
+ * Parse yt-dlp JSON output against a schema.
+ *
+ * Every JSON.parse in this codebase used to be unguarded, so a truncated or
+ * non-JSON response surfaced as a raw SyntaxError; and the guard that replaced
+ * it only checked for an object, so a field of the wrong type still reached
+ * the code that read it.
+ */
+export function parseYtDlpJson(stdout, schema, what) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch (error) {
+        throw outOfDate(what, 'unreadable output', error);
+    }
+    const result = schema.safeParse(parsed);
+    if (!result.success)
+        throw outOfDate(what, 'an unexpected shape');
+    return result.data;
+}
+/** Parse newline-delimited JSON, skipping rows that do not parse or do not match. */
+export function parseYtDlpJsonLines(stdout, schema) {
+    const results = [];
+    for (const line of stdout.trim().split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const result = schema.safeParse(JSON.parse(line));
+            if (result.success)
+                results.push(result.data);
+        }
+        catch {
+            // A single malformed row should not lose the whole result set.
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=ytdlp-parse.js.map

package/dist/utils/ytdlp-parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ytdlp-parse.js","sourceRoot":"","sources":["../../src/utils/ytdlp-parse.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,+DAA+D;AAE/D,SAAS,SAAS,CAAC,IAAY,EAAE,MAAc,EAAE,KAAe;IAC9D,OAAO,IAAI,YAAY,CAAC,oBAAoB,EAAE,mBAAmB,MAAM,QAAQ,IAAI,GAAG,EAAE;QACtF,QAAQ,EAAE,0EAA0E;QACpF,SAAS,EAAE,KAAK,KAAK,SAAS;QAC9B,KAAK;KACN,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAc,EACd,MAA2C,EAC3C,IAAY;IAEZ,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,SAAS,CAAC,IAAI,EAAE,mBAAmB,EAAE,KAAK,CAAC,CAAC;IACpD,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACxC,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,MAAM,SAAS,CAAC,IAAI,EAAE,qBAAqB,CAAC,CAAC;IAClE,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,mBAAmB,CACjC,MAAc,EACd,MAA2C;IAE3C,MAAM,OAAO,GAAQ,EAAE,CAAC;IAExB,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7C,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;YAAE,SAAS;QAC3B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;YAClD,IAAI,MAAM,CAAC,OAAO;gBAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAChD,CAAC;QAAC,MAAM,CAAC;YACP,+DAA+D;QACjE,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/utils/ytdlp-stream.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Running yt-dlp and reading its output a line at a time.
+ *
+ * `runYtDlp` buffers everything into a string, which is right for a metadata
+ * read and wrong for a long walk: a 40,000-entry channel listing killed at
+ * minute nine yields nothing at all, and the 64MB buffer is a hard ceiling.
+ *
+ * Here each line is handed over as it arrives, so a caller can checkpoint as
+ * it goes and keep what it already had. Paired with `--lazy-playlist`, which
+ * makes yt-dlp emit entries while it walks rather than after.
+ */
+export interface StreamOptions {
+    label?: string;
+    timeoutMs?: number;
+    target: string;
+    /** Called per line, in order. A throw here aborts the walk. */
+    onLine: (line: string) => void;
+}
+export interface StreamResult {
+    lines: number;
+    /** False when the walk was cut short, so the caller knows not to claim completeness. */
+    completed: boolean;
+}
+/**
+ * Streams stdout line by line.
+ *
+ * A failure part-way through is not thrown away: the caller keeps every line
+ * delivered so far and is told the walk did not complete, which is the whole
+ * point of streaming rather than buffering.
+ */
+export declare function runYtDlpLines(args: string[], options: StreamOptions): Promise<StreamResult>;
+//# sourceMappingURL=ytdlp-stream.d.ts.map

package/dist/utils/ytdlp-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ytdlp-stream.d.ts","sourceRoot":"","sources":["../../src/utils/ytdlp-stream.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CA+CjG"}