@camstack/addon-pipeline 1.1.21 → 1.1.22

package/dist/pipeline-runner/index.mjs

@@ -1,5 +1,385 @@
-import { A as nodePin, B as BaseAddon, M as pipelineRunnerCapability, S as defineCustomActions, W as EventCategory, X as makeSourceBrokerId, at as lazy, ct as object, nt as array, q as createEvent, rt as boolean, st as number, tt as _enum, ut as string, y as customAction, z as errMsg } from "../dist-tzhTTRq4.mjs";
+import { A as nodePin, B as BaseAddon, M as pipelineRunnerCapability, S as defineCustomActions, W as EventCategory, X as makeSourceBrokerId, at as lazy, ct as object, nt as array, q as createEvent, rt as boolean, st as number, tt as _enum, ut as string, y as customAction, z as errMsg } from "../dist-pd_-3C0T.mjs";
 import { FrameRingReaderCache } from "@camstack/shm-ring";
+//#region src/pipeline-runner/bench-actions.ts
+/**
+* Synthetic-bench custom actions for pipeline-runner.
+*
+* Lets the admin UI drive a production-realistic detection benchmark:
+* the runner — already co-located with detection-pipeline in the
+* `pipeline` group — invokes `api.pipelineExecutor.runPipeline` directly
+* (in-process via localProviderLink, no Moleculer hop), N workers
+* concurrent × M iterations. Returns aggregate stats.
+*
+* Why this exists: the older bench path (UI → benchmark addon → pipeline
+* addon) crosses TWO Moleculer process boundaries that the production
+* camera path does NOT have (broker / runner / detection-pipeline are
+* all in the same group). Running the loop from inside the runner gives
+* fps numbers that match what real cameras achieve.
+*/
+var BenchEngineChoiceSchema = object({
+	runtime: _enum(["node", "python"]),
+	backend: string(),
+	format: _enum([
+		"onnx",
+		"coreml",
+		"openvino",
+		"tflite",
+		"pt"
+	]),
+	device: string().optional()
+});
+var BenchStepSchema = lazy(() => object({
+	addonId: string(),
+	modelId: string(),
+	enabled: boolean(),
+	children: array(BenchStepSchema).optional()
+}));
+var CacheBenchFrameInputSchema = object({
+	imageBase64: string(),
+	ttlSeconds: number().int().positive().optional()
+});
+var CacheBenchFrameResultSchema = object({
+	frameId: string(),
+	width: number(),
+	height: number(),
+	expiresAt: number()
+});
+var ReleaseBenchFrameInputSchema = object({ frameId: string() });
+var ReleaseBenchFrameResultSchema = object({ released: boolean() });
+var RunSyntheticBenchInputSchema = object({
+	frameId: string(),
+	steps: array(BenchStepSchema).min(1),
+	parallel: number().int().min(1).max(32),
+	iterations: number().int().min(1).max(1e4),
+	warmup: number().int().min(0).max(100).optional(),
+	sessionId: string().optional(),
+	simulatePipeline: boolean().optional(),
+	nodeId: string().optional(),
+	engine: BenchEngineChoiceSchema.optional()
+});
+var TimingSplitSchema = object({
+	mean: number(),
+	p50: number(),
+	p95: number(),
+	p99: number()
+});
+var RunSyntheticBenchResultSchema = object({
+	runs: number(),
+	wallSec: number(),
+	fps: number(),
+	detectionsPerSec: number(),
+	avgDetections: number(),
+	callMs: TimingSplitSchema,
+	inferMs: number(),
+	preprocessMs: number(),
+	predictMs: number(),
+	batchSizeMean: number(),
+	batchSizeMax: number(),
+	engine: object({
+		runtime: string(),
+		backend: string(),
+		device: string().optional()
+	}).optional(),
+	tuning: object({
+		batchMode: string(),
+		windowMs: number(),
+		maxBatchSize: number(),
+		concurrency: number()
+	}).optional(),
+	path: string().optional()
+});
+var pipelineRunnerBenchActions = defineCustomActions({
+	cacheBenchFrame: customAction(CacheBenchFrameInputSchema, CacheBenchFrameResultSchema, { kind: "mutation" }),
+	releaseBenchFrame: customAction(ReleaseBenchFrameInputSchema, ReleaseBenchFrameResultSchema, { kind: "mutation" }),
+	runSyntheticBench: customAction(RunSyntheticBenchInputSchema, RunSyntheticBenchResultSchema, { kind: "mutation" })
+});
+//#endregion
+//#region src/pipeline-runner/foreign-handle-throttle.ts
+var ForeignHandleThrottle = class {
+	minFetchIntervalMs;
+	warnIntervalMs;
+	lastFetchStartedAt = Number.NEGATIVE_INFINITY;
+	inFlight = false;
+	lastWarnAt;
+	_foreignHandles = 0;
+	_remoteFetches = 0;
+	_remoteFailures = 0;
+	_dropped = 0;
+	constructor(options = {}) {
+		const maxRemoteFps = options.maxRemoteFps ?? 1;
+		this.minFetchIntervalMs = maxRemoteFps > 0 ? 1e3 / maxRemoteFps : Number.POSITIVE_INFINITY;
+		this.warnIntervalMs = options.warnIntervalMs ?? 6e4;
+	}
+	/**
+	* Decide whether the current foreign handle should trigger a remote fetch.
+	* `'fetch'` only when no fetch is in flight AND at least `1000/maxRemoteFps`
+	* ms have elapsed since the last fetch started; otherwise `'drop'`.
+	*/
+	plan(now) {
+		this._foreignHandles += 1;
+		const rateOpen = now - this.lastFetchStartedAt >= this.minFetchIntervalMs;
+		if (this.inFlight || !rateOpen) {
+			this._dropped += 1;
+			return "drop";
+		}
+		return "fetch";
+	}
+	/** Mark a remote fetch as begun (arms single-flight + the rate window). */
+	noteFetchStart(now) {
+		this.inFlight = true;
+		this.lastFetchStartedAt = now;
+		this._remoteFetches += 1;
+	}
+	/** Mark the in-flight remote fetch as finished; records a failure outcome. */
+	noteFetchEnd(result = "ok") {
+		this.inFlight = false;
+		if (result === "failed") this._remoteFailures += 1;
+	}
+	/** `true` at most once per `warnIntervalMs`; stamps the window when it fires. */
+	shouldWarn(now) {
+		if (this.lastWarnAt !== void 0 && now - this.lastWarnAt < this.warnIntervalMs) return false;
+		this.lastWarnAt = now;
+		return true;
+	}
+	get counters() {
+		return {
+			foreignHandles: this._foreignHandles,
+			remoteFetches: this._remoteFetches,
+			remoteFailures: this._remoteFailures,
+			dropped: this._dropped
+		};
+	}
+};
+//#endregion
+//#region src/pipeline-runner/resolve-polled-frame.ts
+async function resolvePolledFrame(handle, deps) {
+	const { ownNodeId, readers, throttle, getRemoteFrame, logger, tag } = deps;
+	if (handle.nodeId === ownNodeId) return readers.read(handle);
+	const now = Date.now();
+	const decision = throttle.plan(now);
+	if (throttle.shouldWarn(now)) logger.warn("frame poller: foreign handle — decoder session is on another node; using bounded decoder.getFrame fallback", { meta: {
+		tag,
+		producerNode: handle.nodeId,
+		ownNodeId,
+		...throttle.counters
+	} });
+	if (decision === "drop") return null;
+	throttle.noteFetchStart(now);
+	try {
+		const remote = await getRemoteFrame(handle);
+		throttle.noteFetchEnd("ok");
+		return remote;
+	} catch (err) {
+		throttle.noteFetchEnd("failed");
+		logger.debug("frame poller: remote getFrame failed", { meta: {
+			tag,
+			producerNode: handle.nodeId,
+			error: errMsg(err)
+		} });
+		return null;
+	}
+}
+//#endregion
+//#region src/pipeline-runner/frame-handle-poller.ts
+/**
+* `FrameHandlePoller` — the consumer-side poll loop of the shared-memory frame
+* plane (Phase 5 / D9).
+*
+* Replaces the live-object `IStreamBroker.onDecodedFrame(cb)` callback path.
+* A consumer (motion, detection):
+*
+*   1. `subscribeFrames({ brokerId, format, maxFps, tag })` over tRPC — the
+*      broker spins up a `frameSink: 'shm'` decoder session for that format
+*      and returns a `subscriptionId`;
+*   2. polls `pullFrameHandles({ subscriptionId, maxCount })` at the cadence
+*      `maxFps` implies, draining zero-pixel `FrameHandle`s;
+*   3. feeds each handle to a `FrameRingReaderCache` which opens the named shm
+*      segment and reads the pixels back zero-copy;
+*   4. on teardown, `unsubscribeFrames` + closes the cached readers.
+*
+* The loop tolerates an initially-empty stream — `pullFrameHandles` returns
+* `[]` until the broker has a source, and a recycled ring slot yields a `null`
+* pixel read (a dropped frame, the correct latest-wins behaviour).
+*
+* Foreign-handle path: a `FrameHandle` carries the `nodeId` of the node whose
+* shared memory holds its segment. A LOCAL handle is read back zero-copy; a
+* FOREIGN handle (produced on another node — e.g. a camera decoded on the hub
+* whose detection was placed on an agent) cannot be `shm_open`ed here. Reading
+* it unconditionally floods `openSegment failed shm_open ENOENT` at frame rate,
+* so the poll delegates every handle to `resolvePolledFrame`, which gates on
+* `handle.nodeId`: local → shm read; foreign → a BOUNDED, single-flight
+* `getRemoteFrame` (`decoder.getFrame`) fallback (≤ `maxRemoteFps`) plus a
+* rate-limited WARN naming the topology mismatch. `ownNodeId` + `getRemoteFrame`
+* are REQUIRED options — every in-repo call site supplies them, so there is no
+* silent default that re-creates the unconditional read.
+*
+* Boot-race tolerance: the broker for a given camStream may not be registered
+* yet when a consumer attempts to subscribe (the pipeline-runner spawns before
+* provider addons publish their cameraStreams). `subscribeFrames` retries with
+* exponential backoff (capped at `MAX_SUBSCRIBE_RETRY_BACKOFF_MS`) until it
+* succeeds or the returned teardown closure is invoked. The closure always
+* resolves to a function, even when the broker is missing; the function
+* cancels pending retries and releases any subscription acquired in flight.
+*/
+/** How many handles to drain per poll — a small burst absorbs jitter. */
+var PULL_MAX_COUNT = 4;
+/** Floor on the poll period so a 0/absurd `maxFps` can't busy-spin. */
+var MIN_POLL_INTERVAL_MS = 20;
+/** Poll period when the broker reports a non-positive cadence hint. */
+var FALLBACK_POLL_INTERVAL_MS = 200;
+/** First subscribe-retry delay, doubled on every subsequent failure. */
+var INITIAL_SUBSCRIBE_RETRY_BACKOFF_MS = 250;
+/**
+* Subscribe-retry backoff ceiling. 5 s is fast enough to recover within a
+* single roster refresh of the consuming UI and slow enough that a
+* misconfigured camStream costs ~12 op/min, not 50/s.
+*/
+var MAX_SUBSCRIBE_RETRY_BACKOFF_MS = 5e3;
+/**
+* Subscribe to a broker's shm frame stream and start the poll loop. Always
+* resolves to a teardown closure — when the broker is not yet registered the
+* closure cancels the ongoing retry loop; when polling is active it stops the
+* loop, releases the broker subscription, and closes every shm segment the
+* reader cache opened.
+*/
+async function startFrameHandlePoller(options) {
+	const lifecycle = {
+		stopped: false,
+		retryTimer: void 0,
+		activeTeardown: null
+	};
+	const teardown = () => {
+		if (lifecycle.stopped) return;
+		lifecycle.stopped = true;
+		if (lifecycle.retryTimer) {
+			clearTimeout(lifecycle.retryTimer);
+			lifecycle.retryTimer = void 0;
+		}
+		lifecycle.activeTeardown?.();
+	};
+	subscribeWithRetry(options, lifecycle);
+	return teardown;
+}
+/**
+* Run the subscribe → poll handshake with exponential backoff on subscribe
+* failures. Resolves once the subscription is acquired (and the poll loop has
+* been started) or once `lifecycle.stopped` flips, whichever comes first.
+*/
+async function subscribeWithRetry(options, lifecycle) {
+	const { api, brokerId, format, maxFps, tag, logger } = options;
+	let backoffMs = INITIAL_SUBSCRIBE_RETRY_BACKOFF_MS;
+	let attempt = 0;
+	while (!lifecycle.stopped) {
+		attempt += 1;
+		try {
+			const result = await api.streamBroker.subscribeFrames.mutate({
+				brokerId,
+				format,
+				maxFps,
+				tag
+			});
+			if (lifecycle.stopped) {
+				await api.streamBroker.unsubscribeFrames.mutate({ subscriptionId: result.subscriptionId }).catch((err) => {
+					logger.warn("frame-handle poller: late unsubscribe failed", { meta: {
+						brokerId,
+						subscriptionId: result.subscriptionId,
+						error: errMsg(err)
+					} });
+				});
+				return;
+			}
+			lifecycle.activeTeardown = startPolling(options, result.subscriptionId, result.maxFps, lifecycle);
+			return;
+		} catch (err) {
+			if (lifecycle.stopped) return;
+			if (attempt === 1) logger.warn("frame-handle poller: subscribeFrames failed, retrying", { meta: {
+				brokerId,
+				format,
+				tag,
+				error: errMsg(err),
+				nextRetryInMs: backoffMs
+			} });
+			else logger.debug("frame-handle poller: subscribeFrames still failing", { meta: {
+				brokerId,
+				format,
+				tag,
+				attempt,
+				error: errMsg(err),
+				nextRetryInMs: backoffMs
+			} });
+			await sleep(backoffMs, lifecycle);
+			backoffMs = Math.min(MAX_SUBSCRIBE_RETRY_BACKOFF_MS, backoffMs * 2);
+		}
+	}
+}
+/**
+* Sleep `ms` milliseconds, but resolve early when `lifecycle.stopped` flips so
+* a teardown during a retry pause doesn't have to wait out the full backoff.
+*/
+function sleep(ms, lifecycle) {
+	return new Promise((resolve) => {
+		lifecycle.retryTimer = setTimeout(() => {
+			lifecycle.retryTimer = void 0;
+			resolve();
+		}, ms);
+	});
+}
+/**
+* Run the steady-state poll loop for a successfully-acquired subscription.
+* Returns the teardown closure that stops the loop and releases the
+* subscription.
+*/
+function startPolling(options, subscriptionId, resolvedMaxFps, lifecycle) {
+	const { api, brokerId, onFrame, logger, ownNodeId, getRemoteFrame, tag } = options;
+	const readers = new FrameRingReaderCache(logger);
+	const throttle = new ForeignHandleThrottle();
+	const pollIntervalMs = resolvedMaxFps > 0 ? Math.max(MIN_POLL_INTERVAL_MS, Math.round(1e3 / resolvedMaxFps)) : FALLBACK_POLL_INTERVAL_MS;
+	let timer;
+	const tick = async () => {
+		if (lifecycle.stopped) return;
+		try {
+			const handles = await api.streamBroker.pullFrameHandles.query({
+				subscriptionId,
+				maxCount: PULL_MAX_COUNT
+			});
+			for (const handle of handles) {
+				if (lifecycle.stopped) break;
+				const frame = await resolvePolledFrame(handle, {
+					ownNodeId,
+					readers,
+					throttle,
+					getRemoteFrame,
+					logger,
+					tag
+				});
+				if (frame) onFrame(frame, handle);
+			}
+		} catch (err) {
+			logger.warn("frame-handle poller: pullFrameHandles failed", { meta: {
+				brokerId,
+				subscriptionId,
+				error: errMsg(err)
+			} });
+		}
+		if (!lifecycle.stopped) timer = setTimeout(() => void tick(), pollIntervalMs);
+	};
+	tick();
+	return () => {
+		if (timer) {
+			clearTimeout(timer);
+			timer = void 0;
+		}
+		readers.close();
+		api.streamBroker.unsubscribeFrames.mutate({ subscriptionId }).catch((err) => {
+			logger.warn("frame-handle poller: unsubscribeFrames failed", { meta: {
+				brokerId,
+				subscriptionId,
+				error: errMsg(err)
+			} });
+		});
+	};
+}
+//#endregion
 //#region src/pipeline-runner/frame-queue.ts
 /**
 * Latest-frame-only buffer. Keeps only the most recent item, dropping all
@@ -693,252 +1073,6 @@ var PipelineRunner = class {
 	}
 };
 //#endregion
-//#region src/pipeline-runner/frame-handle-poller.ts
-/** How many handles to drain per poll — a small burst absorbs jitter. */
-var PULL_MAX_COUNT = 4;
-/** Floor on the poll period so a 0/absurd `maxFps` can't busy-spin. */
-var MIN_POLL_INTERVAL_MS = 20;
-/** Poll period when the broker reports a non-positive cadence hint. */
-var FALLBACK_POLL_INTERVAL_MS = 200;
-/** First subscribe-retry delay, doubled on every subsequent failure. */
-var INITIAL_SUBSCRIBE_RETRY_BACKOFF_MS = 250;
-/**
-* Subscribe-retry backoff ceiling. 5 s is fast enough to recover within a
-* single roster refresh of the consuming UI and slow enough that a
-* misconfigured camStream costs ~12 op/min, not 50/s.
-*/
-var MAX_SUBSCRIBE_RETRY_BACKOFF_MS = 5e3;
-/**
-* Subscribe to a broker's shm frame stream and start the poll loop. Always
-* resolves to a teardown closure — when the broker is not yet registered the
-* closure cancels the ongoing retry loop; when polling is active it stops the
-* loop, releases the broker subscription, and closes every shm segment the
-* reader cache opened.
-*/
-async function startFrameHandlePoller(options) {
-	const lifecycle = {
-		stopped: false,
-		retryTimer: void 0,
-		activeTeardown: null
-	};
-	const teardown = () => {
-		if (lifecycle.stopped) return;
-		lifecycle.stopped = true;
-		if (lifecycle.retryTimer) {
-			clearTimeout(lifecycle.retryTimer);
-			lifecycle.retryTimer = void 0;
-		}
-		lifecycle.activeTeardown?.();
-	};
-	subscribeWithRetry(options, lifecycle);
-	return teardown;
-}
-/**
-* Run the subscribe → poll handshake with exponential backoff on subscribe
-* failures. Resolves once the subscription is acquired (and the poll loop has
-* been started) or once `lifecycle.stopped` flips, whichever comes first.
-*/
-async function subscribeWithRetry(options, lifecycle) {
-	const { api, brokerId, format, maxFps, tag, logger } = options;
-	let backoffMs = INITIAL_SUBSCRIBE_RETRY_BACKOFF_MS;
-	let attempt = 0;
-	while (!lifecycle.stopped) {
-		attempt += 1;
-		try {
-			const result = await api.streamBroker.subscribeFrames.mutate({
-				brokerId,
-				format,
-				maxFps,
-				tag
-			});
-			if (lifecycle.stopped) {
-				await api.streamBroker.unsubscribeFrames.mutate({ subscriptionId: result.subscriptionId }).catch((err) => {
-					logger.warn("frame-handle poller: late unsubscribe failed", { meta: {
-						brokerId,
-						subscriptionId: result.subscriptionId,
-						error: errMsg(err)
-					} });
-				});
-				return;
-			}
-			lifecycle.activeTeardown = startPolling(options, result.subscriptionId, result.maxFps, lifecycle);
-			return;
-		} catch (err) {
-			if (lifecycle.stopped) return;
-			if (attempt === 1) logger.warn("frame-handle poller: subscribeFrames failed, retrying", { meta: {
-				brokerId,
-				format,
-				tag,
-				error: errMsg(err),
-				nextRetryInMs: backoffMs
-			} });
-			else logger.debug("frame-handle poller: subscribeFrames still failing", { meta: {
-				brokerId,
-				format,
-				tag,
-				attempt,
-				error: errMsg(err),
-				nextRetryInMs: backoffMs
-			} });
-			await sleep(backoffMs, lifecycle);
-			backoffMs = Math.min(MAX_SUBSCRIBE_RETRY_BACKOFF_MS, backoffMs * 2);
-		}
-	}
-}
-/**
-* Sleep `ms` milliseconds, but resolve early when `lifecycle.stopped` flips so
-* a teardown during a retry pause doesn't have to wait out the full backoff.
-*/
-function sleep(ms, lifecycle) {
-	return new Promise((resolve) => {
-		lifecycle.retryTimer = setTimeout(() => {
-			lifecycle.retryTimer = void 0;
-			resolve();
-		}, ms);
-	});
-}
-/**
-* Run the steady-state poll loop for a successfully-acquired subscription.
-* Returns the teardown closure that stops the loop and releases the
-* subscription.
-*/
-function startPolling(options, subscriptionId, resolvedMaxFps, lifecycle) {
-	const { api, brokerId, onFrame, logger } = options;
-	const readers = new FrameRingReaderCache(logger);
-	const pollIntervalMs = resolvedMaxFps > 0 ? Math.max(MIN_POLL_INTERVAL_MS, Math.round(1e3 / resolvedMaxFps)) : FALLBACK_POLL_INTERVAL_MS;
-	let timer;
-	const tick = async () => {
-		if (lifecycle.stopped) return;
-		try {
-			const handles = await api.streamBroker.pullFrameHandles.query({
-				subscriptionId,
-				maxCount: PULL_MAX_COUNT
-			});
-			for (const handle of handles) {
-				if (lifecycle.stopped) break;
-				const frame = readers.read(handle);
-				if (frame) onFrame(frame, handle);
-			}
-		} catch (err) {
-			logger.warn("frame-handle poller: pullFrameHandles failed", { meta: {
-				brokerId,
-				subscriptionId,
-				error: errMsg(err)
-			} });
-		}
-		if (!lifecycle.stopped) timer = setTimeout(() => void tick(), pollIntervalMs);
-	};
-	tick();
-	return () => {
-		if (timer) {
-			clearTimeout(timer);
-			timer = void 0;
-		}
-		readers.close();
-		api.streamBroker.unsubscribeFrames.mutate({ subscriptionId }).catch((err) => {
-			logger.warn("frame-handle poller: unsubscribeFrames failed", { meta: {
-				brokerId,
-				subscriptionId,
-				error: errMsg(err)
-			} });
-		});
-	};
-}
-//#endregion
-//#region src/pipeline-runner/bench-actions.ts
-/**
-* Synthetic-bench custom actions for pipeline-runner.
-*
-* Lets the admin UI drive a production-realistic detection benchmark:
-* the runner — already co-located with detection-pipeline in the
-* `pipeline` group — invokes `api.pipelineExecutor.runPipeline` directly
-* (in-process via localProviderLink, no Moleculer hop), N workers
-* concurrent × M iterations. Returns aggregate stats.
-*
-* Why this exists: the older bench path (UI → benchmark addon → pipeline
-* addon) crosses TWO Moleculer process boundaries that the production
-* camera path does NOT have (broker / runner / detection-pipeline are
-* all in the same group). Running the loop from inside the runner gives
-* fps numbers that match what real cameras achieve.
-*/
-var BenchEngineChoiceSchema = object({
-	runtime: _enum(["node", "python"]),
-	backend: string(),
-	format: _enum([
-		"onnx",
-		"coreml",
-		"openvino",
-		"tflite",
-		"pt"
-	]),
-	device: string().optional()
-});
-var BenchStepSchema = lazy(() => object({
-	addonId: string(),
-	modelId: string(),
-	enabled: boolean(),
-	children: array(BenchStepSchema).optional()
-}));
-var CacheBenchFrameInputSchema = object({
-	imageBase64: string(),
-	ttlSeconds: number().int().positive().optional()
-});
-var CacheBenchFrameResultSchema = object({
-	frameId: string(),
-	width: number(),
-	height: number(),
-	expiresAt: number()
-});
-var ReleaseBenchFrameInputSchema = object({ frameId: string() });
-var ReleaseBenchFrameResultSchema = object({ released: boolean() });
-var RunSyntheticBenchInputSchema = object({
-	frameId: string(),
-	steps: array(BenchStepSchema).min(1),
-	parallel: number().int().min(1).max(32),
-	iterations: number().int().min(1).max(1e4),
-	warmup: number().int().min(0).max(100).optional(),
-	sessionId: string().optional(),
-	simulatePipeline: boolean().optional(),
-	nodeId: string().optional(),
-	engine: BenchEngineChoiceSchema.optional()
-});
-var TimingSplitSchema = object({
-	mean: number(),
-	p50: number(),
-	p95: number(),
-	p99: number()
-});
-var RunSyntheticBenchResultSchema = object({
-	runs: number(),
-	wallSec: number(),
-	fps: number(),
-	detectionsPerSec: number(),
-	avgDetections: number(),
-	callMs: TimingSplitSchema,
-	inferMs: number(),
-	preprocessMs: number(),
-	predictMs: number(),
-	batchSizeMean: number(),
-	batchSizeMax: number(),
-	engine: object({
-		runtime: string(),
-		backend: string(),
-		device: string().optional()
-	}).optional(),
-	tuning: object({
-		batchMode: string(),
-		windowMs: number(),
-		maxBatchSize: number(),
-		concurrency: number()
-	}).optional(),
-	path: string().optional()
-});
-var pipelineRunnerBenchActions = defineCustomActions({
-	cacheBenchFrame: customAction(CacheBenchFrameInputSchema, CacheBenchFrameResultSchema, { kind: "mutation" }),
-	releaseBenchFrame: customAction(ReleaseBenchFrameInputSchema, ReleaseBenchFrameResultSchema, { kind: "mutation" }),
-	runSyntheticBench: customAction(RunSyntheticBenchInputSchema, RunSyntheticBenchResultSchema, { kind: "mutation" })
-});
-//#endregion
 //#region src/pipeline-runner/index.ts
 var DEFAULT_CONFIG = {
 	maxQueueDepth: 30,
@@ -1625,6 +1759,31 @@ var PipelineRunnerAddon = class extends BaseAddon {
 	getLocalCameras() {
 		return [...this.attached.keys()];
 	}
+	/**
+	* Cross-node frame fetch for FOREIGN handles (segment on another node). Wired
+	* into every `startFrameHandlePoller` call so `resolvePolledFrame` can take
+	* the bounded `decoder.getFrame` fallback instead of an unmappable local shm
+	* read. The `nodeId` selector routes the call to the producing node (the
+	* cap's `nodeIdMode: 'routing'` default; agent→hub via `$hub-cap-fwd`). The
+	* wire schema returns `data: Uint8Array`; downstream inference expects a Node
+	* `Buffer`, so we adapt it here exactly as post-analysis does.
+	*/
+	async getRemoteFrame(handle) {
+		const api = this.ctx.api;
+		if (!api) return null;
+		const remote = await api.decoder.getFrame.query({
+			handle,
+			nodeId: handle.nodeId
+		});
+		if (!remote) return null;
+		return {
+			data: Buffer.from(remote.data),
+			width: remote.width,
+			height: remote.height,
+			format: remote.format,
+			timestamp: remote.timestamp
+		};
+	}
 	async subscribeMotionFrames(config) {
 		const ctx = this.ctx;
 		const runner = this.runner;
@@ -1642,6 +1801,8 @@ var PipelineRunnerAddon = class extends BaseAddon {
 			maxFps: config.motionFps,
 			tag: "motion",
 			logger: log,
+			ownNodeId: this.nodeId,
+			getRemoteFrame: (handle) => this.getRemoteFrame(handle),
 			onFrame: (frame, _handle) => {
 				runner.enqueueMotionFrame(config.deviceId, frame);
 			}
@@ -1725,6 +1886,8 @@ var PipelineRunnerAddon = class extends BaseAddon {
 			maxFps: config.detectionFps,
 			tag: "detection",
 			logger: log,
+			ownNodeId: this.nodeId,
+			getRemoteFrame: (handle) => this.getRemoteFrame(handle),
 			onFrame: (frame, handle) => {
 				runner.enqueueDetectionFrame(config.deviceId, frame, handle);
 			}
@@ -1891,6 +2054,8 @@ var PipelineRunnerAddon = class extends BaseAddon {
 				maxFps: config.detectionFps,
 				tag: "occupancy",
 				logger: log,
+				ownNodeId: this.nodeId,
+				getRemoteFrame: (handle) => this.getRemoteFrame(handle),
 				onFrame: (frame, handle) => {
 					if (settled) return;
 					runner.enqueueOccupancyFrame(deviceId, frame, handle);