@nodetool-ai/agents 0.7.0-rc.22 → 0.8.1

package/dist/analysis/video-frames.js

@@ -0,0 +1,288 @@
+/**
+ * Video analysis math — pure functions over RGBA pixels, no decoder.
+ *
+ * A decoded frame arrives as `Uint8Array` in RGBA order; everything here reads
+ * one or two of those and returns numbers. Decoding and frame sampling live in
+ * `media-decode.ts`, so these can be tested on pixel buffers built by hand.
+ *
+ * Two decisions worth stating. Luma is Rec. 709 (`0.2126/0.7152/0.0722`),
+ * matching what every HD codec and NLE calls brightness. And a cut is decided
+ * from a *histogram* distance rather than a pixel difference: a whip pan
+ * changes every pixel without changing the shot, while a cut changes the
+ * distribution. The per-pixel difference is still reported next to it as the
+ * motion score, which is the question the histogram cannot answer.
+ */
+/** Analysis is done on a downscaled frame this many pixels wide. */
+export const ANALYSIS_WIDTH = 64;
+/** Analysis is done on a downscaled frame this many pixels tall. */
+export const ANALYSIS_HEIGHT = 36;
+/** Bins in the luma histogram a scene cut is decided from. */
+export const HISTOGRAM_BINS = 64;
+/** Rec. 709 luma of one 8-bit RGB triple, 0..1. */
+export function luma(red, green, blue) {
+    return (0.2126 * red + 0.7152 * green + 0.0722 * blue) / 255;
+}
+/** Brightness, contrast, saturation and clipping of one RGBA frame. */
+export function frameStats(rgba, width, height) {
+    const pixels = width * height;
+    if (pixels <= 0) {
+        return {
+            brightness: 0,
+            contrast: 0,
+            saturation: 0,
+            meanRgb: [0, 0, 0],
+            clippedHighlights: 0,
+            crushedShadows: 0
+        };
+    }
+    let sumLuma = 0;
+    let sumLumaSquared = 0;
+    let sumSaturation = 0;
+    let sumRed = 0;
+    let sumGreen = 0;
+    let sumBlue = 0;
+    let bright = 0;
+    let dark = 0;
+    for (let index = 0; index < pixels; index += 1) {
+        const offset = index * 4;
+        const red = rgba[offset] ?? 0;
+        const green = rgba[offset + 1] ?? 0;
+        const blue = rgba[offset + 2] ?? 0;
+        const value = luma(red, green, blue);
+        sumLuma += value;
+        sumLumaSquared += value * value;
+        sumRed += red;
+        sumGreen += green;
+        sumBlue += blue;
+        const max = Math.max(red, green, blue);
+        const min = Math.min(red, green, blue);
+        sumSaturation += max > 0 ? (max - min) / max : 0;
+        if (value >= 0.98)
+            bright += 1;
+        else if (value <= 0.02)
+            dark += 1;
+    }
+    const meanLuma = sumLuma / pixels;
+    return {
+        brightness: meanLuma,
+        contrast: Math.sqrt(Math.max(0, sumLumaSquared / pixels - meanLuma * meanLuma)),
+        saturation: sumSaturation / pixels,
+        meanRgb: [sumRed / pixels, sumGreen / pixels, sumBlue / pixels],
+        clippedHighlights: bright / pixels,
+        crushedShadows: dark / pixels
+    };
+}
+/**
+ * Box-filter an RGBA frame down to `targetWidth` × `targetHeight` luma values.
+ *
+ * The comparisons that follow run on this, not on the full frame: a 1080p
+ * difference is dominated by sensor noise and costs two megapixels of work per
+ * pair, while 64×36 keeps the structure a cut destroys and none of the grain.
+ */
+export function downscaleLuma(rgba, width, height, targetWidth = ANALYSIS_WIDTH, targetHeight = ANALYSIS_HEIGHT) {
+    const out = new Float32Array(targetWidth * targetHeight);
+    if (width <= 0 || height <= 0)
+        return out;
+    for (let ty = 0; ty < targetHeight; ty += 1) {
+        const y0 = Math.floor((ty * height) / targetHeight);
+        const y1 = Math.max(y0 + 1, Math.floor(((ty + 1) * height) / targetHeight));
+        for (let tx = 0; tx < targetWidth; tx += 1) {
+            const x0 = Math.floor((tx * width) / targetWidth);
+            const x1 = Math.max(x0 + 1, Math.floor(((tx + 1) * width) / targetWidth));
+            let sum = 0;
+            let count = 0;
+            for (let y = y0; y < Math.min(y1, height); y += 1) {
+                for (let x = x0; x < Math.min(x1, width); x += 1) {
+                    const offset = (y * width + x) * 4;
+                    sum += luma(rgba[offset] ?? 0, rgba[offset + 1] ?? 0, rgba[offset + 2] ?? 0);
+                    count += 1;
+                }
+            }
+            out[ty * targetWidth + tx] = count > 0 ? sum / count : 0;
+        }
+    }
+    return out;
+}
+/** A normalized luma histogram of a downscaled frame. */
+export function lumaHistogram(values, bins = HISTOGRAM_BINS) {
+    const histogram = new Float32Array(bins);
+    if (values.length === 0)
+        return histogram;
+    for (let index = 0; index < values.length; index += 1) {
+        const bin = Math.min(bins - 1, Math.max(0, Math.floor((values[index] ?? 0) * bins)));
+        histogram[bin] += 1;
+    }
+    for (let bin = 0; bin < bins; bin += 1)
+        histogram[bin] /= values.length;
+    return histogram;
+}
+/**
+ * Total-variation distance between two normalized histograms, 0..1.
+ *
+ * 0 means identical distributions; 1 means they share no bin. A hard cut
+ * typically lands above 0.3, a dissolve climbs gradually, and camera movement
+ * inside one shot stays low — which is why this and not a pixel difference
+ * decides a cut.
+ */
+export function histogramDistance(a, b) {
+    const bins = Math.min(a.length, b.length);
+    let sum = 0;
+    for (let bin = 0; bin < bins; bin += 1) {
+        sum += Math.abs((a[bin] ?? 0) - (b[bin] ?? 0));
+    }
+    return sum / 2;
+}
+/** Mean absolute luma difference between two downscaled frames, 0..1. */
+export function motionScore(a, b) {
+    const count = Math.min(a.length, b.length);
+    if (count === 0)
+        return 0;
+    let sum = 0;
+    for (let index = 0; index < count; index += 1) {
+        sum += Math.abs((a[index] ?? 0) - (b[index] ?? 0));
+    }
+    return sum / count;
+}
+/** `#rrggbb` for an 8-bit triple. */
+function toHex(red, green, blue) {
+    const channel = (value) => Math.max(0, Math.min(255, Math.round(value)))
+        .toString(16)
+        .padStart(2, "0");
+    return `#${channel(red)}${channel(green)}${channel(blue)}`;
+}
+/**
+ * The `count` most common colours in a frame, by 4×4×4-bit quantization.
+ *
+ * Quantizing to 4 bits per channel (4096 buckets) and reporting each winning
+ * bucket's *mean* colour is what makes the answer stable: naming the exact
+ * modal pixel would return a different hex on every frame of the same shot.
+ */
+export function dominantColors(rgba, width, height, count = 5) {
+    const pixels = width * height;
+    if (pixels <= 0)
+        return [];
+    const totals = new Map();
+    for (let index = 0; index < pixels; index += 1) {
+        const offset = index * 4;
+        const red = rgba[offset] ?? 0;
+        const green = rgba[offset + 1] ?? 0;
+        const blue = rgba[offset + 2] ?? 0;
+        const key = ((red >> 4) << 8) | ((green >> 4) << 4) | (blue >> 4);
+        const bucket = totals.get(key);
+        if (bucket) {
+            bucket.red += red;
+            bucket.green += green;
+            bucket.blue += blue;
+            bucket.n += 1;
+        }
+        else {
+            totals.set(key, { red, green, blue, n: 1 });
+        }
+    }
+    return [...totals.values()]
+        .sort((a, b) => b.n - a.n)
+        .slice(0, count)
+        .map((bucket) => {
+        const rgb = [
+            bucket.red / bucket.n,
+            bucket.green / bucket.n,
+            bucket.blue / bucket.n
+        ];
+        return {
+            hex: toHex(rgb[0], rgb[1], rgb[2]),
+            share: bucket.n / pixels,
+            rgb
+        };
+    });
+}
+/** The motion and histogram series over a sampled sequence. */
+export function frameTransitions(frames) {
+    const transitions = [];
+    for (let index = 1; index < frames.length; index += 1) {
+        const previous = frames[index - 1];
+        const current = frames[index];
+        transitions.push({
+            time: current.time,
+            motion: motionScore(previous.luma, current.luma),
+            histogramDistance: histogramDistance(previous.histogram, current.histogram)
+        });
+    }
+    return transitions;
+}
+/**
+ * Cut times: transitions whose histogram distance clears `threshold`.
+ *
+ * The sampling rate bounds the accuracy — a cut is placed at the first sampled
+ * frame that belongs to the new shot, so at 4 fps a reported time is within
+ * 250 ms of the real one. `minShotSeconds` suppresses a second cut inside one
+ * dissolve, which otherwise reports a fade as a burst of shots.
+ */
+export function detectCuts(transitions, threshold = 0.3, minShotSeconds = 0.4) {
+    const cuts = [];
+    let lastCut = Number.NEGATIVE_INFINITY;
+    for (const transition of transitions) {
+        if (transition.histogramDistance < threshold)
+            continue;
+        if (transition.time - lastCut < minShotSeconds)
+            continue;
+        cuts.push(transition.time);
+        lastCut = transition.time;
+    }
+    return cuts;
+}
+/** Group sampled frames into shots at the given cut times. */
+export function shotsFromCuts(frames, transitions, cuts, duration) {
+    if (frames.length === 0)
+        return [];
+    const bounds = [0, ...cuts, duration];
+    const shots = [];
+    for (let index = 0; index + 1 < bounds.length; index += 1) {
+        const start = bounds[index];
+        const end = bounds[index + 1];
+        if (end <= start)
+            continue;
+        const inside = frames.filter((frame) => frame.time >= start && frame.time < end);
+        const moving = transitions.filter((transition) => transition.time > start && transition.time < end);
+        shots.push({
+            index: shots.length,
+            start,
+            end,
+            duration: end - start,
+            brightness: inside.length > 0
+                ? inside.reduce((sum, frame) => sum + frame.stats.brightness, 0) /
+                    inside.length
+                : 0,
+            motion: moving.length > 0
+                ? moving.reduce((sum, transition) => sum + transition.motion, 0) /
+                    moving.length
+                : 0
+        });
+    }
+    return shots;
+}
+/** Runs of consecutive frames for which `predicate` holds, by frame index. */
+export function runsOf(frames, predicate, frameDuration, minSeconds) {
+    const runs = [];
+    let start = null;
+    const close = (endTime) => {
+        if (start === null)
+            return;
+        const duration = endTime - start;
+        if (duration >= minSeconds)
+            runs.push({ start, end: endTime, duration });
+        start = null;
+    };
+    for (let index = 0; index < frames.length; index += 1) {
+        if (predicate(index)) {
+            start ??= frames[index].time;
+        }
+        else {
+            close(frames[index].time);
+        }
+    }
+    const last = frames.at(-1);
+    if (last)
+        close(last.time + frameDuration);
+    return runs;
+}
+//# sourceMappingURL=video-frames.js.map

package/dist/analysis/video-frames.js.map

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

package/dist/apify/assets.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Bringing actor-produced bytes into NodeTool.
+ *
+ * An actor that makes a file — a screenshot, a downloaded video, a rendered
+ * PDF — does not hand back the bytes. It hands back a URL into Apify's storage,
+ * and those URLs expire. Returning one as if it were a NodeTool asset produces
+ * a workflow that works today and is broken next week, so anything worth
+ * keeping is fetched through trusted host code and written to NodeTool storage
+ * here.
+ *
+ * Three properties this file exists to hold:
+ *
+ * - **The guest never fetches.** The download runs on the host through
+ *   `safeFetch`, so the URL and every redirect hop are screened for SSRF. An
+ *   actor is a third party, and its output URL is therefore attacker-
+ *   influenced input, not a trusted handle.
+ * - **Size is bounded before it is read.** A `Content-Length` past the cap is
+ *   refused without downloading, and the streaming read is cut off at the cap
+ *   for a server that declares nothing — a 4 GB video must not become a 4 GB
+ *   buffer.
+ * - **A failure to import is not a failure of the run.** The actor already ran
+ *   and already cost money. An import that fails reports itself and leaves the
+ *   remote URL in place, so the caller still has something to use.
+ */
+import type { ProcessingContext } from "@nodetool-ai/runtime";
+/** Largest actor file imported into storage, in bytes. */
+export declare const MAX_IMPORT_BYTES: number;
+/** What an import produced, or why it did not. */
+export interface ImportedFile {
+    /** The URL the bytes came from. Always present, even on failure. */
+    readonly source_url: string;
+    readonly content_type?: string;
+    readonly size_bytes?: number;
+    /** "image" | "audio" | "video" | "file", from the MIME type. */
+    readonly kind?: string;
+    /** UI-fetchable URL for the stored copy. */
+    readonly asset_url?: string;
+    /** Workspace key, when the caller asked for one. */
+    readonly output_file?: string;
+    /** Set when the import failed; the run itself still succeeded. */
+    readonly import_error?: string;
+}
+/**
+ * Fetch one actor-produced URL and persist it.
+ *
+ * Returns a record rather than throwing on an import failure: the actor run
+ * behind this URL has already been paid for, and losing its whole result
+ * because one of twenty images 404'd is the wrong trade.
+ */
+export declare function importActorFile(context: ProcessingContext, url: string, options?: {
+    outputFile?: string;
+    signal?: AbortSignal;
+}): Promise<ImportedFile>;
+/** Persist bytes already in hand — a key-value record, say. */
+export declare function importActorBytes(context: ProcessingContext, bytes: Uint8Array, contentType: string, options?: {
+    outputFile?: string;
+    label?: string;
+}): Promise<ImportedFile>;
+/**
+ * Whether a content type is worth importing rather than leaving remote.
+ *
+ * Text and JSON are already in the result — importing them would store a copy
+ * of something the caller can read directly. Binary is the case an asset
+ * exists for.
+ */
+export declare function isBinaryContentType(contentType: string): boolean;
+/** Most files one run imports from its dataset. */
+export declare const MAX_FILES_PER_RUN = 5;
+/** Whether a string is a URL into Apify's key-value storage — a produced file. */
+export declare function isApifyRecordUrl(value: string): boolean;
+/**
+ * The Apify storage URLs a dataset preview points at, in order of first
+ * appearance and without duplicates. Every actor names its file field
+ * differently (`downloadedFileUrl`, `screenshotUrl`, `fileUrl`), so this walks
+ * every string at any depth and keeps the ones that live in Apify's store —
+ * the URLs that expire, and therefore the ones worth importing. Anything else
+ * (a YouTube manifest, a page URL) is data, not a produced file.
+ */
+export declare function collectRecordUrls(items: readonly unknown[], limit?: number): string[];
+//# sourceMappingURL=assets.d.ts.map

package/dist/apify/assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../../src/apify/assets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAK9D,0DAA0D;AAC1D,eAAO,MAAM,gBAAgB,QAAoB,CAAC;AAElD,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC3B,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,gEAAgE;IAChE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,oDAAoD;IACpD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAqDD;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,iBAAiB,EAC1B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GAC1D,OAAO,CAAC,YAAY,CAAC,CAkCvB;AAED,+DAA+D;AAC/D,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GACpD,OAAO,CAAC,YAAY,CAAC,CA6BvB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAQhE;AAED,mDAAmD;AACnD,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAKnC,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,OAAO,EAAE,EACzB,KAAK,SAAoB,GACxB,MAAM,EAAE,CAsBV"}

package/dist/apify/assets.js

@@ -0,0 +1,192 @@
+/**
+ * Bringing actor-produced bytes into NodeTool.
+ *
+ * An actor that makes a file — a screenshot, a downloaded video, a rendered
+ * PDF — does not hand back the bytes. It hands back a URL into Apify's storage,
+ * and those URLs expire. Returning one as if it were a NodeTool asset produces
+ * a workflow that works today and is broken next week, so anything worth
+ * keeping is fetched through trusted host code and written to NodeTool storage
+ * here.
+ *
+ * Three properties this file exists to hold:
+ *
+ * - **The guest never fetches.** The download runs on the host through
+ *   `safeFetch`, so the URL and every redirect hop are screened for SSRF. An
+ *   actor is a third party, and its output URL is therefore attacker-
+ *   influenced input, not a trusted handle.
+ * - **Size is bounded before it is read.** A `Content-Length` past the cap is
+ *   refused without downloading, and the streaming read is cut off at the cap
+ *   for a server that declares nothing — a 4 GB video must not become a 4 GB
+ *   buffer.
+ * - **A failure to import is not a failure of the run.** The actor already ran
+ *   and already cost money. An import that fails reports itself and leaves the
+ *   remote URL in place, so the caller still has something to use.
+ */
+import { safeFetch } from "@nodetool-ai/runtime";
+import { persistBinaryOutput } from "../tools/binary-output.js";
+import { ApifyError } from "./errors.js";
+/** Largest actor file imported into storage, in bytes. */
+export const MAX_IMPORT_BYTES = 100 * 1024 * 1024;
+/** Read a response body, stopping at `limit` rather than buffering past it. */
+async function readCapped(response, limit) {
+    const declared = Number(response.headers?.get?.("content-length") ?? "");
+    if (Number.isFinite(declared) && declared > limit) {
+        throw new ApifyError("asset_download_failed", `The file is ${declared} bytes, past the ${limit}-byte import limit.`);
+    }
+    const body = response.body;
+    if (!body) {
+        const buffer = new Uint8Array(await response.arrayBuffer());
+        if (buffer.byteLength > limit) {
+            throw new ApifyError("asset_download_failed", `The file exceeded the ${limit}-byte import limit.`);
+        }
+        return buffer;
+    }
+    const chunks = [];
+    let total = 0;
+    const reader = body.getReader();
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > limit) {
+            await reader.cancel().catch(() => undefined);
+            throw new ApifyError("asset_download_failed", `The file exceeded the ${limit}-byte import limit while downloading.`);
+        }
+        chunks.push(value);
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+}
+/**
+ * Fetch one actor-produced URL and persist it.
+ *
+ * Returns a record rather than throwing on an import failure: the actor run
+ * behind this URL has already been paid for, and losing its whole result
+ * because one of twenty images 404'd is the wrong trade.
+ */
+export async function importActorFile(context, url, options = {}) {
+    try {
+        const response = await safeFetch(url, { signal: options.signal });
+        if (!response.ok) {
+            throw new ApifyError("asset_download_failed", `Downloading ${url} failed with HTTP ${response.status}.`);
+        }
+        const contentType = response.headers?.get?.("content-type")?.split(";")[0]?.trim() ??
+            "application/octet-stream";
+        const bytes = await readCapped(response, MAX_IMPORT_BYTES);
+        const persisted = await persistBinaryOutput(context, bytes, {
+            contentType,
+            uiPrefix: "apify",
+            outputFile: options.outputFile
+        });
+        return {
+            source_url: url,
+            content_type: contentType,
+            size_bytes: bytes.byteLength,
+            kind: persisted.kind,
+            asset_url: persisted.asset_url,
+            output_file: persisted.output_file
+        };
+    }
+    catch (e) {
+        return {
+            source_url: url,
+            import_error: e instanceof Error ? e.message : String(e)
+        };
+    }
+}
+/** Persist bytes already in hand — a key-value record, say. */
+export async function importActorBytes(context, bytes, contentType, options = {}) {
+    const label = options.label ?? "record";
+    if (bytes.byteLength > MAX_IMPORT_BYTES) {
+        return {
+            source_url: label,
+            size_bytes: bytes.byteLength,
+            import_error: `The ${label} is ${bytes.byteLength} bytes, past the ${MAX_IMPORT_BYTES}-byte import limit.`
+        };
+    }
+    try {
+        const persisted = await persistBinaryOutput(context, bytes, {
+            contentType,
+            uiPrefix: "apify",
+            outputFile: options.outputFile
+        });
+        return {
+            source_url: label,
+            content_type: contentType,
+            size_bytes: bytes.byteLength,
+            kind: persisted.kind,
+            asset_url: persisted.asset_url,
+            output_file: persisted.output_file
+        };
+    }
+    catch (e) {
+        return {
+            source_url: label,
+            import_error: e instanceof Error ? e.message : String(e)
+        };
+    }
+}
+/**
+ * Whether a content type is worth importing rather than leaving remote.
+ *
+ * Text and JSON are already in the result — importing them would store a copy
+ * of something the caller can read directly. Binary is the case an asset
+ * exists for.
+ */
+export function isBinaryContentType(contentType) {
+    const type = contentType.split(";")[0].trim().toLowerCase();
+    if (type.startsWith("text/"))
+        return false;
+    return !(type === "application/json" ||
+        type === "application/xml" ||
+        type === "application/javascript");
+}
+/** Most files one run imports from its dataset. */
+export const MAX_FILES_PER_RUN = 5;
+const APIFY_RECORD_URL = /^https:\/\/api\.apify\.com\/v2\/key-value-stores\/[A-Za-z0-9]+\/records\/[^\s"']+$/;
+/** Whether a string is a URL into Apify's key-value storage — a produced file. */
+export function isApifyRecordUrl(value) {
+    return APIFY_RECORD_URL.test(value);
+}
+/**
+ * The Apify storage URLs a dataset preview points at, in order of first
+ * appearance and without duplicates. Every actor names its file field
+ * differently (`downloadedFileUrl`, `screenshotUrl`, `fileUrl`), so this walks
+ * every string at any depth and keeps the ones that live in Apify's store —
+ * the URLs that expire, and therefore the ones worth importing. Anything else
+ * (a YouTube manifest, a page URL) is data, not a produced file.
+ */
+export function collectRecordUrls(items, limit = MAX_FILES_PER_RUN) {
+    const found = [];
+    const seen = new Set();
+    const walk = (value, depth) => {
+        if (found.length >= limit || depth > 8)
+            return;
+        if (typeof value === "string") {
+            if (isApifyRecordUrl(value) && !seen.has(value)) {
+                seen.add(value);
+                found.push(value);
+            }
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (const entry of value)
+                walk(entry, depth + 1);
+            return;
+        }
+        if (value !== null && typeof value === "object") {
+            for (const entry of Object.values(value))
+                walk(entry, depth + 1);
+        }
+    };
+    for (const item of items)
+        walk(item, 0);
+    return found;
+}
+//# sourceMappingURL=assets.js.map

package/dist/apify/assets.js.map

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

package/dist/apify/catalog.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The actors NodeTool ships knowing about.
+ *
+ * Two jobs, and they are separate. The catalog is the **default allowlist** —
+ * what an install runs without anyone approving anything — and it is the
+ * lookup behind the ergonomic wrappers (`crawl_website` and friends), which
+ * are thin: a wrapper picks an entry here, maps a handful of named arguments
+ * onto that actor's input, and calls the same generic run path a model would.
+ *
+ * Entries are chosen for being first-party (`apify/*`) or the long-standing
+ * community actor for a capability with no official equivalent, with a stable
+ * documented input schema. An actor is not added because it ranks first in a
+ * store search. `costHint` is the shape of the bill, not a price: the price
+ * moves, and `get_apify_actor` reads the live figure from the store record.
+ */
+/** What an actor is for, so a wrapper and a model can both find one. */
+export type ActorCapability = "crawl" | "extract" | "browser" | "search" | "places" | "social" | "media" | "screenshot" | "transcript";
+export interface CatalogActor {
+    /** Canonical `owner/name` id. */
+    readonly id: string;
+    readonly capability: ActorCapability;
+    /** One line, for a model choosing between entries. */
+    readonly summary: string;
+    /** Roughly what a run bills on, for the cheapest-thing-that-works choice. */
+    readonly costHint: "per-result" | "per-page" | "per-event" | "compute-time";
+}
+/**
+ * The shipped allowlist.
+ *
+ * Ordered cheapest-and-most-specific first within each capability, which is
+ * also the order a model reads them in: `website-content-crawler` before
+ * `playwright-scraper` means the default answer to "get me this page" is an
+ * HTTP fetch, not a browser.
+ */
+export declare const ACTOR_CATALOG: readonly CatalogActor[];
+/** The catalog entry for a canonical actor id, if NodeTool ships one. */
+export declare function catalogActor(id: string): CatalogActor | undefined;
+/** Every shipped actor for one capability, in catalog (preference) order. */
+export declare function actorsFor(capability: ActorCapability): readonly CatalogActor[];
+/** The default actor a wrapper uses for a capability. */
+export declare function defaultActorFor(capability: ActorCapability): CatalogActor | undefined;
+/** The ids that make up the shipped default allowlist. */
+export declare const CATALOG_ACTOR_IDS: readonly string[];
+//# sourceMappingURL=catalog.d.ts.map

package/dist/apify/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/apify/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,wEAAwE;AACxE,MAAM,MAAM,eAAe,GACvB,OAAO,GACP,SAAS,GACT,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,YAAY,GACZ,YAAY,CAAC;AAEjB,MAAM,WAAW,YAAY;IAC3B,iCAAiC;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,UAAU,GAAG,WAAW,GAAG,cAAc,CAAC;CAC7E;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,YAAY,EA2EhD,CAAC;AAIF,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAEjE;AAED,6EAA6E;AAC7E,wBAAgB,SAAS,CACvB,UAAU,EAAE,eAAe,GAC1B,SAAS,YAAY,EAAE,CAEzB;AAED,yDAAyD;AACzD,wBAAgB,eAAe,CAC7B,UAAU,EAAE,eAAe,GAC1B,YAAY,GAAG,SAAS,CAE1B;AAED,0DAA0D;AAC1D,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAE9C,CAAC"}