@camstack/addon-ai 0.4.106 → 0.4.107

package/dist/addon.js

@@ -12,7 +12,7 @@ let _camstack_system_addon_utils = require("@camstack/system/addon-utils");
 let node_fs_promises = require("node:fs/promises");
 node_fs_promises = require_chunk.__toESM(node_fs_promises);
 let node_child_process = require("node:child_process");
-//#region ../types/dist/event-category-ZyX6jcse.mjs
+//#region ../types/dist/event-category-BVDXG4tB.mjs
 var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["SystemBoot"] = "system.boot";
 	EventCategory["SystemAddonsReady"] = "system.addons-ready";
@@ -629,6 +629,20 @@ var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	* pull-reconcile from the provider's `getStatus` on reconnect. */
 	EventCategory["MeshNetworkChanged"] = "network.mesh.changed";
 	EventCategory["BackupCompleted"] = "backup.completed";
+	/**
+	* A whole backup RUN finished — every destination attempted, win or lose.
+	*
+	* `backup.completed` fires once per DESTINATION, which is the right grain for
+	* a progress UI and the wrong one for a notification: an operator with three
+	* destinations would be told three times. And a run where two of three
+	* destinations succeeded is not a clean success — a single "backup
+	* completed" that hid the failed one would be a lie, so the count of each is
+	* carried here and the message says both.
+	*
+	* Emitted by the backup orchestrator only after the destination loop, so a
+	* run that dies during the BUILD phase produces no completion at all.
+	*/
+	EventCategory["BackupRunCompleted"] = "backup.run-completed";
 	EventCategory["BackupRestored"] = "backup.restored";
 	EventCategory["NotificationDispatched"] = "notification.dispatched";
 	EventCategory["NotificationFailed"] = "notification.failed";
@@ -5506,7 +5520,7 @@ function number(params) {
 	return /* @__PURE__ */ _coercedNumber(ZodNumber, params);
 }
 //#endregion
-//#region ../types/dist/sleep-DBKu2-U5.mjs
+//#region ../types/dist/sleep-DEuj7E3j.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -11693,6 +11707,58 @@ method(ListInputSchema, array(BrokerInfoSchema$1)), method(GetInputSchema, Broke
 	auth: "admin"
 }), method(GetStateInputSchema, unknown().nullable()), method(_void(), RegistryStatusSchema);
 DeviceType.Camera;
+/**
+* The signals a device can emit to WAKE its own stream.
+*
+* A camera whose stream is built on demand sleeps until something asks for it,
+* and "something" cannot be a consumer that is merely attached — a Frigate-style
+* puller holds a session open for ever, and treating that as demand would keep
+* a battery camera awake for ever, which is the whole thing the battery is for
+* (D173). So the wake has to come from the CAMERA: an event it noticed by
+* itself, with no stream running.
+*
+* ## The vocabulary is the PROVIDER'S, not ours
+*
+* Like `consumables`, this cap declares no vocabulary of its own. A provider
+* names each signal with a `code` it chooses and a `label` an operator reads.
+* Reolink offers motion and camera-native detection; another provider may offer
+* a tamper, a doorbell press, a PIR, or something no camera in this fleet has
+* yet. A fixed enum here would mean every new signal is a framework release.
+*
+* It is deliberately NOT derived from the caps a device already binds. Whether
+* a camera CAN push firmware motion is expressed by `motionSources` containing
+* `'onboard'`, and whether it does AI on-camera by the `native-object-detection`
+* binding — but both answer "what drives the detection pipeline", which is a
+* different question from "what may wake a sleeping stream". A camera can do
+* the first and not be trusted with the second, and the operator picks per
+* camera. Two questions, two authorities.
+*
+* ## Availability is not permission
+*
+* `listSignals` says what the device CAN emit. Whether a given signal actually
+* wakes the stream is the operator's per-camera choice, held by the broker
+* alongside the cooldown — see the stream-broker cap's wake settings. A
+* provider declaring a signal is not a provider enabling it.
+*/
+/** One signal a device can emit. */
+var StreamSignalSchema = object({
+	/** Stable id chosen by the provider, e.g. `'motion'`, `'person'`, `'tamper'`. */
+	code: string().min(1),
+	/** What an operator reads in the picker. The provider's own wording. */
+	label: string().min(1),
+	/**
+	* Whether the provider recommends this signal ON when a camera is first set
+	* up. A provider knows which of its signals are cheap and reliable; an
+	* operator should not have to discover that by trial. Reolink recommends
+	* both of its own.
+	*/
+	recommended: boolean()
+});
+object({
+	signals: array(StreamSignalSchema),
+	lastFetchedAt: number$1()
+});
+Object.values(DeviceType), method(_void(), array(StreamSignalSchema).readonly());
 /** Stream delivery format. (Relocated from the retired `streaming-engine` cap.) */
 var StreamFormatSchema = _enum([
 	"webrtc",
@@ -12089,6 +12155,22 @@ var EgressTranscodeSchema = object({
 	camStreamId: string().nullable()
 });
 method(object({
+	deviceId: number$1().int().nonnegative(),
+	/** The provider's signal code. */
+	code: string().min(1),
+	/** Ms epoch. Absent ⇒ now. */
+	at: number$1().optional()
+}), object({
+	/** Whether the broker acted on it, and if not, why. */
+	accepted: boolean(),
+	reason: _enum([
+		"woke",
+		"hold-extended",
+		"not-enabled",
+		"no-consumer",
+		"unknown-code"
+	])
+}), { kind: "mutation" }), method(object({
 	deviceId: number$1().int().nonnegative(),
 	camStreamId: string().min(1),
 	kind: CamStreamKindSchema,
@@ -12343,6 +12425,16 @@ var PickStreamRequirementsSchema = object({
 	acceptCodecs: array(StreamCodecSchema).readonly().optional(),
 	/** Minimum vertical resolution. Streams shorter than this are dropped. */
 	minHeight: number$1().int().positive().optional(),
+	/**
+	* Maximum vertical resolution. Streams TALLER than this are dropped.
+	*
+	* A consumer can have a ceiling as real as its floor: Alexa documents
+	* 480p to 1080p, and a 4K stream is as unusable to an Echo as a 360p one.
+	* Without this the ceiling had to be re-implemented by every caller — and
+	* one caller implementing it privately is how a second scoring authority
+	* gets born.
+	*/
+	maxHeight: number$1().int().positive().optional(),
 	/** Minimum horizontal resolution. */
 	minWidth: number$1().int().positive().optional(),
 	/**
@@ -12359,7 +12451,22 @@ var PickStreamRequirementsSchema = object({
 	* transcoded" guard: if the device is already serving the consumer's
 	* codec end-to-end, there's nothing to optimise.
 	*/
-	requireSiblingCodec: array(StreamCodecSchema).readonly().optional()
+	requireSiblingCodec: array(StreamCodecSchema).readonly().optional(),
+	/**
+	* Whether a stream the consumer CANNOT decode may still be picked, on the
+	* understanding that it will be transcoded.
+	*
+	* Default `false` — today's behaviour, and the right one for a bypass
+	* question ("is there a stream I can forward untouched?"). Set `true` to
+	* ask the larger question: "what is the best stream for me, transcoding if
+	* I must?" A stream that satisfies `acceptCodecs` always outranks one that
+	* does not, so a passthrough is never lost to a transcode; the answer says
+	* which it is in {@link PickedCamStreamSchema.transcodes}.
+	*
+	* This is what lets one picker serve both the bypass and the full source
+	* choice, instead of a consumer scoring privately when the bypass misses.
+	*/
+	allowTranscode: boolean().optional()
 }).readonly();
 var PickStreamPreferencesSchema = object({
 	/**
@@ -12373,12 +12480,32 @@ var PickStreamPreferencesSchema = object({
 	* picks the tallest stream; `'lowest'` picks the shortest (used by
 	* memory-constrained consumers / Apple Home guest sessions).
 	*/
-	resolutionPreference: _enum(["highest", "lowest"]).optional()
+	resolutionPreference: _enum(["highest", "lowest"]).optional(),
+	/**
+	* The height the consumer actually wants to DELIVER.
+	*
+	* Not a constraint — an ordering. With it set, the SMALLEST stream at or
+	* above the target wins, and only if nothing reaches it does the tallest
+	* take over. Pulling 1296 lines to draw 720 on a 1280x800 Echo panel costs
+	* a decode and buys nothing, and `resolutionPreference: 'highest'` cannot
+	* express that: it says "as big as possible", which is a different wish.
+	*
+	* Ignored when absent, so every existing caller keeps its ordering.
+	*/
+	targetHeight: number$1().int().positive().optional()
 }).readonly();
 var PickedCamStreamSchema = object({
 	camStreamId: string(),
 	codec: string().optional(),
 	resolution: CamStreamResolutionSchema.optional(),
+	/**
+	* Whether serving this stream requires a decode + re-encode.
+	*
+	* `false` is a stream the consumer can take as it stands. Only ever `true`
+	* when the caller asked for it with `allowTranscode`, so a caller that did
+	* not ask cannot be handed a cost it never agreed to pay.
+	*/
+	transcodes: boolean(),
 	/** One-line explanation of why this stream won — for logs / debug UI. */
 	reason: string()
 });
@@ -16661,6 +16788,8 @@ var NcSystemEventKindSchema = _enum([
 	"device-enabled",
 	"device-battery-low",
 	"device-battery-normal",
+	"device-consumable-low",
+	"device-consumable-normal",
 	"stream-online",
 	"stream-offline",
 	"node-online",
@@ -16679,6 +16808,7 @@ var NcSystemEventKindSchema = _enum([
 	"addon-updated",
 	"server-updated",
 	"export-completed",
+	"backup-completed",
 	"camera-online",
 	"camera-offline",
 	"camera-disabled",
@@ -23920,10 +24050,28 @@ DeviceType.Camera, method(object({ deviceId: number$1().int().nonnegative() }),
 }), boolean()), method(object({
 	deviceId: number$1().int().nonnegative(),
 	sessionId: string()
-}), object({ pendingRenegotiation: object({
-	target: WebrtcStreamTargetSchema,
-	epoch: number$1()
-}).nullable() }));
+}), object({
+	pendingRenegotiation: object({
+		target: WebrtcStreamTargetSchema,
+		epoch: number$1()
+	}).nullable(),
+	/**
+	* Whether the session still EXISTS.
+	*
+	* A consumer that holds a resource for the life of a session needs to
+	* be able to ask, because a session does not always end the way it
+	* began. Measured on this hub 2026-09-13: an Echo that got stuck never
+	* sent `SessionDisconnected`, so the Alexa exporter's
+	* `releaseEgressTranscode` never ran, and a 2304x1296 HEVC to 720p
+	* H.264 transcode kept running for NOBODY for more than twenty
+	* minutes. The WebRTC session had logged `WebRTC session closed`
+	* minutes earlier — the broker knew; the holder had no way to ask.
+	*
+	* `false` for a session id the provider has never heard of, which is
+	* the same answer as "it ended": either way nothing is holding it up.
+	*/
+	alive: boolean()
+}));
 object({
 	/** All accessory children of the parent. */
 	childDeviceIds: array(number$1()).readonly(),
@@ -36427,6 +36575,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"streamBroker.reportStreamSignal": {
+		capName: "stream-broker",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"streamBroker.restartProfile": {
 		capName: "stream-broker",
 		capScope: "system",
@@ -36511,6 +36665,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"streamSignals.listSignals": {
+		capName: "stream-signals",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"switch.setState": {
 		capName: "switch",
 		capScope: "device",
@@ -38883,6 +39043,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"streamBroker.reportStreamSignal": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"streamBroker.restartProfile": [{
 		name: "deviceId",
 		form: "single",

package/dist/addon.mjs

@@ -39,7 +39,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 //#endregion
-//#region ../types/dist/event-category-ZyX6jcse.mjs
+//#region ../types/dist/event-category-BVDXG4tB.mjs
 var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["SystemBoot"] = "system.boot";
 	EventCategory["SystemAddonsReady"] = "system.addons-ready";
@@ -656,6 +656,20 @@ var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	* pull-reconcile from the provider's `getStatus` on reconnect. */
 	EventCategory["MeshNetworkChanged"] = "network.mesh.changed";
 	EventCategory["BackupCompleted"] = "backup.completed";
+	/**
+	* A whole backup RUN finished — every destination attempted, win or lose.
+	*
+	* `backup.completed` fires once per DESTINATION, which is the right grain for
+	* a progress UI and the wrong one for a notification: an operator with three
+	* destinations would be told three times. And a run where two of three
+	* destinations succeeded is not a clean success — a single "backup
+	* completed" that hid the failed one would be a lie, so the count of each is
+	* carried here and the message says both.
+	*
+	* Emitted by the backup orchestrator only after the destination loop, so a
+	* run that dies during the BUILD phase produces no completion at all.
+	*/
+	EventCategory["BackupRunCompleted"] = "backup.run-completed";
 	EventCategory["BackupRestored"] = "backup.restored";
 	EventCategory["NotificationDispatched"] = "notification.dispatched";
 	EventCategory["NotificationFailed"] = "notification.failed";
@@ -5533,7 +5547,7 @@ function number(params) {
 	return /* @__PURE__ */ _coercedNumber(ZodNumber, params);
 }
 //#endregion
-//#region ../types/dist/sleep-DBKu2-U5.mjs
+//#region ../types/dist/sleep-DEuj7E3j.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -11720,6 +11734,58 @@ method(ListInputSchema, array(BrokerInfoSchema$1)), method(GetInputSchema, Broke
 	auth: "admin"
 }), method(GetStateInputSchema, unknown().nullable()), method(_void(), RegistryStatusSchema);
 DeviceType.Camera;
+/**
+* The signals a device can emit to WAKE its own stream.
+*
+* A camera whose stream is built on demand sleeps until something asks for it,
+* and "something" cannot be a consumer that is merely attached — a Frigate-style
+* puller holds a session open for ever, and treating that as demand would keep
+* a battery camera awake for ever, which is the whole thing the battery is for
+* (D173). So the wake has to come from the CAMERA: an event it noticed by
+* itself, with no stream running.
+*
+* ## The vocabulary is the PROVIDER'S, not ours
+*
+* Like `consumables`, this cap declares no vocabulary of its own. A provider
+* names each signal with a `code` it chooses and a `label` an operator reads.
+* Reolink offers motion and camera-native detection; another provider may offer
+* a tamper, a doorbell press, a PIR, or something no camera in this fleet has
+* yet. A fixed enum here would mean every new signal is a framework release.
+*
+* It is deliberately NOT derived from the caps a device already binds. Whether
+* a camera CAN push firmware motion is expressed by `motionSources` containing
+* `'onboard'`, and whether it does AI on-camera by the `native-object-detection`
+* binding — but both answer "what drives the detection pipeline", which is a
+* different question from "what may wake a sleeping stream". A camera can do
+* the first and not be trusted with the second, and the operator picks per
+* camera. Two questions, two authorities.
+*
+* ## Availability is not permission
+*
+* `listSignals` says what the device CAN emit. Whether a given signal actually
+* wakes the stream is the operator's per-camera choice, held by the broker
+* alongside the cooldown — see the stream-broker cap's wake settings. A
+* provider declaring a signal is not a provider enabling it.
+*/
+/** One signal a device can emit. */
+var StreamSignalSchema = object({
+	/** Stable id chosen by the provider, e.g. `'motion'`, `'person'`, `'tamper'`. */
+	code: string().min(1),
+	/** What an operator reads in the picker. The provider's own wording. */
+	label: string().min(1),
+	/**
+	* Whether the provider recommends this signal ON when a camera is first set
+	* up. A provider knows which of its signals are cheap and reliable; an
+	* operator should not have to discover that by trial. Reolink recommends
+	* both of its own.
+	*/
+	recommended: boolean()
+});
+object({
+	signals: array(StreamSignalSchema),
+	lastFetchedAt: number$1()
+});
+Object.values(DeviceType), method(_void(), array(StreamSignalSchema).readonly());
 /** Stream delivery format. (Relocated from the retired `streaming-engine` cap.) */
 var StreamFormatSchema = _enum([
 	"webrtc",
@@ -12116,6 +12182,22 @@ var EgressTranscodeSchema = object({
 	camStreamId: string().nullable()
 });
 method(object({
+	deviceId: number$1().int().nonnegative(),
+	/** The provider's signal code. */
+	code: string().min(1),
+	/** Ms epoch. Absent ⇒ now. */
+	at: number$1().optional()
+}), object({
+	/** Whether the broker acted on it, and if not, why. */
+	accepted: boolean(),
+	reason: _enum([
+		"woke",
+		"hold-extended",
+		"not-enabled",
+		"no-consumer",
+		"unknown-code"
+	])
+}), { kind: "mutation" }), method(object({
 	deviceId: number$1().int().nonnegative(),
 	camStreamId: string().min(1),
 	kind: CamStreamKindSchema,
@@ -12370,6 +12452,16 @@ var PickStreamRequirementsSchema = object({
 	acceptCodecs: array(StreamCodecSchema).readonly().optional(),
 	/** Minimum vertical resolution. Streams shorter than this are dropped. */
 	minHeight: number$1().int().positive().optional(),
+	/**
+	* Maximum vertical resolution. Streams TALLER than this are dropped.
+	*
+	* A consumer can have a ceiling as real as its floor: Alexa documents
+	* 480p to 1080p, and a 4K stream is as unusable to an Echo as a 360p one.
+	* Without this the ceiling had to be re-implemented by every caller — and
+	* one caller implementing it privately is how a second scoring authority
+	* gets born.
+	*/
+	maxHeight: number$1().int().positive().optional(),
 	/** Minimum horizontal resolution. */
 	minWidth: number$1().int().positive().optional(),
 	/**
@@ -12386,7 +12478,22 @@ var PickStreamRequirementsSchema = object({
 	* transcoded" guard: if the device is already serving the consumer's
 	* codec end-to-end, there's nothing to optimise.
 	*/
-	requireSiblingCodec: array(StreamCodecSchema).readonly().optional()
+	requireSiblingCodec: array(StreamCodecSchema).readonly().optional(),
+	/**
+	* Whether a stream the consumer CANNOT decode may still be picked, on the
+	* understanding that it will be transcoded.
+	*
+	* Default `false` — today's behaviour, and the right one for a bypass
+	* question ("is there a stream I can forward untouched?"). Set `true` to
+	* ask the larger question: "what is the best stream for me, transcoding if
+	* I must?" A stream that satisfies `acceptCodecs` always outranks one that
+	* does not, so a passthrough is never lost to a transcode; the answer says
+	* which it is in {@link PickedCamStreamSchema.transcodes}.
+	*
+	* This is what lets one picker serve both the bypass and the full source
+	* choice, instead of a consumer scoring privately when the bypass misses.
+	*/
+	allowTranscode: boolean().optional()
 }).readonly();
 var PickStreamPreferencesSchema = object({
 	/**
@@ -12400,12 +12507,32 @@ var PickStreamPreferencesSchema = object({
 	* picks the tallest stream; `'lowest'` picks the shortest (used by
 	* memory-constrained consumers / Apple Home guest sessions).
 	*/
-	resolutionPreference: _enum(["highest", "lowest"]).optional()
+	resolutionPreference: _enum(["highest", "lowest"]).optional(),
+	/**
+	* The height the consumer actually wants to DELIVER.
+	*
+	* Not a constraint — an ordering. With it set, the SMALLEST stream at or
+	* above the target wins, and only if nothing reaches it does the tallest
+	* take over. Pulling 1296 lines to draw 720 on a 1280x800 Echo panel costs
+	* a decode and buys nothing, and `resolutionPreference: 'highest'` cannot
+	* express that: it says "as big as possible", which is a different wish.
+	*
+	* Ignored when absent, so every existing caller keeps its ordering.
+	*/
+	targetHeight: number$1().int().positive().optional()
 }).readonly();
 var PickedCamStreamSchema = object({
 	camStreamId: string(),
 	codec: string().optional(),
 	resolution: CamStreamResolutionSchema.optional(),
+	/**
+	* Whether serving this stream requires a decode + re-encode.
+	*
+	* `false` is a stream the consumer can take as it stands. Only ever `true`
+	* when the caller asked for it with `allowTranscode`, so a caller that did
+	* not ask cannot be handed a cost it never agreed to pay.
+	*/
+	transcodes: boolean(),
 	/** One-line explanation of why this stream won — for logs / debug UI. */
 	reason: string()
 });
@@ -16688,6 +16815,8 @@ var NcSystemEventKindSchema = _enum([
 	"device-enabled",
 	"device-battery-low",
 	"device-battery-normal",
+	"device-consumable-low",
+	"device-consumable-normal",
 	"stream-online",
 	"stream-offline",
 	"node-online",
@@ -16706,6 +16835,7 @@ var NcSystemEventKindSchema = _enum([
 	"addon-updated",
 	"server-updated",
 	"export-completed",
+	"backup-completed",
 	"camera-online",
 	"camera-offline",
 	"camera-disabled",
@@ -23947,10 +24077,28 @@ DeviceType.Camera, method(object({ deviceId: number$1().int().nonnegative() }),
 }), boolean()), method(object({
 	deviceId: number$1().int().nonnegative(),
 	sessionId: string()
-}), object({ pendingRenegotiation: object({
-	target: WebrtcStreamTargetSchema,
-	epoch: number$1()
-}).nullable() }));
+}), object({
+	pendingRenegotiation: object({
+		target: WebrtcStreamTargetSchema,
+		epoch: number$1()
+	}).nullable(),
+	/**
+	* Whether the session still EXISTS.
+	*
+	* A consumer that holds a resource for the life of a session needs to
+	* be able to ask, because a session does not always end the way it
+	* began. Measured on this hub 2026-09-13: an Echo that got stuck never
+	* sent `SessionDisconnected`, so the Alexa exporter's
+	* `releaseEgressTranscode` never ran, and a 2304x1296 HEVC to 720p
+	* H.264 transcode kept running for NOBODY for more than twenty
+	* minutes. The WebRTC session had logged `WebRTC session closed`
+	* minutes earlier — the broker knew; the holder had no way to ask.
+	*
+	* `false` for a session id the provider has never heard of, which is
+	* the same answer as "it ended": either way nothing is holding it up.
+	*/
+	alive: boolean()
+}));
 object({
 	/** All accessory children of the parent. */
 	childDeviceIds: array(number$1()).readonly(),
@@ -36454,6 +36602,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"streamBroker.reportStreamSignal": {
+		capName: "stream-broker",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"streamBroker.restartProfile": {
 		capName: "stream-broker",
 		capScope: "system",
@@ -36538,6 +36692,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"streamSignals.listSignals": {
+		capName: "stream-signals",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"switch.setState": {
 		capName: "switch",
 		capScope: "device",
@@ -38910,6 +39070,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"streamBroker.reportStreamSignal": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"streamBroker.restartProfile": [{
 		name: "deviceId",
 		form: "single",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-ai",
-  "version": "0.4.106",
+  "version": "0.4.107",
   "description": "AI addon for CamStack — the `llm` collection provider (cloud, LAN, and camstack-managed local llama.cpp profiles) plus the per-node `llm-runtime` managed executor.",
   "keywords": [
     "camstack",