@camstack/addon-pipeline-orchestrator 1.0.4 → 1.0.5

package/dist/index.mjs

@@ -4981,6 +4981,18 @@ var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	*/
 	EventCategory["PipelineEngineMetricsSnapshot"] = "pipeline.engine-metrics-snapshot";
 	/**
+	* Per-node detection-engine runtime-provisioning transition. Emitted by
+	* the detection-pipeline provider on every state change of its lazy
+	* engine-provisioning machine (idle → installing → verifying → ready,
+	* or → failed with a `nextRetryAt`). Payload is the
+	* `EngineProvisioningState` snapshot; `event.source.nodeId` carries the
+	* node. The Pipeline page subscribes to drive a live "installing
+	* OpenVINO… / ready" indicator per node without polling
+	* `pipelineExecutor.getEngineProvisioning`. Telemetry-grade (D8): the UI
+	* also reads the cap snapshot on mount / reconnect. Phase 2.
+	*/
+	EventCategory["PipelineEngineProvisioning"] = "pipeline.engine-provisioning";
+	/**
 	* Cluster topology snapshot. Carries the same payload returned by
 	* `nodes.topology` (every reachable node + addons + processes).
 	* Emitted by the hub on any agent / addon lifecycle change
@@ -9562,6 +9574,24 @@ var DetectorOutputSchema = object({
 	inferenceMs: number(),
 	modelId: string()
 });
+var EngineProvisioningSchema = object({
+	runtimeId: _enum([
+		"onnx",
+		"openvino",
+		"coreml"
+	]).nullable(),
+	device: string().nullable(),
+	state: _enum([
+		"idle",
+		"installing",
+		"verifying",
+		"ready",
+		"failed"
+	]),
+	progress: number().optional(),
+	error: string().optional(),
+	nextRetryAt: number().optional()
+});
 var PipelineStepInputSchema = lazy(() => object({
 	addonId: string(),
 	modelId: string(),
@@ -9661,6 +9691,15 @@ var pipelineExecutorCapability = {
 			kind: "mutation",
 			auth: "admin"
 		}),
+		/**
+		* Per-node detection-engine provisioning snapshot. Returns the live
+		* state of the lazy runtime-provisioning machine on `nodeId`
+		* (idle / installing / verifying / ready / failed). The UI pairs this
+		* one-shot query with the `pipeline.engine-provisioning` live event
+		* (emitted on every transition) to drive a per-node "engine ready?"
+		* indicator without polling. Phase 2.
+		*/
+		getEngineProvisioning: method(object({ nodeId: string() }), EngineProvisioningSchema),
 		getVideoPipelineSteps: method(_void(), record(string(), object({
 			modelId: string(),
 			settings: record(string(), unknown()).readonly()
@@ -13537,7 +13576,10 @@ var AgentAddonConfigSchema = object({
 	modelId: string(),
 	settings: record(string(), unknown()).readonly()
 });
-var AgentPipelineSettingsSchema = object({ addonDefaults: record(string(), AgentAddonConfigSchema).readonly() });
+var AgentPipelineSettingsSchema = object({
+	addonDefaults: record(string(), AgentAddonConfigSchema).readonly(),
+	maxCameras: number().int().nonnegative().nullable().default(null)
+});
 var CameraPipelineForAgentSchema = object({
 	steps: array(PipelineStepInputSchema).readonly(),
 	audio: object({
@@ -13639,6 +13681,133 @@ var GlobalMetricsSchema = object({
 * capability providers.
 */
 var CapabilityBindingsSchema = record(string(), string());
+/** Source block — always present; derives from the stream catalog. */
+var CameraSourceStatusSchema = object({ streams: array(object({
+	camStreamId: string(),
+	codec: string(),
+	width: number(),
+	height: number(),
+	fps: number(),
+	kind: string()
+})).readonly() });
+/** Assignment block — always present (orchestrator-local, no remote call). */
+var CameraAssignmentStatusSchema = object({
+	detectionNodeId: string().nullable(),
+	decoderNodeId: string().nullable(),
+	audioNodeId: string().nullable(),
+	pinned: object({
+		detection: boolean(),
+		decoder: boolean(),
+		audio: boolean()
+	}),
+	reasons: object({
+		detection: string().optional(),
+		decoder: string().optional(),
+		audio: string().optional()
+	})
+});
+/** Broker block — null when the broker stage is unreachable or inactive. */
+var CameraBrokerStatusSchema = object({
+	profiles: array(object({
+		profile: string(),
+		status: string(),
+		codec: string(),
+		width: number(),
+		height: number(),
+		subscribers: number(),
+		inFps: number(),
+		outFps: number()
+	})).readonly(),
+	webrtcSessions: number(),
+	rtspRestream: boolean()
+});
+/** Shared-memory ring statistics within the decoder block. */
+var CameraDecoderShmSchema = object({
+	framesWritten: number(),
+	getFrameHits: number(),
+	getFrameMisses: number(),
+	budgetMb: number()
+});
+/** Decoder block — null when the decoder stage is unreachable or inactive. */
+var CameraDecoderStatusSchema = object({
+	nodeId: string(),
+	formats: array(string()).readonly(),
+	sessionCount: number(),
+	shm: CameraDecoderShmSchema
+});
+/** Motion block — null when motion detection is not active for this device. */
+var CameraMotionStatusSchema = object({
+	enabled: boolean(),
+	fps: number()
+});
+/** Detection provisioning sub-block. */
+var CameraDetectionProvisioningSchema = object({
+	state: _enum([
+		"idle",
+		"installing",
+		"verifying",
+		"ready",
+		"failed"
+	]),
+	error: string().optional()
+});
+/** Detection phase — derived from the runner's engine phase. */
+var CameraDetectionPhaseSchema = _enum([
+	"idle",
+	"watching",
+	"active"
+]);
+/** Detection block — null when no detection node is assigned or reachable. */
+var CameraDetectionStatusSchema = object({
+	nodeId: string(),
+	engine: object({
+		backend: string(),
+		device: string()
+	}),
+	phase: CameraDetectionPhaseSchema,
+	configuredFps: number(),
+	actualFps: number(),
+	queueDepth: number(),
+	avgInferenceMs: number(),
+	provisioning: CameraDetectionProvisioningSchema
+});
+/** Audio block — null when no audio node is assigned or reachable. */
+var CameraAudioStatusSchema = object({
+	nodeId: string(),
+	enabled: boolean()
+});
+/** Recording block — null when no recording cap is active for this device. */
+var CameraRecordingStatusSchema = object({
+	mode: _enum([
+		"off",
+		"continuous",
+		"events"
+	]),
+	active: boolean(),
+	storageBytes: number()
+});
+/**
+* Aggregated per-camera pipeline status — server-composed, single call.
+*
+* The `assignment` and `source` blocks are always present.
+* Every other block is `null` when the stage is inactive or unreachable
+* during the bounded parallel fan-out in the orchestrator implementation.
+*
+* See spec: `docs/superpowers/specs/2026-06-24-camera-status-aggregator-cap.md`
+*/
+var CameraStatusSchema = object({
+	deviceId: number(),
+	assignment: CameraAssignmentStatusSchema,
+	source: CameraSourceStatusSchema,
+	broker: CameraBrokerStatusSchema.nullable(),
+	decoder: CameraDecoderStatusSchema.nullable(),
+	motion: CameraMotionStatusSchema.nullable(),
+	detection: CameraDetectionStatusSchema.nullable(),
+	audio: CameraAudioStatusSchema.nullable(),
+	recording: CameraRecordingStatusSchema.nullable(),
+	/** Unix timestamp (ms) when this snapshot was composed server-side. */
+	fetchedAt: number()
+});
 /**
 * Pipeline Orchestrator capability — global load balancer + camera dispatcher.
 *
@@ -13815,6 +13984,25 @@ var pipelineOrchestratorCapability = {
 			kind: "mutation",
 			auth: "admin"
 		}),
+		/**
+		* Set the per-node camera cap for one agent.
+		*
+		* `maxCameras: 0` and `maxCameras: null` are both treated as unlimited
+		* by the load balancer (0 is stored as-is; the balancer treats ≤0 as
+		* unlimited alongside null). Pass `null` to clear an existing cap.
+		* Note: the admin UI normalises 0→null before calling this method, so
+		* `maxCameras: 0` only reaches the store via direct SDK or CLI calls.
+		* Changes take effect immediately on the next dispatch cycle — cameras
+		* currently assigned over-cap are left in place (no forced eviction),
+		* but new assignments obey the updated cap.
+		*/
+		setAgentMaxCameras: method(object({
+			agentNodeId: string(),
+			maxCameras: number().int().nonnegative().nullable()
+		}), object({ success: literal(true) }), {
+			kind: "mutation",
+			auth: "admin"
+		}),
 		/** Read one camera's settings. Null when never touched (inherits agent defaults fully). */
 		getCameraSettings: method(object({ deviceId: number() }), CameraPipelineSettingsSchema.nullable()),
 		/** Set or clear the 3-state toggle for one (camera, addonId). Pass `enabled: null` to clear and revert to agent default. */
@@ -13855,6 +14043,29 @@ var pipelineOrchestratorCapability = {
 			deviceId: number(),
 			agentNodeId: string().optional()
 		}), CameraPipelineConfigSchema),
+		/**
+		* Server-composed aggregated status for a single camera.
+		*
+		* Fans out in parallel (bounded, per-stage graceful degradation) to
+		* broker / decoder / motion / detection / audio / recording source caps
+		* via `ctx.api`. A stage whose source errors or times out becomes `null`
+		* in the returned payload — one slow agent never breaks the whole call.
+		*
+		* Intended for "on open / on camera select" snapshots. Live deltas
+		* keep arriving from the existing ~1Hz events the UI already subscribes to.
+		*/
+		getCameraStatus: method(object({ deviceId: number() }), CameraStatusSchema),
+		/**
+		* Server-composed aggregated status for multiple cameras in one call.
+		*
+		* `deviceIds` defaults to all cameras currently tracked by the
+		* orchestrator's assignment map when omitted.
+		*
+		* Runs per-device composition in parallel (bounded). Use this to
+		* populate the cluster assignments table and the pipeline flow overview
+		* rail without issuing N parallel browser round-trips.
+		*/
+		getCameraStatuses: method(object({ deviceIds: array(number()).optional() }), array(CameraStatusSchema).readonly()),
 		/** List every template the operator has saved. */
 		listTemplates: method(_void(), array(PipelineTemplateSchema).readonly()),
 		/** Create a new named preset from a given CameraPipelineConfig. */
@@ -19694,6 +19905,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineExecutor.getEngineProvisioning": {
+		capName: "pipeline-executor",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineExecutor.getGlobalPipelineConfig": {
 		capName: "pipeline-executor",
 		capScope: "system",
@@ -19898,6 +20115,18 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineOrchestrator.getCameraStatus": {
+		capName: "pipeline-orchestrator",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
+	"pipelineOrchestrator.getCameraStatuses": {
+		capName: "pipeline-orchestrator",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineOrchestrator.getCameraStepOverrides": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
@@ -19982,6 +20211,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"pipelineOrchestrator.setAgentMaxCameras": {
+		capName: "pipeline-orchestrator",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineOrchestrator.setCameraPipelineForAgent": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
@@ -22012,7 +22247,10 @@ var StoredAgentAddonConfigSchema = object({
 	modelId: string(),
 	settings: record(string(), unknown()).readonly()
 });
-var StoredAgentPipelineSettingsSchema = object({ addonDefaults: record(string(), StoredAgentAddonConfigSchema).readonly() });
+var StoredAgentPipelineSettingsSchema = object({
+	addonDefaults: record(string(), StoredAgentAddonConfigSchema).readonly(),
+	maxCameras: number().int().nonnegative().nullable().default(null)
+});
 var AgentSettingsMapSchema = record(string(), StoredAgentPipelineSettingsSchema);
 var StoredCameraStepOverridePatchSchema = object({
 	enabled: boolean().optional(),
@@ -22057,10 +22295,26 @@ function computeCapacityScore(load) {
 	return load.attachedCameras * Math.max(load.avgInferenceFps, 0) + Math.max(load.queueDepthTotal, 0);
 }
 /**
+* Returns true when the node has remaining capacity.
+* A node is eligible iff `cap` is unlimited (null/absent/<=0) OR
+* its `attachedCameras` count is strictly less than the cap.
+* Pins count toward the cap via `attachedCameras`.
+*/
+function isEligible(node, caps) {
+	const cap = caps?.[node.nodeId];
+	if (cap === null || cap === void 0 || cap <= 0) return true;
+	return node.attachedCameras < cap;
+}
+/**
 * Run the two-level camera balancer.
 *
-* L1 (manual affinity): if `preferredAgent` names an online node, return it.
-* L2 (capacity): compute capacity scores and pick the lowest.
+* L1 (manual affinity): if `preferredAgent` names an online node AND that
+* node is under its `maxCameras` cap, return it. If the node is online but at
+* or over cap, return `{kind:'pending'}` — a pinned camera is never silently
+* over-assigned.
+*
+* L2 (capacity): filter to eligible nodes and pick the lowest capacity score.
+* If all nodes are at/over cap, return `{kind:'pending'}`.
 *
 * Returns `null` when no runners are online. The orchestrator decides how to
 * react — typically by logging and deferring the assignment until a runner
@@ -22069,19 +22323,32 @@ function computeCapacityScore(load) {
 function balance(input) {
 	const online = input.nodes.filter((n) => n.nodeId.length > 0);
 	if (online.length === 0) return null;
+	const eligible = online.filter((n) => isEligible(n, input.nodeCaps));
 	if (input.preferredAgent) {
-		const match = online.find((n) => n.nodeId === input.preferredAgent);
-		if (match) return {
-			agentNodeId: match.nodeId,
-			reason: "manual",
-			score: computeCapacityScore(match)
-		};
+		const pinnedOnline = online.find((n) => n.nodeId === input.preferredAgent);
+		if (pinnedOnline) {
+			if (eligible.some((n) => n.nodeId === pinnedOnline.nodeId)) return {
+				kind: "assigned",
+				agentNodeId: pinnedOnline.nodeId,
+				reason: "manual",
+				score: computeCapacityScore(pinnedOnline)
+			};
+			return {
+				kind: "pending",
+				reason: "over-cap"
+			};
+		}
 	}
-	const best = online.map((node) => ({
+	if (eligible.length === 0) return {
+		kind: "pending",
+		reason: "over-cap"
+	};
+	const best = eligible.map((node) => ({
 		node,
 		score: computeCapacityScore(node)
 	})).toSorted((a, b) => a.score - b.score)[0];
 	return {
+		kind: "assigned",
 		agentNodeId: best.node.nodeId,
 		reason: "capacity",
 		score: best.score
@@ -22500,6 +22767,139 @@ var PipelineWatchdog = class {
 	}
 };
 //#endregion
+//#region src/camera-status/compose-camera-status.ts
+function mapAssignment(input) {
+	return {
+		detectionNodeId: input.detectionNodeId,
+		decoderNodeId: input.decoderNodeId,
+		audioNodeId: input.audioNodeId,
+		pinned: {
+			detection: input.pinned.detection,
+			decoder: input.pinned.decoder,
+			audio: input.pinned.audio
+		},
+		reasons: {
+			detection: input.reasons.detection,
+			decoder: input.reasons.decoder,
+			audio: input.reasons.audio
+		}
+	};
+}
+function mapSource(sourceResult) {
+	if (sourceResult === null) return { streams: [] };
+	return { streams: sourceResult.streams.map((s) => ({
+		camStreamId: s.camStreamId,
+		codec: s.codec,
+		width: s.width,
+		height: s.height,
+		fps: s.fps,
+		kind: s.kind
+	})) };
+}
+function mapBroker(brokerResult) {
+	if (brokerResult === null) return null;
+	return {
+		profiles: brokerResult.profiles.map((p) => ({
+			profile: p.profile,
+			status: p.status,
+			codec: p.codec,
+			width: p.width,
+			height: p.height,
+			subscribers: p.subscribers,
+			inFps: p.inFps,
+			outFps: p.outFps
+		})),
+		webrtcSessions: brokerResult.webrtcSessions,
+		rtspRestream: brokerResult.rtspRestream
+	};
+}
+function mapDecoderShm(shm) {
+	return {
+		framesWritten: shm.framesWritten,
+		getFrameHits: shm.getFrameHits,
+		getFrameMisses: shm.getFrameMisses,
+		budgetMb: shm.budgetMb
+	};
+}
+function mapDecoder(decoderResult) {
+	if (decoderResult === null) return null;
+	return {
+		nodeId: decoderResult.nodeId,
+		formats: [...decoderResult.formats],
+		sessionCount: decoderResult.sessionCount,
+		shm: mapDecoderShm(decoderResult.shm)
+	};
+}
+function mapMotion(motionResult) {
+	if (motionResult === null) return null;
+	return {
+		enabled: motionResult.enabled,
+		fps: motionResult.fps
+	};
+}
+function mapProvisioning(p) {
+	if (p.error !== void 0) return {
+		state: p.state,
+		error: p.error
+	};
+	return { state: p.state };
+}
+function mapDetection(detectionResult) {
+	if (detectionResult === null) return null;
+	const phase = detectionResult.phase;
+	return {
+		nodeId: detectionResult.nodeId,
+		engine: {
+			backend: detectionResult.engine.backend,
+			device: detectionResult.engine.device
+		},
+		phase,
+		configuredFps: detectionResult.configuredFps,
+		actualFps: detectionResult.actualFps,
+		queueDepth: detectionResult.queueDepth,
+		avgInferenceMs: detectionResult.avgInferenceMs,
+		provisioning: mapProvisioning(detectionResult.provisioning)
+	};
+}
+function mapAudio(audioResult) {
+	if (audioResult === null) return null;
+	return {
+		nodeId: audioResult.nodeId,
+		enabled: audioResult.enabled
+	};
+}
+function mapRecording(recordingResult) {
+	if (recordingResult === null) return null;
+	return {
+		mode: recordingResult.mode,
+		active: recordingResult.active,
+		storageBytes: recordingResult.storageBytes
+	};
+}
+/**
+* Pure function that composes a `CameraStatus` from per-stage fetch results.
+*
+* - `assignment` is always built from orchestrator-local data (never null).
+* - `source` always present: defaults to `{ streams: [] }` when sourceResult is null.
+* - Every other block is null when its stage result is null (graceful degradation).
+* - `fetchedAt` is stamped exactly as provided — never calls `Date.now()`.
+* - No mutation of the input.
+*/
+function composeCameraStatus(input) {
+	return {
+		deviceId: input.deviceId,
+		assignment: mapAssignment(input),
+		source: mapSource(input.sourceResult),
+		broker: mapBroker(input.brokerResult),
+		decoder: mapDecoder(input.decoderResult),
+		motion: mapMotion(input.motionResult),
+		detection: mapDetection(input.detectionResult),
+		audio: mapAudio(input.audioResult),
+		recording: mapRecording(input.recordingResult),
+		fetchedAt: input.fetchedAt
+	};
+}
+//#endregion
 //#region src/index.ts
 var PHASE_MODE_VALUES = new Set([
 	"disabled",
@@ -23257,8 +23657,7 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 					});
 					return {
 						success: true,
-						agentNodeId: "",
-						reason: "capacity"
+						kind: "pending"
 					};
 				}
 			}
@@ -23268,14 +23667,22 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 		const preferredAgent = typeof pipelinePin === "string" && pipelinePin !== "auto" ? pipelinePin : legacyPreferred;
 		const decision = balance({
 			nodes: await this.collectAgentLoad({ onlyEnabled: true }),
-			preferredAgent
+			preferredAgent,
+			nodeCaps: this.buildNodeCaps()
 		});
-		const targetNodeId = decision?.agentNodeId ?? await this.localRunnerNodeId();
-		if (!targetNodeId) throw new Error(`dispatchCamera: no runner available for ${runnerConfig.deviceId}`);
+		if (!decision) throw new Error(`dispatchCamera: no runner available for ${runnerConfig.deviceId}`);
+		if (decision.kind === "pending") {
+			this.ctx.logger.warn("camera left pending — all nodes at maxCameras", { tags: { deviceId: runnerConfig.deviceId } });
+			return {
+				success: true,
+				kind: "pending"
+			};
+		}
+		const targetNodeId = decision.agentNodeId;
 		await this.attachOn(targetNodeId, runnerConfig);
 		if (targetNodeId === this.localNodeId) this.pipelineWatchdog?.register(this.buildWatchdogCamera(runnerConfig, String(runnerConfig.deviceId)));
-		const reason = decision?.reason ?? "capacity";
-		const pinned = decision?.reason === "manual";
+		const reason = decision.reason;
+		const pinned = decision.reason === "manual";
 		this.recordAssignment(runnerConfig.deviceId, targetNodeId, reason, pinned);
 		const decoderNodeId = await this.resolveDecoderNode(runnerConfig.deviceId, targetNodeId);
 		this.ctx.logger.info("dispatchCamera", {
@@ -23285,12 +23692,13 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 			},
 			meta: {
 				reason,
-				score: decision?.score ?? "n/a",
+				score: decision.score,
 				decoderNodeId
 			}
 		});
 		return {
 			success: true,
+			kind: "assigned",
 			agentNodeId: targetNodeId,
 			reason
 		};
@@ -23364,10 +23772,13 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 		if (cached) {
 			const decision = balance({
 				nodes: await this.collectAgentLoad({ onlyEnabled: true }),
-				preferredAgent: null
+				preferredAgent: null,
+				nodeCaps: this.buildNodeCaps()
 			});
-			const targetNodeId = decision?.agentNodeId ?? await this.localRunnerNodeId();
-			if (targetNodeId) {
+			if (!decision) this.ctx.logger.warn("unassignPipeline: no runner available, leaving unassigned", { tags: { deviceId: input.deviceId } });
+			else if (decision.kind === "pending") this.ctx.logger.warn("camera left pending — all nodes at maxCameras", { tags: { deviceId: input.deviceId } });
+			else {
+				const targetNodeId = decision.agentNodeId;
 				if (current && current.agentNodeId !== targetNodeId) await this.detachOn(current.agentNodeId, input.deviceId).catch((err) => {
 					const msg = errMsg(err);
 					this.ctx.logger.debug("unassignPipeline detach-old failed", {
@@ -23376,7 +23787,7 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 					});
 				});
 				if (!current || current.agentNodeId !== targetNodeId) await this.attachOn(targetNodeId, cached);
-				const reason = decision?.reason === "manual" ? "capacity" : decision?.reason ?? "capacity";
+				const reason = decision.reason === "manual" ? "capacity" : decision.reason;
 				this.recordAssignment(input.deviceId, targetNodeId, reason, false);
 				this.ctx.logger.info("unassignPipeline: re-dispatched via auto", {
 					tags: {
@@ -23387,7 +23798,6 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 				});
 				return { success: true };
 			}
-			this.ctx.logger.warn("unassignPipeline: no runner available, leaving unassigned", { tags: { deviceId: input.deviceId } });
 		}
 		if (current) {
 			await this.detachOn(current.agentNodeId, input.deviceId).catch((err) => {
@@ -23405,15 +23815,21 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 	async rebalance() {
 		if (!this.ctx) throw new Error("PipelineOrchestrator: rebalance called before initialize");
 		const loads = await this.collectAgentLoad({ onlyEnabled: true });
+		const nodeCaps = this.buildNodeCaps();
 		let migrated = 0;
 		for (const [deviceId, config] of this.cameraConfigs) {
 			const current = this.assignments.get(deviceId);
 			if (current?.pinned) continue;
 			const decision = balance({
 				nodes: loads,
-				preferredAgent: await this.readPreferredAgent(deviceId)
+				preferredAgent: await this.readPreferredAgent(deviceId),
+				nodeCaps
 			});
 			if (!decision) continue;
+			if (decision.kind === "pending") {
+				this.ctx.logger.warn("camera left pending — all nodes at maxCameras", { tags: { deviceId } });
+				continue;
+			}
 			if (current && current.agentNodeId === decision.agentNodeId) continue;
 			if (current) await this.detachOn(current.agentNodeId, deviceId).catch((err) => {
 				const msg = errMsg(err);
@@ -23551,15 +23967,6 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 			nodeId
 		});
 	}
-	async localRunnerNodeId() {
-		const api = this.ctx.api;
-		if (!api) return null;
-		try {
-			return (await api.pipelineRunner.getLocalLoad.query({ nodeId: this.localNodeId }))?.nodeId ?? this.localNodeId;
-		} catch {
-			return this.localNodeId;
-		}
-	}
 	/**
 	* Enumerate every runner-capable node currently known (populated via
 	* AgentOnline/AgentOffline events). Used to populate the `enabledNodes`
@@ -23714,6 +24121,18 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 			return null;
 		}
 	}
+	/**
+	* Build a per-node camera cap map from the persisted agent settings.
+	* Returns `null` for nodes where `maxCameras` is null (unlimited).
+	* Used by every `balance()` call so the balancer can honour operator-set
+	* per-node maximums without polling the store on each decision.
+	*/
+	buildNodeCaps() {
+		const blob = this.agentSettingsState.get();
+		const caps = {};
+		for (const [nodeId, settings] of Object.entries(blob)) caps[nodeId] = settings.maxCameras ?? null;
+		return caps;
+	}
 	async readAudioNodePin(deviceId) {
 		if (!this.ctx?.settings) return null;
 		try {
@@ -23856,13 +24275,19 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 		for (const { deviceId, config } of affected) {
 			const decision = balance({
 				nodes: loads,
-				preferredAgent: null
+				preferredAgent: null,
+				nodeCaps: this.buildNodeCaps()
 			});
 			if (!decision) {
 				this.ctx.logger.error("Failover: no online runner", { tags: { deviceId } });
 				this.assignments.delete(deviceId);
 				continue;
 			}
+			if (decision.kind === "pending") {
+				this.ctx.logger.warn("camera left pending — all nodes at maxCameras", { tags: { deviceId } });
+				this.assignments.delete(deviceId);
+				continue;
+			}
 			try {
 				await this.attachOn(decision.agentNodeId, config);
 				this.recordAssignment(deviceId, decision.agentNodeId, "failover", false);
@@ -24342,7 +24767,10 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 	}
 	async setAgentAddonDefaults(input) {
 		let existing = (await this.readAgentSettingsMap())[input.agentNodeId];
-		if (!existing) existing = await this.seedAgentSettingsFromCatalog(input.agentNodeId) ?? void 0;
+		if (!existing) {
+			await this.seedAgentSettingsFromCatalog(input.agentNodeId);
+			existing = (await this.readAgentSettingsMap())[input.agentNodeId];
+		}
 		if (!existing) await this.writeAgentSettings(input.agentNodeId, { addonDefaults: { ...input.defaults } });
 		else await this.writeAgentSettings(input.agentNodeId, {
 			...existing,
@@ -24380,6 +24808,22 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 			removed: true
 		};
 	}
+	async setAgentMaxCameras(input) {
+		const existing = (await this.readAgentSettingsMap())[input.agentNodeId];
+		const next = existing ? {
+			...existing,
+			maxCameras: input.maxCameras
+		} : {
+			addonDefaults: {},
+			maxCameras: input.maxCameras
+		};
+		await this.writeAgentSettings(input.agentNodeId, next);
+		this.ctx.logger.info("agentSettings.maxCameras updated", {
+			tags: { nodeId: input.agentNodeId },
+			meta: { maxCameras: input.maxCameras }
+		});
+		return { success: true };
+	}
 	async getCameraSettings(input) {
 		return (await this.readCameraSettingsMap())[String(input.deviceId)] ?? null;
 	}
@@ -24509,6 +24953,204 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 		this.ctx.logger.info("template deleted", { meta: { templateId: input.id } });
 		return { success: true };
 	}
+	/**
+	* Races a promise against a timeout. Returns `null` on timeout OR rejection.
+	* Never throws — individual stage failures become `null` in the aggregate.
+	*
+	* @param p   The stage fetch promise.
+	* @param ms  Timeout in milliseconds.
+	*/
+	boundedStage(p, ms) {
+		let timer;
+		const timeout = new Promise((resolve) => {
+			timer = setTimeout(() => resolve(null), ms);
+		});
+		return Promise.race([p, timeout]).catch(() => null).finally(() => {
+			if (timer !== void 0) clearTimeout(timer);
+		});
+	}
+	/**
+	* Server-composed aggregated status for a single camera.
+	*
+	* Fans out in parallel (bounded, per-stage graceful degradation) to
+	* broker / decoder / motion / detection / audio / recording source caps
+	* via `ctx.api`. A stage whose source errors or times out becomes `null`
+	* in the returned payload — one slow agent never breaks the whole call.
+	*/
+	async getCameraStatus(input) {
+		const { deviceId } = input;
+		const api = this.ctx.api;
+		const STAGE_TIMEOUT_MS = 3e3;
+		const pipelineAssignment = this.assignments.get(deviceId) ?? null;
+		const detectionNodeId = pipelineAssignment?.agentNodeId ?? null;
+		const decoderPinRaw = (api ? await this.ctx.settings?.readDeviceStore(deviceId).catch(() => ({})) ?? {} : {})["decoderNodeId"];
+		const decoderPinned = typeof decoderPinRaw === "string" && decoderPinRaw !== "auto";
+		const decoderNodeId = detectionNodeId ? await this.resolveDecoderNode(deviceId, detectionNodeId).catch(() => null) : null;
+		const audioAssignment = this.audioAssignments.get(deviceId) ?? null;
+		const audioNodeId = audioAssignment?.nodeId ?? null;
+		const audioPinned = audioAssignment?.pinned ?? false;
+		const pinned = {
+			detection: pipelineAssignment?.pinned ?? false,
+			decoder: decoderPinned,
+			audio: audioPinned
+		};
+		const reasons = {
+			detection: pipelineAssignment?.reason,
+			decoder: decoderPinned ? "manual" : "co-located",
+			audio: audioPinned ? "manual" : void 0
+		};
+		const allSlotsFetch = api ? api.streamBroker.listAllProfileSlots.query() : null;
+		const sourceFetch = api && allSlotsFetch ? this.boundedStage(allSlotsFetch.then((slots) => {
+			return { streams: slots.filter((s) => s.deviceId === deviceId).map((s) => ({
+				camStreamId: s.sourceCamStreamId ?? s.brokerId,
+				codec: s.codec ?? "",
+				width: s.resolution?.width ?? 0,
+				height: s.resolution?.height ?? 0,
+				fps: 0,
+				kind: s.profile
+			})) };
+		}), STAGE_TIMEOUT_MS) : Promise.resolve(null);
+		const WEBRTC_KINDS = new Set([
+			"webrtc-browser",
+			"webrtc-mobile",
+			"webrtc-whep"
+		]);
+		const brokerFetch = api && allSlotsFetch ? this.boundedStage(allSlotsFetch.then(async (slots) => {
+			const deviceSlots = slots.filter((s) => s.deviceId === deviceId);
+			if (deviceSlots.length === 0) return {
+				profiles: [],
+				webrtcSessions: 0,
+				rtspRestream: false
+			};
+			const [statsAndClients, rtspEntry] = await Promise.all([Promise.all(deviceSlots.map(async (slot) => {
+				return {
+					slot,
+					stats: await api.streamBroker.getBrokerStats.query({ brokerId: slot.brokerId }).catch(() => null),
+					clients: await api.streamBroker.listClients.query({ brokerId: slot.brokerId }).catch(() => null)
+				};
+			})), api.streamBroker.getAllRtspEntries.query({}).catch(() => null)]);
+			return {
+				profiles: statsAndClients.map(({ slot, stats, clients }) => ({
+					profile: slot.profile,
+					status: slot.status,
+					codec: stats?.codec ?? slot.codec ?? "",
+					width: slot.resolution?.width ?? 0,
+					height: slot.resolution?.height ?? 0,
+					subscribers: clients?.encodedSubscribers ?? 0,
+					inFps: stats?.inputFps ?? 0,
+					outFps: stats?.decodeFps ?? 0
+				})),
+				webrtcSessions: statsAndClients.reduce((total, { clients }) => {
+					if (!clients) return total;
+					return total + clients.encoded.filter((c) => WEBRTC_KINDS.has(c.attribution.kind)).length;
+				}, 0),
+				rtspRestream: rtspEntry?.some((e) => {
+					return e.brokerId.split("/")[0] === String(deviceId) && e.enabled;
+				}) ?? false
+			};
+		}), STAGE_TIMEOUT_MS) : Promise.resolve(null);
+		const decoderFetch = decoderNodeId ? Promise.resolve({
+			nodeId: decoderNodeId,
+			formats: [],
+			sessionCount: 0,
+			shm: {
+				framesWritten: 0,
+				getFrameHits: 0,
+				getFrameMisses: 0,
+				budgetMb: 0
+			}
+		}) : Promise.resolve(null);
+		const motionResult = (() => {
+			const config = this.cameraConfigs.get(deviceId);
+			if (!config) return null;
+			return {
+				enabled: config.motionSources.includes("analyzer") || config.motionSources.includes("onboard"),
+				fps: config.motionFps
+			};
+		})();
+		const detectionFetch = api && detectionNodeId ? this.boundedStage(Promise.all([api.pipelineExecutor.getEngineProvisioning.query({ nodeId: detectionNodeId }).catch(() => null), api.pipelineExecutor.getSelectedEngine.query({ nodeId: detectionNodeId }).catch(() => null)]).then(async ([provisioning, engine]) => {
+			const metrics = await api.pipelineRunner.getCameraMetrics.query({
+				deviceId,
+				nodeId: detectionNodeId
+			}).catch(() => null);
+			const phase = (() => {
+				const p = metrics?.phase;
+				if (p === "active") return "active";
+				if (p === "idle") return "idle";
+				return "watching";
+			})();
+			return {
+				nodeId: detectionNodeId,
+				engine: {
+					backend: engine?.backend ?? "",
+					device: engine?.device ?? ""
+				},
+				phase,
+				configuredFps: metrics?.configuredFps ?? 0,
+				actualFps: metrics?.actualFps ?? 0,
+				queueDepth: metrics?.queueDepth ?? 0,
+				avgInferenceMs: metrics?.avgInferenceTimeMs ?? 0,
+				provisioning: {
+					state: provisioning?.state ?? "idle",
+					...provisioning?.error !== void 0 ? { error: provisioning.error } : {}
+				}
+			};
+		}), STAGE_TIMEOUT_MS) : Promise.resolve(null);
+		const audioResult = audioNodeId ? {
+			nodeId: audioNodeId,
+			enabled: true
+		} : null;
+		function isRecordingStatus(v) {
+			return v !== null && typeof v === "object" && "activeMode" in v && (v.activeMode === "off" || v.activeMode === "continuous" || v.activeMode === "events") && "enabled" in v && typeof v.enabled === "boolean" && "storageBytes" in v && typeof v.storageBytes === "number";
+		}
+		const recordingFetch = api ? this.boundedStage(api.recording.getStatus.query({ deviceId }).then((rawStatus) => {
+			if (!isRecordingStatus(rawStatus)) return null;
+			return {
+				mode: rawStatus.activeMode,
+				active: rawStatus.enabled && rawStatus.activeMode !== "off",
+				storageBytes: rawStatus.storageBytes
+			};
+		}).catch(() => null), STAGE_TIMEOUT_MS) : Promise.resolve(null);
+		const [sourceResult, brokerResult, decoderResult, detectionResult, recordingResult] = await Promise.all([
+			sourceFetch,
+			brokerFetch,
+			decoderFetch,
+			detectionFetch,
+			recordingFetch
+		]);
+		return composeCameraStatus({
+			deviceId,
+			fetchedAt: Date.now(),
+			detectionNodeId,
+			decoderNodeId,
+			audioNodeId,
+			pinned,
+			reasons,
+			sourceResult,
+			brokerResult,
+			decoderResult,
+			motionResult,
+			detectionResult,
+			audioResult,
+			recordingResult
+		});
+	}
+	/**
+	* Server-composed aggregated status for multiple cameras in one call.
+	*
+	* `deviceIds` defaults to all cameras currently tracked by the
+	* orchestrator's assignment map when omitted.
+	*
+	* v1: `Promise.all` over per-device composition (no concurrency cap).
+	* Note: for large fleets (hundreds of cameras) this may fan out many
+	* parallel calls. A concurrency limiter (p-limit / semaphore) should be
+	* added if latency measurements show it's necessary — deliberately
+	* deferred per the YAGNI constraint in the spec.
+	*/
+	async getCameraStatuses(input) {
+		const ids = input.deviceIds !== void 0 && input.deviceIds.length > 0 ? input.deviceIds : [...this.assignments.keys()];
+		return Promise.all(ids.map((deviceId) => this.getCameraStatus({ deviceId })));
+	}
 	/** Read the templates map from the addon store via the durable handle. */
 	async readTemplatesMap() {
 		const raw = await this.templatesState.get();
@@ -24539,7 +25181,11 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 			return;
 		}
 		const all = await this.readAgentSettingsMap();
-		all[nodeId] = settings;
+		const existing = all[nodeId];
+		all[nodeId] = {
+			addonDefaults: settings.addonDefaults,
+			maxCameras: settings.maxCameras !== void 0 ? settings.maxCameras ?? null : existing?.maxCameras ?? null
+		};
 		await this.agentSettingsState.set(all);
 	}
 	/** Read the `cameraSettings` map (keyed on `deviceId` as string) via the durable handle. */
@@ -24749,12 +25395,15 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 			}
 			let agent = (await this.readAgentSettingsMap())[nodeId];
 			if (!agent || Object.keys(agent.addonDefaults ?? {}).length === 0) {
-				const seeded = await this.seedAgentSettingsFromCatalog(nodeId);
-				if (!seeded) {
+				if (!await this.seedAgentSettingsFromCatalog(nodeId)) {
 					await sleep$1(2e3);
 					continue;
 				}
-				agent = seeded;
+				agent = (await this.readAgentSettingsMap())[nodeId];
+			}
+			if (!agent) {
+				await sleep$1(2e3);
+				continue;
 			}
 			const engine = await this.readDetectionPipelineEngine(nodeId) ?? catalog.selectedEngine;
 			return {
@@ -25661,7 +26310,8 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 		};
 		let dispatchedNodeId = null;
 		try {
-			dispatchedNodeId = (await this.dispatchCamera(runnerConfig)).agentNodeId;
+			const result = await this.dispatchCamera(runnerConfig);
+			if (result.kind === "assigned") dispatchedNodeId = result.agentNodeId;
 		} catch (err) {
 			const msg = errMsg(err);
 			log.error("dispatchCamera failed", { meta: { error: msg } });