@camstack/addon-pipeline 1.1.42 → 1.1.44

package/dist/session-decode/decode-worker-child.js

@@ -1,5 +1,11 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_chunk = require("../chunk-D6vf50IK.js");
 const require_worker_protocol = require("../worker-protocol-BCfO8gUF.js");
+let node_url = require("node:url");
+let node_fs = require("node:fs");
+node_fs = require_chunk.__toESM(node_fs);
+let node_path = require("node:path");
+node_path = require_chunk.__toESM(node_path);
 //#region src/session-decode/frame-slot.ts
 function toReply(held) {
 	return {
@@ -104,6 +110,30 @@ var FrameSlot = class {
 };
 //#endregion
 //#region src/session-decode/decode-worker-child.ts
+/**
+* Decode-worker CHILD entry point — Epic C P1, Task 2.
+*
+* This file is the whole program run by a per-session `child_process.fork`
+* that the pipeline-runner's session-decode coordinator (Task 3) spawns and
+* tears down on session end, so the OS reclaims the VAAPI/GPU decode pool by
+* process exit (Task 0 live-validated that reclaim-by-exit works — node-av
+* does not release the hw_frames_ctx pool on `dispose()` alone). It decodes
+* with node-av in-process and hands decoded frames to its parent as a
+* request/response PULL over its own dedicated fork IPC channel. Frames
+* NEVER touch `/dev/shm` — no shm sink is ever constructed here.
+*
+* ‼ SANCTIONED RAW IPC — READ BEFORE "FIXING" THIS FILE ‼
+* CLAUDE.md rule #8 forbids `process.send`/`process.on('message')` for
+* BUSINESS LOGIC — that rule governs cross-ADDON traffic, which must travel
+* over the UDS cap/event channel (`LocalChildRegistry`/`LocalChildClient`)
+* instead of raw IPC. This file is NOT a second addon: it is a private
+* worker directly forked by the pipeline-runner addon, exactly like the
+* Python inference pool's own subprocess. The Epic C P1 plan's Global
+* Constraints explicitly carve this out — "a directly-forked worker child
+* talks to its parent over its own IPC channel (this is NOT a cap call and
+* NOT `$process`)". Raw `process.on('message')` / `process.send` are the
+* correct, sanctioned mechanism for this specific file only.
+*/
 /** Re-dial backoff on a transient dial error/EOF (mirrors the decoder's PULL_REDIAL_MS). */
 var REDIAL_MS = 3e3;
 /** How often the worker emits its `framesDecoded/framesSkipped/deliveredFps` line. */
@@ -129,12 +159,66 @@ function pixelFilterName(format) {
 }
 var _nav = null;
 var _consts = null;
+/**
+* Candidate file URLs for a node-av entry (`.` or `./constants`) in the
+* module locations an AGENT lays node-av out in.
+*
+* WHY: this worker runs as a plain `child_process.fork` (see `fork-decode-
+* worker.ts`) which does NOT inherit the addon-runner's module resolution
+* (NODE_PATH / the framework ESM hook). On the HUB the fork inherits that hook,
+* so the bare `import('node-av')` resolves. On an AGENT it does not, so the
+* bare import throws `Cannot find package 'node-av'` and we resolve node-av
+* explicitly from the agent's known layout:
+*   • DOCKER agent — the framework overlay `CAMSTACK_FRAMEWORK_DIR`
+*     (`/data/framework/node_modules/node-av`).
+*   • ELECTRON agent — the app bundle beside `CAMSTACK_BUNDLED_ADDONS_DIR`
+*     (`<resources>/addons`): `<resources>/node_modules/node-av` (+ the
+*     `app.asar.unpacked` mirror).
+* Both env vars point at real dirs only on the respective platform; a missing
+* dir is skipped, and `[]` (dev / hub with the bare import already working)
+* keeps the bare specifier the only path.
+*/
+function fallbackNodeAvUrls(subpath) {
+	const rel = subpath === "." ? "dist/index.js" : "dist/constants/index.js";
+	const dirs = [];
+	const frameworkDir = process.env["CAMSTACK_FRAMEWORK_DIR"];
+	if (frameworkDir !== void 0 && frameworkDir.length > 0) dirs.push(node_path.join(frameworkDir, "node_modules", "node-av"));
+	const bundledAddons = process.env["CAMSTACK_BUNDLED_ADDONS_DIR"];
+	if (bundledAddons !== void 0 && bundledAddons.length > 0) {
+		const resourcesRoot = node_path.dirname(bundledAddons);
+		dirs.push(node_path.join(resourcesRoot, "node_modules", "node-av"));
+		dirs.push(node_path.join(resourcesRoot, "app.asar.unpacked", "node_modules", "node-av"));
+	}
+	const urls = [];
+	for (const dir of dirs) {
+		const entry = node_path.join(dir, rel);
+		if (node_fs.existsSync(entry)) urls.push((0, node_url.pathToFileURL)(entry).href);
+	}
+	return urls;
+}
+/**
+* Import a node-av entry, falling back to the agent's explicit node-av path
+* when the bare specifier can't be resolved (see {@link fallbackNodeAvUrls}).
+* Each candidate is tried in turn so a copy whose native binary fails to load
+* doesn't mask a working one. A dynamic `import(url)` is typed `any`, so the
+* caller's declared module type applies without a cast.
+*/
+async function importNodeAv(bareSpecifier, subpath) {
+	try {
+		return await import(bareSpecifier);
+	} catch (bareErr) {
+		for (const url of fallbackNodeAvUrls(subpath)) try {
+			return await import(url);
+		} catch {}
+		throw bareErr;
+	}
+}
 async function getNodeAv() {
-	if (!_nav) _nav = await import("node-av");
+	if (!_nav) _nav = await importNodeAv("node-av", ".");
 	return _nav;
 }
 async function getConstants() {
-	if (!_consts) _consts = await import("node-av/constants");
+	if (!_consts) _consts = await importNodeAv("node-av/constants", "./constants");
 	return _consts;
 }
 function errMessage(err) {
@@ -318,6 +402,16 @@ var DecodeWorkerChild = class {
 	abortController = null;
 	started = false;
 	stopped = false;
+	/**
+	* The numeric device id this worker decodes for — learned from the `start`
+	* message's {@link VideoFrameSource}. The child's stderr is INHERITED by the
+	* pipeline-runner (silent:false fork), so these lines land in the runner's
+	* raw stderr WITHOUT passing through a scoped logger; prefixing every line
+	* with `[dev:<id>]` (see {@link emitStderr}) is what lets the per-device log
+	* UI attribute the forked worker's output to its camera. `null` only for the
+	* brief pre-`start` window (e.g. a malformed first message).
+	*/
+	deviceId = null;
 	sessionFormat = "rgb";
 	minIntervalMs = 0;
 	/**
@@ -390,16 +484,17 @@ var DecodeWorkerChild = class {
 		const deliveredDelta = this.framesDelivered - this.lastDeliveredSnapshot;
 		const deliveredFps = Math.round(deliveredDelta / windowMs * 1e3 * 10) / 10;
 		const skipped = this.framesSkipped + this.frames.droppedCount;
-		process.stderr.write(`session-decode metrics {framesDecoded:${this.framesDecoded}, framesSkipped:${skipped}, deliveredFps:${deliveredFps}}${final ? " (final)" : ""}\n`);
+		this.emitStderr(`session-decode metrics {framesDecoded:${this.framesDecoded}, framesSkipped:${skipped}, deliveredFps:${deliveredFps}}${final ? " (final)" : ""}\n`);
 		this.lastMetricsAt = now;
 		this.lastDeliveredSnapshot = this.framesDelivered;
 	}
 	handleStart(source, opts) {
 		if (this.started) {
-			process.stderr.write("decode-worker-child: duplicate start ignored\n");
+			this.emitStderr("decode-worker-child: duplicate start ignored\n");
 			return;
 		}
 		this.started = true;
+		this.deviceId = source.deviceId;
 		this.sessionFormat = opts.format ?? "rgb";
 		this.minIntervalMs = opts.fps && opts.fps > 0 ? 1e3 / opts.fps : 0;
 		this.lastMetricsAt = Date.now();
@@ -456,7 +551,7 @@ var DecodeWorkerChild = class {
 				await this.dialAndDecode(nav, C, url);
 			} catch (err) {
 				if (this.stopped) break;
-				process.stderr.write(`decode-worker-child: dial ended — re-dial scheduled: ${errMessage(err)}\n`);
+				this.emitStderr(`decode-worker-child: dial ended — re-dial scheduled: ${errMessage(err)}\n`);
 			} finally {
 				this.closeInput();
 			}
@@ -549,7 +644,7 @@ var DecodeWorkerChild = class {
 				return;
 			}
 			this.hwFilterDecision = "hardware";
-			process.stderr.write(`decode-worker-child: GPU crop+scale path active (${this.gpuScaleFilter})\n`);
+			this.emitStderr(`decode-worker-child: GPU crop+scale path active (${this.gpuScaleFilter})\n`);
 		}
 		this.publishFrame(frame);
 	}
@@ -587,7 +682,7 @@ var DecodeWorkerChild = class {
 			for (const out of outputs) out.free();
 			return ok;
 		} catch (err) {
-			process.stderr.write(`decode-worker-child: GPU filter probe failed — using software decode: ${errMessage(err)}\n`);
+			this.emitStderr(`decode-worker-child: GPU filter probe failed — using software decode: ${errMessage(err)}\n`);
 			return false;
 		} finally {
 			filter?.close();
@@ -764,7 +859,7 @@ var DecodeWorkerChild = class {
 			if (deviceType === null) continue;
 			const hw = nav.HardwareContext.create(deviceType);
 			if (!hw) {
-				process.stderr.write(`decode-worker-child: hwaccel candidate '${backend}' failed — trying next\n`);
+				this.emitStderr(`decode-worker-child: hwaccel candidate '${backend}' failed — trying next\n`);
 				continue;
 			}
 			this.hwContext = hw;
@@ -772,7 +867,7 @@ var DecodeWorkerChild = class {
 			this.hwFilterDecision = this.gpuScaleFilter !== null ? "undecided" : "software";
 			return;
 		}
-		process.stderr.write("decode-worker-child: no hwaccel backend available — using software decode\n");
+		this.emitStderr("decode-worker-child: no hwaccel backend available — using software decode\n");
 	}
 	/** Interruptible re-dial backoff — `teardown` clears the pending timer. */
 	sleep(ms) {
@@ -803,8 +898,19 @@ var DecodeWorkerChild = class {
 	send(reply) {
 		process.send?.(reply);
 	}
+	/**
+	* Write one diagnostic line to the (inherited) stderr, prefixed with the
+	* device tag so the per-device log UI can attribute the forked worker's
+	* output. Public so the module-level process handlers — which only hold the
+	* `worker` instance — emit device-tagged lines too. Callers pass the line
+	* INCLUDING its trailing newline (unchanged from the prior direct writes).
+	*/
+	emitStderr(line) {
+		const tag = this.deviceId === null ? "[dev:?]" : `[dev:${this.deviceId}]`;
+		process.stderr.write(`${tag} ${line}`);
+	}
 	sendError(message, frameId) {
-		process.stderr.write(`${message}\n`);
+		this.emitStderr(`${message}\n`);
 		this.send(frameId === void 0 ? {
 			kind: "error",
 			message
@@ -824,12 +930,12 @@ process.on("disconnect", () => {
 	process.exit(0);
 });
 process.on("uncaughtException", (err) => {
-	process.stderr.write(`decode-worker-child: uncaught exception — ${errMessage(err)}\n`);
+	worker.emitStderr(`decode-worker-child: uncaught exception — ${errMessage(err)}\n`);
 	worker.teardown();
 	process.exit(1);
 });
 process.on("unhandledRejection", (reason) => {
-	process.stderr.write(`decode-worker-child: unhandled rejection — ${errMessage(reason)}\n`);
+	worker.emitStderr(`decode-worker-child: unhandled rejection — ${errMessage(reason)}\n`);
 });
 //#endregion
 exports.DecodeWorkerChild = DecodeWorkerChild;

package/dist/session-decode/decode-worker-child.mjs

@@ -1,4 +1,7 @@
 import { n as isWorkerRequest } from "../worker-protocol-pk7qdYXt.mjs";
+import { pathToFileURL } from "node:url";
+import * as fs from "node:fs";
+import * as path$1 from "node:path";
 //#region src/session-decode/frame-slot.ts
 function toReply(held) {
 	return {
@@ -103,6 +106,30 @@ var FrameSlot = class {
 };
 //#endregion
 //#region src/session-decode/decode-worker-child.ts
+/**
+* Decode-worker CHILD entry point — Epic C P1, Task 2.
+*
+* This file is the whole program run by a per-session `child_process.fork`
+* that the pipeline-runner's session-decode coordinator (Task 3) spawns and
+* tears down on session end, so the OS reclaims the VAAPI/GPU decode pool by
+* process exit (Task 0 live-validated that reclaim-by-exit works — node-av
+* does not release the hw_frames_ctx pool on `dispose()` alone). It decodes
+* with node-av in-process and hands decoded frames to its parent as a
+* request/response PULL over its own dedicated fork IPC channel. Frames
+* NEVER touch `/dev/shm` — no shm sink is ever constructed here.
+*
+* ‼ SANCTIONED RAW IPC — READ BEFORE "FIXING" THIS FILE ‼
+* CLAUDE.md rule #8 forbids `process.send`/`process.on('message')` for
+* BUSINESS LOGIC — that rule governs cross-ADDON traffic, which must travel
+* over the UDS cap/event channel (`LocalChildRegistry`/`LocalChildClient`)
+* instead of raw IPC. This file is NOT a second addon: it is a private
+* worker directly forked by the pipeline-runner addon, exactly like the
+* Python inference pool's own subprocess. The Epic C P1 plan's Global
+* Constraints explicitly carve this out — "a directly-forked worker child
+* talks to its parent over its own IPC channel (this is NOT a cap call and
+* NOT `$process`)". Raw `process.on('message')` / `process.send` are the
+* correct, sanctioned mechanism for this specific file only.
+*/
 /** Re-dial backoff on a transient dial error/EOF (mirrors the decoder's PULL_REDIAL_MS). */
 var REDIAL_MS = 3e3;
 /** How often the worker emits its `framesDecoded/framesSkipped/deliveredFps` line. */
@@ -128,12 +155,66 @@ function pixelFilterName(format) {
 }
 var _nav = null;
 var _consts = null;
+/**
+* Candidate file URLs for a node-av entry (`.` or `./constants`) in the
+* module locations an AGENT lays node-av out in.
+*
+* WHY: this worker runs as a plain `child_process.fork` (see `fork-decode-
+* worker.ts`) which does NOT inherit the addon-runner's module resolution
+* (NODE_PATH / the framework ESM hook). On the HUB the fork inherits that hook,
+* so the bare `import('node-av')` resolves. On an AGENT it does not, so the
+* bare import throws `Cannot find package 'node-av'` and we resolve node-av
+* explicitly from the agent's known layout:
+*   • DOCKER agent — the framework overlay `CAMSTACK_FRAMEWORK_DIR`
+*     (`/data/framework/node_modules/node-av`).
+*   • ELECTRON agent — the app bundle beside `CAMSTACK_BUNDLED_ADDONS_DIR`
+*     (`<resources>/addons`): `<resources>/node_modules/node-av` (+ the
+*     `app.asar.unpacked` mirror).
+* Both env vars point at real dirs only on the respective platform; a missing
+* dir is skipped, and `[]` (dev / hub with the bare import already working)
+* keeps the bare specifier the only path.
+*/
+function fallbackNodeAvUrls(subpath) {
+	const rel = subpath === "." ? "dist/index.js" : "dist/constants/index.js";
+	const dirs = [];
+	const frameworkDir = process.env["CAMSTACK_FRAMEWORK_DIR"];
+	if (frameworkDir !== void 0 && frameworkDir.length > 0) dirs.push(path$1.join(frameworkDir, "node_modules", "node-av"));
+	const bundledAddons = process.env["CAMSTACK_BUNDLED_ADDONS_DIR"];
+	if (bundledAddons !== void 0 && bundledAddons.length > 0) {
+		const resourcesRoot = path$1.dirname(bundledAddons);
+		dirs.push(path$1.join(resourcesRoot, "node_modules", "node-av"));
+		dirs.push(path$1.join(resourcesRoot, "app.asar.unpacked", "node_modules", "node-av"));
+	}
+	const urls = [];
+	for (const dir of dirs) {
+		const entry = path$1.join(dir, rel);
+		if (fs.existsSync(entry)) urls.push(pathToFileURL(entry).href);
+	}
+	return urls;
+}
+/**
+* Import a node-av entry, falling back to the agent's explicit node-av path
+* when the bare specifier can't be resolved (see {@link fallbackNodeAvUrls}).
+* Each candidate is tried in turn so a copy whose native binary fails to load
+* doesn't mask a working one. A dynamic `import(url)` is typed `any`, so the
+* caller's declared module type applies without a cast.
+*/
+async function importNodeAv(bareSpecifier, subpath) {
+	try {
+		return await import(bareSpecifier);
+	} catch (bareErr) {
+		for (const url of fallbackNodeAvUrls(subpath)) try {
+			return await import(url);
+		} catch {}
+		throw bareErr;
+	}
+}
 async function getNodeAv() {
-	if (!_nav) _nav = await import("node-av");
+	if (!_nav) _nav = await importNodeAv("node-av", ".");
 	return _nav;
 }
 async function getConstants() {
-	if (!_consts) _consts = await import("node-av/constants");
+	if (!_consts) _consts = await importNodeAv("node-av/constants", "./constants");
 	return _consts;
 }
 function errMessage(err) {
@@ -317,6 +398,16 @@ var DecodeWorkerChild = class {
 	abortController = null;
 	started = false;
 	stopped = false;
+	/**
+	* The numeric device id this worker decodes for — learned from the `start`
+	* message's {@link VideoFrameSource}. The child's stderr is INHERITED by the
+	* pipeline-runner (silent:false fork), so these lines land in the runner's
+	* raw stderr WITHOUT passing through a scoped logger; prefixing every line
+	* with `[dev:<id>]` (see {@link emitStderr}) is what lets the per-device log
+	* UI attribute the forked worker's output to its camera. `null` only for the
+	* brief pre-`start` window (e.g. a malformed first message).
+	*/
+	deviceId = null;
 	sessionFormat = "rgb";
 	minIntervalMs = 0;
 	/**
@@ -389,16 +480,17 @@ var DecodeWorkerChild = class {
 		const deliveredDelta = this.framesDelivered - this.lastDeliveredSnapshot;
 		const deliveredFps = Math.round(deliveredDelta / windowMs * 1e3 * 10) / 10;
 		const skipped = this.framesSkipped + this.frames.droppedCount;
-		process.stderr.write(`session-decode metrics {framesDecoded:${this.framesDecoded}, framesSkipped:${skipped}, deliveredFps:${deliveredFps}}${final ? " (final)" : ""}\n`);
+		this.emitStderr(`session-decode metrics {framesDecoded:${this.framesDecoded}, framesSkipped:${skipped}, deliveredFps:${deliveredFps}}${final ? " (final)" : ""}\n`);
 		this.lastMetricsAt = now;
 		this.lastDeliveredSnapshot = this.framesDelivered;
 	}
 	handleStart(source, opts) {
 		if (this.started) {
-			process.stderr.write("decode-worker-child: duplicate start ignored\n");
+			this.emitStderr("decode-worker-child: duplicate start ignored\n");
 			return;
 		}
 		this.started = true;
+		this.deviceId = source.deviceId;
 		this.sessionFormat = opts.format ?? "rgb";
 		this.minIntervalMs = opts.fps && opts.fps > 0 ? 1e3 / opts.fps : 0;
 		this.lastMetricsAt = Date.now();
@@ -455,7 +547,7 @@ var DecodeWorkerChild = class {
 				await this.dialAndDecode(nav, C, url);
 			} catch (err) {
 				if (this.stopped) break;
-				process.stderr.write(`decode-worker-child: dial ended — re-dial scheduled: ${errMessage(err)}\n`);
+				this.emitStderr(`decode-worker-child: dial ended — re-dial scheduled: ${errMessage(err)}\n`);
 			} finally {
 				this.closeInput();
 			}
@@ -548,7 +640,7 @@ var DecodeWorkerChild = class {
 				return;
 			}
 			this.hwFilterDecision = "hardware";
-			process.stderr.write(`decode-worker-child: GPU crop+scale path active (${this.gpuScaleFilter})\n`);
+			this.emitStderr(`decode-worker-child: GPU crop+scale path active (${this.gpuScaleFilter})\n`);
 		}
 		this.publishFrame(frame);
 	}
@@ -586,7 +678,7 @@ var DecodeWorkerChild = class {
 			for (const out of outputs) out.free();
 			return ok;
 		} catch (err) {
-			process.stderr.write(`decode-worker-child: GPU filter probe failed — using software decode: ${errMessage(err)}\n`);
+			this.emitStderr(`decode-worker-child: GPU filter probe failed — using software decode: ${errMessage(err)}\n`);
 			return false;
 		} finally {
 			filter?.close();
@@ -763,7 +855,7 @@ var DecodeWorkerChild = class {
 			if (deviceType === null) continue;
 			const hw = nav.HardwareContext.create(deviceType);
 			if (!hw) {
-				process.stderr.write(`decode-worker-child: hwaccel candidate '${backend}' failed — trying next\n`);
+				this.emitStderr(`decode-worker-child: hwaccel candidate '${backend}' failed — trying next\n`);
 				continue;
 			}
 			this.hwContext = hw;
@@ -771,7 +863,7 @@ var DecodeWorkerChild = class {
 			this.hwFilterDecision = this.gpuScaleFilter !== null ? "undecided" : "software";
 			return;
 		}
-		process.stderr.write("decode-worker-child: no hwaccel backend available — using software decode\n");
+		this.emitStderr("decode-worker-child: no hwaccel backend available — using software decode\n");
 	}
 	/** Interruptible re-dial backoff — `teardown` clears the pending timer. */
 	sleep(ms) {
@@ -802,8 +894,19 @@ var DecodeWorkerChild = class {
 	send(reply) {
 		process.send?.(reply);
 	}
+	/**
+	* Write one diagnostic line to the (inherited) stderr, prefixed with the
+	* device tag so the per-device log UI can attribute the forked worker's
+	* output. Public so the module-level process handlers — which only hold the
+	* `worker` instance — emit device-tagged lines too. Callers pass the line
+	* INCLUDING its trailing newline (unchanged from the prior direct writes).
+	*/
+	emitStderr(line) {
+		const tag = this.deviceId === null ? "[dev:?]" : `[dev:${this.deviceId}]`;
+		process.stderr.write(`${tag} ${line}`);
+	}
 	sendError(message, frameId) {
-		process.stderr.write(`${message}\n`);
+		this.emitStderr(`${message}\n`);
 		this.send(frameId === void 0 ? {
 			kind: "error",
 			message
@@ -823,12 +926,12 @@ process.on("disconnect", () => {
 	process.exit(0);
 });
 process.on("uncaughtException", (err) => {
-	process.stderr.write(`decode-worker-child: uncaught exception — ${errMessage(err)}\n`);
+	worker.emitStderr(`decode-worker-child: uncaught exception — ${errMessage(err)}\n`);
 	worker.teardown();
 	process.exit(1);
 });
 process.on("unhandledRejection", (reason) => {
-	process.stderr.write(`decode-worker-child: unhandled rejection — ${errMessage(reason)}\n`);
+	worker.emitStderr(`decode-worker-child: unhandled rejection — ${errMessage(reason)}\n`);
 });
 //#endregion
 export { DecodeWorkerChild };