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

package/dist/host-binaries.js

@@ -0,0 +1,344 @@
+/**
+ * Spawn a PATH binary with argv (no shell) inside the workspace.
+ *
+ * Used by the ffmpeg and yt-dlp capabilities. A missing binary is a named
+ * error, not an ENOENT stack.
+ *
+ * What the caller gets is bounded on every axis a media tool can exhaust,
+ * because the argv behind it comes from a model:
+ *
+ * - **Wall clock** — `timeoutMs`, SIGTERM then SIGKILL five seconds later.
+ * - **Memory** — captured stdout/stderr stop at {@link MAX_CAPTURED_BYTES}
+ *   each. `-loglevel debug` over a long clip used to accumulate the whole
+ *   stream into one string in the server's heap.
+ * - **Disk** — `maxArtifactBytes` watches the file being written and kills the
+ *   child when it passes the cap. ffmpeg's own `-fs` does not hold: measured
+ *   against ffmpeg 6.1, `-fs 50000` still produced a 164 KB mp4.
+ * - **CPU** — spawns run at most `maxConcurrentHostBinaries` at once per
+ *   concurrency class; the rest queue. One run cannot take every core from
+ *   the request handlers. The `render` class has its own cap
+ *   (`NODETOOL_BLENDER_CONCURRENCY`) so a minutes-long render never holds a
+ *   slot a two-second ffmpeg call is waiting for.
+ *
+ * The filesystem/network half of the boundary lives in
+ * `host-binary-guard.ts` in `@nodetool-ai/agents`.
+ */
+import { spawn } from "node:child_process";
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { isNumber, isObjectLike } from "@nodetool-ai/protocol";
+/** Captured bytes kept per stream. Beyond this the tail is dropped. */
+export const MAX_CAPTURED_BYTES = 256 * 1024;
+/** Default ceiling on a single artifact a host binary writes (2 GiB). */
+export const MAX_ARTIFACT_BYTES = 2 * 1024 * 1024 * 1024;
+/** How often the artifact watchdog stats the file it is watching. */
+const ARTIFACT_POLL_MS = 500;
+/**
+ * Concurrent host-binary spawns. `NODETOOL_HOST_BINARY_CONCURRENCY` overrides
+ * it; anything unparseable or non-positive keeps the default.
+ */
+export function maxConcurrentHostBinaries() {
+    const raw = Number(process.env["NODETOOL_HOST_BINARY_CONCURRENCY"]);
+    return Number.isFinite(raw) && raw >= 1 ? Math.floor(raw) : 2;
+}
+/**
+ * Concurrent spawns in the `render` class. `NODETOOL_BLENDER_CONCURRENCY`
+ * overrides it; anything unparseable or non-positive keeps the default of 1.
+ */
+function maxConcurrentBlenderRenders() {
+    const raw = Number(process.env["NODETOOL_BLENDER_CONCURRENCY"]);
+    return Number.isFinite(raw) && raw >= 1 ? Math.floor(raw) : 1;
+}
+/** The class every run queues on when it passes no `concurrencyClass`. */
+const DEFAULT_CONCURRENCY_CLASS = "default";
+/** The class for long renders; capped separately from the default class. */
+const RENDER_CONCURRENCY_CLASS = "render";
+const slots = new Map();
+function slotFor(concurrencyClass) {
+    let slot = slots.get(concurrencyClass);
+    if (slot === undefined) {
+        slot = { running: 0, waiting: [] };
+        slots.set(concurrencyClass, slot);
+    }
+    return slot;
+}
+function capFor(concurrencyClass) {
+    return concurrencyClass === RENDER_CONCURRENCY_CLASS
+        ? maxConcurrentBlenderRenders()
+        : maxConcurrentHostBinaries();
+}
+/**
+ * Take a slot in the run's class, waiting behind that class's queue when
+ * every slot is busy. Classes are independent: a run in one class never
+ * blocks another class.
+ *
+ * A waiter does not increment on wake: the releasing run *hands over* its
+ * slot, so the count never dips between the two. Decrementing first and
+ * letting the waiter re-increment leaves a window — between resolving the
+ * waiter's promise and its continuation running — in which the count reads one
+ * below the truth, and a caller arriving inside it would take a slot the woken
+ * waiter is also about to take. No test here reproduces that interleaving; the
+ * hand-off removes the window rather than relying on it staying unreachable.
+ */
+async function acquireSlot(concurrencyClass, signal) {
+    const slot = slotFor(concurrencyClass);
+    if (slot.running < capFor(concurrencyClass)) {
+        slot.running++;
+        return;
+    }
+    signal?.throwIfAborted();
+    await new Promise((resolve, reject) => {
+        let settled = false;
+        const waiter = () => {
+            if (settled)
+                return;
+            settled = true;
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        };
+        const onAbort = () => {
+            if (settled)
+                return;
+            settled = true;
+            const index = slot.waiting.indexOf(waiter);
+            if (index >= 0)
+                slot.waiting.splice(index, 1);
+            const reason = signal?.reason;
+            reject(reason instanceof Error
+                ? reason
+                : new Error(`Host binary run aborted: ${String(reason)}`));
+        };
+        slot.waiting.push(waiter);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function releaseSlot(concurrencyClass) {
+    const slot = slotFor(concurrencyClass);
+    const next = slot.waiting.shift();
+    if (next) {
+        next();
+        return;
+    }
+    slot.running--;
+}
+/** Append to a captured stream, stopping at the cap. */
+function capture(buffer, chunk) {
+    if (buffer.length >= MAX_CAPTURED_BYTES) {
+        return { text: buffer, truncated: true };
+    }
+    const room = MAX_CAPTURED_BYTES - buffer.length;
+    if (chunk.length <= room)
+        return { text: buffer + chunk, truncated: false };
+    return { text: buffer + chunk.slice(0, room), truncated: true };
+}
+export class HostBinaryMissingError extends Error {
+    binary;
+    constructor(binary) {
+        super(`${binary} is not installed or is not on PATH. ` +
+            `Install it with the Package Manager, or add it to PATH.`);
+        this.name = "HostBinaryMissingError";
+        this.binary = binary;
+    }
+}
+export async function runHostBinary(cmd, args, opts) {
+    opts.signal?.throwIfAborted();
+    const concurrencyClass = opts.concurrencyClass === undefined || opts.concurrencyClass === ""
+        ? DEFAULT_CONCURRENCY_CLASS
+        : opts.concurrencyClass;
+    const queuedStart = Date.now();
+    await acquireSlot(concurrencyClass, opts.signal);
+    const queuedMs = Date.now() - queuedStart;
+    try {
+        const result = await spawnBounded(cmd, args, opts);
+        return { ...result, queuedMs };
+    }
+    finally {
+        releaseSlot(concurrencyClass);
+    }
+}
+function spawnBounded(cmd, args, opts) {
+    return new Promise((resolve, reject) => {
+        opts.signal?.throwIfAborted();
+        const signal = opts.signal;
+        const child = spawn(cmd, args, {
+            cwd: opts.cwd,
+            stdio: "pipe",
+            env: opts.env ?? process.env
+        });
+        let stdout = "";
+        let stderr = "";
+        let truncated = false;
+        let timedOut = false;
+        let overran = false;
+        let aborted = false;
+        let killTimer;
+        const kill = () => {
+            child.kill("SIGTERM");
+            killTimer = setTimeout(() => child.kill("SIGKILL"), 5000);
+        };
+        // Record the abort and kill, but settle only on `close` below: the
+        // caller frees its concurrency slot and deletes its scratch directory
+        // when this promise settles, and both must wait until the child is
+        // actually gone — a child that ignores SIGTERM lives on until SIGKILL.
+        const onAbort = () => {
+            aborted = true;
+            kill();
+        };
+        const abortReason = () => {
+            const reason = signal?.reason;
+            return reason instanceof Error
+                ? reason
+                : new Error(`Host binary run aborted: ${String(reason)}`);
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            kill();
+        }, opts.timeoutMs);
+        const artifactCap = opts.maxArtifactBytes ?? MAX_ARTIFACT_BYTES;
+        const artifact = opts.artifactPath !== undefined && opts.artifactPath !== ""
+            ? path.resolve(opts.cwd, opts.artifactPath)
+            : undefined;
+        const watchdog = artifact === undefined
+            ? undefined
+            : setInterval(() => {
+                void stat(artifact)
+                    .then((info) => {
+                    if (info.size <= artifactCap || overran)
+                        return;
+                    overran = true;
+                    kill();
+                })
+                    // Not written yet, or already gone: nothing to bound.
+                    .catch(() => undefined);
+            }, ARTIFACT_POLL_MS);
+        const done = () => {
+            clearTimeout(timer);
+            if (killTimer)
+                clearTimeout(killTimer);
+            if (watchdog)
+                clearInterval(watchdog);
+            if (signal !== undefined)
+                signal.removeEventListener("abort", onAbort);
+        };
+        // A line with no newline yet. Flushed as a line at MAX_CAPTURED_BYTES so
+        // a child that never prints a newline cannot grow this buffer without
+        // bound; every newline-terminated line still arrives as exactly one call.
+        let stderrPending = "";
+        const feedStderrLines = (chunk) => {
+            const onStderrLine = opts.onStderrLine;
+            if (onStderrLine === undefined)
+                return;
+            stderrPending += chunk;
+            let newline = stderrPending.indexOf("\n");
+            while (newline >= 0) {
+                const line = stderrPending.slice(0, newline).replace(/\r$/, "");
+                stderrPending = stderrPending.slice(newline + 1);
+                try {
+                    onStderrLine(line);
+                }
+                catch {
+                    // A progress callback must not kill the run it observes.
+                }
+                newline = stderrPending.indexOf("\n");
+            }
+            if (stderrPending.length > MAX_CAPTURED_BYTES) {
+                const line = stderrPending;
+                stderrPending = "";
+                try {
+                    onStderrLine(line);
+                }
+                catch {
+                    // A progress callback must not kill the run it observes.
+                }
+            }
+        };
+        if (signal !== undefined)
+            signal.addEventListener("abort", onAbort);
+        child.stdout.on("data", (chunk) => {
+            const next = capture(stdout, String(chunk));
+            stdout = next.text;
+            truncated = truncated || next.truncated;
+        });
+        child.stderr.on("data", (chunk) => {
+            const text = String(chunk);
+            const next = capture(stderr, text);
+            stderr = next.text;
+            truncated = truncated || next.truncated;
+            feedStderrLines(text);
+        });
+        child.on("error", (err) => {
+            done();
+            if (aborted) {
+                reject(abortReason());
+                return;
+            }
+            const code = isObjectLike(err) && "code" in err ? String(err.code) : "";
+            if (code === "ENOENT") {
+                reject(new HostBinaryMissingError(cmd));
+                return;
+            }
+            reject(err);
+        });
+        child.on("close", (code) => {
+            done();
+            if (aborted) {
+                reject(abortReason());
+                return;
+            }
+            if (timedOut) {
+                resolve({
+                    stdout,
+                    stderr: `${stderr}\nProcess timed out after ${opts.timeoutMs}ms`,
+                    exitCode: 124,
+                    truncated
+                });
+                return;
+            }
+            if (overran) {
+                resolve({
+                    stdout,
+                    stderr: `${stderr}\nStopped: ${opts.artifactPath} passed the ` +
+                        `${artifactCap}-byte output limit`,
+                    exitCode: 124,
+                    truncated
+                });
+                return;
+            }
+            resolve({ stdout, stderr, exitCode: code ?? 0, truncated });
+        });
+    });
+}
+const EXT_MIME = {
+    mp4: "video/mp4",
+    webm: "video/webm",
+    mkv: "video/x-matroska",
+    mov: "video/quicktime",
+    mp3: "audio/mpeg",
+    wav: "audio/wav",
+    flac: "audio/flac",
+    ogg: "audio/ogg",
+    m4a: "audio/mp4",
+    aac: "audio/aac",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    webp: "image/webp",
+    gif: "image/gif"
+};
+export function mimeFromFilename(filePath) {
+    const ext = path.extname(filePath).slice(1).toLowerCase();
+    return EXT_MIME[ext] ?? "application/octet-stream";
+}
+/**
+ * Whole seconds in `[1, max]`, or `fallback` when `raw` states no usable
+ * duration. The floor is 1, not 0: truncating a sub-second request to 0 would
+ * reach `runHostBinary` as `setTimeout(kill, 0)` and SIGTERM the child on the
+ * next tick.
+ */
+export function clampTimeoutSeconds(raw, fallback, max) {
+    const n = isNumber(raw) ? raw : fallback;
+    if (!Number.isFinite(n) || n <= 0)
+        return fallback;
+    return Math.min(Math.max(Math.floor(n), 1), max);
+}
+//# sourceMappingURL=host-binaries.js.map

package/dist/host-binaries.js.map

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

package/dist/image-codec.d.ts

@@ -0,0 +1,74 @@
+import { type ImageRef } from "@nodetool-ai/protocol";
+/**
+ * Actionable error for a missing/broken `sharp` native addon, thrown by the
+ * raw-RGBA → PNG encoder when {@link loadSharp} resolves null and no Canvas
+ * fallback applies.
+ */
+export declare const SHARP_UNAVAILABLE_MESSAGE: string;
+/** Encode raw straight-alpha RGBA8 pixels to PNG bytes. */
+export declare function encodeRawRgbaToPng(data: Uint8Array, width: number, height: number): Promise<Uint8Array>;
+/**
+ * If `ref` is a raw-RGBA image, return an equivalent ImageRef with `data`
+ * encoded to PNG and `mimeType` set to `image/png`; otherwise return it
+ * unchanged. Use at any boundary that must hand out a portable image.
+ */
+export declare function encodeRawImageRef<T>(ref: T): Promise<T | ImageRef>;
+/**
+ * Rasterize SVG markup to PNG bytes.
+ *
+ * Vector sources reach the raster paths (a vision provider's image block, a
+ * crop, a downscale) only through here. Two rules the caller does not have to
+ * know about:
+ *
+ * - **No external references.** The decoder behind `sharp` is librsvg, which
+ *   resolves `href` and `url()` against the process's own filesystem and
+ *   network. Since the markup here is written by a model or uploaded by
+ *   whoever, a document that reaches outward is refused by name rather than
+ *   rendered — the error tells the caller to inline the resource.
+ * - **A usable size.** An SVG that declares `width="24"` renders to a 24px
+ *   PNG, which is not something a model can read. `minSide` scales the render
+ *   up so the result is worth looking at, defaulting to
+ *   {@link SVG_FALLBACK_SIDE}.
+ */
+export declare function rasterizeSvg(bytes: Uint8Array, opts?: {
+    minSide?: number;
+    maxSide?: number;
+}): Promise<{
+    data: Uint8Array;
+    width: number;
+    height: number;
+}>;
+/** A crop box in source-image pixels. */
+export interface ImageRegion {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Decode encoded image bytes (PNG/JPEG/WebP/…), optionally crop to a pixel
+ * `region` and/or downscale so the longest side fits `maxSide`, then re-encode
+ * to PNG. Used by the `view_image` tool to load only the pixels an agent asks
+ * for — a region crop and a "low" detail downscale both cut the token cost of
+ * the image the model actually sees.
+ *
+ * Coordinates are clamped to the image bounds, so an over-large or partly
+ * out-of-frame region yields the overlapping area rather than an error. When
+ * `sharp` is unavailable (off Node, or a broken native addon) the original
+ * bytes are returned unchanged with `width`/`height` 0 — the caller still gets
+ * a viewable full image, just uncropped. In that pass-through case the returned
+ * `mimeType` is `opts.sourceMime` (the caller's known format) so the bytes are
+ * never mislabeled; it falls back to `image/png` only when the caller didn't
+ * provide one.
+ */
+export declare function extractImageRegion(bytes: Uint8Array, opts?: {
+    region?: ImageRegion;
+    maxSide?: number;
+    sourceMime?: string;
+}): Promise<{
+    data: Uint8Array;
+    mimeType: string;
+    width: number;
+    height: number;
+}>;
+//# sourceMappingURL=image-codec.d.ts.map

package/dist/image-codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-codec.d.ts","sourceRoot":"","sources":["../src/image-codec.ts"],"names":[],"mappings":"AAWA,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAQtE;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,QAIsC,CAAC;AA+B7E,2DAA2D;AAC3D,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,UAAU,CAAC,CA2BrB;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,QAAQ,CAAC,CAIxE;AA2ED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,UAAU,EACjB,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAChD,OAAO,CAAC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAmD9D;AAED,yCAAyC;AACzC,MAAM,WAAW,WAAW;IAC1B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,UAAU,EACjB,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACzE,OAAO,CAAC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA+ChF"}